diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
index a716197..be1378d 100644
--- a/.github/workflows/linux.yml
+++ b/.github/workflows/linux.yml
@@ -1,8 +1,8 @@
 # Linux 流水线：Rust 存储 + Haskell 引擎/Web/CLI 的构建与测试。
 #
 # 这里每条命令都在 WSL Debian（cargo 1.98 / GHC 9.10.3 / stack 3.11.1）上跑通过，
-# 见仓库根 README 的「构建与测试」段。IPC 用例需要 chusql-storage 可执行文件，
-# 所以 Rust 先构建，Haskell 的 engine/web 用例才能真跑而不是 pending。
+# 见仓库根 README 的「构建与测试」段。Haskell 这边链接并装入 libchusql_core_storage.so，
+# 所以 Rust 先构建，LD_LIBRARY_PATH 指向它的输出目录，Haskell 用例才能真跑而不是 pending。
 # 打包和发版资源走 .github/workflows/release.yml（tag 触发，也可手动 dispatch）。
 name: linux
 
@@ -18,6 +18,7 @@ concurrency:
 
 env:
   CARGO_TERM_COLOR: always
+  LD_LIBRARY_PATH: ${{ github.workspace }}/chusql-core/storage/target/release
 
 jobs:
   linux:
@@ -39,24 +40,20 @@ jobs:
           path: |
             ~/.cargo/registry
             ~/.cargo/git
-            chusql-storage/target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('chusql-storage/Cargo.lock') }}
+            chusql-core/storage/target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('chusql-core/storage/Cargo.lock') }}
           restore-keys: ${{ runner.os }}-cargo-
 
       - name: cargo build (release)
-        working-directory: chusql-storage
+        working-directory: chusql-core/storage
         run: cargo build --release
 
-      - name: cargo build (debug, IPC 用例要它)
-        working-directory: chusql-storage
-        run: cargo build --bin chusql-storage
-
       - name: cargo test
-        working-directory: chusql-storage
+        working-directory: chusql-core/storage
         run: cargo test --release
 
       - name: cargo clippy (-D warnings)
-        working-directory: chusql-storage
+        working-directory: chusql-core/storage
         run: cargo clippy --all-targets -- -D warnings
 
       # 故意不做 rustfmt 检查：仓库里没有 rustfmt.toml，历史代码也不是按当前 rustfmt 的
@@ -76,7 +73,8 @@ jobs:
         with:
           path: |
             ~/.stack
-            chusql-engine/.stack-work
+            chusql-core/engine/.stack-work
+            chusql-server/.stack-work
             chusql-web/.stack-work
             chusql-cli/.stack-work
           key: ${{ runner.os }}-stack-${{ hashFiles('**/stack.yaml', '**/stack.yaml.lock') }}
@@ -87,7 +85,11 @@ jobs:
         run: stack build --fast
 
       - name: engine tests
-        working-directory: chusql-engine
+        working-directory: chusql-core/engine
+        run: stack test --fast
+
+      - name: server tests
+        working-directory: chusql-server
         run: stack test --fast
 
       - name: web tests
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 8083dca..d510807 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,10 +1,11 @@
-# 发版流水线：打 tag（v*）时为四个平台各出 web / cli 两个发行包，附 sha256，挂到 Release。
+# 发版流水线：打 tag（v*）时为四个平台各出一个发行包，附 sha256，挂到 Release。
 #
-# 资源命名（install.sh 按 <os>-<arch> 挑资源，见 scripts/install.sh）：
-#   chusql-web-linux-x86_64.tar.gz     chusql-cli-linux-x86_64.tar.gz
-#   chusql-web-windows-x86_64.zip      chusql-cli-windows-x86_64.zip
-#   chusql-web-macos-x86_64.tar.gz     chusql-cli-macos-x86_64.tar.gz
-#   chusql-web-macos-arm64.tar.gz      chusql-cli-macos-arm64.tar.gz
+# 资源命名（install.sh / install.ps1 按 <os>-<arch> 挑资源，见 scripts/install.sh）：
+#   chusql-linux-x86_64.tar.gz     chusql-windows-x86_64.zip
+#   chusql-macos-x86_64.tar.gz     chusql-macos-arm64.tar.gz
+#
+# 一个平台一个包，里面 Web 前端与命令行客户端两部分都在；装哪几个由包内的安装脚本
+# 当场问（非交互时用 --component / -Component 指定）。
 #
 # 装的人拿到的就是编好的二进制，不需要 GHC / Rust：
 #   curl -fsSL https://raw.githubusercontent.com/TheBadRoger/ChuSQL/main/scripts/install.sh \
@@ -33,9 +34,9 @@ env:
 
 jobs:
   build:
-    name: ${{ matrix.platform }} / ${{ matrix.component }}
+    name: ${{ matrix.platform }}
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 120
+    timeout-minutes: 150
     strategy:
       fail-fast: false
       matrix:
@@ -44,7 +45,6 @@ jobs:
           - { os: windows-latest, platform: windows-x86_64 }
           - { os: macos-13, platform: macos-x86_64 }
           - { os: macos-14, platform: macos-arm64 }
-        component: [web, cli]
     steps:
       - uses: actions/checkout@v4
 
@@ -58,8 +58,8 @@ jobs:
           path: |
             ~/.cargo/registry
             ~/.cargo/git
-            chusql-storage/target
-          key: ${{ runner.os }}-${{ matrix.platform }}-cargo-${{ hashFiles('chusql-storage/Cargo.lock') }}
+            chusql-core/storage/target
+          key: ${{ runner.os }}-${{ matrix.platform }}-cargo-${{ hashFiles('chusql-core/storage/Cargo.lock') }}
           restore-keys: ${{ runner.os }}-cargo-
 
       - name: Haskell toolchain
@@ -74,7 +74,7 @@ jobs:
         with:
           path: |
             ~/.stack
-            chusql-engine/.stack-work
+            chusql-core/engine/.stack-work
             chusql-web/.stack-work
             chusql-cli/.stack-work
           key: ${{ runner.os }}-${{ matrix.platform }}-stack-${{ hashFiles('**/stack.yaml', '**/stack.yaml.lock') }}
@@ -82,59 +82,62 @@ jobs:
 
       # ---------- 构建 ----------
       - name: build storage (Rust)
-        working-directory: chusql-storage
+        working-directory: chusql-core/storage
         run: cargo build --release
 
       - name: build web front end
-        if: matrix.component == 'web'
         working-directory: chusql-cli
         run: stack build --fast chusql-web:exe:chusql-web
 
       - name: build cli
-        if: matrix.component == 'cli'
         working-directory: chusql-cli
         run: stack build --fast chusql-cli:exe:csql
 
-      # ---------- 装配 + 打归档（原来放在一个独立的打包脚本里，那个脚本已经删掉）----------
+      - name: build tcp server
+        working-directory: chusql-cli
+        run: stack build --fast chusql-server:exe:chusql-server
+
+      # ---------- 装配 + 打归档（CI 里直接写在这里；本机打同一个包用 scripts/package.sh）----------
       # 归档里是包内容本身（bin/、scripts/、static/、install.sh 就在根上），安装脚本按这个布局找文件。
       - name: package (Unix)
         if: runner.os != 'Windows'
         shell: bash
         run: |
           set -eu
-          component='${{ matrix.component }}'
-          name="chusql-$component-${{ matrix.platform }}"
+          name="chusql-${{ matrix.platform }}"
           stage="dist/$name"
           rm -rf "$stage"
           mkdir -p "$stage/bin" "$stage/scripts"
 
-          cp chusql-storage/target/release/chusql-storage "$stage/bin/"
+          cp chusql-core/storage/target/release/libchusql_core_storage.* "$stage/bin/"
 
           stack_root="$(cd chusql-cli && stack path --local-install-root | tail -n 1 | tr -d '\r')"
-          if [ "$component" = web ]; then front_name=chusql-web; else front_name=csql; fi
-          front="$stack_root/bin/$front_name"
-          if [ ! -f "$front" ]; then
-            front="$(find chusql-web/.stack-work chusql-cli/.stack-work -name "$front_name" -type f 2>/dev/null | head -n 1 || true)"
-          fi
-          [ -n "$front" ] && [ -f "$front" ] || { echo "front end binary not found: $front_name" >&2; exit 1; }
-          cp "$front" "$stage/bin/"
+          for front_name in chusql-web chusql-server csql; do
+            front="$stack_root/bin/$front_name"
+            if [ ! -f "$front" ]; then
+              front="$(find chusql-web/.stack-work chusql-cli/.stack-work -name "$front_name" -type f 2>/dev/null | head -n 1 || true)"
+            fi
+            [ -n "$front" ] && [ -f "$front" ] || { echo "front end binary not found: $front_name" >&2; exit 1; }
+            cp "$front" "$stage/bin/"
+          done
 
-          # Haskell 一般静态链接，靶目录里真有共享库就一起带上
-          for lib in chusql-storage/target/release/*.so chusql-storage/target/release/*.dylib; do
-            [ -f "$lib" ] && cp "$lib" "$stage/bin/"
+          # Haskell 一般静态链接，靶目录里真有共享库就一起带上；改名前的旧库（libchusql_storage.*）不能进包
+          for lib in chusql-core/storage/target/release/*.so chusql-core/storage/target/release/*.dylib; do
+            [ -f "$lib" ] || continue
+            case "$(basename "$lib")" in
+              libchusql_storage.*|libchusql_storage-*) continue ;;
+            esac
+            cp "$lib" "$stage/bin/"
           done
 
           cp scripts/chusql.toml scripts/init.sql "$stage/scripts/"
           cp scripts/install.ps1 scripts/install.sh "$stage/"
-          if [ "$component" = web ]; then
-            mkdir -p "$stage/static"
-            cp -R chusql-web/static/. "$stage/static/"
-            cp scripts/csql-web.sh "$stage/"
-            if [ -f scripts/csql-web.ps1 ]; then cp scripts/csql-web.ps1 "$stage/"; fi
-          fi
+          mkdir -p "$stage/static"
+          cp -R chusql-web/static/. "$stage/static/"
+          cp scripts/csql-web.sh "$stage/"
+          if [ -f scripts/csql-web.ps1 ]; then cp scripts/csql-web.ps1 "$stage/"; fi
 
-          chmod +x "$stage/install.sh"
-          if [ -f "$stage/csql-web.sh" ]; then chmod +x "$stage/csql-web.sh"; fi
+          chmod +x "$stage/install.sh" "$stage/csql-web.sh"
 
           mkdir -p dist
           tar -czf "dist/$name.tar.gz" -C "$stage" .
@@ -146,35 +149,35 @@ jobs:
         shell: pwsh
         run: |
           $ErrorActionPreference = 'Stop'
-          $component = '${{ matrix.component }}'
-          $name = "chusql-$component-${{ matrix.platform }}"
+          $name = "chusql-${{ matrix.platform }}"
           $stage = "dist/$name"
           if (Test-Path $stage) { Remove-Item -Recurse -Force $stage }
           New-Item -ItemType Directory -Force -Path "$stage/bin", "$stage/scripts" | Out-Null
 
-          Copy-Item 'chusql-storage/target/release/chusql-storage.exe' "$stage/bin/"
+          Copy-Item 'chusql-core/storage/target/release/chusql_core_storage.dll' "$stage/bin/"
 
           $stackRoot = (& stack path --local-install-root | Select-Object -Last 1).Trim()
-          $frontName = if ($component -eq 'web') { 'chusql-web.exe' } else { 'csql.exe' }
-          $front = Join-Path $stackRoot "bin/$frontName"
-          if (-not (Test-Path $front)) {
-            $front = Get-ChildItem -Path 'chusql-web/.stack-work', 'chusql-cli/.stack-work' -Recurse -Filter $frontName -File -ErrorAction SilentlyContinue |
-              Sort-Object LastWriteTime -Descending | Select-Object -First 1 -ExpandProperty FullName
+          foreach ($frontName in @('chusql-web.exe', 'chusql-server.exe', 'csql.exe')) {
+            $front = Join-Path $stackRoot "bin/$frontName"
+            if (-not (Test-Path $front)) {
+              $front = Get-ChildItem -Path 'chusql-web/.stack-work', 'chusql-cli/.stack-work' -Recurse -Filter $frontName -File -ErrorAction SilentlyContinue |
+                Sort-Object LastWriteTime -Descending | Select-Object -First 1 -ExpandProperty FullName
+            }
+            if (-not $front -or -not (Test-Path $front)) { throw "front end binary not found: $frontName" }
+            Copy-Item $front "$stage/bin/"
           }
-          if (-not $front -or -not (Test-Path $front)) { throw "front end binary not found: $frontName" }
-          Copy-Item $front "$stage/bin/"
 
-          Get-ChildItem 'chusql-storage/target/release' -Filter '*.dll' -File -ErrorAction SilentlyContinue |
+          # 第三方 dll 才要连带上：名字带 chusql 的是本 crate 产物或改名前的残留，上面已按名拷过
+          Get-ChildItem 'chusql-core/storage/target/release' -Filter '*.dll' -File -ErrorAction SilentlyContinue |
+            Where-Object { $_.Name -notlike 'chusql*' } |
             ForEach-Object { Copy-Item $_.FullName "$stage/bin/" }
 
           Copy-Item 'scripts/chusql.toml', 'scripts/init.sql' "$stage/scripts/"
           Copy-Item 'scripts/install.ps1', 'scripts/install.sh' $stage
-          if ($component -eq 'web') {
-            New-Item -ItemType Directory -Force -Path "$stage/static" | Out-Null
-            Copy-Item 'chusql-web/static/*' "$stage/static" -Recurse
-            Copy-Item 'scripts/csql-web.sh' $stage
-            if (Test-Path 'scripts/csql-web.ps1') { Copy-Item 'scripts/csql-web.ps1' $stage }
-          }
+          New-Item -ItemType Directory -Force -Path "$stage/static" | Out-Null
+          Copy-Item 'chusql-web/static/*' "$stage/static" -Recurse
+          Copy-Item 'scripts/csql-web.sh' $stage
+          if (Test-Path 'scripts/csql-web.ps1') { Copy-Item 'scripts/csql-web.ps1' $stage }
 
           New-Item -ItemType Directory -Force -Path dist | Out-Null
           Compress-Archive -Path "$stage/*" -DestinationPath "dist/$name.zip" -Force
@@ -193,7 +196,7 @@ jobs:
       - name: upload
         uses: actions/upload-artifact@v4
         with:
-          name: ${{ matrix.platform }}-${{ matrix.component }}
+          name: ${{ matrix.platform }}
           path: |
             dist/*.zip
             dist/*.tar.gz
diff --git a/.gitignore b/.gitignore
index 7a55486..c1e7d33 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,12 +1,12 @@
 # ============================================================
 # ChuSQL 单仓库 .gitignore
-#   chusql-engine/   Haskell (Stack + Cabal)
-#   chusql-storage/  Rust (Cargo)
+#   chusql-core/engine/   Haskell (Stack + Cabal)
+#   chusql-core/storage/  Rust (Cargo)
 #   chusql-web/      前端 (手写 HTML / CSS / JS，无 Node 工具链)
 # ============================================================
 
 # ------------------------------------------------------------
-# Haskell / Stack / Cabal —— chusql-engine
+# Haskell / Stack / Cabal —— chusql-core/engine
 # ------------------------------------------------------------
 .stack-work/
 dist-newstyle/
@@ -26,21 +26,24 @@ cabal.project.local
 cabal.project.local~
 
 # 锁文件要入库，不要忽略：
-#   chusql-engine/stack.yaml.lock
+#   chusql-core/engine/stack.yaml.lock
 #   cabal.project.freeze
 
 # ------------------------------------------------------------
-# Rust / Cargo —— chusql-storage
+# Rust / Cargo —— chusql-core/storage
 # ------------------------------------------------------------
 target/
 **/*.rs.bk
 
 # 运行时数据（Rust 服务默认数据目录 CHUSQL_DATA_DIR=data/），不入库
-chusql-storage/data/
+chusql-core/storage/data/
 
 # 一键启动脚本的默认数据目录与日志，不入库
 localdata/
 
+# 本机打出来的发行包（scripts/package.sh / package.ps1 的产物），不入库
+releases/
+
 # 前端 IDE 设置（字体等，由 /api/ui-settings 读写），本机专用，不入库
 scripts/chusql.ui.settings.json
 
@@ -74,7 +77,7 @@ scripts/chusql.ui.settings.json
 \#*\#
 .\#*
 agent_credientials
-
+.dsh
 # 注意：.zed/tasks.json 是本仓库共享的构建任务（stack build / run / test / repl），
 # 需要入库，所以这里不忽略 .zed/
 
diff --git a/.zed/tasks.json b/.zed/tasks.json
index b70113d..e2fadf3 100644
--- a/.zed/tasks.json
+++ b/.zed/tasks.json
@@ -2,7 +2,7 @@
     {
         "label": "haskell: stack build",
         "command": "stack build",
-        "cwd": "$ZED_WORKTREE_ROOT/chusql-engine",
+        "cwd": "$ZED_WORKTREE_ROOT/chusql-core/engine",
         "reveal": "always",
         "hide": "on_success",
         "save": "all",
@@ -10,7 +10,7 @@
     {
         "label": "haskell: stack test",
         "command": "stack test",
-        "cwd": "$ZED_WORKTREE_ROOT/chusql-engine",
+        "cwd": "$ZED_WORKTREE_ROOT/chusql-core/engine",
         "reveal": "always",
         "hide": "never",
         "save": "all",
@@ -18,7 +18,7 @@
     {
         "label": "haskell: stack run",
         "command": "stack run",
-        "cwd": "$ZED_WORKTREE_ROOT/chusql-engine",
+        "cwd": "$ZED_WORKTREE_ROOT/chusql-core/engine",
         "reveal": "always",
         "hide": "never",
         "save": "all",
@@ -26,7 +26,7 @@
     {
         "label": "haskell: stack repl",
         "command": "stack ghci",
-        "cwd": "$ZED_WORKTREE_ROOT/chusql-engine",
+        "cwd": "$ZED_WORKTREE_ROOT/chusql-core/engine",
         "reveal": "always",
         "hide": "never",
         "save": "all",
@@ -35,7 +35,7 @@
         "label": "rust: cargo check",
         "command": "cargo",
         "args": ["check", "--all-targets"],
-        "cwd": "$ZED_WORKTREE_ROOT/chusql-storage",
+        "cwd": "$ZED_WORKTREE_ROOT/chusql-core/storage",
         "reveal": "always",
         "hide": "on_success",
         "save": "all",
@@ -44,16 +44,7 @@
         "label": "rust: cargo test",
         "command": "cargo",
         "args": ["test"],
-        "cwd": "$ZED_WORKTREE_ROOT/chusql-storage",
-        "reveal": "always",
-        "hide": "never",
-        "save": "all",
-    },
-    {
-        "label": "rust: cargo run server",
-        "command": "cargo",
-        "args": ["run", "--bin", "server"],
-        "cwd": "$ZED_WORKTREE_ROOT/chusql-storage",
+        "cwd": "$ZED_WORKTREE_ROOT/chusql-core/storage",
         "reveal": "always",
         "hide": "never",
         "save": "all",
diff --git a/AGENTS.md b/AGENTS.md
index f17f296..5948870 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,9 +14,17 @@
 - 索引由存储层管理，优化器只判断可点查条件。
 - 优化不能改变结果语义。
 
+## 注释规范
+- 文件级：外部引用语句（Haskell `import`、Rust `use`、JS `import`、HTML 的 `<link>`/`<script>`、
+  CSS `@import`、脚本的依赖/参数区）之后写一段注释，概括本文件的功能；没有引用语句的文件写在
+  文件开头。长度不超过 3 行、合计不超过 90 字。
+- 函数级：每个函数（含 Haskell 的 `where`/`let` 内函数、Rust 的私有 `fn`）前用一行不超过
+  30 字的注释说明它做什么。
+- 只写"做什么"，不写设计理由、历史与被删掉的旧实现；那些放 `design-decisions.txt` /
+  `known-issues.txt`。
+
 ## 协作规则
 - engine / web / storage 使用规定测试入口。
-- 注释、文案保持简短。
 - 改动说明只在交流中记录。
 
 ## 当前重点
diff --git a/README.md b/README.md
index 1423c2c..8d66260 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 优点：
 
-- 轻量：两个可执行文件加一份静态资源，解包即用，没有 Node / Python 之类的运行时依赖
+- 轻量：几个可执行文件加两个动态库、一份静态资源，解包即用，没有 Node / Python 之类的运行时依赖
 - 部署容易：Linux 与 macOS 一条命令装完并启动，Windows 解压后跑一次安装脚本
 - 配置统一：一个 `chusql.toml` 同时管住存储、Web 与命令行
 - 账号统一：Web 管理端与命令行共用同一个管理员和同一张账号表
@@ -14,16 +14,17 @@
 Linux / macOS（自动识别当前平台，取对应发行包）：
 
 ```sh
-curl -fsSL https://github.com/TheBadRoger/ChuSQL/releases/latest/download/install.sh | sh -s -- --component web
+curl -fsSL https://raw.githubusercontent.com/TheBadRoger/ChuSQL/main/scripts/install.sh | sh -s -- --component web
 ```
 
-Windows：下载 `chusql-web-windows-x86_64.zip`，解压后在 PowerShell 里执行
+Windows：下载 `chusql-windows-x86_64.zip`，解压后在 PowerShell 里执行
 
 ```powershell
 .\install.ps1 -Component web
 ```
 
-只装命令行客户端就把 `web` 换成 `cli`，入口变成 `csql`。安装位置、目录结构与卸载方式见
+不写 `--component` 时脚本会逐个问「装 cli 吗」「装 web 吗」（默认装 `csql`、不装 Web）；只装命令行
+客户端就把 `web` 换成 `cli`，两个都要用 `both`。安装位置、目录结构与卸载方式见
 [doc/install.md](doc/install.md)。
 
 ## 启动
@@ -32,7 +33,7 @@ Windows：下载 `chusql-web-windows-x86_64.zip`，解压后在 PowerShell 里
 csql-web
 ```
 
-浏览器打开 http://127.0.0.1:7777 ，默认账号 `root`，口令是安装时给的那个。服务启动后只有系统库 `system`（里面是账号表），**没有默认工作库**：自己建一个库再用 `USE <库名>` 选中它。
+浏览器打开 http://127.0.0.1:7778 ，默认账号 `root`，口令是安装时给的那个。服务启动后只有系统库 `system`（里面是账号表），**没有默认工作库**：自己建一个库再用 `USE <库名>` 选中它。
 换口令、换端口、改数据目录都在安装时写好的 `chusql.toml` 里。
 
 ## 文档
@@ -40,6 +41,6 @@ csql-web
 | 文档                              | 内容                                                                     |
 | --------------------------------- | ------------------------------------------------------------------------ |
 | [安装与卸载](doc/install.md)      | 三种安装方式、全部安装选项、装完的目录结构、从源码安装、卸载             |
-| [配置选项](doc/config.md)         | 配置位置与优先级、全部配置键与默认值、端点规则、口令与安全               |
+| [配置选项](doc/config.md)         | 配置位置与优先级、全部配置键与默认值、数据目录、口令与安全               |
 | [命令与选项](doc/commands.md)     | `csql` 与 `chusql-web` 的选项、元命令、账号与角色权限、REST 接口         |
 | [架构与组件](doc/architecture.md) | 三个组件怎么分工、一次请求经过什么、数据落在哪                           |
diff --git a/benchmark/chusql-fullchain.cabal b/benchmark/chusql-fullchain.cabal
index 67bf3d1..a40aa25 100644
--- a/benchmark/chusql-fullchain.cabal
+++ b/benchmark/chusql-fullchain.cabal
@@ -2,16 +2,22 @@ cabal-version: 2.4
 
 name:           chusql-fullchain
 version:        1.0.0
-synopsis:       ChuSQL 全链路基准：Haskell 引擎 + Rust 存储进程一起跑
+synopsis:       ChuSQL 全链路基准：起真 server，全部请求走 TCP
+description:    以基准客户端身份起一个 chusql-server 进程（存储与引擎都在那个进程里），
+                再经 TCP JSON-lines 协议打登录、ping、catalog、查询等场景。
+                本程序不链引擎、不链 server 库，只用 TCP 客户端与协议模型。
 build-type:     Simple
 
 executable chusql-fullchain
     main-is:          Main.hs
     hs-source-dirs:   src
+    build-tool-depends: chusql-server:chusql-server
     build-depends:    base >= 4.14 && < 5
-                    , chusql-engine
+                    , chusql-core-model
+                    , chusql-interface
                     , directory
                     , filepath
                     , process
+                    , text
     default-language: Haskell2010
     ghc-options:      -O2 -Wall
diff --git a/benchmark/src/Main.hs b/benchmark/src/Main.hs
index 2eb2ee9..8313e3b 100644
--- a/benchmark/src/Main.hs
+++ b/benchmark/src/Main.hs
@@ -1,40 +1,39 @@
+{-# LANGUAGE OverloadedStrings #-}
+
 module Main where
 
-import ChuSQL.Engine (runStatementM)
-import ChuSQL.Model (Row, Value (..))
-import ChuSQL.Storage (IndexResult (..))
-import ChuSQL.Storage.IPC (
-    IPCStorage (..),
-    Request (..),
-    Response (..),
-    TableInfo (..),
-    closeConnection,
-    doInsert,
-    doListCatalog,
-    doLookupByColumn,
-    sendRequest,
-    setPipeName,
+import ChuSQL.Core.Protocol (QueryResult (..), TableInfo (..))
+import ChuSQL.Interface.Link (Client, clientPing, closeClient, connectClient)
+import ChuSQL.Interface.Session (
+    Session,
+    authenticateSession,
+    catalog,
+    newSession,
+    runStatement,
+    switchDatabase,
  )
-import ChuSQL.Syntax.Parser (parseStatement)
-import Control.Concurrent (threadDelay)
-import Control.Exception (SomeException, bracket, evaluate, try)
-import Control.Monad (filterM, unless, when)
-import Data.List (intercalate, isInfixOf)
+import Control.Concurrent (forkIO, threadDelay)
+import Control.Exception (IOException, bracket, evaluate, try)
+import Control.Monad (unless, when)
+import Data.List (intercalate)
+import Data.Text (Text)
+import qualified Data.Text as T
 import GHC.Clock (getMonotonicTime)
 import System.Directory (
     createDirectoryIfMissing,
-    doesFileExist,
+    findExecutable,
     getTemporaryDirectory,
     removeDirectoryRecursive,
  )
 import System.Environment (getArgs)
-import System.Exit (exitFailure)
+import System.Exit (ExitCode (..), exitFailure)
 import System.FilePath ((</>))
 import System.Info (os)
+import System.IO (Handle, hGetLine)
 import System.Process (
-    CreateProcess (..),
+    CreateProcess (std_err, std_out),
     ProcessHandle,
-    StdStream (..),
+    StdStream (CreatePipe, NoStream),
     createProcess,
     proc,
     terminateProcess,
@@ -42,103 +41,51 @@ import System.Process (
  )
 import Text.Printf (printf)
 
--- 全链路基准：Haskell 引擎与 Rust 存储进程一起跑，语句走完整链路并打印墙上耗时。
+-- 全链路基准：客户端经 TCP 连 chusql-server，落盘到进程内 Rust 存储。
+-- 每条语句都走完整链路：解析、语义检查、提交。
+-- 对照项：ping 与 catalog。
 
--- | 找 Rust 存储进程：优先 release
-findServer :: FilePath -> IO FilePath
-findServer "" = do
-    let dirs =
-            [ "chusql-storage/target"
-            , "../chusql-storage/target"
-            ]
-        modes = ["release", "debug"]
-        -- 名字跟平台走：同一个 target 目录里可能躺着一份别处交叉编译出来的 .exe，
-        -- 在 Linux 上误选它只会拿到 config file not found
-        exes = [if os == "mingw32" then "chusql-storage.exe" else "chusql-storage"]
-        candidates = [d </> m </> e | d <- dirs, m <- modes, e <- exes]
-    found <- filterM doesFileExist candidates
-    case found of
-        (p : _) -> do
-            unless ("release" `isInfixOf` p) $
-                putStrLn "!! using the debug storage binary; numbers will be slower, run: cargo build --release"
-            pure p
-        [] -> do
-            putStrLn "Rust storage binary not found. Build it first:"
-            putStrLn "    cd chusql-storage && cargo build --release"
-            exitFailure
-findServer p = do
-    ok <- doesFileExist p
-    if ok
-        then pure p
-        else do
-            putStrLn ("storage binary not found: " ++ p)
-            exitFailure
+-- | 一个基准世界：真 server 进程 + 一条 TCP 会话
+data Bench = Bench
+    { bProcess :: ProcessHandle
+    , bDataDir :: FilePath
+    , bClient :: Client
+    , bSession :: Session
+    }
 
--- | 起存储进程并等管道可连：调参走 --config 指的那份配置文件，环境原样继承
-startServer :: FilePath -> FilePath -> IO ProcessHandle
-startServer serverPath configPath = do
-    (_, _, _, ph) <-
-        createProcess
-            (proc serverPath ["--config", configPath]){std_out = NoStream, std_err = Inherit}
-    ready <- waitReady (200 :: Int)
-    unless ready $ do
-        putStrLn "storage process was not ready within 5 s"
-        exitFailure
-    pure ph
-
--- | 轮询 ping，直到对面应答
-waitReady :: Int -> IO Bool
-waitReady 0 = pure False
-waitReady n = do
-    r <- try (sendRequest ReqPing) :: IO (Either SomeException Response)
-    case r of
-        Right RespPong -> pure True
-        _ -> threadDelay 25000 >> waitReady (n - 1)
-
--- | 停存储进程并清掉缓存连接
-stopServer :: ProcessHandle -> FilePath -> IO ()
-stopServer ph dataDir = do
-    closeConnection
-    terminateProcess ph
-    _ <- waitForProcess ph
-    _ <- try (removeDirectoryRecursive dataDir) :: IO (Either SomeException ())
-    pure ()
+-- | 跑一条 SQL 文本（整条链路）
+runSql :: Bench -> String -> IO (Either Text QueryResult)
+runSql bench sql = runStatement (bSession bench) (T.pack sql)
 
 -- | 量一次墙上耗时并强制求出行数
-timedRows :: IO (Either String [Row]) -> IO (Double, Either String Int)
-timedRows act = do
+timedQuery :: Bench -> String -> IO (Double, Either Text Int)
+timedQuery bench sql = do
     t0 <- getMonotonicTime
-    r <- act
+    r <- runSql bench sql
     n <- case r of
         Left _ -> pure (-1)
-        Right rows -> evaluate (length rows)
+        Right result -> evaluate (qrRowCount result)
     t1 <- getMonotonicTime
     pure (t1 - t0, either Left (const (Right n)) r)
 
--- | 跑一条 SQL 文本（整条链路）
-runSql :: String -> IO (Either String [Row])
-runSql sql = case parseStatement sql of
-    Left e -> pure (Left e)
-    Right stmt -> runIPCStorage (runStatementM stmt)
-
 -- | 打印一行结果
-report :: String -> Either String Int -> Double -> IO ()
+report :: String -> Either Text Int -> Double -> IO ()
 report label result dt = case result of
-    Left e -> printf "%-38s %10s   !! %s\n" label "FAILED" e
+    Left e -> printf "%-38s %10s   !! %s\n" label ("FAILED" :: String) (T.unpack e)
     Right n -> printf "%-38s %8.1f ms %8d rows\n" label (dt * 1000) n
 
 -- | 单独量一条可重复的 SQL（先预热）
-benchSql :: String -> String -> IO (Either String Int)
-benchSql label sql = do
-    _ <- runSql sql
-    (dt, r) <- timedRows (runSql sql)
+benchSql :: Bench -> String -> String -> IO (Either Text Int)
+benchSql bench label sql = do
+    _ <- runSql bench sql
+    (dt, r) <- timedQuery bench sql
     report label r dt
     pure r
 
 -- | 只跑一次的语句（重跑会报错）
-benchSqlOnce :: String -> String -> IO (Either String Int)
-benchSqlOnce label sql = do
-    (dt, r) <- timedRows (runSql sql)
+benchSqlOnce :: Bench -> String -> String -> IO (Either Text Int)
+benchSqlOnce bench label sql = do
+    (dt, r) <- timedQuery bench sql
     report label r dt
     pure r
 
@@ -157,10 +104,10 @@ orderSql u j =
         (j `mod` 50)
 
 -- | 批量插入并报平均耗时
-batchInsert :: String -> Int -> (Int -> String) -> IO (Either String ())
-batchInsert label n mkSql = do
+batchInsert :: Bench -> String -> Int -> (Int -> String) -> IO (Either Text ())
+batchInsert bench label n mkSql = do
     t0 <- getMonotonicTime
-    results <- mapM (runSql . mkSql) [1 .. n]
+    results <- mapM (runSql bench . mkSql) [1 .. n]
     t1 <- getMonotonicTime
     let total = t1 - t0
         errs = [e | Left e <- results]
@@ -173,66 +120,66 @@ batchInsert label n mkSql = do
                 (total * 1000 / fromIntegral n)
             pure (Right ())
         (e : _) -> do
-            printf "%-38s %10s   !! %s\n" label "FAILED" e
+            printf "%-38s %10s   !! %s\n" label ("FAILED" :: String) (T.unpack e)
             pure (Left e)
 
--- | 一次点查（原始 IPC，不经过引擎）
-benchLookup :: String -> String -> Int -> Int -> IO ()
-benchLookup table column key times = do
-    _ <- doLookupByColumn table column (VInt key)
+-- | 纯 TCP 往返：只过协议层，不过引擎与存储
+benchPing :: Bench -> Int -> IO ()
+benchPing bench times = do
+    _ <- clientPing (bClient bench)
     t0 <- getMonotonicTime
-    results <- mapM (const (doLookupByColumn table column (VInt key))) [1 .. times]
+    results <- mapM (const (clientPing (bClient bench))) [1 .. times]
     t1 <- getMonotonicTime
     let total = t1 - t0
-        hit = length [() | Right (IndexRows (_ : _)) <- results]
+        hits = length [() | Right _ <- results]
     printf
-        "%-38s %8.1f ms %7.3f ms/op (hits %d/%d)\n"
-        "lookup_by_index (raw IPC, by id)"
+        "%-38s %8.1f ms %7.3f ms/op (pongs %d/%d)\n"
+        ("tcp round trip (ping, no engine)" :: String)
         (total * 1000)
         (total * 1000 / fromIntegral times)
-        hit
+        hits
+        times
+
+-- | 一次点查（走语句，等于把 id 索引那一支也量进去）
+benchLookup :: Bench -> Int -> Int -> IO ()
+benchLookup bench key times = do
+    let sql = printf "SELECT name FROM users WHERE id = %d" key
+    _ <- runSql bench sql
+    t0 <- getMonotonicTime
+    results <- mapM (const (runSql bench sql)) [1 .. times]
+    t1 <- getMonotonicTime
+    let total = t1 - t0
+        hits = length [() | Right result <- results, qrRowCount result > 0]
+    printf
+        "%-38s %8.1f ms %7.3f ms/op (hits %d/%d)\n"
+        ("point lookup by id (statement, over TCP)" :: String)
+        (total * 1000)
+        (total * 1000 / fromIntegral times)
+        hits
         times
 
 -- | 量 list_catalog（只取结构，不取行）
-benchListCatalog :: Int -> IO ()
-benchListCatalog n = do
+benchCatalog :: Bench -> Int -> IO ()
+benchCatalog bench n = do
+    _ <- catalog (bSession bench)
     t0 <- getMonotonicTime
-    _ <- mapM (const doListCatalog) [1 .. n]
+    results <- mapM (const (catalog (bSession bench))) [1 .. n]
     t1 <- getMonotonicTime
     let total = t1 - t0
+        hits = length [() | Right _ <- results]
     printf
-        "%-38s %8.1f ms %7.3f ms/op\n"
-        "list_catalog (schema only)"
+        "%-38s %8.1f ms %7.3f ms/op (%d/%d ok)\n"
+        ("list_catalog (schema only, over TCP)" :: String)
         (total * 1000)
         (total * 1000 / fromIntegral n)
-
--- | 量原始 IPC 插入（不经过引擎）
-benchRawInsert :: String -> [Row] -> IO ()
-benchRawInsert table rows = do
-    t0 <- getMonotonicTime
-    results <- mapM (\r -> doInsert table r) rows
-    t1 <- getMonotonicTime
-    let total = t1 - t0
-        n = length rows
-        errs = [e | Left e <- results]
-    case errs of
-        [] ->
-            printf
-                "%-38s %8.1f ms %7.3f ms/row\n"
-                ("raw IPC insert x " ++ show n)
-                (total * 1000)
-                (total * 1000 / fromIntegral n)
-        (e : _) -> printf "%-38s %10s   !! %s\n" "raw IPC insert" "FAILED" e
-
--- | 造一行 users 数据（给原始 IPC 用）
-userRow :: Int -> Row
-userRow i = [("id", VInt i), ("name", VStr ("user" ++ show i)), ("age", VInt (i `mod` 100))]
+        hits
+        n
 
 -- | 依次跑一批语句，返回 (耗时秒, 错误清单)
-runBatch :: [String] -> IO (Double, [String])
-runBatch sqls = do
+runBatch :: Bench -> [String] -> IO (Double, [Text])
+runBatch bench sqls = do
     t0 <- getMonotonicTime
-    results <- mapM runSql sqls
+    results <- mapM (runSql bench) sqls
     t1 <- getMonotonicTime
     pure (t1 - t0, [e | Left e <- results])
 
@@ -240,6 +187,7 @@ runBatch sqls = do
 chunked :: Int -> Int -> [[Int]]
 chunked size n = go [1 .. n]
   where
+    -- | 递归切分
     go [] = []
     go xs = let (a, b) = splitAt size xs in a : go b
 
@@ -264,11 +212,11 @@ printStats i =
         )
 
 -- | 主场景
-runScenarios :: Int -> Int -> IO ()
-runScenarios u o = do
+runScenarios :: Bench -> Int -> Int -> IO ()
+runScenarios bench u o = do
     putStrLn "\n[create tables]"
-    r1 <- benchSqlOnce "CREATE TABLE users" "CREATE TABLE users (id int, name str, age int)"
-    r2 <- benchSqlOnce "CREATE TABLE orders" "CREATE TABLE orders (id int, user_id int, product str)"
+    r1 <- benchSqlOnce bench "CREATE TABLE users" "CREATE TABLE users (id int, name str, age int)"
+    r2 <- benchSqlOnce bench "CREATE TABLE orders" "CREATE TABLE orders (id int, user_id int, product str)"
     case (r1, r2) of
         (Right _, Right _) -> pure ()
         _ -> do
@@ -276,91 +224,246 @@ runScenarios u o = do
             exitFailure
 
     putStrLn "\n[write: every INSERT is a full durable commit]"
-    _ <- batchInsert (printf "%d INSERT INTO users" u) u userSql
-    _ <- batchInsert (printf "%d INSERT INTO orders" o) o (orderSql u)
+    _ <- batchInsert bench (printf "%d INSERT INTO users" u) u userSql
+    _ <- batchInsert bench (printf "%d INSERT INTO orders" o) o (orderSql u)
 
-    putStrLn "\n[breakdown: same INSERT split in two, both via raw IPC, no engine]"
-    _ <- benchSqlOnce "CREATE TABLE raw_users" "CREATE TABLE raw_users (id int, name str, age int)"
-    benchListCatalog 200
-    benchRawInsert "raw_users" [userRow i | i <- [1 .. u]]
+    putStrLn "\n[breakdown: protocol round trip vs one catalog call, both over TCP]"
+    benchPing bench 200
+    benchCatalog bench 200
 
     putStrLn "\n[read/query: full statement, including parsing and semantic checks]"
-    _ <- benchSql "SELECT * FROM users" "SELECT * FROM users"
-    ageR <- benchSql "SELECT name FROM users WHERE age > 90" "SELECT name FROM users WHERE age > 90"
+    _ <- benchSql bench "SELECT * FROM users" "SELECT * FROM users"
+    ageR <- benchSql bench "SELECT name FROM users WHERE age > 90" "SELECT name FROM users WHERE age > 90"
 
     putStrLn "\n[read/query: join]"
     joinR <-
         benchSql
+            bench
             "JOIN + WHERE (hash join)"
             "SELECT u.name FROM users u JOIN orders o ON u.id = o.user_id WHERE u.age > 90"
 
     putStrLn "\n[point lookup]"
-    benchLookup "users" "id" (u `div` 2) 100
-    _ <- benchSql "SELECT ... WHERE id = k (via Lookup)" (printf "SELECT name FROM users WHERE id = %d" (u `div` 2))
+    benchLookup bench (u `div` 2) 100
 
     putStrLn "\n[batch insert: one statement with N rows, one durable commit]"
-    _ <- benchSqlOnce "CREATE TABLE batch_t" "CREATE TABLE batch_t (id int, name str, age int)"
+    _ <- benchSqlOnce bench "CREATE TABLE batch_t" "CREATE TABLE batch_t (id int, name str, age int)"
     let groups = chunked 100 u
-    (bt, batchErrs) <- runBatch (map multiInsertSql groups)
+        perStmt = maximum (0 : map length groups)
+    (bt, batchErrs) <- runBatch bench (map multiInsertSql groups)
     case batchErrs of
         [] ->
             printf
                 "%-38s %8.1f ms %7.3f ms/row (%d rows/stmt x %d statements)\n"
-                "multi-row INSERT"
+                ("multi-row INSERT" :: String)
                 (bt * 1000)
                 (bt * 1000 / fromIntegral u)
-                (100 :: Int)
+                (perStmt :: Int)
                 (length groups)
-        (e : _) -> printf "%-38s %10s   !! %s\n" "multi-row INSERT" "FAILED" e
+        (e : _) -> printf "%-38s %10s   !! %s\n" ("multi-row INSERT" :: String) ("FAILED" :: String) (T.unpack e)
 
     putStrLn "\n[row delete: cost tracks the scan plus one commit, not the row count]"
-    _ <- benchSqlOnce "DELETE FROM users WHERE id = k (1 row)" (printf "DELETE FROM users WHERE id = %d" (u `div` 2))
-    _ <- benchSqlOnce "DELETE FROM users (all)" "DELETE FROM users"
+    _ <- benchSqlOnce bench "DELETE FROM users WHERE id = k (1 row)" (printf "DELETE FROM users WHERE id = %d" (u `div` 2))
+    _ <- benchSqlOnce bench "DELETE FROM users (all)" "DELETE FROM users"
 
     putStrLn "\n[secondary index: falls back to scan, then uses the index once built]"
-    _ <- benchSqlOnce "CREATE TABLE items" "CREATE TABLE items (id int, code int)"
+    _ <- benchSqlOnce bench "CREATE TABLE items" "CREATE TABLE items (id int, code int)"
     let itemGroups = chunked 100 o
         itemSql ids =
             "INSERT INTO items (id, code) VALUES "
                 ++ intercalate ", " [printf "(%d, %d)" i (i * 7 + 1) | i <- ids]
-    (it, itemErrs) <- runBatch (map itemSql itemGroups)
+    (it, itemErrs) <- runBatch bench (map itemSql itemGroups)
     case itemErrs of
         [] -> pure ()
-        (e : _) -> printf "  !! %s\n" e
+        (e : _) -> printf "  !! %s\n" (T.unpack e)
     printf "  (loaded %d rows into items: %.1f ms)\n" o (it * 1000)
     let targetCode = (o `div` 2) * 7 + 1
     _ <-
         benchSql
+            bench
             "SELECT ... WHERE code = k (no index)"
             (printf "SELECT id FROM items WHERE code = %d" targetCode)
-    _ <- benchSqlOnce "CREATE INDEX ON items (code)" "CREATE INDEX ON items (code)"
+    _ <- benchSqlOnce bench "CREATE INDEX ON items (code)" "CREATE INDEX ON items (code)"
     _ <-
         benchSql
+            bench
             "SELECT ... WHERE code = k (via index)"
             (printf "SELECT id FROM items WHERE code = %d" targetCode)
 
     putStrLn "\n[catalog stats]"
-    cat <- doListCatalog
+    cat <- catalog (bSession bench)
     case cat of
-        Left e -> printf "  failed to read stats: %s\n" e
+        Left e -> printf "  failed to read stats: %s\n" (T.unpack e)
         Right infos -> mapM_ printStats infos
 
     putStrLn "\n[checks]"
     let expectAge = 9 * (u `div` 100) + max 0 (u `mod` 100 - 90)
     printf
         "age > 90 matched %s (expected %d rows from the data distribution)\n"
-        (either show show ageR)
+        (either T.unpack show ageR)
         expectAge
     when (u == o) $
         printf
             "JOIN matched %s (one order per user, should equal the line above = %d)\n"
-            (either show show joinR)
+            (either T.unpack show joinR)
             expectAge
     unless (u == o) $
         putStrLn "(users and orders differ in size; no simple formula, printing only)"
-    printf "multi-row INSERT loaded %d rows (expected %d)\n" u u
+    loadedCheck <- runSql bench "SELECT id FROM batch_t"
+    printf
+        "multi-row INSERT loaded %s rows (expected %d)\n"
+        (either T.unpack (show . qrRowCount) loadedCheck)
+        u
     printf "secondary index: code = %d should find id = %d\n" targetCode (o `div` 2)
 
+-- | 基准用的库名
+benchDatabase :: String
+benchDatabase = "bench"
+
+-- | 服务端没有默认库：先开一个库，再把之后的语句都落进它
+prepareDatabase :: Session -> IO ()
+prepareDatabase session = do
+    created <- runStatement session ("CREATE DATABASE " <> T.pack benchDatabase)
+    case created of
+        Left e -> die ("cannot create the benchmark database: " ++ T.unpack e)
+        Right _ -> do
+            used <- switchDatabase session (T.pack benchDatabase)
+            case used of
+                Left e -> die ("cannot select the benchmark database: " ++ T.unpack e)
+                Right () -> pure ()
+  where
+    -- | 报错退出
+    die message = do
+        putStrLn message
+        exitFailure
+
+-- | 按平台补上 .exe 后缀
+binaryName :: String -> String
+binaryName stem = if os == "mingw32" then stem ++ ".exe" else stem
+
+-- | 在 PATH 里找 server 可执行文件
+locateServerExe :: IO FilePath
+locateServerExe = do
+    found <- findExecutable (binaryName "chusql-server")
+    case found of
+        Just path -> pure path
+        Nothing -> do
+            putStrLn "chusql-server was not found on PATH: run `stack build` first"
+            exitFailure
+
+-- | 从 server 输出里读出监听端口
+readListeningPort :: Handle -> IO Int
+readListeningPort handle = do
+    line <- hGetLine handle
+    case portFromBanner line of
+        Just port -> pure port
+        Nothing -> readListeningPort handle
+
+-- | 取一行里最后一串数字
+portFromBanner :: String -> Maybe Int
+portFromBanner line
+    | not ("listening:" `isInfixOf` line) = Nothing
+    | otherwise = case span isDigit (dropWhile (not . isDigit) (reverse line)) of
+        ([], _) -> Nothing
+        (digits, _) -> Just (read (reverse digits))
+
+-- | 判断子串是否出现
+isInfixOf :: String -> String -> Bool
+isInfixOf needle haystack = any (prefix needle) (tails haystack)
+  where
+    -- | 前缀匹配
+    prefix [] _ = True
+    prefix _ [] = False
+    prefix (x : xs) (y : ys) = x == y && prefix xs ys
+    -- | 所有后缀
+    tails [] = [[]]
+    tails s@(_ : rest) = s : tails rest
+
+-- | 判断是不是数字字符
+isDigit :: Char -> Bool
+isDigit ch = ch >= '0' && ch <= '9'
+
+-- | 把 server 的 stdout 抽干，免得管道塞满
+drainHandle :: Handle -> IO ()
+drainHandle handle = do
+    result <- try (hGetLine handle) :: IO (Either IOException String)
+    case result of
+        Left _ -> pure ()
+        Right _ -> drainHandle handle
+
+-- | 起 server、连上去、登录、开库
+startBench :: IO Bench
+startBench = do
+    bin <- locateServerExe
+    tmp <- getTemporaryDirectory
+    stamp <- getMonotonicTime
+    let name = "chusql-fullchain-" ++ show (round (stamp * 1e6) :: Int)
+        dataDir = tmp </> name
+        configPath = tmp </> (name ++ ".toml")
+        -- TOML 的普通字符串会吃反斜杠，路径统一用正斜杠
+        slashed = map (\c -> if c == '\\' then '/' else c) dataDir
+    createDirectoryIfMissing True dataDir
+    writeFile configPath (benchConfigText slashed)
+    printf "config   : %s\n" configPath
+    printf "data dir : %s\n" dataDir
+    (_, Just out, _, process) <-
+        createProcess (proc bin ["--config", configPath]){std_out = CreatePipe, std_err = NoStream}
+    port <- readListeningPort out
+    _ <- forkIO (drainHandle out)
+    printf "server   : pid launched, tcp port %d\n" port
+    linked <- connectClient "127.0.0.1" port
+    case linked of
+        Left err -> do
+            putStrLn ("cannot connect to the server: " ++ T.unpack err)
+            stopProcess process
+            exitFailure
+        Right client -> do
+            session <- newSession client
+            auth <- authenticateSession session (T.pack "admin") (T.pack "s3cret")
+            case auth of
+                Left err -> do
+                    putStrLn ("cannot sign in: " ++ T.unpack err)
+                    closeClient client
+                    stopProcess process
+                    exitFailure
+                Right () -> do
+                    prepareDatabase session
+                    pure (Bench process dataDir client session)
+
+-- | 基准用的配置：管理员凭据、随机端口、临时数据目录
+benchConfigText :: String -> String
+benchConfigText dataDir =
+    unlines
+        [ "[web]"
+        , "user = \"admin\""
+        , "password = \"s3cret\""
+        , ""
+        , "[server]"
+        , "host = \"127.0.0.1\""
+        , "port = 0"
+        , ""
+        , "[storage]"
+        , "data_dir = \"" ++ dataDir ++ "\""
+        , ""
+        , "[log]"
+        , "level = \"error\""
+        ]
+
+-- | 收摊：关会话、停 server、清数据目录
+stopBench :: Bench -> IO ()
+stopBench bench = do
+    putStrLn "\n[teardown] closing the TCP session, stopping the server, removing the data dir"
+    closeClient (bClient bench)
+    stopProcess (bProcess bench)
+    _ <- try (removeDirectoryRecursive (bDataDir bench)) :: IO (Either IOException ())
+    pure ()
+
+-- | 杀掉 server 进程
+stopProcess :: ProcessHandle -> IO ()
+stopProcess process = do
+    terminateProcess process
+    _ <- try (waitForProcess process) :: IO (Either IOException ExitCode)
+    pure ()
+
 -- | 主入口
 main :: IO ()
 main = do
@@ -368,48 +471,18 @@ main = do
     let pick i d = if length args > i then args !! i else d
         u = read (pick 0 "200") :: Int
         o = read (pick 1 "200") :: Int
-        serverArg = pick 2 ""
-    serverPath <- findServer serverArg
-
-    tmp <- getTemporaryDirectory
-    stamp <- getMonotonicTime
-    let pipe = "chusql-fullchain-" ++ show (round (stamp * 1e6) :: Int)
-        dataDir = tmp </> pipe
-        configPath = tmp </> (pipe ++ ".toml")
-        -- TOML 的普通字符串会吃反斜杠，路径统一用正斜杠
-        slashed = map (\c -> if c == '\\' then '/' else c) dataDir
-    createDirectoryIfMissing True dataDir
-    writeFile
-        configPath
-        ( unlines
-            [ "[storage]"
-            , "data_dir = \"" ++ slashed ++ "\""
-            , "[server]"
-            , "pipe_name = \"" ++ pipe ++ "\""
-            , "[log]"
-            , "level = \"error\""
-            ]
-        )
-    setPipeName pipe
-
-    printf "full-chain benchmark: Haskell engine <--named pipe--> Rust storage\n"
-    printf "storage  : %s\n" serverPath
-    printf "config   : %s\n" configPath
-    printf "pipe     : %s\n" pipe
-    printf "data dir : %s\n" dataDir
+    printf "full-chain benchmark: TCP client --> chusql-server --> in-process Rust storage\n"
     printf "dataset  : users = %d rows, orders = %d rows\n" u o
-    printf "timing   : wall clock (monotonic); every statement runs the full chain\n"
-
+    printf "timing   : wall clock (monotonic); every statement runs the full chain over TCP\n"
+    printf "note     : the client no longer links the engine or the storage library\n"
     bracket
         (do
             t1 <- getMonotonicTime
-            ph <- startServer serverPath configPath
+            bench <- startBench
             t2 <- getMonotonicTime
-            printf "\n[startup] storage ready in %.2f s\n" (t2 - t1)
-            pure ph
+            printf "\n[startup] server up, storage ready, signed in: %.2f s\n" (t2 - t1)
+            threadDelay 25000
+            pure bench
         )
-        (\ph -> do
-            putStrLn "\n[teardown] stopping storage and removing the data dir"
-            stopServer ph dataDir
-        )
-        (const (runScenarios u o))
+        stopBench
+        (\bench -> runScenarios bench u o)
diff --git a/benchmark/stack.yaml b/benchmark/stack.yaml
index 4048110..acfb0d8 100644
--- a/benchmark/stack.yaml
+++ b/benchmark/stack.yaml
@@ -1,5 +1,11 @@
 resolver: lts-24.59
 
+extra-lib-dirs:
+    - ../chusql-core/storage/target/release
+
 packages:
     - .
-    - ../chusql-engine
+    - ../chusql-core/engine
+    - ../chusql-core/model
+    - ../chusql-interface
+    - ../chusql-server
diff --git a/chusql-cli/app/Main.hs b/chusql-cli/app/Main.hs
index 586a667..1a608d8 100644
--- a/chusql-cli/app/Main.hs
+++ b/chusql-cli/app/Main.hs
@@ -11,19 +11,11 @@ import ChuSQL.CLI.Session (
     newSession,
     switchDatabase,
  )
-import ChuSQL.Web.Auth (Credential (..))
-import ChuSQL.Web.Backend (ipcBackend)
-import ChuSQL.Web.Config (WebConfig (..), defaultPassword, loadWebConfigAt, resolveCredential, resolvePipeName)
-import ChuSQL.Web.Settings (readSettingsFile)
-import ChuSQL.Web.TOML (resolveConfigPath)
-import ChuSQL.Web.StorageProcess (
-    StorageProcess,
-    findStorageServer,
-    startStorageProcessAt,
-    stopStorageProcess,
-    waitForStorage,
- )
-import ChuSQL.Storage.IPC (setPipeName)
+import ChuSQL.Interface.Auth (Credential (..))
+import ChuSQL.Interface.Config (ServerConfig (..), loadServerConfigAt, loadWebConfigAt, resolveCredential, resolvePlainPassword)
+import ChuSQL.Interface.Link (Client, closeClient, connectClient)
+import ChuSQL.Interface.Settings (readSettingsFile)
+import ChuSQL.Interface.TOML (resolveConfigPath)
 import Control.Exception (finally)
 import Control.Monad (unless)
 import Data.IORef (newIORef)
@@ -39,7 +31,7 @@ import System.Exit (exitFailure)
 import System.FilePath ((</>))
 import System.IO (hSetEncoding, stderr, stdout, utf8)
 
--- chusql-cli：与 Web 管理端并列的前端，直连存储与引擎，账号与 Web 共用。
+-- chusql-cli：与 Web 管理端并列的前端，接到拥有存储的 server 上跑 SQL，账号与 Web 共用。
 
 data Options = Options
     { optUser :: Maybe Text
@@ -48,11 +40,10 @@ data Options = Options
     , optFormat :: OutputFormat
     , optExecute :: Maybe Text
     , optHistory :: Maybe FilePath
-    , optPipe :: Maybe String
-    , optStorage :: Maybe FilePath
     , optConfig :: Maybe FilePath
     }
 
+-- | 命令行参数解析器
 optionsParser :: Parser Options
 optionsParser =
     Options
@@ -78,13 +69,13 @@ optionsParser =
             )
         <*> optional (T.pack <$> strOption (long "execute" <> short 'e' <> metavar "SQL" <> help "Run one statement and exit"))
         <*> optional (strOption (long "history" <> metavar "FILE" <> help "SQL history file (default ~/.chusql_history)"))
-        <*> optional (strOption (long "pipe" <> metavar "NAME" <> help "Endpoint name of the storage process (Windows named pipe, Unix socket file; default: [server] pipe_name in chusql.toml)"))
-        <*> optional (strOption (long "storage" <> metavar "SERVER" <> help "Rust storage executable to spawn when nothing answers the endpoint"))
         <*> optional (strOption (long "config" <> metavar "FILE" <> help "Config file to read (default: the fixed chusql.toml under the system config directory)"))
 
+-- | 把 --format 的取值解析成格式
 formatReader :: String -> Either String OutputFormat
 formatReader raw = maybe (Left "format must be table, json or csv") Right (parseFormat (T.pack raw))
 
+-- | 命令行界面与帮助
 parserInfo :: ParserInfo Options
 parserInfo =
     info
@@ -94,6 +85,7 @@ parserInfo =
             <> header "csql - the ChuSQL command line client"
         )
 
+-- | 解析参数、登录 server 后进入会话
 main :: IO ()
 main = do
     hSetEncoding stdout utf8
@@ -101,31 +93,29 @@ main = do
     options <- execParser parserInfo
     configPath <- resolveConfigPath (optConfig options)
     base <- loadWebConfigAt configPath
-    let settingsFile = configPath
-    saved <- readSettingsFile settingsFile
+    saved <- readSettingsFile configPath
     credential <- resolveCredential base saved
+    config <- loadServerConfigAt configPath
     let rootName = credUser credential
         userName = fromMaybe rootName (optUser options)
-        pipeName = resolvePipe options base
-    setPipeName pipeName
     password <- resolvePassword (optPromptPassword options) userName rootName saved
-    storage <- acquireStorage options pipeName settingsFile
-    case storage of
+    connected <- connectClient (T.pack (scHost config)) (scPort config)
+    case connected of
         Left message -> reportError message >> exitFailure
-        Right spawned ->
-            connect options credential settingsFile userName password
-                `finally` maybe (pure ()) stopStorageProcess spawned
+        Right client ->
+            connect options client userName password
+                `finally` closeClient client
 
--- | 接上存储，登录，然后进交互或跑单条语句
-connect :: Options -> Credential -> FilePath -> Text -> Text -> IO ()
-connect options credential settingsFile userName password = do
-    backend <- ipcBackend
-    session <- newSession backend credential settingsFile
+-- | 连 server、登录，之后转入会话
+connect :: Options -> Client -> Text -> Text -> IO ()
+connect options client userName password = do
+    session <- newSession client
     signedIn <- authenticateSession session userName password
     case signedIn of
         Left message -> reportError message >> exitFailure
         Right () -> runSession options session
 
+-- | 执行 -e 的单条语句，否则进交互循环
 runSession :: Options -> Session -> IO ()
 runSession options session = do
     formatRef <- newIORef (optFormat options)
@@ -140,7 +130,7 @@ runSession options session = do
                 historyFile <- resolveHistory (optHistory options)
                 runRepl session formatRef historyFile
 
--- | 只有 -d 明确给了一个库才切；没给就保持"未选库"（服务没有默认库）
+-- | -d 指定了库才切，否则保持未选库
 selectDatabase :: Session -> Text -> IO Bool
 selectDatabase _ wanted | T.null wanted = pure True
 selectDatabase session wanted
@@ -151,54 +141,20 @@ selectDatabase session wanted
             Left message -> reportError message >> pure False
             Right () -> pure True
 
--- | 口令：-p 强制交互输入；否则配置里的 root 明文（同 Web）> 交互输入
+-- | 决定口令是交互输入还是取自配置
 resolvePassword :: Bool -> Text -> Text -> Map.Map Text Text -> IO Text
 resolvePassword forcePrompt userName rootName saved
     | forcePrompt = promptPassword userName
-    | T.toLower userName == T.toLower rootName = pure (configuredPassword saved)
+    | T.toLower userName == T.toLower rootName = pure (resolvePlainPassword saved)
     | otherwise = promptPassword userName
-  where
-    configuredPassword values = case nonEmpty (Map.lookup "password" values) of
-        Just plain -> plain
-        Nothing -> defaultPassword
 
+-- | 交互式读取口令
 promptPassword :: Text -> IO Text
 promptPassword user = do
     entered <- runInputT defaultSettings (getPassword (Just '*') (T.unpack user <> "'s password: "))
     pure (maybe "" T.pack entered)
 
--- | 先找已经在跑的存储；--storage 给了可执行文件才自己拉一个
-acquireStorage :: Options -> String -> FilePath -> IO (Either Text (Maybe StorageProcess))
-acquireStorage options pipeName configPath = do
-    up <- waitForStorage 4
-    case optStorage options of
-        Nothing
-            | up -> pure (Right Nothing)
-            | otherwise ->
-                pure
-                    ( Left
-                        ( "no storage process answered on pipe "
-                            <> T.pack pipeName
-                            <> "; start the server first, or pass --storage <path>"
-                        )
-                    )
-        Just given
-            | up -> pure (Right Nothing)
-            | otherwise -> do
-                found <- findStorageServer (Just given)
-                case found of
-                    Left err -> pure (Left (T.pack err))
-                    Right binary -> fmap (either (Left . T.pack) (Right . Just)) (startStorageProcessAt binary pipeName configPath)
-
--- | 管名：--pipe > chusql.toml 的 [server] pipe_name（缺省 chusql-joint）
-resolvePipe :: Options -> WebConfig -> String
-resolvePipe options base = fromMaybe (resolvePipeName base) (optPipe options)
-
-nonEmpty :: Maybe Text -> Maybe Text
-nonEmpty given = case T.strip <$> given of
-    Just text | not (T.null text) -> Just text
-    _ -> Nothing
-
+-- | 取历史文件路径，没给就用默认
 resolveHistory :: Maybe FilePath -> IO (Maybe FilePath)
 resolveHistory (Just path) = pure (Just path)
 resolveHistory Nothing = do
diff --git a/chusql-cli/app/Repl.hs b/chusql-cli/app/Repl.hs
index 4cf666b..2fc667a 100644
--- a/chusql-cli/app/Repl.hs
+++ b/chusql-cli/app/Repl.hs
@@ -8,9 +8,9 @@ module Repl
 
 import ChuSQL.CLI.Format (OutputFormat, formatName, renderResult, renderRows)
 import ChuSQL.CLI.Script (Meta (..), errorHint, metaHelp, parseMeta, takeStatement)
-import ChuSQL.CLI.Session (Session, accountTable, catalog, databases, roleViews, runStatement, sessionDatabase, switchDatabase)
-import ChuSQL.Storage.IPC (SchemaColumn (..), TableInfo (..))
-import ChuSQL.Web.Privileges (Grant (..), RoleView (..))
+import ChuSQL.CLI.Session (Session, catalog, databases, roleViews, runStatement, sessionDatabase, switchDatabase)
+import ChuSQL.Core.Protocol (SchemaColumn (..), TableInfo (..))
+import ChuSQL.Interface.Protocol (Grant (..), RoleView (..))
 import Control.Monad (forM_, when)
 import Control.Monad.IO.Class (liftIO)
 import Data.IORef (IORef, readIORef, writeIORef)
@@ -22,7 +22,7 @@ import System.IO (hIsTerminalDevice, stderr, stdin)
 
 -- 交互层：提示符、多行输入、历史、元命令与错误提示。
 
--- | 交互循环；historyPath 为 Nothing 就不落盘历史
+-- | 交互循环，没有历史文件就不落盘
 runRepl :: Session -> IORef OutputFormat -> Maybe FilePath -> IO ()
 runRepl session formatRef historyPath =
     runInputT (defaultSettings{historyFile = historyPath}) (loop session formatRef T.empty)
@@ -41,6 +41,7 @@ runStatementOnce session format sql = do
         Left message -> reportError message >> pure False
         Right answer -> TIO.putStrLn (renderResult format answer) >> pure True
 
+-- | 读一行输入，分派到元命令或语句缓冲
 loop :: Session -> IORef OutputFormat -> Text -> InputT IO ()
 loop session formatRef buffer = do
     prompt <- liftIO (promptFor session buffer)
@@ -62,7 +63,7 @@ loop session formatRef buffer = do
                         remaining <- drain session formatRef extended
                         loop session formatRef remaining
 
--- | 提示符带上当前库；续行换个样子，方便看出语句还没写完；管道输入时不出提示符
+-- | 生成提示符；续行与非终端输入另有样式
 promptFor :: Session -> Text -> IO Text
 promptFor session buffer = do
     interactive <- hIsTerminalDevice stdin
@@ -83,6 +84,7 @@ drain session formatRef buffer = case takeStatement buffer of
         when (not (T.null statement)) (runOne session formatRef statement)
         drain session formatRef rest
 
+-- | 执行一条语句并打印结果
 runOne :: Session -> IORef OutputFormat -> Text -> InputT IO ()
 runOne session formatRef statement = do
     result <- liftIO (runStatement session statement)
@@ -92,6 +94,7 @@ runOne session formatRef statement = do
             format <- liftIO (readIORef formatRef)
             outputStrLn (T.unpack (renderResult format answer))
 
+-- | 执行元命令，返回是否继续循环
 runMeta :: Session -> IORef OutputFormat -> Meta -> InputT IO Bool
 runMeta session formatRef meta = case meta of
     MetaQuit -> pure False
@@ -120,17 +123,16 @@ listDatabases session = do
         Left message -> liftIO (reportError message)
         Right names -> outputStrLn (T.unpack (renderRows ["database"] (map (: []) names)))
 
--- | \dt：表清单（base 里补上账号表）
+-- | \dt：表清单（含 server 补的账号表）
 listTables :: Session -> InputT IO ()
 listTables session = do
     answer <- liftIO (catalog session)
     case answer of
         Left message -> liftIO (reportError message)
-        Right tables -> do
-            allTables <- liftIO (withAccountTable session tables)
-            outputStrLn (T.unpack (renderRows headers (map tableRow allTables)))
+        Right tables -> outputStrLn (T.unpack (renderRows headers (map tableRow tables)))
   where
     headers = ["table", "columns", "rows", "indexes"]
+    -- | 把表信息排成一行
     tableRow info =
         [ T.pack (tiTable info)
         , tshow (length (tiColumns info))
@@ -144,14 +146,15 @@ describeTable session name = do
     answer <- liftIO (catalog session)
     case answer of
         Left message -> liftIO (reportError message)
-        Right tables -> do
-            allTables <- liftIO (withAccountTable session tables)
-            case filter (matches name) allTables of
+        Right tables ->
+            case filter (matches name) tables of
                 [] -> liftIO (reportError ("unknown table: " <> name))
                 (info : _) -> outputStrLn (T.unpack (renderRows headers (map columnRow (tiColumns info))))
   where
     headers = ["column", "type", "primary", "unique", "nullable", "auto"]
+    -- | 表名忽略大小写比较
     matches wanted info = T.toLower (T.pack (tiTable info)) == T.toLower wanted
+    -- | 把列信息排成一行
     columnRow column =
         [ T.pack (scName column)
         , T.pack (scType column)
@@ -160,6 +163,7 @@ describeTable session name = do
         , yesNo (scNullable column)
         , yesNo (scAutoIncrement column)
         ]
+    -- | 布尔值转成 yes/no
     yesNo True = "yes"
     yesNo False = "no"
 
@@ -171,22 +175,15 @@ listRoles session = do
         Left message -> liftIO (reportError message)
         Right roles -> outputStrLn (T.unpack (renderRows ["role", "grants", "members"] (map roleRow roles)))
   where
+    -- | 把角色信息排成一行
     roleRow view =
         [ roleName view
         , if null (roleGrants view) then "-" else T.intercalate ", " (map grantText (roleGrants view))
         , if null (roleMembers view) then "-" else T.intercalate ", " (roleMembers view)
         ]
+    -- | 拼一条授权说明
     grantText grant = grantPrivilege grant <> " on " <> grantObject grant
 
--- | 当前库是 system 时，把账号表也列出来（与 Web 端一致）
-withAccountTable :: Session -> [TableInfo] -> IO [TableInfo]
-withAccountTable session tables = do
-    current <- sessionDatabase session
-    if current /= "system"
-        then pure tables
-        else do
-            extra <- accountTable session
-            pure (maybe tables (: tables) extra)
-
+-- | 用 show 转成 Text
 tshow :: Show a => a -> Text
 tshow = T.pack . show
diff --git a/chusql-cli/chusql-cli.cabal b/chusql-cli/chusql-cli.cabal
index 50affcb..78685e7 100644
--- a/chusql-cli/chusql-cli.cabal
+++ b/chusql-cli/chusql-cli.cabal
@@ -2,9 +2,9 @@ cabal-version: 2.4
 
 name:           chusql-cli
 version:        1.0.0
-synopsis:       ChuSQL 命令行客户端：直连引擎与存储，与 Web 管理端共用账号
-description:    ChuSQL 的命令行前端。直接走命名管道接 Rust 存储进程与 Haskell 引擎，
-                不经过 Web REST；root 凭据与 __chusql_users 表与 Web 管理端完全共用。
+synopsis:       ChuSQL 命令行客户端：直连数据库服务，与 Web 管理端共用账号
+description:    ChuSQL 的命令行前端。自己不开存储、不链引擎，所有 SQL 与会话
+                 都走 chusql-server 的 TCP 端点；账号表与权限服务与 Web 管理端完全共用。
 build-type:     Simple
 
 library
@@ -15,11 +15,9 @@ library
     build-depends:    base >= 4.14 && < 5
                     , aeson
                     , bytestring
-                    , chusql-engine
-                    , chusql-web
-                    , scientific
+                    , chusql-core-model
+                    , chusql-interface
                     , text
-                    , time
     default-language: Haskell2010
     ghc-options:      -Wall
 
@@ -28,10 +26,9 @@ executable csql
     other-modules:    Repl
     hs-source-dirs:   app
     build-depends:    base
-                    , aeson
                     , chusql-cli
-                    , chusql-engine
-                    , chusql-web
+                    , chusql-core-model
+                    , chusql-interface
                     , containers
                     , directory
                     , filepath
@@ -40,6 +37,11 @@ executable csql
                     , text
     default-language: Haskell2010
     ghc-options:      -Wall
+    -- 运行期找 libchusql_core_storage.so：$ORIGIN 让二进制与动态库同目录即可
+    if os(linux)
+        ld-options: -Wl,-rpath,$ORIGIN
+    if os(osx)
+        ld-options: -Wl,-rpath,@loader_path
 
 test-suite chusql-cli-test
     type:             exitcode-stdio-1.0
@@ -49,8 +51,7 @@ test-suite chusql-cli-test
                     , aeson
                     , bytestring
                     , chusql-cli
-                    , chusql-engine
-                    , chusql-web
+                    , chusql-core-model
                     , hspec
                     , text
     default-language: Haskell2010
diff --git a/chusql-cli/src/ChuSQL/CLI/Format.hs b/chusql-cli/src/ChuSQL/CLI/Format.hs
index 86b0aaa..4b1a275 100644
--- a/chusql-cli/src/ChuSQL/CLI/Format.hs
+++ b/chusql-cli/src/ChuSQL/CLI/Format.hs
@@ -12,8 +12,8 @@ module ChuSQL.CLI.Format
     , displayValue
     ) where
 
-import ChuSQL.CLI.Session (QueryResult (..), queryResultJson)
-import ChuSQL.Model (Value (..))
+import ChuSQL.Core.Model (Value (..))
+import ChuSQL.Core.Protocol (QueryResult (..), queryResultJson)
 import qualified Data.Aeson as A
 import qualified Data.ByteString.Lazy as BL
 import Data.Text (Text)
@@ -25,6 +25,7 @@ import Data.Text.Encoding (decodeUtf8)
 data OutputFormat = FormatTable | FormatJson | FormatCsv
     deriving (Eq, Show)
 
+-- | 格式的对外名字
 formatName :: OutputFormat -> Text
 formatName FormatTable = "table"
 formatName FormatJson = "json"
@@ -38,6 +39,7 @@ parseFormat raw = case T.toLower (T.strip raw) of
     "csv" -> Just FormatCsv
     _ -> Nothing
 
+-- | 按格式渲染查询结果
 renderResult :: OutputFormat -> QueryResult -> Text
 renderResult FormatTable = renderTable
 renderResult FormatJson = renderJson
@@ -47,10 +49,12 @@ renderResult FormatCsv = renderCsv
 renderJson :: QueryResult -> Text
 renderJson = decodeUtf8 . BL.toStrict . A.encode . queryResultJson
 
+-- | 渲染成 CSV
 renderCsv :: QueryResult -> Text
 renderCsv result = T.unlines (header : map rowLine (qrRows result))
   where
     header = T.intercalate "," (map csvField (qrColumns result))
+    -- | 拼一行 CSV
     rowLine row = T.intercalate "," (map (csvField . csvCell) row)
 
 -- | CSV 里的空值就是空字段
@@ -64,6 +68,7 @@ csvField field
     | T.any (`elem` (",\"\n\r" :: String)) field = "\"" <> T.replace "\"" "\"\"" field <> "\""
     | otherwise = field
 
+-- | 渲染成等宽表格
 renderTable :: QueryResult -> Text
 renderTable result
     | null (qrColumns result) = "OK"
@@ -74,10 +79,13 @@ renderRows :: [Text] -> [[Text]] -> Text
 renderRows columns rawRows = T.unlines (border : headerLine : border : body ++ [border, summary])
   where
     widths = [columnWidth index | index <- [0 .. length columns - 1]]
+    -- | 一列的显示宽度，有上限
     columnWidth index =
         min maxColumnWidth (maximum (T.length (columns !! index) : [T.length (cellAt row index) | row <- rawRows]))
     maxColumnWidth = 64
+    -- | 取某行某列，缺的当空
     cellAt row index = if index < length row then row !! index else ""
+    -- | 拼一行带竖线的表行
     cellLine cells = "| " <> T.intercalate " | " (zipWith pad widths (cells ++ repeat "")) <> " |"
     headerLine = cellLine columns
     body = map cellLine rawRows
@@ -93,6 +101,7 @@ pad width text = clipped <> T.replicate (width - T.length clipped) " "
         | width <= 3 = T.take width text
         | otherwise = T.take (width - 3) text <> "..."
 
+-- | 把值转成可显示的文本
 displayValue :: Value -> Text
 displayValue VNull = "NULL"
 displayValue (VInt n) = T.pack (show n)
diff --git a/chusql-cli/src/ChuSQL/CLI/Script.hs b/chusql-cli/src/ChuSQL/CLI/Script.hs
index 0201364..e8c5957 100644
--- a/chusql-cli/src/ChuSQL/CLI/Script.hs
+++ b/chusql-cli/src/ChuSQL/CLI/Script.hs
@@ -57,15 +57,18 @@ parseMeta raw = do
         "format" -> selectFormat argument
         other -> MetaUnknown other
   where
+    -- | 拼出切库命令
     connectTo argument
         | T.null argument = MetaUnknown "c"
         | otherwise = MetaConnect argument
+    -- | 解析格式参数
     selectFormat argument = maybe (MetaUnknown "format") MetaSetFormat (parseFormat argument)
 
--- | 取出第一条以分号结束的语句与后面的残余；字符串与注释里的分号不算
+-- | 取出第一条语句，忽略引号与注释里的分号
 takeStatement :: Text -> Maybe (Text, Text)
 takeStatement = go ScanNormal [] . T.unpack
   where
+    -- | 逐字符扫描语句边界
     go _ _ [] = Nothing
     go ScanNormal acc (';' : rest) = Just (T.strip (T.pack (reverse acc)), T.pack rest)
     go ScanNormal acc ('-' : '-' : rest) = go ScanLineComment ('-' : '-' : acc) rest
diff --git a/chusql-cli/src/ChuSQL/CLI/Session.hs b/chusql-cli/src/ChuSQL/CLI/Session.hs
index b9fde7b..e1e89b3 100644
--- a/chusql-cli/src/ChuSQL/CLI/Session.hs
+++ b/chusql-cli/src/ChuSQL/CLI/Session.hs
@@ -1,270 +1,5 @@
-{-# LANGUAGE OverloadedStrings #-}
+module ChuSQL.CLI.Session (module ChuSQL.Interface.Session) where
 
-module ChuSQL.CLI.Session
-    ( QueryResult (..)
-    , Session
-    , newSession
-    , sessionUser
-    , sessionIsAdmin
-    , sessionDatabase
-    , isPlainIdentifier
-    , authenticateSession
-    , switchDatabase
-    , runStatement
-    , catalog
-    , accountTable
-    , roleViews
-    , databases
-    , queryResultJson
-    ) where
+import ChuSQL.Interface.Session
 
-import ChuSQL.Model (Value (..))
-import ChuSQL.Storage.IPC (TableInfo (..))
-import ChuSQL.Syntax.AST (Statement (..))
-import ChuSQL.Syntax.Parser (parseStatement)
-import ChuSQL.Web.Accounts
-import ChuSQL.Web.API (configurePasswordPolicy, systemTableInfo)
-import ChuSQL.Web.Auth (Credential, defaultSessionPolicy, newSessionStore)
-import ChuSQL.Web.Backend (Backend (..), StatementResult (..))
-import ChuSQL.Web.Privileges (PrivilegeCommand, PrivilegeError (..), Privileges, RoleView, authorize, filterTables, listRoleViews, newPrivileges, privilegeCommand, runPrivilegeCommand)
-import Data.Aeson (object, (.=))
-import qualified Data.Aeson as A
-import Data.Char (isAlpha, isAlphaNum)
-import Data.IORef (IORef, newIORef, readIORef, writeIORef)
-import Data.Scientific (fromFloatDigits)
-import Data.Text (Text)
-import qualified Data.Text as T
-import Data.Time.Clock (getCurrentTime)
-
--- CLI 会话：直接连存储与引擎，但账号服务与 Web 管理端是同一套
--- （同一个 root 凭据，同一张 __chusql_users）。
-
-data QueryResult = QueryResult
-    { qrColumns :: [Text]
-    , qrRows :: [[Value]]
-    , qrRowCount :: Int
-    , qrTruncated :: Bool
-    , qrDatabase :: Maybe Text
-    }
-    deriving (Eq, Show)
-
-data Session = Session
-    { ssBackend :: Backend
-    , ssAccounts :: Accounts
-    , ssPrivileges :: Privileges
-    , ssCurrent :: IORef Text
-    , ssPrincipal :: IORef (Maybe Principal)
-    }
-
--- | 开一个会话：账号与角色服务、配置策略都和 Web 端一致
-newSession :: Backend -> Credential -> FilePath -> IO Session
-newSession backend credential settingsFile = do
-    sessions <- newSessionStore getCurrentTime defaultSessionPolicy
-    accounts <- newAccounts backend sessions credential
-    privileges <- newPrivileges backend
-    configurePasswordPolicy accounts settingsFile
-    -- 服务启动后只有系统库：没 USE 之前不预设任何工作库
-    current <- newIORef ""
-    principal <- newIORef Nothing
-    pure (Session backend accounts privileges current principal)
-
--- | 当前登录的账号名
-sessionUser :: Session -> IO (Maybe Text)
-sessionUser session = fmap principalName <$> readIORef (ssPrincipal session)
-
--- | 是不是配置里的 root
-sessionIsAdmin :: Session -> IO Bool
-sessionIsAdmin session = maybe False principalIsRoot <$> readIORef (ssPrincipal session)
-
--- | 当前库
-sessionDatabase :: Session -> IO Text
-sessionDatabase = readIORef . ssCurrent
-
--- | 与解析器一致的裸标识符判断
-isPlainIdentifier :: Text -> Bool
-isPlainIdentifier name =
-    not (T.null name)
-        && T.length name <= 64
-        && (isAlpha (T.head name) || T.head name == '_')
-        && T.all (\ch -> isAlphaNum ch || ch == '_') name
-
--- | 登录：root 比配置里的凭据，普通账号查 __chusql_users
-authenticateSession :: Session -> Text -> Text -> IO (Either Text ())
-authenticateSession session user password = do
-    result <- authenticate (ssAccounts session) user password
-    case result of
-        Left err -> pure (Left (accountMessage err))
-        Right token -> do
-            who <- currentPrincipal (ssAccounts session) token
-            case who of
-                Left err -> pure (Left (accountMessage err))
-                Right principal -> do
-                    writeIORef (ssPrincipal session) (Just principal)
-                    pure (Right ())
-
--- | 换库；系统库只有 root 能进
-switchDatabase :: Session -> Text -> IO (Either Text ())
-switchDatabase session rawName
-    | not (isPlainIdentifier name) = pure (Left ("not a plain database name: " <> name))
-    | name == "system" = do
-        admin <- sessionIsAdmin session
-        if admin then go else pure (Left "the system database is only available to the administrator")
-    | otherwise = go
-  where
-    name = T.toLower (T.strip rawName)
-    go = do
-        backend <- currentBackend session
-        result <- beStatement backend ("USE " ++ T.unpack name)
-        case result of
-            Left err -> pure (Left (T.pack err))
-            Right _ -> writeIORef (ssCurrent session) name >> pure (Right ())
-
--- | 跑一条语句：USE、账号语句与角色语句在这里分流，其余交给引擎
--- （普通身份先过一遍权限判定，管理员与未登录直接放行）
-runStatement :: Session -> Text -> IO (Either Text QueryResult)
-runStatement session sql = case parseStatement (T.unpack sql) of
-    Right (UseDatabase name) -> do
-        switched <- switchDatabase session (T.pack name)
-        case switched of
-            Left err -> pure (Left err)
-            Right () -> do
-                current <- readIORef (ssCurrent session)
-                pure (Right (emptyResult (Just current)))
-    Right statement
-        | Just command <- accountCommand statement -> runAccount session command
-        | Just command <- privilegeCommand statement -> runPrivilege session command
-        | otherwise -> do
-            allowed <- authorized session statement
-            case allowed of
-                Left err -> pure (Left err)
-                Right () -> runPlain session sql
-    Left _ -> runPlain session sql
-
--- | 普通身份跑语句前的权限判定；管理员与未登录放行
-authorized :: Session -> Statement -> IO (Either Text ())
-authorized session statement = do
-    who <- readIORef (ssPrincipal session)
-    case who of
-        Just principal | not (principalIsRoot principal) -> do
-            database <- readIORef (ssCurrent session)
-            result <- authorize (ssPrivileges session) principal database statement
-            pure (either (Left . privilegeMessage) (const (Right ())) result)
-        _ -> pure (Right ())
-
--- | 落到引擎/存储层的一条语句
-runPlain :: Session -> Text -> IO (Either Text QueryResult)
-runPlain session sql = do
-    backend <- currentBackend session
-    result <- beStatement backend (T.unpack sql)
-    pure (either (Left . T.pack) (Right . resultOf) result)
-
--- | 数据字典（\dt 与 \d 用）；普通身份只看得到自己有 SELECT 的表
-catalog :: Session -> IO (Either Text [TableInfo])
-catalog session = do
-    current <- readIORef (ssCurrent session)
-    if T.null current
-        then pure (Left "no database selected")
-        else do
-            backend <- currentBackend session
-            result <- beCatalog backend
-            case result of
-                Left e -> pure (Left (T.pack e))
-                Right infos -> do
-                    who <- readIORef (ssPrincipal session)
-                    case who of
-                        Just principal | not (principalIsRoot principal) -> do
-                            allowed <- filterTables (ssPrivileges session) principal current (map (T.pack . tiTable) infos)
-                            pure (either (Left . privilegeMessage) (\names -> Right (filter (\info -> T.pack (tiTable info) `elem` names) infos)) allowed)
-                        _ -> pure (Right infos)
-
--- | 库清单（\l 用）
-databases :: Session -> IO (Either Text [Text])
-databases session = do
-    result <- beDatabases (ssBackend session)
-    pure (either (Left . T.pack) (Right . map T.pack) result)
-
--- | 系统库里的账号表：列定义与 Web 端共用一份，行数从同一套账号服务来
-accountTable :: Session -> IO (Maybe TableInfo)
-accountTable session = do
-    admin <- sessionIsAdmin session
-    if not admin
-        then pure Nothing
-        else do
-            result <- listAccounts (ssAccounts session)
-            pure (either (const Nothing) (\accounts -> Just systemTableInfo{tiRows = length accounts}) result)
-
--- | 角色总览（\dr 用）；与 Web 的 /api/roles 一样只给管理员
-roleViews :: Session -> IO (Either Text [RoleView])
-roleViews session = do
-    admin <- sessionIsAdmin session
-    if not admin
-        then pure (Left "administrator required")
-        else do
-            result <- listRoleViews (ssPrivileges session)
-            pure (either (Left . privilegeMessage) Right result)
-
--- | 当前库对应的后端
-currentBackend :: Session -> IO Backend
-currentBackend session = do
-    name <- readIORef (ssCurrent session)
-    pure (beWithDatabase (ssBackend session) (T.unpack name))
-
--- | 账号语句走账号服务，普通账号一律拒绝
-runAccount :: Session -> AccountCommand -> IO (Either Text QueryResult)
-runAccount session command = do
-    who <- readIORef (ssPrincipal session)
-    case who of
-        Nothing -> pure (Left "sign in first")
-        Just principal -> do
-            result <- runAccountCommand (ssAccounts session) principal command
-            pure (either (Left . accountMessage) (const (Right (emptyResult Nothing))) result)
-
--- | 角色语句走权限服务，普通账号一律拒绝；当前库决定授权对象的落库口径
-runPrivilege :: Session -> PrivilegeCommand -> IO (Either Text QueryResult)
-runPrivilege session command = do
-    who <- readIORef (ssPrincipal session)
-    case who of
-        Nothing -> pure (Left "sign in first")
-        Just principal -> do
-            database <- readIORef (ssCurrent session)
-            result <- runPrivilegeCommand (ssPrivileges session) principal database command
-            pure (either (Left . privilegeMessage) (const (Right (emptyResult Nothing))) result)
-
-accountMessage :: AccountError -> Text
-accountMessage (AccountError _ message) = message
-
-privilegeMessage :: PrivilegeError -> Text
-privilegeMessage (PrivilegeError _ message) = message
-
-emptyResult :: Maybe Text -> QueryResult
-emptyResult database = QueryResult [] [] 0 False database
-
-resultOf :: StatementResult -> QueryResult
-resultOf result =
-    QueryResult
-        { qrColumns = map T.pack (srColumns result)
-        , qrRows = [map (cellOf row) (srColumns result) | row <- srRows result]
-        , qrRowCount = length (srRows result)
-        , qrTruncated = False
-        , qrDatabase = Nothing
-        }
-  where
-    cellOf row name = maybe VNull id (lookup name row)
-
--- | 结果还原成 JSON（JSON 输出用）
-queryResultJson :: QueryResult -> A.Value
-queryResultJson result =
-    object
-        [ "columns" .= qrColumns result
-        , "rows" .= map (map valueToJson) (qrRows result)
-        , "rowCount" .= qrRowCount result
-        , "truncated" .= qrTruncated result
-        , "database" .= qrDatabase result
-        ]
-
-valueToJson :: Value -> A.Value
-valueToJson VNull = A.Null
-valueToJson (VInt n) = A.Number (fromIntegral n)
-valueToJson (VFloat d) = A.Number (fromFloatDigits d)
-valueToJson (VStr s) = A.String (T.pack s)
-valueToJson (VBool b) = A.Bool b
+-- 命令行会话：转出前端共享的会话接口，一切请求走 server。
diff --git a/chusql-cli/stack.yaml b/chusql-cli/stack.yaml
index e232734..b8ec4bf 100644
--- a/chusql-cli/stack.yaml
+++ b/chusql-cli/stack.yaml
@@ -1,6 +1,12 @@
 resolver: lts-24.59
 
+extra-lib-dirs:
+    - ../chusql-core/storage/target/release
+
 packages:
     - .
-    - ../chusql-engine
+    - ../chusql-core/engine
+    - ../chusql-server
     - ../chusql-web
+    - ../chusql-core/model
+    - ../chusql-interface
diff --git a/chusql-cli/test/Spec.hs b/chusql-cli/test/Spec.hs
index 7eeb53b..91e5bb9 100644
--- a/chusql-cli/test/Spec.hs
+++ b/chusql-cli/test/Spec.hs
@@ -1,52 +1,31 @@
 {-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE PatternSynonyms #-}
 
 module Main (main) where
 
 import ChuSQL.CLI.Format (OutputFormat (..), parseFormat, renderCsv, renderJson, renderTable)
 import ChuSQL.CLI.Script (Meta (..), errorHint, parseMeta, statementComplete, stripTerminator, takeStatement)
-import ChuSQL.CLI.Session (
-    QueryResult (..),
-    Session,
-    authenticateSession,
-    catalog,
-    databases,
-    newSession,
-    queryResultJson,
-    roleViews,
-    runStatement,
-    sessionDatabase,
-    sessionIsAdmin,
-    switchDatabase,
- )
-import ChuSQL.Model (Database, Table (..), Value (..), pattern TInt, pattern TStr)
-import ChuSQL.Storage.IPC (TableInfo (..))
-import ChuSQL.Web.Auth (Credential (..), hashPasswordWith)
-import ChuSQL.Web.Backend (memoryBackend)
-import ChuSQL.Web.Privileges (Grant (..), RoleView (..))
-import Control.Concurrent.MVar (newMVar)
+import ChuSQL.Core.Model (Value (..))
+import ChuSQL.Core.Protocol (QueryResult (..), queryResultJson)
 import Data.Aeson (decode)
 import qualified Data.Aeson as A
-import qualified Data.ByteString as BS
 import qualified Data.ByteString.Lazy as BL
-import Data.Either (isLeft, isRight)
-import Data.List (nub, sort)
 import qualified Data.Text as T
 import Data.Text.Encoding (encodeUtf8)
 import Test.Hspec
 
--- chusql-cli 测试：输出格式、交互层纯逻辑与共享账号会话。
+-- chusql-cli 测试：只覆盖本前端的纯逻辑（输出格式、语句缓冲与元命令）。
 
+-- | 测试入口
 main :: IO ()
 main = hspec spec
 
+-- | 全部测试用例
 spec :: Spec
 spec = do
     formatSpec
     scriptSpec
-    sessionSpec
-    roleSpec
 
+-- | 输出格式的用例
 formatSpec :: Spec
 formatSpec = describe "CLI: output formats" $ do
     it "renders a boxed table and marks NULL" $
@@ -79,6 +58,7 @@ formatSpec = describe "CLI: output formats" $ do
         parseFormat "csv" `shouldBe` Just FormatCsv
         parseFormat "xml" `shouldBe` Nothing
 
+-- | 语句缓冲与元命令的用例
 scriptSpec :: Spec
 scriptSpec = do
     describe "CLI: statement buffering" $ do
@@ -117,114 +97,6 @@ scriptSpec = do
             parseMeta "\\nope" `shouldBe` Just (MetaUnknown "nope")
             parseMeta "\\f xml" `shouldBe` Just (MetaUnknown "format")
 
-sessionSpec :: Spec
-sessionSpec = describe "CLI: session over the shared account service" $ do
-    it "signs in as the configured administrator and refuses a wrong password" $ do
-        session <- cliSession
-        authenticateSession session "admin" "wrong-password" >>= \answer -> isLeft answer `shouldBe` True
-        authenticateSession session "admin" "s3cret" >>= \answer -> isRight answer `shouldBe` True
-    it "runs SQL straight through the engine" $ do
-        session <- cliSession
-        signInRoot session
-        result <- runStatement session "SELECT id, name FROM users ORDER BY id LIMIT 1"
-        fmap qrColumns result `shouldBe` Right ["id", "name"]
-        fmap qrRowCount result `shouldBe` Right 1
-    it "starts with nothing selected, lists what exists and refuses an unknown USE" $ do
-        session <- cliSession
-        authenticateSession session "admin" "s3cret" >>= (`shouldBe` Right ())
-        sessionDatabase session >>= (`shouldBe` "")
-        runStatement session "SELECT id FROM users" >>= \answer -> answer `shouldBe` Left "no database selected"
-        listed <- databases session
-        listed `shouldBe` Right ["test", "system"]
-        runStatement session "USE missing" >>= \answer -> isLeft answer `shouldBe` True
-        sessionDatabase session >>= (`shouldBe` "")
-        runStatement session "USE test" >>= \answer -> isRight answer `shouldBe` True
-        sessionDatabase session >>= (`shouldBe` "test")
-    it "keeps accounts on the same store and system administrator-only" $ do
-        session <- cliSession
-        signInRoot session
-        runStatement session "CREATE USER alice IDENTIFIED BY 'alice-password-1'" >>= \answer -> isRight answer `shouldBe` True
-        authenticateSession session "alice" "alice-password-1" >>= \answer -> isRight answer `shouldBe` True
-        sessionIsAdmin session >>= (`shouldBe` False)
-        switchDatabase session "system" >>= \answer -> isLeft answer `shouldBe` True
-        runStatement session "DROP USER admin" >>= \answer -> isLeft answer `shouldBe` True
-
-roleSpec :: Spec
-roleSpec = describe "CLI: roles and grants over the shared privilege service" $ do
-    it "runs role statements as the administrator and refuses them for anyone else" $ do
-        session <- cliSession
-        signInRoot session
-        created <- runStatement session "CREATE ROLE analyst"
-        isRight created `shouldBe` True
-        duplicate <- runStatement session "CREATE ROLE analyst"
-        duplicate `shouldBe` Left "role already exists: analyst"
-        granted <- runStatement session "GRANT SELECT ON users TO analyst"
-        isRight granted `shouldBe` True
-        tallied <- runStatement session "GRANT SELECT, INSERT, UPDATE, DELETE ON users TO analyst"
-        isRight tallied `shouldBe` True
-        views <- roleViews session
-        fmap (map roleName) views `shouldBe` Right ["analyst"]
-        fmap (sort . nub . concatMap (map grantPrivilege . roleGrants)) views `shouldBe` Right ["delete", "insert", "select", "update"]
-        fmap (sort . nub . concatMap (map grantObject . roleGrants)) views `shouldBe` Right ["test.users"]
-        unknown <- runStatement session "GRANT SELECT ON users TO nobody"
-        unknown `shouldBe` Left "unknown role: nobody"
-        dropped <- runStatement session "DROP ROLE analyst"
-        isRight dropped `shouldBe` True
-        missing <- runStatement session "GRANT SELECT ON users TO analyst"
-        missing `shouldBe` Left "unknown role: analyst"
-    it "an ordinary account only gets what a grant allows" $ do
-        session <- cliSession
-        signInRoot session
-        runStatement session "CREATE TABLE secrets (id INT)" >>= \answer -> isRight answer `shouldBe` True
-        runStatement session "CREATE ROLE reader" >>= \answer -> isRight answer `shouldBe` True
-        runStatement session "GRANT SELECT ON users TO reader" >>= \answer -> isRight answer `shouldBe` True
-        runStatement session "CREATE USER bob IDENTIFIED BY 'bob-password-1'" >>= \answer -> isRight answer `shouldBe` True
-        runStatement session "GRANT reader TO bob" >>= \answer -> isRight answer `shouldBe` True
-        authenticateSession session "bob" "bob-password-1" >>= \answer -> isRight answer `shouldBe` True
-        granted <- runStatement session "SELECT id, name FROM users"
-        fmap qrRowCount granted `shouldBe` Right 3
-        refused <- runStatement session "SELECT id FROM secrets"
-        refused `shouldBe` Left "permission denied: SELECT ON secrets"
-        write <- runStatement session "INSERT INTO users (id, name) VALUES (4, 'four')"
-        write `shouldBe` Left "permission denied: INSERT ON users"
-        admin <- runStatement session "CREATE ROLE other"
-        admin `shouldBe` Left "administrator required"
-        listed <- catalog session
-        fmap (map tiTable) listed `shouldBe` Right ["users"]
-        hidden <- roleViews session
-        hidden `shouldBe` Left "administrator required"
-    it "revoking the membership closes the door again" $ do
-        session <- cliSession
-        signInRoot session
-        runStatement session "CREATE ROLE guest" >>= \answer -> isRight answer `shouldBe` True
-        runStatement session "GRANT SELECT ON users TO guest" >>= \answer -> isRight answer `shouldBe` True
-        runStatement session "CREATE USER carol IDENTIFIED BY 'carol-password-1'" >>= \answer -> isRight answer `shouldBe` True
-        runStatement session "GRANT guest TO carol" >>= \answer -> isRight answer `shouldBe` True
-        roster <- roleViews session
-        fmap (concatMap roleMembers) roster `shouldBe` Right ["carol"]
-        authenticateSession session "carol" "carol-password-1" >>= \answer -> isRight answer `shouldBe` True
-        runStatement session "SELECT id FROM users" >>= \answer -> isRight answer `shouldBe` True
-        signInRoot session
-        runStatement session "REVOKE guest FROM carol" >>= \answer -> isRight answer `shouldBe` True
-        authenticateSession session "carol" "carol-password-1" >>= \answer -> isRight answer `shouldBe` True
-        refused <- runStatement session "SELECT id FROM users"
-        refused `shouldBe` Left "permission denied: SELECT ON users"
-
-cliSession :: IO Session
-cliSession = do
-    db <- newMVar testDb
-    newSession (memoryBackend testDatabaseName db) testCredential "chusql-test-missing.settings.json"
-
--- | 夹具库名：服务不再有默认库，这个库要显式选
-testDatabaseName :: String
-testDatabaseName = "test"
-
--- | 登录管理员并选中夹具库（未选库时连表名都解析不了）
-signInRoot :: Session -> Expectation
-signInRoot session = do
-    authenticateSession session "admin" "s3cret" >>= (`shouldBe` Right ())
-    switchDatabase session (T.pack testDatabaseName) >>= (`shouldBe` Right ())
-
 sampleResult :: QueryResult
 sampleResult =
     QueryResult
@@ -234,18 +106,3 @@ sampleResult =
         , qrTruncated = False
         , qrDatabase = Nothing
         }
-
--- | 测试库：三行 users
-testDb :: Database
-testDb =
-    [ ( "users"
-      , Table
-            "users"
-            [("id", TInt), ("name", TStr)]
-            [[("id", VInt i), ("name", VStr ("user" ++ show i))] | i <- [1 .. 3]]
-      )
-    ]
-
--- | 测试账号：迭代次数压低（跑得快），口令 `s3cret`
-testCredential :: Credential
-testCredential = Credential "admin" (hashPasswordWith 1000 (BS.replicate 16 7) "s3cret")
diff --git a/chusql-engine/app/Main.hs b/chusql-core/engine/app/Main.hs
similarity index 85%
rename from chusql-engine/app/Main.hs
rename to chusql-core/engine/app/Main.hs
index 1928ef2..054bdf8 100644
--- a/chusql-engine/app/Main.hs
+++ b/chusql-core/engine/app/Main.hs
@@ -1,14 +1,14 @@
 module Main where
 
-import ChuSQL.Algebra.Op (renderPlan)
-import ChuSQL.Algebra.Optimize (optimize)
-import ChuSQL.Algebra.Planner (translate)
-import ChuSQL.Engine
-import ChuSQL.Model
-import ChuSQL.Syntax.AST
-import ChuSQL.Syntax.Parser
+import ChuSQL.Core.Engine.Algebra.Op (renderPlan)
+import ChuSQL.Core.Engine.Algebra.Optimize (optimize)
+import ChuSQL.Core.Engine.Algebra.Planner (translate)
+import ChuSQL.Core.Engine
+import ChuSQL.Core.Model
+import ChuSQL.Core.Engine.Syntax.AST
+import ChuSQL.Core.Engine.Syntax.Parser
 
--- 命令行演示：跑几条语句，打印结果与优化前后的计划。
+-- 命令行演示入口：跑几条语句并打印结果与优化前后的计划。
 
 users :: Table
 users =
@@ -37,7 +37,7 @@ orders =
 db :: Database
 db = [("users", users), ("orders", orders)]
 
--- | 演示入口
+-- | 跑演示语句，打印结果与优化前后的计划
 main :: IO ()
 main = do
     putStrLn "==================== Engine ====================="
diff --git a/chusql-core/engine/chusql-core-engine.cabal b/chusql-core/engine/chusql-core-engine.cabal
new file mode 100644
index 0000000..4c64516
--- /dev/null
+++ b/chusql-core/engine/chusql-core-engine.cabal
@@ -0,0 +1,70 @@
+cabal-version: 2.4
+
+name:           chusql-core-engine
+version:        1.0.0
+synopsis:       ChuSQL 执行引擎：SQL 词法与语法分析、表达式求值
+description:    ChuSQL 服务端执行引擎。负责 SQL 词法分析与 AST 构建、
+                WHERE 条件表达式求值、关系代数运算与内存表管理。
+build-type:     Simple
+
+library
+    hs-source-dirs:   src
+    exposed-modules:  ChuSQL.Core.Engine.Algebra.Eval
+                      ChuSQL.Core.Engine.Algebra.Expr
+                      ChuSQL.Core.Engine.Algebra.Op
+                      ChuSQL.Core.Engine.Algebra.Optimize
+                      ChuSQL.Core.Engine.Algebra.Planner
+                      ChuSQL.Core.Engine.Algebra.Sort
+                      ChuSQL.Core.Engine
+                      ChuSQL.Core.Engine.Semantic
+                      ChuSQL.Core.Engine.Storage
+                      ChuSQL.Core.Engine.Storage.FFI
+                      ChuSQL.Core.Engine.Storage.IPC
+                      ChuSQL.Core.Engine.Storage.Memory
+                      ChuSQL.Core.Engine.Syntax.AST
+                      ChuSQL.Core.Engine.Syntax.Parser
+    build-depends:    base >= 4.14 && < 5
+                    , aeson
+                    , bytestring
+                    , hashable
+                    , chusql-core-model
+                    , megaparsec
+                    , parser-combinators
+                    , scientific
+                    , text
+                    , unordered-containers
+    extra-libraries:  chusql_core_storage
+    -- 运行期找 libchusql_core_storage.so：$ORIGIN 让二进制与动态库同目录即可
+    if os(linux)
+        ld-options: -Wl,-rpath,$ORIGIN
+    if os(osx)
+        ld-options: -Wl,-rpath,@loader_path
+    default-language: Haskell2010
+    ghc-options:      -Wall
+
+executable chusql-core-engine
+    main-is:          Main.hs
+    hs-source-dirs:   app
+    build-depends:    base
+                    , chusql-core-engine
+                    , chusql-core-model
+    default-language: Haskell2010
+    ghc-options:      -Wall
+    -- 运行期找 libchusql_core_storage.so：$ORIGIN 让二进制与动态库同目录即可
+    if os(linux)
+        ld-options: -Wl,-rpath,$ORIGIN
+    if os(osx)
+        ld-options: -Wl,-rpath,@loader_path
+
+test-suite chusql-core-engine-test
+    type:             exitcode-stdio-1.0
+    main-is:          Spec.hs
+    hs-source-dirs:   test
+    build-depends:    base
+                    , chusql-core-engine
+                    , chusql-core-model
+                    , directory
+                    , filepath
+                    , hspec
+    default-language: Haskell2010
+    ghc-options:      -Wall
diff --git a/chusql-engine/src/ChuSQL/Engine.hs b/chusql-core/engine/src/ChuSQL/Core/Engine.hs
similarity index 91%
rename from chusql-engine/src/ChuSQL/Engine.hs
rename to chusql-core/engine/src/ChuSQL/Core/Engine.hs
index c37af82..504c3b2 100644
--- a/chusql-engine/src/ChuSQL/Engine.hs
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine.hs
@@ -1,18 +1,18 @@
-module ChuSQL.Engine (runStatement, runStatementM, rowsOf) where
+module ChuSQL.Core.Engine (runStatement, runStatementM, rowsOf) where
 
-import ChuSQL.Algebra.Eval (evalCondForRowM, evalExprM, evalRelOpM)
-import ChuSQL.Algebra.Expr (evalCondForRow, evalExpr)
-import ChuSQL.Algebra.Optimize (optimize)
-import ChuSQL.Algebra.Planner (translate)
-import ChuSQL.Model
-import ChuSQL.Semantic (prepare)
-import ChuSQL.Storage (MonadStorage (..))
-import ChuSQL.Storage.Memory (MemoryStorage (runMemoryStorage))
-import ChuSQL.Syntax.AST
-import ChuSQL.Syntax.Parser (parseExpression)
+import ChuSQL.Core.Engine.Algebra.Eval (evalCondForRowM, evalExprM, evalRelOpM)
+import ChuSQL.Core.Engine.Algebra.Expr (evalCondForRow, evalExpr)
+import ChuSQL.Core.Engine.Algebra.Optimize (optimize)
+import ChuSQL.Core.Engine.Algebra.Planner (translate)
+import ChuSQL.Core.Model
+import ChuSQL.Core.Engine.Semantic (prepare)
+import ChuSQL.Core.Engine.Storage (MonadStorage (..))
+import ChuSQL.Core.Engine.Storage.Memory (MemoryStorage (runMemoryStorage))
+import ChuSQL.Core.Engine.Syntax.AST
+import ChuSQL.Core.Engine.Syntax.Parser (parseExpression)
 import Data.Maybe (mapMaybe)
 
--- 引擎入口：语义检查 + 分发执行，以及内存实现与泛型版本。
+-- 引擎入口：检查语义、按语句分发执行，另有内存实现与泛型版本。
 
 -- | 跑一条语句（内存实现）
 runStatement :: Database -> Statement -> Either String (Database, [Row])
@@ -74,6 +74,7 @@ runStatementUncheckedM db (Delete tbl mWhere) = do
                             result <- replaceAll tbl kept
                             pure (result >> Right [])
   where
+    -- | 取行里的整数 id，取不到就报错
     rowId :: Row -> Either String Int
     rowId r = case lookup "id" r of
         Just (VInt k) -> Right k
@@ -137,7 +138,9 @@ existingRows tbl table
     | needsRows table = scan tbl
     | otherwise = pure (Right [])
   where
+    -- | 这一表有没有要判约束的列
     needsRows t = any (constraintColumn . snd) (tableCols t)
+    -- | 这一列带不带要判的约束
     constraintColumn c = columnAutoIncrement c || columnUnique c || columnPrimaryKey c
 
 -- | 插一行：补齐缺列、给自增值、收类型、查约束
@@ -150,6 +153,7 @@ buildRows table current cols rows = do
             let auto = autoColumn table
             go auto (autoStart auto current) values []
   where
+    -- | 逐行构造，最后统一查一遍约束
     go _ _ [] acc = do
         let built = reverse acc
         mapM_ (runChecks table) built
@@ -165,11 +169,13 @@ buildRow :: Table -> Maybe (String, Column) -> [String] -> Int -> [Value] -> Eit
 buildRow table auto cols counter vals = go (tableCols table) counter []
   where
     provided = zip cols vals
+    -- | 按列定义逐列补值
     go [] c acc = Right (reverse acc, c)
     go ((name, col) : rest) c acc = do
         (v, c') <- pick name col c
         v' <- coerceValue (columnType col) v
         go rest c' ((name, v') : acc)
+    -- | 决定这一列取什么值
     pick name col c
         | Just (autoName, _) <- auto
         , name == autoName
@@ -178,11 +184,13 @@ buildRow table auto cols counter vals = go (tableCols table) counter []
         | Just d <- columnDefault col = Right (d, c)
         | columnNullable col = Right (VNull, c)
         | otherwise = Left ("INSERT: column " ++ name ++ " is NOT NULL and has no default")
+    -- | 自增值跟着已有的值往前推
     bump name _ c v
         | Just (autoName, _) <- auto
         , name == autoName = max (c + 1) (valueInt v + 1)
         | otherwise = c
 
+-- | 取自增值，不是整数就当 0
 valueInt :: Value -> Int
 valueInt (VInt n) = n
 valueInt _ = 0
@@ -204,6 +212,7 @@ autoStart (Just (name, _)) rows = case [n | r <- rows, Just (VInt n) <- [lookup
 runChecks :: Table -> Row -> Either String ()
 runChecks table row = mapM_ check (tableCols table)
   where
+    -- | 查这一列的 CHECK
     check (name, col) = case columnCheck col of
         Nothing -> Right ()
         Just text -> case parseExpression text of
@@ -213,6 +222,7 @@ runChecks table row = mapM_ check (tableCols table)
                 Right True -> Right ()
                 Right False -> Left ("CHECK on " ++ name ++ " failed")
 
+-- | 只取第一行（报错提示用）
 firstLine :: String -> String
 firstLine = takeWhile (/= '\n')
 
@@ -220,6 +230,7 @@ firstLine = takeWhile (/= '\n')
 enforceNotNull :: [(String, Column)] -> [Row] -> Either String ()
 enforceNotNull cols rows = mapM_ check cols
   where
+    -- | 查这一列的 NOT NULL
     check (name, col)
         | columnNullable col = Right ()
         | any (\r -> lookup name r == Just VNull) rows = Left ("NOT NULL: column " ++ name ++ " cannot be null")
@@ -230,8 +241,11 @@ enforceUnique :: [(String, Column)] -> [Row] -> Either String ()
 enforceUnique cols rows = mapM_ check targets
   where
     targets = [(n, c) | (n, c) <- cols, columnUnique c || columnPrimaryKey c]
+    -- | 查这一列有没有重复值
     check (name, _) = go name [] (mapMaybe (lookup name) rows)
+    -- | 逐个值比过去
     go _ _ [] = Right ()
+    -- | NULL 不算冲突，跳过
     go name seen (VNull : rest) = go name seen rest
     go name seen (v : rest)
         | v `elem` seen = Left ("UNIQUE: duplicate value in column " ++ name)
@@ -271,6 +285,7 @@ setColumn col v = map (\(k, val) -> if k == col then (k, v) else (k, val))
 splitByConditionM :: (MonadStorage m) => Database -> Maybe Expr -> [Row] -> m (Either String ([Row], [Row]))
 splitByConditionM db cond = go [] []
   where
+    -- | 逐行分流
     go doomed kept [] = pure (Right (reverse doomed, reverse kept))
     go doomed kept (r : rs) = do
         hit <- case cond of
@@ -299,6 +314,7 @@ alterTable db tbl change = case lookupTable db tbl of
                     result <- replaceSchema tbl cols newRows
                     pure (result >> Right [])
   where
+    -- | 改完再统一查一遍约束
     checkAltered (cols, rows) = do
         let table = Table tbl cols rows
         mapM_ (runChecks table) rows
@@ -306,7 +322,7 @@ alterTable db tbl change = case lookupTable db tbl of
         enforceUnique cols rows
         Right (cols, rows)
 
--- | ADD COLUMN：老行补默认值或 NULL，自增列从 1 开始
+-- | ADD COLUMN：老行补默认值或 NULL
 addColumnTo :: (String, Column) -> [(String, Column)] -> [Row] -> Either String ([(String, Column)], [Row])
 addColumnTo (name, col) cols rows
     | name `elem` map fst cols = Left ("ADD COLUMN: column already exists: " ++ name)
@@ -338,6 +354,7 @@ retypeColumn col ty cols rows
         rows' <- mapM convert rows
         Right (map (\entry@(n, c) -> if n == col then (n, c{columnType = ty}) else entry) cols, rows')
   where
+    -- | 把这一列的老值收进新类型
     convert row = case lookup col row of
         Nothing -> Right row
         Just v -> do
diff --git a/chusql-engine/src/ChuSQL/Algebra/Eval.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Eval.hs
similarity index 90%
rename from chusql-engine/src/ChuSQL/Algebra/Eval.hs
rename to chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Eval.hs
index 7f73df3..00504b1 100644
--- a/chusql-engine/src/ChuSQL/Algebra/Eval.hs
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Eval.hs
@@ -1,21 +1,20 @@
-module ChuSQL.Algebra.Eval (evalRelOp, evalRelOpM, evalExprM, evalCondForRowM) where
+module ChuSQL.Core.Engine.Algebra.Eval (evalRelOp, evalRelOpM, evalExprM, evalCondForRowM) where
 
-import ChuSQL.Algebra.Expr (evalCondForRow, evalExpr)
-import ChuSQL.Algebra.Optimize (optimize, relOpCols)
-import ChuSQL.Algebra.Op
-import ChuSQL.Algebra.Planner (translate)
-import ChuSQL.Algebra.Sort (compareValue, sortRows)
-import ChuSQL.Model
-import ChuSQL.Storage (IndexResult (..), MonadStorage (..))
-import ChuSQL.Storage.Memory (runMemoryStorage)
-import ChuSQL.Syntax.AST (Expr (..), JoinKind (..), Subquery (..))
+import ChuSQL.Core.Engine.Algebra.Expr (evalCondForRow, evalExpr)
+import ChuSQL.Core.Engine.Algebra.Optimize (optimize, relOpCols)
+import ChuSQL.Core.Engine.Algebra.Op
+import ChuSQL.Core.Engine.Algebra.Planner (translate)
+import ChuSQL.Core.Engine.Algebra.Sort (compareValue, sortRows)
+import ChuSQL.Core.Model
+import ChuSQL.Core.Engine.Storage (IndexResult (..), MonadStorage (..))
+import ChuSQL.Core.Engine.Storage.Memory (runMemoryStorage)
+import ChuSQL.Core.Engine.Syntax.AST (Expr (..), JoinKind (..), Subquery (..))
 import Control.Monad (filterM, foldM)
 import qualified Data.HashMap.Strict as HM
 
--- 执行：按算子树算出结果行（Scan 阶段会加别名前缀）。
--- 外层行 outer 给相关子查询用：子查询里的列先在本层行里找，找不到再落到外层行。
+-- 执行：按算子树算出结果行，外层行供相关子查询引用。
 
--- | 只保留清单里的列，顺序按清单（SELECT 的列序就是结果的列序）
+-- | 只保留清单里的列，顺序照清单
 project :: [String] -> Row -> Row
 project ["*"] row = row
 project cs row = [(c, v) | c <- cs, Just v <- [lookup c row]]
@@ -24,6 +23,7 @@ project cs row = [(c, v) | c <- cs, Just v <- [lookup c row]]
 addPrefix :: Maybe String -> Row -> Row
 addPrefix mAlias = map (\(k, v) -> (qualify mAlias k, v))
 
+-- | 给一批行加别名前缀
 prefixRows :: Maybe String -> [Row] -> [Row]
 prefixRows mAlias = map (addPrefix mAlias)
 
@@ -48,6 +48,7 @@ rangeCondition mAlias col lo hi = case (lo, hi) of
     (Nothing, Nothing) -> LitBool True
   where
     c = Col (qualify mAlias col)
+    -- | 一个端点的比较，闭端再加上等号
     bound rel (v, inclusive)
         | inclusive = Or (rel c (valueLiteral v)) (Eq c (valueLiteral v))
         | otherwise = rel c (valueLiteral v)
@@ -57,8 +58,7 @@ rowsCols :: [Row] -> [String]
 rowsCols (r : _) = map fst r
 rowsCols [] = []
 
--- | 参与等值匹配的键：NULL 不参与匹配，整数值的浮点归一到整数
--- （嵌套循环走 compareValues，哈希要对齐它）
+-- | 参与等值匹配的键：NULL 不参与，整数值的浮点归一
 joinKey :: Value -> Maybe Value
 joinKey VNull = Nothing
 joinKey (VFloat d)
@@ -70,9 +70,11 @@ joinKey (VFloat d)
     rounded = round d :: Integer
 joinKey v = Just v
 
+-- | 取一行的连接键
 joinKeyOf :: String -> Row -> Maybe Value
 joinKeyOf c row = lookup c row >>= joinKey
 
+-- | 等值连接的两侧列名
 data EquiKeys = EquiKeys
     { ekLeft :: String
     , ekRight :: String
@@ -85,7 +87,7 @@ equiKeys lcols rcols (Eq (Col a) (Col b))
     | a /= b, b `elem` lcols, a `elem` rcols = Just (EquiKeys b a)
 equiKeys _ _ _ = Nothing
 
--- | 连接：能认出等值键就走哈希，否则退回嵌套循环；左连接没配上的左行补 NULL
+-- | 连接两批行：等值键走哈希，否则嵌套循环
 joinRowsIn ::
     (MonadStorage m) =>
     Database ->
@@ -104,7 +106,7 @@ joinRowsIn db outer kind rcols cond lrows rrows =
     -- 右表为空时行上没有列名，用算子推导出来的列名补 NULL
     ncols = if null rrows then rcols else rowsCols rrows
 
--- | 左连接里配不上的左行补右表 NULL；内连接里没有匹配就是没行
+-- | 左连接配不上的左行补 NULL，内连接丢弃
 unmatched :: JoinKind -> Row -> [String] -> [Row]
 unmatched InnerJoin _ _ = []
 unmatched LeftJoin l cols = [l ++ [(c, VNull) | c <- cols]]
@@ -114,6 +116,7 @@ hashJoin :: JoinKind -> EquiKeys -> [String] -> [Row] -> [Row] -> [Row]
 hashJoin kind ks ncols lrows rrows = concatMap probe lrows
   where
     buckets = HM.fromListWith (flip (++)) [(v, [r]) | r <- rrows, Just v <- [joinKeyOf (ekRight ks) r]]
+    -- | 拿左行的键去桶里找
     probe l =
         let miss = case kind of
                 InnerJoin -> []
@@ -138,6 +141,7 @@ filterPairsM ::
     m (Either String [Row])
 filterPairsM db outer kind ncols cond lrows rrows = go lrows []
   where
+    -- | 逐左行配对，左连接没配上就补 NULL
     go [] acc = pure (Right (reverse acc))
     go (l : ls) acc = do
         hits <- keep l rrows []
@@ -148,6 +152,7 @@ filterPairsM db outer kind ncols cond lrows rrows = go lrows []
                         (LeftJoin, []) -> [l ++ nullRow]
                         _ -> hs
                 go ls (reverse hs' ++ acc)
+    -- | 拿一行右行去比条件
     keep _ [] acc = pure (Right (reverse acc))
     keep l (r : rs) acc = do
         ok <- evalCondForRowM db cond (l ++ r ++ outer)
@@ -157,7 +162,7 @@ filterPairsM db outer kind ncols cond lrows rrows = go lrows []
             Right False -> keep l rs acc
     nullRow = [(c, VNull) | c <- ncols]
 
--- | 索引连接：右表是裸 Scan 时逐左行点查，返回 Nothing 表示该走通用路径
+-- | 索引连接：右表是裸 Scan 时逐左行点查
 probeIndexJoin ::
     (MonadStorage m) =>
     Database ->
@@ -183,8 +188,7 @@ probeIndexJoin db outer kind mAlias t ks rcols cond l = case lookup (ekLeft ks)
                     pairs <- joinRowsIn db outer kind rcols cond [l] (prefixRows mAlias rows)
                     pure (fmap Just pairs)
 
--- | 索引按值的相等匹配，而数值比较会把 2 和 2.0 看成相等，
--- 所以只有非浮点列 + 非浮点键才敢用索引，保证优化不改变结果语义
+-- | 列与键都不是浮点时才敢用索引
 indexSafe :: Database -> String -> String -> Value -> Bool
 indexSafe db t col k = case lookupTable db t of
     Left _ -> False
@@ -192,12 +196,14 @@ indexSafe db t col k = case lookupTable db t of
         Nothing -> False
         Just c -> not (floatType (columnType c)) && not (floatValue k)
 
+-- | 是不是浮点列类型
 floatType :: ColumnType -> Bool
 floatType CFloat = True
 floatType CDouble = True
 floatType (CDecimal _ _) = True
 floatType _ = False
 
+-- | 是不是浮点值
 floatValue :: Value -> Bool
 floatValue (VFloat _) = True
 floatValue _ = False
@@ -206,12 +212,14 @@ floatValue _ = False
 groupKey :: [String] -> Row -> Either String [Value]
 groupKey keys row = mapM get keys
   where
+    -- | 取这一列的分组值
     get c = maybe (Left ("unknown column: " ++ c)) Right (lookup c row)
 
 -- | 按分组键把行分组，保留分组首次出现的顺序
 groupRows :: [String] -> [Row] -> Either String [([Value], [Row])]
 groupRows keys rows = go rows (HM.empty, [])
   where
+    -- | 逐行塞进对应分组，并记住分组首次出现的顺序
     go [] (acc, order) = Right [(k, reverse (HM.lookupDefault [] k acc)) | k <- reverse order]
     go (r : rs) (acc, order) = do
         k <- groupKey keys r
@@ -269,7 +277,9 @@ evalAgg outer agg rows = case agg of
     MaxOf e -> valuesOf outer e rows >>= extremeOf higher . nonNull
     _ -> Left "only COUNT, SUM, AVG, MIN and MAX can be aggregated"
   where
+    -- | 取更小的那个
     lower a b = if compareValue b a == LT then b else a
+    -- | 取更大的那个
     higher a b = if compareValue b a == GT then b else a
 
 -- | 一组的输出行：分组列 + 各聚合值
@@ -289,6 +299,7 @@ evalAggregate outer keys aggs rows = do
 filterRowsM :: (Monad m) => (Row -> m (Either String Bool)) -> [Row] -> m (Either String [Row])
 filterRowsM p = go []
   where
+    -- | 逐行留下通过条件的
     go acc [] = pure (Right (reverse acc))
     go acc (r : rs) = do
         keep <- p r
@@ -301,6 +312,7 @@ filterRowsM p = go []
 computeM :: (MonadStorage m) => Database -> Row -> [(String, Expr)] -> Row -> m (Either String Row)
 computeM db outer items row = go items []
   where
+    -- | 逐项求值并攒成一行
     go [] acc = pure (Right (reverse acc))
     go ((label, e) : rest) acc = do
         v <- evalExprM db e (row ++ outer)
@@ -375,6 +387,7 @@ substSubqueries db e env = case e of
     MaxOf a -> un MaxOf a
     _ -> pure (Right e)
   where
+    -- | 递归处理两个子表达式
     bin ctor a b = do
         ra <- substSubqueries db a env
         case ra of
@@ -382,6 +395,7 @@ substSubqueries db e env = case e of
             Right a' -> do
                 rb <- substSubqueries db b env
                 pure ((ctor a') <$> rb)
+    -- | 递归处理一个子表达式
     un ctor a = do
         ra <- substSubqueries db a env
         pure (ctor <$> ra)
diff --git a/chusql-engine/src/ChuSQL/Algebra/Expr.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Expr.hs
similarity index 92%
rename from chusql-engine/src/ChuSQL/Algebra/Expr.hs
rename to chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Expr.hs
index 5ab1de0..7354e0c 100644
--- a/chusql-engine/src/ChuSQL/Algebra/Expr.hs
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Expr.hs
@@ -1,7 +1,7 @@
-module ChuSQL.Algebra.Expr (evalExpr, evalCondForRow, colsInExpr, aggregatesIn, hasAggregate, bareColumns, hasSubquery, inValues, threeValuedNot) where
+module ChuSQL.Core.Engine.Algebra.Expr (evalExpr, evalCondForRow, colsInExpr, aggregatesIn, hasAggregate, bareColumns, hasSubquery, inValues, threeValuedNot) where
 
-import ChuSQL.Model
-import ChuSQL.Syntax.AST
+import ChuSQL.Core.Model
+import ChuSQL.Core.Engine.Syntax.AST
 import Control.Monad (join)
 
 -- 表达式求值：三值逻辑，NULL 参与运算结果仍是 NULL。
@@ -54,7 +54,7 @@ evalExpr agg _ = Left ("aggregate functions are not allowed here: " ++ show agg)
 subqueryNeedsDatabase :: String
 subqueryNeedsDatabase = "subquery needs a database to run"
 
--- | IN 的三值逻辑：命中为真，没命中但碰到 NULL 就给 NULL，否则为假
+-- | IN 三值逻辑：命中为真，碰 NULL 得 NULL
 inValues :: Value -> [Value] -> Either String Value
 inValues VNull _ = Right VNull
 inValues v vs = do
@@ -121,6 +121,7 @@ hasSubquery e = case e of
     MaxOf a -> hasSubquery a
     _ -> False
   where
+    -- | 两个子表达式里任意一个有
     both a b = hasSubquery a || hasSubquery b
 
 -- | 表达式里出现的聚合调用（按出现顺序）
@@ -146,6 +147,7 @@ aggregatesIn e = case e of
     IsNotNull a -> aggregatesIn a
     _ -> []
   where
+    -- | 两个子表达式的聚合拼起来
     both a b = aggregatesIn a ++ aggregatesIn b
 
 -- | 表达式里有没有聚合调用
@@ -174,6 +176,7 @@ bareColumns e = case e of
     ExistsSub sq _ -> subqueryRefs sq
     _ -> []
   where
+    -- | 两个子表达式的裸列拼起来
     both a b = bareColumns a ++ bareColumns b
 
 -- | 判断条件真假：只有 TRUE 通过，NULL 当作不通过
@@ -204,6 +207,7 @@ data Arith = Arith
 liftArith :: Arith -> Expr -> Expr -> Row -> Either String Value
 liftArith ops a b row = liftBinOp go a b row
   where
+    -- | NULL 出 NULL，整数配整数走整数算术
     go VNull _ = Right VNull
     go _ VNull = Right VNull
     go (VInt x) (VInt y) = VInt <$> arithInt ops x y
@@ -217,12 +221,15 @@ asDouble (VInt n) = Just (fromIntegral n)
 asDouble (VFloat d) = Just d
 asDouble _ = Nothing
 
+-- | 加法
 addArith :: Arith
 addArith = Arith (\x y -> Right (x + y)) (\x y -> Right (x + y))
 
+-- | 减法
 subArith :: Arith
 subArith = Arith (\x y -> Right (x - y)) (\x y -> Right (x - y))
 
+-- | 乘法
 mulArith :: Arith
 mulArith = Arith (\x y -> Right (x * y)) (\x y -> Right (x * y))
 
@@ -230,10 +237,12 @@ mulArith = Arith (\x y -> Right (x * y)) (\x y -> Right (x * y))
 divArith :: Arith
 divArith = Arith intDiv floatDiv
   where
+    -- | 整数除法：除零与溢出都报错
     intDiv _ 0 = Left "division by zero"
     intDiv x y
         | x == minBound && y == -1 = Left "integer division overflow"
         | otherwise = Right (x `quot` y)
+    -- | 浮点除法：不能除以零
     floatDiv _ 0 = Left "division by zero"
     floatDiv x y = Right (x / y)
 
@@ -246,6 +255,7 @@ liftCompare ::
     Either String Value
 liftCompare rel a b row = liftBinOp (compareValues rel) a b row
 
+-- | 比较两个值：NULL 给 NULL，其余按数、串、布尔比
 compareValues :: (Ordering -> Bool) -> Value -> Value -> Either String Value
 compareValues rel x y
     | x == VNull || y == VNull = Right VNull
@@ -263,6 +273,7 @@ liftBool ::
     Either String Value
 liftBool f = liftBinOp f
 
+-- | 逻辑与的三值真值表
 andValues :: Value -> Value -> Either String Value
 andValues (VBool False) _ = Right (VBool False)
 andValues _ (VBool False) = Right (VBool False)
@@ -272,6 +283,7 @@ andValues (VBool True) VNull = Right VNull
 andValues VNull VNull = Right VNull
 andValues _ _ = Left "type error: expected two booleans"
 
+-- | 逻辑或的三值真值表
 orValues :: Value -> Value -> Either String Value
 orValues (VBool True) _ = Right (VBool True)
 orValues _ (VBool True) = Right (VBool True)
diff --git a/chusql-engine/src/ChuSQL/Algebra/Op.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Op.hs
similarity index 87%
rename from chusql-engine/src/ChuSQL/Algebra/Op.hs
rename to chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Op.hs
index 2d95689..663776f 100644
--- a/chusql-engine/src/ChuSQL/Algebra/Op.hs
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Op.hs
@@ -1,9 +1,9 @@
-module ChuSQL.Algebra.Op (RelOp (..), renderPlan) where
+module ChuSQL.Core.Engine.Algebra.Op (RelOp (..), renderPlan) where
 
-import ChuSQL.Model (Value)
-import ChuSQL.Syntax.AST (Expr, JoinKind (..), SortDir)
+import ChuSQL.Core.Model (Value)
+import ChuSQL.Core.Engine.Syntax.AST (Expr, JoinKind (..), SortDir)
 
--- 关系代数算子，以及把算子树渲染成文本。
+-- 关系代数算子定义与算子树文本渲染。
 
 data RelOp
     = Scan (Maybe String) String (Maybe [String])
@@ -28,6 +28,7 @@ kindLabel LeftJoin = "LeftJoin"
 renderPlan :: RelOp -> String
 renderPlan = go 0
   where
+    -- | 按缩进渲染一个算子
     go ind op = case op of
         Scan a t cols -> pad ++ "Scan " ++ show a ++ " " ++ show t ++ maybe "" ((" columns=" ++) . show) cols
         Lookup _ t c k -> pad ++ "Lookup " ++ show t ++ "." ++ show c ++ " = " ++ show k
diff --git a/chusql-engine/src/ChuSQL/Algebra/Optimize.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Optimize.hs
similarity index 94%
rename from chusql-engine/src/ChuSQL/Algebra/Optimize.hs
rename to chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Optimize.hs
index 3593640..510fac3 100644
--- a/chusql-engine/src/ChuSQL/Algebra/Optimize.hs
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Optimize.hs
@@ -1,12 +1,12 @@
-module ChuSQL.Algebra.Optimize (optimize, pushProject, relOpCols) where
+module ChuSQL.Core.Engine.Algebra.Optimize (optimize, pushProject, relOpCols) where
 
-import ChuSQL.Algebra.Expr (colsInExpr, evalExpr)
-import ChuSQL.Algebra.Op (RelOp (..))
-import ChuSQL.Model
-import ChuSQL.Syntax.AST (Expr (..), JoinKind (..))
+import ChuSQL.Core.Engine.Algebra.Expr (colsInExpr, evalExpr)
+import ChuSQL.Core.Engine.Algebra.Op (RelOp (..))
+import ChuSQL.Core.Model
+import ChuSQL.Core.Engine.Syntax.AST (Expr (..), JoinKind (..))
 import Data.List (nub)
 
--- 查询优化：谓词下推 + 投影下推 + 常量折叠，跑到不动点。
+-- 查询优化：谓词下推、投影下推与常量折叠。
 
 -- | 算子会产出哪些列
 relOpCols :: Database -> RelOp -> [String]
@@ -48,6 +48,7 @@ combineConj (e : es) = Just (foldl And e es)
 partitionPred :: [String] -> [Expr] -> ([Expr], [Expr])
 partitionPred have = foldr pick ([], [])
   where
+    -- | 按列归属收到左边或右边
     pick e (yes, no)
         | colsInExpr e `isSubsetOf` have = (e : yes, no)
         | otherwise = (yes, e : no)
@@ -72,8 +73,7 @@ pushJoin db p l r c =
             Nothing -> joined
             Just p' -> Filter p' joined
 
--- | Filter 压在左连接上时，只把纯左表的谓词下推到左表；
--- 右表没配上会补 NULL，右表谓词不能提前算。
+-- | Filter 压在左连接上时只下推纯左表的谓词
 pushLeftJoin :: Database -> Expr -> RelOp -> RelOp -> Expr -> RelOp
 pushLeftJoin db p l r c =
     let (lPs, rest) = partitionPred (relOpCols db l) (splitConj p)
@@ -105,6 +105,7 @@ hasDivision e = case e of
     Or a b -> both a b
     _ -> False
   where
+    -- | 两个子表达式里任意一个有除法
     both a b = hasDivision a || hasDivision b
 
 -- | 检查子计划中可能报错的除法
@@ -216,6 +217,7 @@ rewriteNode db op = pushOne db op
 optimizeRelOp :: Database -> RelOp -> RelOp
 optimizeRelOp db = rewriteNode db . descend
   where
+    -- | 先递归处理子算子
     descend (Filter p x) = Filter p (optimizeRelOp db x)
     descend (Project cols x) = Project cols (optimizeRelOp db x)
     descend (Compute items x) = Compute items (optimizeRelOp db x)
diff --git a/chusql-engine/src/ChuSQL/Algebra/Planner.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Planner.hs
similarity index 92%
rename from chusql-engine/src/ChuSQL/Algebra/Planner.hs
rename to chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Planner.hs
index a5947ad..0777bd3 100644
--- a/chusql-engine/src/ChuSQL/Algebra/Planner.hs
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Planner.hs
@@ -1,8 +1,8 @@
-module ChuSQL.Algebra.Planner (translate) where
+module ChuSQL.Core.Engine.Algebra.Planner (translate) where
 
-import ChuSQL.Algebra.Expr (aggregatesIn)
-import ChuSQL.Algebra.Op
-import ChuSQL.Syntax.AST
+import ChuSQL.Core.Engine.Algebra.Expr (aggregatesIn)
+import ChuSQL.Core.Engine.Algebra.Op
+import ChuSQL.Core.Engine.Syntax.AST
 
 -- 计划生成：把语句翻译成算子树。
 
@@ -23,6 +23,7 @@ source fromC mWhere = case mWhere of
 nameAggs :: [(String, Expr)] -> [(String, Expr)]
 nameAggs items = go (1 :: Int) [] (concatMap (aggregatesIn . snd) items)
   where
+    -- | 逐个聚合起名，重复的不再起名
     go :: Int -> [(String, Expr)] -> [Expr] -> [(String, Expr)]
     go _ acc [] = reverse acc
     go n acc (e : es)
diff --git a/chusql-engine/src/ChuSQL/Algebra/Sort.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Sort.hs
similarity index 83%
rename from chusql-engine/src/ChuSQL/Algebra/Sort.hs
rename to chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Sort.hs
index af57849..c7a25bf 100644
--- a/chusql-engine/src/ChuSQL/Algebra/Sort.hs
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Algebra/Sort.hs
@@ -1,10 +1,10 @@
-module ChuSQL.Algebra.Sort (sortRows, compareValue) where
+module ChuSQL.Core.Engine.Algebra.Sort (sortRows, compareValue) where
 
-import ChuSQL.Model
-import ChuSQL.Syntax.AST
+import ChuSQL.Core.Model
+import ChuSQL.Core.Engine.Syntax.AST
 import Data.List (sortBy)
 
--- 排序：按多列排序，每列可升可降。
+-- 排序：按多列规格排出结果行，每列可升可降。
 
 -- | 反转比较结果
 flipOrdering :: Ordering -> Ordering
@@ -41,10 +41,12 @@ compareKeys ((_, dir) : rest) (a : as) (b : bs) =
         _ -> compareKeys rest as bs
 compareKeys _ _ _ = EQ
 
--- | 排序若干行（先取键再排，避免每次比较都查列）
+-- | 按排序规格排序若干行
 sortRows :: [(String, SortDir)] -> [Row] -> [Row]
 sortRows [] rows = rows
 sortRows spec rows = map snd (sortBy cmp (map decorate rows))
   where
+    -- | 取键并带上原行
     decorate row = (sortKey spec row, row)
+    -- | 比较两个带键的行
     cmp (k1, _) (k2, _) = compareKeys spec k1 k2
diff --git a/chusql-engine/src/ChuSQL/Semantic.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Semantic.hs
similarity index 95%
rename from chusql-engine/src/ChuSQL/Semantic.hs
rename to chusql-core/engine/src/ChuSQL/Core/Engine/Semantic.hs
index e228259..96511ce 100644
--- a/chusql-engine/src/ChuSQL/Semantic.hs
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Semantic.hs
@@ -1,9 +1,9 @@
-module ChuSQL.Semantic (check, prepare) where
+module ChuSQL.Core.Engine.Semantic (check, prepare) where
 
-import ChuSQL.Algebra.Expr (bareColumns, colsInExpr, hasAggregate)
-import ChuSQL.Model
-import ChuSQL.Syntax.AST
-import ChuSQL.Syntax.Parser (parseExpression)
+import ChuSQL.Core.Engine.Algebra.Expr (bareColumns, colsInExpr, hasAggregate)
+import ChuSQL.Core.Model
+import ChuSQL.Core.Engine.Syntax.AST
+import ChuSQL.Core.Engine.Syntax.Parser (parseExpression)
 import Data.Char (isAlphaNum, isAscii, toLower)
 import Data.List (intercalate, isInfixOf, isPrefixOf, nub)
 import Data.Maybe (fromMaybe)
@@ -22,8 +22,7 @@ prefixColumns mAlias cols = [(prefix ++ c, ty) | (c, ty) <- cols]
   where
     prefix = maybe "" (++ ".") mAlias
 
--- | 检查期的作用域：本层优先，外层兜底。
--- 不能把两层平铺成一个列表：同名裸列会出现两次，被误报成 ambiguous。
+-- | 检查期的作用域：本层优先，外层兜底
 data Scope = Scope
     { scopeInner :: [(String, Column)]
     , scopeOuter :: [(String, Column)]
@@ -39,7 +38,7 @@ scopeAt place scope c
             | "ambiguous column:" `isInfixOf` err -> Left err
             | otherwise -> columnAt place (scopeOuter scope) c
 
--- | 收集 FROM 能提供的列；outer 是外层作用域，给 ON 里的相关子查询用
+-- | 收集 FROM 能提供的列，含外层作用域
 checkFrom :: Database -> [(String, Column)] -> FromClause -> Either String [(String, Column)]
 checkFrom _ _ FromUnit = Right []
 checkFrom db _ (FromTable mAlias tbl) = do
@@ -52,11 +51,11 @@ checkFrom db outer (FromJoin _ left mAlias tbl cond) = do
     checkBool db "ON" (Scope env outer) cond
     Right env
 
--- | 本层作用域优先：外层已有的同名键不再重复堆进来（否则同一个键被数两次，误报 ambiguous）
+-- | 合并两层列，本层优先且不重复
 scopedEnv :: [(String, Column)] -> [(String, Column)] -> [(String, Column)]
 scopedEnv env outer = env ++ [o | o <- outer, o `notElem` env]
 
--- | 作用域摊平成一层（只用于继续往外传，查找仍走 scopeAt 的本层优先）
+-- | 把作用域摊平成一层的列清单
 scopeFlat :: Scope -> [(String, Column)]
 scopeFlat scope = scopedEnv (scopeInner scope) (scopeOuter scope)
 
@@ -73,7 +72,7 @@ missingColumn place c env =
 checkColumns :: String -> Scope -> [String] -> Either String ()
 checkColumns place env = mapM_ (\c -> if c == allColumns then Right () else () <$ scopeAt place env c)
 
--- | 保留子句名与可用列提示
+-- | 在一层里查一列，报错时带上子句名与可用列
 columnAt :: String -> [(String, Column)] -> String -> Either String (String, Column)
 columnAt place env c = case resolveColumn c env of
     Right entry -> Right entry
@@ -94,6 +93,7 @@ checkGrouping env keys items
         checkColumns "GROUP BY" env keys
         mapM_ okCol (nub (concatMap (bareColumns . snd) items))
   where
+    -- | 这一列能不能出现在分组查询里
     okCol c
         | c == allColumns = Left "SELECT: * cannot be selected together with GROUP BY"
         | c `elem` keys = Right ()
@@ -173,7 +173,7 @@ itemType place want got
     | compatible want got = Right ()
     | otherwise = Left (place ++ ": IN list item has type " ++ renderType got ++ ", expected " ++ renderType want)
 
--- | 子查询的输出列与类型（外层作用域 outerScope 可做相关引用，内层整条查一遍）
+-- | 推导子查询的输出列与类型
 inferSubqueryOutput :: Database -> Scope -> Subquery -> Either String [(String, InferredType)]
 inferSubqueryOutput db outerScope sq = case subqueryStatement sq of
     q@Select { selectCols = cols } -> do
@@ -187,6 +187,7 @@ inferSubqueryOutput db outerScope sq = case subqueryStatement sq of
     _ -> Left "subquery must be a SELECT"
   where
     enclosing = scopeFlat outerScope
+    -- | 查这一列的推导类型
     columnTypeOf env c = do
         (_, col) <- scopeAt "SELECT" (Scope env enclosing) c
         Right (c, InferType (columnType col))
@@ -222,6 +223,7 @@ arithmetic db place env a b = do
     mapM_ (numericOperand place (InferType want) (InferType want)) [ta, tb]
     Right (arithResult ta tb)
   where
+    -- | 是不是浮点类型
     isFloatSide (InferType x) = numericType x && not (integerType x)
     isFloatSide _ = False
 
@@ -260,6 +262,7 @@ boolean db place env a b = do
     mapM_ (boolOperand place ta) [ta, tb]
     Right (InferType CBool)
   where
+    -- | 挨个查操作数是不是布尔
     boolOperand _ _ InferNull = Right ()
     boolOperand _ _ (InferType CBool) = Right ()
     boolOperand p other t = Left (p ++ ": operator needs TBool on both sides, got " ++ renderType other ++ " and " ++ renderType t)
@@ -453,7 +456,7 @@ checkInsertTargets t cols = mapM_ checkTarget (tableCols t)
         | Just _ <- columnDefault c = Right ()
         | otherwise = Left ("INSERT: column " ++ name ++ " is NOT NULL and has no default")
 
--- | 一列定义是否合法；names 是校验 CHECK 列引用时可用的全部列名
+-- | 检查一列定义是否合法（names 给 CHECK 用）
 checkColumnDefs :: [String] -> [(String, Column)] -> Either String ()
 checkColumnDefs names cols = do
     mapM_ (\(_, c) -> mapM_ (checkDefault c) (columnDefault c)) cols
@@ -480,11 +483,13 @@ checkDefault c v
 checkChecks :: [String] -> [(String, Column)] -> Either String ()
 checkChecks names = mapM_ checkOne
   where
+    -- | 查这一列的 CHECK
     checkOne (_, c) = case columnCheck c of
         Nothing -> Right ()
         Just text -> case parseExpression text of
             Left err -> Left ("CHECK: " ++ firstLine err)
             Right e -> mapM_ (known e) (colsInExpr e)
+    -- | 这个列名在不在定义里
     known _ col
         | col `elem` names = Right ()
         | otherwise = Left ("CHECK: unknown column: " ++ col)
@@ -494,6 +499,7 @@ checkChecks names = mapM_ checkOne
 accountNameLimit :: Int
 accountNameLimit = 64
 
+-- | 检查库名是否合法
 checkDatabaseName :: String -> Either String ()
 checkDatabaseName name
     | null name || length name > 64 || not (all (\c -> isAscii c && (isAlphaNum c || c == '_')) name) = Left "invalid database name"
@@ -511,6 +517,7 @@ checkUserName name
     | not (all allowed name) = Left "USER: account name may only contain ASCII letters, digits, dot, dash or underscore"
     | otherwise = Right ()
   where
+    -- | 账号名字符规则
     allowed c = isAscii c && (isAlphaNum c || c `elem` ("_.-" :: String))
 
 -- | 建号 / 改口令：名字合法且口令不空
@@ -524,7 +531,7 @@ checkAccount name password = do
                 then Left "USER: password is too long"
                 else Right ()
 
--- | 角色名：字符规则同账号名，另外不许拿权限关键字当名字（否则 GRANT 读不出来）
+-- | 检查角色名是否合法（不许用权限关键字）
 checkRoleName :: String -> Either String ()
 checkRoleName name
     | null name = Left "ROLE: empty role name"
@@ -533,6 +540,7 @@ checkRoleName name
     | map toLower name `elem` privilegeNames = Left "ROLE: role name must not be a privilege keyword"
     | otherwise = Right ()
   where
+    -- | 角色名字符规则
     allowed c = isAscii c && (isAlphaNum c || c `elem` ("_.-" :: String))
 
 -- | 权限关键字（小写，只用于比较）
@@ -554,8 +562,10 @@ checkGrantObject obj
     | not (all allowed obj) = Left "GRANT: object name may only contain ASCII letters, digits, dot, dash or underscore"
     | otherwise = Right ()
   where
+    -- | 授权对象字符规则
     allowed c = isAscii c && (isAlphaNum c || c `elem` ("_.-" :: String))
 
+-- | 内置 id 列名
 idColumn :: String
 idColumn = "id"
 -- | 把列引用统一为执行期名字（子查询一起解析）
@@ -592,10 +602,10 @@ resolveExpr db env outer f e = case e of
     ExistsSub sq negated -> ExistsSub <$> resolveSubquery db (env ++ outer) sq <*> pure negated
     _ -> Right e
   where
+    -- | 递归处理两个子表达式
     binary ctor a b = ctor <$> resolveExpr db env outer f a <*> resolveExpr db env outer f b
 
--- | 子查询：内层整条解析一遍，外层列参与解析（相关引用）
--- 解析完把“引用了哪些外层列”记进 subqueryRefs：投影下推要靠它保住这些列
+-- | 解析子查询，并记下它引用的外层列
 resolveSubquery :: Database -> [(String, Column)] -> Subquery -> Either String Subquery
 resolveSubquery db outer sq = do
     stmt <- resolveSubqueryStatement db outer (subqueryStatement sq)
@@ -608,11 +618,12 @@ outerRefsOf db stmt = nub [c | c <- statementColumns stmt, not (inInner c)]
     inner = case checkFrom db [] (statementFrom stmt) of
         Right env -> env
         Left _ -> []
+    -- | 这一列能不能在内层解析到
     inInner c = case resolveColumn c inner of
         Right _ -> True
         Left _ -> False
 
--- | 一条语句里出现的所有列引用（含 JOIN 的 ON 和嵌套子查询的外层引用）
+-- | 一条语句里出现的所有列引用
 statementColumns :: Statement -> [String]
 statementColumns stmt = case stmt of
     Select cols fromC mWhere groupBy orderBy _ ->
@@ -621,15 +632,18 @@ statementColumns stmt = case stmt of
         concatMap (colsInExpr . snd) items ++ fromColumns fromC ++ concatMap colsInExpr mWhere ++ groupBy ++ map fst orderBy
     _ -> []
   where
+    -- | 取 FROM 里出现的列
     fromColumns FromUnit = []
     fromColumns (FromTable _ _) = []
     fromColumns (FromJoin _ l _ _ c) = fromColumns l ++ colsInExpr c
 
+-- | 取语句的 FROM 子句，没有就是 FromUnit
 statementFrom :: Statement -> FromClause
 statementFrom Select { selectFrom = fromC } = fromC
 statementFrom SelectExpr { selectFrom = fromC } = fromC
 statementFrom _ = FromUnit
 
+-- | 解析子查询里的 SELECT
 resolveSubqueryStatement :: Database -> [(String, Column)] -> Statement -> Either String Statement
 resolveSubqueryStatement db outer q@Select{} = resolveQuery db outer q (map (\c -> (c, Col c)) (selectCols q))
 resolveSubqueryStatement db outer q@SelectExpr{} = resolveQuery db outer q (selectItems q)
@@ -672,14 +686,17 @@ resolveSelect db q@Select{} = resolveQuery db [] q (map (\c -> (c, Col c)) (sele
 resolveSelect db q@SelectExpr{} = resolveQuery db [] q (selectItems q)
 resolveSelect _ q = Right q
 
--- | 解析投影、条件、排序与连接引用；outer 是相关子查询能看见的外层列
+-- | 解析投影、条件、排序与连接引用
 resolveQuery :: Database -> [(String, Column)] -> Statement -> [(String, Expr)] -> Either String Statement
 resolveQuery db outer q items = do
     env <- checkFrom db outer (selectFrom q)
+    -- | 单表查询里把裸列名换成物理列名
     let physical c = case selectFrom q of
             FromTable Nothing tbl -> unqualify (Just tbl) c
             _ -> c
+        -- | 查一列并换算成物理名
         name place c = physical . fst <$> scopedColumnAt place env outer c
+        -- | 换算一个投影项
         output (_, Col c) = do
             k <- name "SELECT" c
             pure (k, Col k)
diff --git a/chusql-engine/src/ChuSQL/Storage.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Storage.hs
similarity index 88%
rename from chusql-engine/src/ChuSQL/Storage.hs
rename to chusql-core/engine/src/ChuSQL/Core/Engine/Storage.hs
index 706ad42..1960fe1 100644
--- a/chusql-engine/src/ChuSQL/Storage.hs
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Storage.hs
@@ -1,11 +1,11 @@
-module ChuSQL.Storage (
+module ChuSQL.Core.Engine.Storage (
     MonadStorage (..),
     IndexResult (..),
 ) where
 
-import ChuSQL.Model (Column, Database, Row, Table (..), Value (..))
+import ChuSQL.Core.Model (Column, Database, Row, Table (..), Value (..))
 
--- 存储层抽象：上层只认 domain 类型，不关心底层实现。
+-- 存储层抽象：MonadStorage 类与 IndexResult。
 
 data IndexResult
     = IndexRows [Row]
@@ -13,12 +13,16 @@ data IndexResult
     deriving (Show, Eq)
 
 class (Monad m) => MonadStorage m where
+    -- \| 建一个库
     createDatabase :: String -> m (Either String ())
     createDatabase _ = pure (Left "database management is unavailable in this storage")
+    -- \| 删一个库
     dropDatabase :: String -> m (Either String ())
     dropDatabase _ = pure (Left "database management is unavailable in this storage")
+    -- \| 切当前库
     useDatabase :: String -> m (Either String ())
     useDatabase _ = pure (Left "database selection is unavailable in this storage")
+    -- \| 列出现有库
     listDatabases :: m (Either String [String])
     listDatabases = pure (Right [])
 
@@ -38,6 +42,7 @@ class (Monad m) => MonadStorage m where
     insertMany :: String -> [Row] -> m (Either String ())
     insertMany t = go
       where
+        -- | 逐行插入，出错就停
         go [] = pure (Right ())
         go (r : rs) = do
             x <- insert t r
@@ -53,6 +58,7 @@ class (Monad m) => MonadStorage m where
             Left e -> pure (Left e)
             Right rs -> replaceAll t [r | r <- rs, not (doomed r)]
       where
+        -- | 这一行要不要删
         doomed r = case lookup "id" r of
             Just (VInt k) -> k `elem` ks
             _ -> False
@@ -79,7 +85,7 @@ class (Monad m) => MonadStorage m where
     -- \| 删除表
     dropTable :: String -> m (Either String ())
 
-    -- \| 给某一列建索引（要求这一列整数取值唯一）
+    -- \| 给某一列建索引（id 列要求唯一）
     createIndex :: String -> String -> m (Either String ())
     createIndex _ _ = pure (Right ())
 
@@ -100,4 +106,5 @@ class (Monad m) => MonadStorage m where
     schema :: m Database
     schema = fmap (map withoutRows) snapshot
       where
+        -- | 表定义去掉所有行
         withoutRows (name, t) = (name, t {tableRows = []})
diff --git a/chusql-core/engine/src/ChuSQL/Core/Engine/Storage/FFI.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Storage/FFI.hs
new file mode 100644
index 0000000..5457a69
--- /dev/null
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Storage/FFI.hs
@@ -0,0 +1,90 @@
+{-# LANGUAGE ForeignFunctionInterface #-}
+{-# LANGUAGE ImportQualifiedPost #-}
+
+module ChuSQL.Core.Engine.Storage.FFI (
+    StorageHandle,
+    storageVersion,
+    openStorage,
+    closeStorage,
+    storageRequest,
+) where
+
+import Control.Exception (SomeException, try)
+import Data.ByteString qualified as BS
+import Data.Text qualified as T
+import Data.Text.Encoding qualified as TE
+import Data.Text.Encoding.Error (lenientDecode)
+import Foreign
+import Foreign.C
+
+-- Rust 存储库 cdylib 的 C ABI 绑定（ffi.rs），收发单行 JSON。
+
+-- | 存储实例句柄（Rust 侧的 *mut Storage）
+newtype StorageHandle = StorageHandle (Ptr ())
+
+foreign import ccall unsafe "chusql_storage_version"
+    cStorageVersion :: IO CString
+
+foreign import ccall safe "chusql_storage_open"
+    cStorageOpen :: CString -> IO (Ptr ())
+
+foreign import ccall safe "chusql_storage_close"
+    cStorageClose :: Ptr () -> IO ()
+
+foreign import ccall safe "chusql_storage_request"
+    cStorageRequest :: Ptr () -> Ptr CChar -> CSize -> Ptr (Ptr CChar) -> Ptr CSize -> IO CInt
+
+foreign import ccall unsafe "chusql_storage_free"
+    cStorageFree :: Ptr CChar -> CSize -> IO ()
+
+foreign import ccall unsafe "chusql_storage_last_error"
+    cStorageLastError :: Ptr CSize -> IO (Ptr CChar)
+
+-- | 库版本（Rust 侧的 CARGO_PKG_VERSION）
+storageVersion :: IO String
+storageVersion = cStorageVersion >>= peekCString
+
+-- | 打开存储实例，失败给错误文本
+openStorage :: Maybe FilePath -> IO (Either String StorageHandle)
+openStorage path = do
+    result <- try (withCStringOrNull path cStorageOpen) :: IO (Either SomeException (Ptr ()))
+    case result of
+        Left e -> pure (Left ("storage library call failed: " ++ show e))
+        Right ptr
+            | ptr == nullPtr -> Left <$> lastError
+            | otherwise -> pure (Right (StorageHandle ptr))
+  where
+    -- | 没有路径就传空指针，否则转成 C 字符串
+    withCStringOrNull Nothing f = f nullPtr
+    withCStringOrNull (Just s) f = withCString s f
+
+-- | 关掉存储实例
+closeStorage :: StorageHandle -> IO ()
+closeStorage (StorageHandle handle) = cStorageClose handle
+
+-- | 一条 JSON 请求换一条 JSON 响应
+storageRequest :: StorageHandle -> BS.ByteString -> IO (Either String BS.ByteString)
+storageRequest (StorageHandle handle) payload =
+    BS.useAsCStringLen payload $ \(inPtr, inLen) ->
+        alloca $ \outPtrRef ->
+            alloca $ \outLenRef -> do
+                code <- cStorageRequest handle (castPtr inPtr) (fromIntegral inLen) outPtrRef outLenRef
+                if code /= 0
+                    then Left <$> lastError
+                    else do
+                        outPtr <- peek outPtrRef
+                        outLen <- peek outLenRef
+                        bytes <- BS.packCStringLen (castPtr outPtr, fromIntegral outLen)
+                        cStorageFree outPtr outLen
+                        pure (Right bytes)
+
+-- | 当前线程最近一次失败的文本
+lastError :: IO String
+lastError = alloca $ \lenRef -> do
+    ptr <- cStorageLastError lenRef
+    if ptr == nullPtr
+        then pure "storage: unknown error"
+        else do
+            len <- peek lenRef
+            raw <- BS.packCStringLen (ptr, fromIntegral len)
+            pure (T.unpack (TE.decodeUtf8With lenientDecode raw))
diff --git a/chusql-core/engine/src/ChuSQL/Core/Engine/Storage/IPC.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Storage/IPC.hs
new file mode 100644
index 0000000..9b174a2
--- /dev/null
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Storage/IPC.hs
@@ -0,0 +1,368 @@
+{-# LANGUAGE ImportQualifiedPost #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+module ChuSQL.Core.Engine.Storage.IPC (
+    IPCStorage (..),
+    Request (..),
+    Response (..),
+    Account (..),
+    SchemaColumn (..),
+    TableInfo (..),
+    StorageLink (..),
+    setStorageLink,
+    localStorageLink,
+    sendRequest,
+    sendRawRequest,
+    closeConnection,
+    setDatabaseName,
+    getDatabaseName,
+    doListTables,
+    doLookupByColumn,
+    doInsert,
+    doInsertMany,
+    doDeleteKeys,
+    doDescribeTable,
+    doDropTable,
+    doListCatalog,
+) where
+
+import ChuSQL.Core.Model
+import ChuSQL.Core.Protocol (Account (..), Request (..), Response (..), SchemaColumn (..), TableInfo (..))
+import ChuSQL.Core.Engine.Storage
+import ChuSQL.Core.Engine.Storage.FFI (closeStorage, openStorage, storageRequest)
+import Control.Concurrent.MVar (MVar, modifyMVar_, newMVar, readMVar)
+import Data.Aeson (eitherDecodeStrict, encode)
+import Data.ByteString qualified as BS
+import Data.ByteString.Lazy qualified as BL
+import Data.Maybe (fromMaybe)
+import System.IO.Unsafe (unsafePerformIO)
+
+-- IPC 存储实现：把 MonadStorage 的操作变成发给存储库的 JSON 请求。
+
+newtype IPCStorage a = IPCStorage
+    { runIPCStorage :: IO a
+    }
+
+instance Functor IPCStorage where
+    fmap f (IPCStorage m) = IPCStorage (fmap f m)
+
+instance Applicative IPCStorage where
+    pure = IPCStorage . pure
+    IPCStorage mf <*> IPCStorage ma = IPCStorage (mf <*> ma)
+
+instance Monad IPCStorage where
+    IPCStorage m >>= k = IPCStorage $ do
+        a <- m
+        runIPCStorage (k a)
+
+-- | 一条到存储库的链路：管请求与关闭
+data StorageLink = StorageLink
+    { slRequest :: BS.ByteString -> IO (Either String BS.ByteString)
+    , slClose :: IO ()
+    }
+
+{-# NOINLINE linkRef #-}
+-- | 进程全局的存储链路
+linkRef :: MVar (Maybe StorageLink)
+linkRef = unsafePerformIO (newMVar Nothing)
+
+-- | 装入一条链路；一个进程只装一次
+setStorageLink :: StorageLink -> IO ()
+setStorageLink link = modifyMVar_ linkRef (const (pure (Just link)))
+
+-- | 打开本地的存储动态库，得到一条链路
+localStorageLink :: Maybe FilePath -> IO (Either String StorageLink)
+localStorageLink path = fmap (fmap toLink) (openStorage path)
+  where
+    -- | 把句柄包成一条链路
+    toLink handle =
+        StorageLink
+            { slRequest = storageRequest handle
+            , slClose = closeStorage handle
+            }
+
+-- | 关掉当前链路（进程退出前调用）；没有链路就什么都不做
+closeConnection :: IO ()
+closeConnection = modifyMVar_ linkRef $ \current -> do
+    case current of
+        Nothing -> pure ()
+        Just link -> slClose link
+    pure Nothing
+
+-- | 发一条请求并解码应答；链路没装就报错，不崩
+sendRequest :: Request -> IO Response
+sendRequest req = do
+    current <- readMVar linkRef
+    case current of
+        Nothing -> pure (RespError "storage not configured")
+        Just link -> do
+            raw <- slRequest link (BL.toStrict (encode req))
+            case raw of
+                Left e -> pure (RespError ("storage error: " ++ e))
+                Right bytes -> case eitherDecodeStrict (BS.dropWhileEnd (== 13) bytes) of
+                    Left e -> pure (RespError ("decode error: " ++ e))
+                    Right resp -> pure resp
+
+-- | 原样转发一条载荷给存储库
+sendRawRequest :: BS.ByteString -> IO (Either String BS.ByteString)
+sendRawRequest payload = do
+    current <- readMVar linkRef
+    case current of
+        Nothing -> pure (Left "storage not configured")
+        Just link -> slRequest link payload
+
+{-# NOINLINE databaseRef #-}
+-- | 进程全局的当前库名
+databaseRef :: MVar (Maybe String)
+databaseRef = unsafePerformIO (newMVar Nothing)
+
+-- | 设定当前库名（会话层决定，本层只记住并发给存储）
+setDatabaseName :: Maybe String -> IO ()
+setDatabaseName name = modifyMVar_ databaseRef (const (pure name))
+
+-- | 当前库名
+getDatabaseName :: IO (Maybe String)
+getDatabaseName = readMVar databaseRef
+
+
+-- | 给语句类请求盖上当前库名
+stampDatabase :: Maybe String -> Request -> Request
+stampDatabase Nothing req = req
+stampDatabase (Just db) req
+    | globalRequest req = req
+    | otherwise = ReqInDatabase db req
+
+-- | 是不是不该带库名的全局请求
+globalRequest :: Request -> Bool
+globalRequest ReqDatabase{} = True
+globalRequest ReqAllCatalog = True
+globalRequest ReqAccountsList = True
+globalRequest ReqAccountCreate{} = True
+globalRequest ReqAccountReset{} = True
+globalRequest ReqAccountLogin{} = True
+globalRequest ReqAccountDrop{} = True
+globalRequest ReqPing = True
+globalRequest _ = False
+
+-- | 发请求并把响应翻成 Either
+ask :: String -> Request -> (Response -> Maybe a) -> IO (Either String a)
+ask what req recognize = do
+    current <- getDatabaseName
+    resp <- sendRequest (stampDatabase current req)
+    pure $ case resp of
+        RespError e -> Left e
+        other -> case recognize other of
+            Just a -> Right a
+            Nothing -> Left ("unexpected response to " ++ what)
+
+-- | 只认"成了"（多数写操作都这样）
+okOnly :: Response -> Maybe ()
+okOnly RespOk = Just ()
+okOnly _ = Nothing
+
+-- | 发 Scan
+doScan :: String -> IO (Either String [Row])
+doScan t = ask "scan" (ReqScan t) $ \resp -> case resp of
+    RespRows rows -> Just rows
+    _ -> Nothing
+
+-- | 发 Insert（索引由存储层维护）
+doInsert :: String -> Row -> IO (Either String ())
+doInsert t r = ask "insert" (ReqInsert t r) okOnly
+
+-- | 发 InsertBatch：一批行一次请求
+doInsertMany :: String -> [Row] -> IO (Either String ())
+doInsertMany t rs = ask "insert_batch" (ReqInsertBatch t rs) okOnly
+
+-- | 发 DeleteKeys
+doDeleteKeys :: String -> [Int] -> IO (Either String ())
+doDeleteKeys t ks = ask "delete_keys" (ReqDeleteKeys t ks) okOnly
+
+-- | 发 ReplaceAll
+doReplaceAll :: String -> [Row] -> IO (Either String ())
+doReplaceAll t rs = ask "replace_all" (ReqReplaceAll t rs) okOnly
+
+-- | 发 ListTables
+doListTables :: IO (Either String [String])
+doListTables = ask "list_tables" ReqListTables $ \resp -> case resp of
+    RespTables ts -> Just ts
+    _ -> Nothing
+
+-- | 一次拿全库 schema
+doListCatalog :: IO (Either String [TableInfo])
+doListCatalog = ask "list_catalog" ReqListCatalog $ \resp -> case resp of
+    RespCatalog xs -> Just xs
+    _ -> Nothing
+
+-- | 按某一列的索引取一行（键可以是整数或字符串）
+doLookupByColumn :: String -> String -> Value -> IO (Either String IndexResult)
+doLookupByColumn t c k = ask "lookup_by_index" (ReqLookupByColumn t c k) $ \resp -> case resp of
+    RespRows rows -> Just (IndexRows rows)
+    RespNoIndex -> Just NoIndex
+    _ -> Nothing
+
+-- | 范围扫描：没有可用索引就回 Nothing，让上层退回扫描
+doScanRange ::
+    String ->
+    String ->
+    Maybe (Value, Bool) ->
+    Maybe (Value, Bool) ->
+    IO (Either String (Maybe [Row]))
+doScanRange t c lo hi = ask "range_by_index" (ReqRangeByIndex t c lo hi) $ \resp -> case resp of
+    RespRows rows -> Just (Just rows)
+    RespNoIndex -> Just Nothing
+    _ -> Nothing
+
+-- | 发 DescribeTable
+doDescribeTable :: String -> IO (Either String TableInfo)
+doDescribeTable t = ask "describe_table" (ReqDescribeTable t) $ \resp -> case resp of
+    RespSchema info -> Just info
+    _ -> Nothing
+
+-- | 给某一列建索引
+doCreateIndex :: String -> String -> IO (Either String ())
+doCreateIndex t c = ask "create_index" (ReqCreateIndex t c) okOnly
+
+-- | 去掉某一列的索引
+doDropIndex :: String -> String -> IO (Either String ())
+doDropIndex t c = ask "drop_index" (ReqDropIndex t c) okOnly
+
+-- | 删一列（列定义、这一列上的索引、每行里的那一格一起没）
+doDropColumn :: String -> String -> IO (Either String ())
+doDropColumn t c = ask "drop_column" (ReqDropColumn t c) okOnly
+
+-- | 发 ReplaceSchema（ALTER 用）
+doReplaceSchema :: String -> [SchemaColumn] -> [Row] -> IO (Either String ())
+doReplaceSchema t cols rs = ask "replace_schema" (ReqReplaceSchema t cols rs) okOnly
+
+-- | 发 CreateTable
+doCreateTable :: String -> [SchemaColumn] -> IO (Either String ())
+doCreateTable t cols = ask "create_table" (ReqCreateTable t cols) okOnly
+
+-- | 发 DropTable
+doDropTable :: String -> IO (Either String ())
+doDropTable t = ask "drop_table" (ReqDropTable t) okOnly
+
+-- | 线上 schema 转本地列
+schemaToColumns :: [SchemaColumn] -> [(String, Column)]
+schemaToColumns = map toColumn
+
+-- | 线上 schema 转本地 column
+toColumn :: SchemaColumn -> (String, Column)
+toColumn sc =
+    ( scName sc
+    , Column
+        { columnType = fromMaybe CStr (parseColumnType (scType sc))
+        , columnNullable = scNullable sc
+        , columnDefault = scDefault sc
+        , columnAutoIncrement = scAutoIncrement sc
+        , columnUnique = scUnique sc
+        , columnPrimaryKey = scPrimaryKey sc
+        , columnCheck = scCheck sc
+        }
+    )
+
+-- | 本地列转线上 schema
+toWire :: (String, Column) -> SchemaColumn
+toWire (n, c) =
+    SchemaColumn
+        { scName = n
+        , scType = typeName (columnType c)
+        , scNullable = columnNullable c
+        , scDefault = columnDefault c
+        , scAutoIncrement = columnAutoIncrement c
+        , scPrimaryKey = columnPrimaryKey c
+        , scUnique = columnUnique c
+        , scCheck = columnCheck c
+        }
+
+instance MonadStorage IPCStorage where
+    -- \| 建一个库
+    createDatabase name = IPCStorage (ask "create_database" (ReqDatabase "create_database" name) okOnly)
+    -- \| 删一个库
+    dropDatabase name = IPCStorage (ask "drop_database" (ReqDatabase "drop_database" name) okOnly)
+    -- \| 切当前库
+    useDatabase name = IPCStorage (ask "use_database" (ReqDatabase "use_database" name) okOnly)
+    -- \| 列出现有库
+    listDatabases = IPCStorage $ ask "list_databases" (ReqDatabase "list_databases" "") $ \resp -> case resp of
+        RespTables names -> Just names
+        _ -> Nothing
+    -- \| 发 Scan
+    scan t = IPCStorage (doScan t)
+    -- \| 只取指定列
+    scanColumns t cols = IPCStorage $ ask "scan" (ReqScanColumns t cols) $ \resp -> case resp of
+        RespRows rows -> Just [[(c, v) | c <- cols, Just v <- [lookup c row]] | row <- rows]
+        _ -> Nothing
+
+    -- \| 发 Insert（索引由存储层自己维护）
+    insert t r = IPCStorage (doInsert t r)
+
+    -- \| 一批行一次请求：N 行只落一次盘
+    insertMany t rs = IPCStorage (doInsertMany t rs)
+
+    -- \| 按 id 批量删行
+    deleteKeys t ks = IPCStorage (doDeleteKeys t ks)
+
+    -- \| 发 ReplaceAll
+    replaceAll t rs = IPCStorage (doReplaceAll t rs)
+
+    -- \| 按某一列的索引取一行（没有索引就回 NoIndex）
+    lookupByColumn t c k = IPCStorage (doLookupByColumn t c k)
+
+    -- \| 范围扫描（没有索引就回 Nothing）
+    scanRange t c lo hi = IPCStorage (doScanRange t c lo hi)
+
+    -- \| 发 CreateTable
+    createTable name cols = IPCStorage (doCreateTable name (map toWire cols))
+
+    -- \| ALTER：整表换列定义与全部行
+    replaceSchema name cols rows = IPCStorage (doReplaceSchema name (map toWire cols) rows)
+
+    -- \| 发 DropTable
+    dropTable name = IPCStorage (doDropTable name)
+
+    -- \| 建索引
+    createIndex t c = IPCStorage (doCreateIndex t c)
+
+    -- \| 删索引
+    dropIndex t c = IPCStorage (doDropIndex t c)
+
+    -- \| 删一列
+    dropColumn t c = IPCStorage (doDropColumn t c)
+
+    -- \| 列表 + 逐表扫描拼库
+    snapshot = IPCStorage $ do
+        result <- doListCatalog
+        case result of
+            Left _ -> pure []
+            Right xs -> mapM loadEntry xs
+      where
+        loadEntry info = do
+            rows <- doScan (tiTable info)
+            pure
+                ( tiTable info
+                , Table (tiTable info) (schemaToColumns (tiColumns info)) (either (const []) id rows)
+                )
+
+    -- \| 只问数据字典要结构，设了当前库只留它的表
+    schema = IPCStorage $ do
+        current <- getDatabaseName
+        result <- ask "all_catalogs" ReqAllCatalog $ \resp -> case resp of
+            RespCatalog infos -> Just infos
+            _ -> Nothing
+        pure $ case result of
+            Left _ -> []
+            Right xs -> concatMap (visibleTables current) xs
+
+-- | 没设库名就照单全收；设了库名只收这个库的表，键名去掉库名前缀
+visibleTables :: Maybe String -> TableInfo -> [(String, Table)]
+visibleTables current info
+    | Just db <- current =
+        if unqualify (Just db) (tiTable info) /= tiTable info
+            then [bare named]
+            else []
+    | otherwise = [bare info]
+  where
+    named = info {tiTable = unqualify current (tiTable info)}
+    -- | 组装成不带行的表
+    bare i = (tiTable i, Table (tiTable i) (schemaToColumns (tiColumns i)) [])
diff --git a/chusql-engine/src/ChuSQL/Storage/Memory.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Storage/Memory.hs
similarity index 95%
rename from chusql-engine/src/ChuSQL/Storage/Memory.hs
rename to chusql-core/engine/src/ChuSQL/Core/Engine/Storage/Memory.hs
index b5933ed..3e0eb07 100644
--- a/chusql-engine/src/ChuSQL/Storage/Memory.hs
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Storage/Memory.hs
@@ -1,7 +1,7 @@
-module ChuSQL.Storage.Memory (MemoryStorage (runMemoryStorage)) where
+module ChuSQL.Core.Engine.Storage.Memory (MemoryStorage (runMemoryStorage)) where
 
-import ChuSQL.Model
-import ChuSQL.Storage
+import ChuSQL.Core.Model
+import ChuSQL.Core.Engine.Storage
 
 -- 内存实现：Database 上的状态，错误通道是 Either String。
 
diff --git a/chusql-engine/src/ChuSQL/Syntax/AST.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Syntax/AST.hs
similarity index 86%
rename from chusql-engine/src/ChuSQL/Syntax/AST.hs
rename to chusql-core/engine/src/ChuSQL/Core/Engine/Syntax/AST.hs
index c5251c3..01500ae 100644
--- a/chusql-engine/src/ChuSQL/Syntax/AST.hs
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Syntax/AST.hs
@@ -1,6 +1,6 @@
-module ChuSQL.Syntax.AST (Statement (..), FromClause (..), JoinKind (..), Expr (..), Subquery (..), SortDir (..), makeSelect) where
+module ChuSQL.Core.Engine.Syntax.AST (Statement (..), FromClause (..), JoinKind (..), Expr (..), Subquery (..), SortDir (..), makeSelect) where
 
-import ChuSQL.Model (Column (..), ColumnType, Value (..))
+import ChuSQL.Core.Model (Column (..), ColumnType, Value (..))
 
 -- 语法树：语句、数据来源、条件表达式、排序方向。
 
@@ -41,11 +41,11 @@ data Statement
     | CreateRole String
     -- | 删角色：连同它的授权与成员一起删
     | DropRole String
-    -- | GRANT <权限>[, ...] ON <表|*> TO <角色>
+    -- | GRANT 权限 ON 表 TO 角色
     | GrantPrivileges [String] String String
-    -- | REVOKE <权限>[, ...] ON <表|*> FROM <角色>
+    -- | REVOKE 权限 ON 表 FROM 角色
     | RevokePrivileges [String] String String
-    -- | GRANT <角色> TO <用户>[, ...]：给用户加角色
+    -- | GRANT 角色 TO 用户：给用户加角色
     | GrantRole String [String]
     -- | REVOKE <角色> FROM <用户>[, ...]
     | RevokeRole String [String]
@@ -61,6 +61,7 @@ data JoinKind
     | LeftJoin
     deriving (Show, Eq)
 
+-- | 数据来源：单表、带连接的来源，或空
 data FromClause
     = FromTable (Maybe String) String
     | FromJoin JoinKind FromClause (Maybe String) String Expr
@@ -74,6 +75,7 @@ data Subquery = Subquery
     }
     deriving (Show, Eq)
 
+-- | 条件表达式：列、字面量、算术、比较、逻辑、聚合与子查询
 data Expr
     = Col String
     | LitNull
@@ -108,6 +110,7 @@ data Expr
     | ExistsSub Subquery Bool
     deriving (Show, Eq)
 
+-- | 排序方向：升序或降序
 data SortDir
     = Asc
     | Desc
diff --git a/chusql-engine/src/ChuSQL/Syntax/Parser.hs b/chusql-core/engine/src/ChuSQL/Core/Engine/Syntax/Parser.hs
similarity index 95%
rename from chusql-engine/src/ChuSQL/Syntax/Parser.hs
rename to chusql-core/engine/src/ChuSQL/Core/Engine/Syntax/Parser.hs
index 15c219c..2a3d605 100644
--- a/chusql-engine/src/ChuSQL/Syntax/Parser.hs
+++ b/chusql-core/engine/src/ChuSQL/Core/Engine/Syntax/Parser.hs
@@ -1,9 +1,9 @@
 {-# LANGUAGE ImportQualifiedPost #-}
 
-module ChuSQL.Syntax.Parser (parseStatement, parseExpression) where
+module ChuSQL.Core.Engine.Syntax.Parser (parseStatement, parseExpression) where
 
-import ChuSQL.Model (Column (..), ColumnType (..), Value (..), plainColumn)
-import ChuSQL.Syntax.AST
+import ChuSQL.Core.Model (Column (..), ColumnType (..), Value (..), plainColumn)
+import ChuSQL.Core.Engine.Syntax.AST
 import Control.Monad (void)
 import Control.Monad.Combinators.Expr (Operator (..), makeExprParser)
 import Data.Char (isAlpha, isAlphaNum, isHexDigit, isSpace, toLower, toUpper)
@@ -43,7 +43,7 @@ identifier = lexeme $ do
     rest <- many (satisfy isIdentChar)
     return (first : rest)
 
--- | 账号名：裸名字或单引号字符串（账号名允许点与短横线，字符串形式才写得出来）
+-- | 账号名：裸名字或单引号字符串
 userName :: Parser String
 userName = identifier <|> stringLit
 
@@ -154,7 +154,7 @@ existsPredicate = do
 scalarSubquery :: Parser Expr
 scalarSubquery = ScalarSub <$> between (symbol "(") (symbol ")") subquerySelect
 
--- | [NOT] IN (SELECT ...) 或 [NOT] IN (值清单)
+-- | 读 [NOT] IN：子查询或值清单
 inPredicate :: Parser (Expr -> Expr)
 inPredicate = do
     negated <- (True <$ try (keyword "not" *> keyword "in")) <|> (False <$ keyword "in")
@@ -172,7 +172,7 @@ inPredicate = do
 subquerySelect :: Parser Subquery
 subquerySelect = Subquery <$> selectStatement <*> pure []
 
--- | 聚合调用：COUNT(*) / COUNT(x) / SUM(x) / AVG(x) / MIN(x) / MAX(x)
+-- | 聚合调用：COUNT/SUM/AVG/MIN/MAX
 aggregateCall :: Parser Expr
 aggregateCall =
     choice
@@ -184,6 +184,7 @@ aggregateCall =
         , MaxOf <$> aggArg "max"
         ]
   where
+    -- | 读聚合函数的参数
     aggArg name = try (keyword name *> between (symbol "(") (symbol ")") expr)
 
 -- | 只认字面量，给 DEFAULT 用
@@ -199,6 +200,7 @@ literalValue =
         , VStr <$> stringLit
         ]
   where
+    -- | 负浮点字面量
     negateLit d = VFloat (negate d)
 
 -- | 一个排序列
@@ -230,6 +232,7 @@ assignment = do
     e <- expr
     return (col, e)
 
+-- | 保留字清单，别名不许用
 reservedWords :: [String]
 reservedWords =
     [ "select"
@@ -367,7 +370,7 @@ dropIndexStatement = do
     col <- between (symbol "(") (symbol ")") identifier
     return (DropIndex tbl col)
 
--- | 读 ALTER TABLE：加列、删列、改名、改类型、改默认值、改可空
+-- | 读 ALTER TABLE 的加列、删列、改名与改属性
 alterTableStatement :: Parser Statement
 alterTableStatement = do
     keyword "alter"
@@ -402,7 +405,7 @@ alterTableStatement = do
                 ]
         ]
 
--- | 读 CREATE USER（口令是明文，交给账号服务加盐派生）
+-- | 读 CREATE USER，口令是明文
 createUserStatement :: Parser Statement
 createUserStatement = do
     keyword "create"
@@ -418,7 +421,7 @@ identifiedBy = do
     keyword "by"
     stringLit
 
--- | 读 ALTER USER ... IDENTIFIED BY（改一个普通账号的口令）
+-- | 读 ALTER USER 改口令
 alterUserStatement :: Parser Statement
 alterUserStatement = do
     keyword "alter"
@@ -460,11 +463,11 @@ privilegeName =
         , "ALL" <$ keyword "all"
         ]
 
--- | ON 后面的授权对象：* 表示全部表，否则是一张表（可带库前缀）
+-- | ON 后面的授权对象：* 或一张表
 grantObject :: Parser String
 grantObject = ("*" <$ symbol "*") <|> tableName
 
--- | 读 GRANT：带 ON 的是给角色授权限，不带的是给用户加角色
+-- | 读 GRANT：带 ON 的授权限，不带的加角色
 grantStatement :: Parser Statement
 grantStatement = do
     keyword "grant"
@@ -554,6 +557,7 @@ decimalType = do
         Nothing -> CDecimal 10 0
         Just (p, s) -> CDecimal p s
 
+-- | DECIMAL 的精度与小数位参数
 decimalArgs :: Parser (Int, Int)
 decimalArgs = do
     p <- integer
@@ -619,6 +623,7 @@ parseStatement input =
         Left err -> Left (errorBundlePretty err)
         Right q -> Right q
   where
+    -- | 按关键字分派到各语句解析器
     statementP =
         selectStatement
             <|> try (CreateDatabase <$> (keyword "create" *> keyword "database" *> identifier))
diff --git a/chusql-core/engine/stack.yaml b/chusql-core/engine/stack.yaml
new file mode 100644
index 0000000..e49d6ac
--- /dev/null
+++ b/chusql-core/engine/stack.yaml
@@ -0,0 +1,8 @@
+resolver: lts-24.59
+
+extra-lib-dirs:
+    - ../storage/target/release
+
+packages:
+    - .
+    - ../model
diff --git a/chusql-engine/stack.yaml.lock b/chusql-core/engine/stack.yaml.lock
similarity index 100%
rename from chusql-engine/stack.yaml.lock
rename to chusql-core/engine/stack.yaml.lock
diff --git a/chusql-engine/test/Spec.hs b/chusql-core/engine/test/Spec.hs
similarity index 91%
rename from chusql-engine/test/Spec.hs
rename to chusql-core/engine/test/Spec.hs
index d7ec22a..e498789 100644
--- a/chusql-engine/test/Spec.hs
+++ b/chusql-core/engine/test/Spec.hs
@@ -2,32 +2,29 @@
 
 module Main where
 
-import ChuSQL.Algebra.Eval (evalRelOp)
-import ChuSQL.Algebra.Expr (colsInExpr, evalExpr)
-import ChuSQL.Algebra.Op (RelOp (..), renderPlan)
-import ChuSQL.Algebra.Optimize (optimize, pushProject)
-import ChuSQL.Algebra.Planner (translate)
-import ChuSQL.Engine
-import ChuSQL.Model
-import ChuSQL.Semantic (prepare)
-import ChuSQL.Storage (IndexResult (..), MonadStorage (..))
-import ChuSQL.Storage.IPC (IPCStorage (runIPCStorage), Request (ReqPing), Response (RespPong), doListTables, getPipeName, sendRequest, setPipeName)
-import ChuSQL.Syntax.AST
-import ChuSQL.Syntax.Parser
-import Control.Concurrent (threadDelay)
-import Control.Exception (IOException, bracket, finally, try)
+import ChuSQL.Core.Engine.Algebra.Eval (evalRelOp)
+import ChuSQL.Core.Engine.Algebra.Expr (colsInExpr, evalExpr)
+import ChuSQL.Core.Engine.Algebra.Op (RelOp (..), renderPlan)
+import ChuSQL.Core.Engine.Algebra.Optimize (optimize, pushProject)
+import ChuSQL.Core.Engine.Algebra.Planner (translate)
+import ChuSQL.Core.Engine
+import ChuSQL.Core.Model
+import ChuSQL.Core.Engine.Semantic (prepare)
+import ChuSQL.Core.Engine.Storage (IndexResult (..), MonadStorage (..))
+import ChuSQL.Core.Engine.Storage.IPC (IPCStorage (runIPCStorage), closeConnection, doListTables, getDatabaseName, localStorageLink, setDatabaseName, setStorageLink)
+import ChuSQL.Core.Engine.Syntax.AST
+import ChuSQL.Core.Engine.Syntax.Parser
+import Control.Exception (IOException, finally, try)
 import Data.List (isInfixOf, sortOn)
 import Data.Unique (hashUnique, newUnique)
 import System.CPUTime (getCPUTime)
-import System.Directory (createDirectoryIfMissing, doesDirectoryExist, doesFileExist, getTemporaryDirectory, removePathForcibly)
-import System.Exit (ExitCode (..))
+import System.Directory (createDirectoryIfMissing, getTemporaryDirectory, removePathForcibly)
 import System.FilePath ((</>))
-import System.IO (Handle, IOMode (WriteMode), withFile)
-import System.Process (CreateProcess (..), ProcessHandle, StdStream (NoStream, UseHandle), createProcess, proc, terminateProcess, waitForProcess)
 import Test.Hspec
 
--- 引擎层的 hspec 测试：语法、执行、优化器与 IPC 行为。
+-- 引擎层的 hspec 测试：语法、执行、优化器与存储链路行为。
 
+-- | 测试表 users：id / name / age
 users :: Table
 users =
     Table
@@ -40,6 +37,7 @@ users =
             ]
         }
 
+-- | 测试表 orders：id/user_id/product
 orders :: Table
 orders =
     Table
@@ -52,12 +50,14 @@ orders =
             ]
         }
 
+-- | 两个测试表组成的默认库
 testDB :: Database
 testDB = [("users", users), ("orders", orders)]
 
+-- | 跑引擎层全部 hspec 用例
 main :: IO ()
 main = hspec $ do
-    describe "ChuSQL.Syntax.Parser" $ do
+    describe "ChuSQL.Core.Engine.Syntax.Parser" $ do
         it "resolves table-qualified columns inside database-qualified tables" $ do
             let db = [("sales.users", users)]
             rowsOf (parseStatement "SELECT users.name FROM sales.users WHERE users.id = 1" >>= runStatement db)
@@ -194,7 +194,7 @@ main = hspec $ do
             parseStatement "SELECT name FROM"
                 `shouldSatisfy` isLeft
 
-    describe "ChuSQL.Syntax.Parser (JOIN)" $ do
+    describe "ChuSQL.Core.Engine.Syntax.Parser (JOIN)" $ do
         it "parses a simple JOIN without aliases" $ do
             parseStatement "SELECT name FROM users JOIN orders ON id = user_id"
                 `shouldBe` Right
@@ -263,8 +263,10 @@ main = hspec $ do
                         (Eq (Col "u.id") (Col "o.user_id"))
                     )
 
-    describe "ChuSQL.Engine (SELECT)" $ do
+    describe "ChuSQL.Core.Engine (SELECT)" $ do
+        -- sql：在默认库上跑 SQL 取结果行
         let sql input = parseStatement input >>= rowsOf . runStatement testDB
+            -- values：只取结果里的值
             values input = fmap (map (map snd)) (sql input)
         it "skips line comments between tokens and at EOF" $ do
             sql "-- start\nSELECT name -- list\nFROM users -- end" `shouldBe` sql "SELECT name FROM users"
@@ -415,7 +417,7 @@ main = hspec $ do
             runStatement testDB (makeSelect ["nope"] "users" Nothing)
                 `shouldSatisfy` isLeft
 
-    describe "ChuSQL.Engine (INSERT)" $ do
+    describe "ChuSQL.Core.Engine (INSERT)" $ do
         it "parses a simple INSERT" $ do
             parseStatement "INSERT INTO users (name, age) VALUES ('Dave', 22)"
                 `shouldBe` Right (Insert "users" ["name", "age"] [[LitStr "Dave", LitInt 22]])
@@ -464,7 +466,7 @@ main = hspec $ do
                     runStatement testDB (Insert "users" ["id", "name"] [[LitInt 1, LitStr "A"], [LitInt 2]])
                         `shouldSatisfy` isLeft
 
-    describe "ChuSQL.Engine (INDEX)" $ do
+    describe "ChuSQL.Core.Engine (INDEX)" $ do
         it "parses CREATE INDEX and DROP INDEX" $ do
             parseStatement "CREATE INDEX ON users (age)"
                 `shouldBe` Right (CreateIndex "users" "age")
@@ -485,7 +487,7 @@ main = hspec $ do
             rowsOf (parseStatement "DROP INDEX ON users (age)" >>= runStatement testDB)
                 `shouldBe` Right []
 
-    describe "ChuSQL.Engine (DROP COLUMN)" $ do
+    describe "ChuSQL.Core.Engine (DROP COLUMN)" $ do
         it "parses ALTER TABLE ... DROP COLUMN case-insensitively" $ do
             parseStatement "ALTER TABLE users DROP COLUMN age"
                 `shouldBe` Right (DropColumn "users" "age")
@@ -514,7 +516,7 @@ main = hspec $ do
         it "the built-in id column cannot be dropped (the UI locates a row by it)" $ do
             (parseStatement "ALTER TABLE users DROP COLUMN id" >>= runStatement testDB)
                 `shouldSatisfy` isLeft
-    describe "ChuSQL.Engine (USER)" $ do
+    describe "ChuSQL.Core.Engine (USER)" $ do
         it "parses CREATE USER / ALTER USER / DROP USER case-insensitively" $ do
             parseStatement "CREATE USER alice IDENTIFIED BY 's3cret'"
                 `shouldBe` Right (CreateUser "alice" "s3cret")
@@ -552,7 +554,7 @@ main = hspec $ do
             (parseStatement "DROP USER alice" >>= runStatement testDB)
                 `shouldSatisfy` isLeft
 
-    describe "ChuSQL.Engine (ROLE)" $ do
+    describe "ChuSQL.Core.Engine (ROLE)" $ do
         it "parses CREATE ROLE / DROP ROLE case-insensitively" $ do
             parseStatement "CREATE ROLE analyst" `shouldBe` Right (CreateRole "analyst")
             parseStatement "create role analyst" `shouldBe` Right (CreateRole "analyst")
@@ -616,7 +618,7 @@ main = hspec $ do
             parseStatement "SELECT * FROM users user" `shouldSatisfy` isLeft
             parseStatement "SELECT user1 FROM users" `shouldBe` Right (Select ["user1"] (FromTable Nothing "users") Nothing [] [] Nothing)
 
-    describe "ChuSQL.Engine (DELETE)" $ do
+    describe "ChuSQL.Core.Engine (DELETE)" $ do
         it "parses DELETE with WHERE" $ do
             parseStatement "DELETE FROM users WHERE age < 18"
                 `shouldBe` Right (Delete "users" (Just (Lt (Col "age") (LitInt 18))))
@@ -646,7 +648,7 @@ main = hspec $ do
             runStatement testDB (Delete "users" (Just (Gt (Col "unknown") (LitInt 18))))
                 `shouldSatisfy` isLeft
 
-    describe "ChuSQL.Engine (UPDATE)" $ do
+    describe "ChuSQL.Core.Engine (UPDATE)" $ do
         it "parses UPDATE with WHERE" $ do
             parseStatement "UPDATE users SET age = 26 WHERE name = 'Alice'"
                 `shouldBe` Right
@@ -707,7 +709,7 @@ main = hspec $ do
             runStatement testDB (Update "users" [("age", LitInt 0)] (Just (Gt (Col "unknown") (LitInt 1))))
                 `shouldSatisfy` isLeft
 
-    describe "ChuSQL.Engine (ORDER BY)" $ do
+    describe "ChuSQL.Core.Engine (ORDER BY)" $ do
         it "parses ORDER BY DESC" $ do
             case parseStatement "SELECT name FROM users ORDER BY age DESC" of
                 Right q -> selectOrderBy q `shouldBe` [("age", Desc)]
@@ -757,7 +759,7 @@ main = hspec $ do
                     , [("name", VStr "Bob")]
                     ]
 
-    describe "ChuSQL.Engine (LIMIT)" $ do
+    describe "ChuSQL.Core.Engine (LIMIT)" $ do
         it "parses LIMIT" $ do
             case parseStatement "SELECT * FROM users LIMIT 2" of
                 Right q -> selectLimit q `shouldBe` Just 2
@@ -819,7 +821,7 @@ main = hspec $ do
             parseStatement "SELECT * FROM users LIMIT -1"
                 `shouldSatisfy` isLeft
 
-    describe "ChuSQL.Engine (JOIN)" $ do
+    describe "ChuSQL.Core.Engine (JOIN)" $ do
         it "executes a two-table JOIN with aliases" $ do
             rowsOf (parseStatement "SELECT u.name, o.product FROM users u JOIN orders o ON u.id = o.user_id" >>= runStatement testDB)
                 `shouldBe` Right
@@ -870,7 +872,8 @@ main = hspec $ do
                 )
                 `shouldSatisfy` isLeft
 
-    describe "ChuSQL.Engine (LEFT JOIN)" $ do
+    describe "ChuSQL.Core.Engine (LEFT JOIN)" $ do
+        -- sql：在默认库上跑 SQL 取结果行
         let sql input = parseStatement input >>= rowsOf . runStatement testDB
 
         it "keeps unmatched left rows and fills the right side with NULL" $ do
@@ -930,7 +933,8 @@ main = hspec $ do
                     , [("u.name", VStr "Carol"), ("o.product", VStr "Cup")]
                     ]
 
-    describe "ChuSQL.Engine (JOIN 嵌套循环)" $ do
+    describe "ChuSQL.Core.Engine (JOIN 嵌套循环)" $ do
+        -- sql：在默认库上跑 SQL 取结果行
         let sql input = parseStatement input >>= rowsOf . runStatement testDB
 
         it "keeps columns from both sides when the ON has no equi key" $ do
@@ -943,7 +947,8 @@ main = hspec $ do
                     , [("u.name", VStr "Carol"), ("o.product", VStr "Cup")]
                     ]
 
-    describe "ChuSQL.Engine (子查询)" $ do
+    describe "ChuSQL.Core.Engine (子查询)" $ do
+        -- sql：在默认库上跑 SQL 取结果行
         let sql input = parseStatement input >>= rowsOf . runStatement testDB
 
         it "IN (subquery) keeps the rows whose value the subquery returns" $ do
@@ -997,9 +1002,12 @@ main = hspec $ do
             sameResultAsUnoptimized "SELECT name FROM users WHERE id IN (SELECT user_id FROM orders)"
             sameResultAsUnoptimized "SELECT u.name FROM users u WHERE EXISTS (SELECT * FROM orders o WHERE o.user_id = u.id)"
 
-    describe "ChuSQL.Engine (聚合与 GROUP BY)" $ do
+    describe "ChuSQL.Core.Engine (聚合与 GROUP BY)" $ do
+        -- sql：在默认库上跑 SQL 取结果行
         let sql input = parseStatement input >>= rowsOf . runStatement testDB
+            -- sqlDb：在指定库上跑 SQL
             sqlDb db input = parseStatement input >>= rowsOf . runStatement db
+            -- vals：只取结果里的值
             vals input = fmap (map (map snd)) (sql input)
 
         it "counts rows without GROUP BY" $ do
@@ -1104,7 +1112,7 @@ main = hspec $ do
                     [ [("name", VStr "Carol")]
                     ]
 
-    describe "ChuSQL.Algebra.Optimize" $ do
+    describe "ChuSQL.Core.Engine.Algebra.Optimize" $ do
         it "keeps single-table WHERE results identical" $ do
             sameResultAsUnoptimized "SELECT name FROM users WHERE age > 18"
 
@@ -1285,7 +1293,7 @@ main = hspec $ do
             rowsOf (parseStatement "SELECT u.name FROM users u WHERE u.id = 1" >>= runStatement testDB)
                 `shouldBe` Right [[("u.name", VStr "Alice")]]
 
-    describe "ChuSQL.Semantic" $ do
+    describe "ChuSQL.Core.Engine.Semantic" $ do
         it "rejects an unknown column in WHERE" $ do
             (parseStatement "SELECT name FROM users WHERE nope > 18" >>= runStatement testDB)
                 `shouldSatisfy` isLeft
@@ -1386,7 +1394,7 @@ main = hspec $ do
             (parseStatement "SELECT * FROM users u JOIN orders o ON u.id = o.user_id" >>= runStatement testDB)
                 `shouldSatisfy` isRight
 
-    describe "ChuSQL.Algebra.Op" $ do
+    describe "ChuSQL.Core.Engine.Algebra.Op" $ do
         it "renders a plan as indented text" $ do
             case parseStatement "SELECT name FROM users WHERE age > 18" >>= translate of
                 Left err -> expectationFailure err
@@ -1405,12 +1413,13 @@ main = hspec $ do
                                    , "    Scan Just \"o\" \"orders\""
                                    ]
 
-    describe "ChuSQL.Storage.IPC" $ do
-        it "projects scan columns and preserves constant rows over the pipe" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+    describe "ChuSQL.Core.Engine.Storage.IPC" $ do
+        it "projects scan columns and preserves constant rows" $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 runIPCStorage (insertMany "projected" [[("id", VInt 1), ("name", VStr "one")], [("id", VInt 2), ("name", VNull)]]) `shouldReturn` Right ()
                 runIPCStorage (scanColumns "projected" ["name"]) `shouldReturn` Right [[("name", VStr "one")], [("name", VNull)]]
                 runIPCStorage (scanColumns "projected" []) `shouldReturn` Right [[], []]
+                -- query：解析并执行一条 SQL
                 let query sql = case parseStatement sql of
                         Left err -> expectationFailure err >> pure (Left err)
                         Right stmt -> runIPCStorage (runStatementM stmt)
@@ -1418,8 +1427,9 @@ main = hspec $ do
                 fmap (map (map snd)) result `shouldBe` Right [[VInt 1], [VInt 1]]
                 query "SELECT p.name FROM projected p ORDER BY p.id DESC" `shouldReturn` Right [[("p.name", VNull)], [("p.name", VStr "one")]]
 
-        it "recreates a dropped column without resurrecting old values over the pipe" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+        it "recreates a dropped column without resurrecting old values" $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
+                -- query：解析并执行一条 SQL
                 let query sql = case parseStatement sql of
                         Left err -> expectationFailure err >> pure (Left err)
                         Right stmt -> runIPCStorage (runStatementM stmt)
@@ -1433,19 +1443,19 @@ main = hspec $ do
                 query "SELECT secret FROM reused WHERE id = 1" `shouldReturn` Right [[("secret", VStr "new")]]
 
         it "scan returns rows with all three value types after insert" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 let row = [("id", VInt 7), ("name", VStr "Alice"), ("flag", VBool True)]
                 runIPCStorage (insert "users" row) `shouldReturn` Right ()
                 rows <- runIPCStorage (scan "users")
                 (map sortRow <$> rows) `shouldBe` Right [sortRow row]
 
         it "scan on a missing table returns Left" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 result <- runIPCStorage (scan "no_such_table")
                 result `shouldSatisfy` isLeft
 
         it "scan returns all 20 inserted rows in order" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 mapM_ (\i -> runIPCStorage (insert "many" [("id", VInt i)])) [1 .. 20 :: Int]
                 rows <- runIPCStorage (scan "many")
                 fmap length rows `shouldBe` Right 20
@@ -1453,15 +1463,15 @@ main = hspec $ do
                     `shouldBe` Right (sortOn show (map (Just . VInt) [1 .. 20]))
 
         it "replaceAll leaves only the new rows" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 runIPCStorage (insert "t" [("id", VInt 1)]) `shouldReturn` Right ()
                 runIPCStorage (replaceAll "t" [[("id", VInt 9)], [("id", VInt 8)]]) `shouldReturn` Right ()
                 rows <- runIPCStorage (scan "t")
                 fmap (sortOn show . map (lookup "id")) rows
                     `shouldBe` Right (sortOn show [Just (VInt 9), Just (VInt 8)])
 
-        it "lookupByColumn finds a row inserted with an id over the pipe" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+        it "lookupByColumn finds a row inserted with an id" $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 let row = [("id", VInt 7), ("name", VStr "Zoe")]
                 runIPCStorage (insert "keyed" row) `shouldReturn` Right ()
                 found <- runIPCStorage (lookupByColumn "keyed" "id" (VInt 7))
@@ -1469,8 +1479,8 @@ main = hspec $ do
                 missing <- runIPCStorage (lookupByColumn "keyed" "id" (VInt 8))
                 missing `shouldBe` Right (IndexRows [])
 
-        it "looks up a string index over the pipe" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+        it "looks up a string index" $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 runIPCStorage (insert "names" [("id", VInt 1), ("name", VStr "alice")]) `shouldReturn` Right ()
                 runIPCStorage (insert "names" [("id", VInt 2), ("name", VStr "bob")]) `shouldReturn` Right ()
                 runIPCStorage (createIndex "names" "name") `shouldReturn` Right ()
@@ -1479,8 +1489,8 @@ main = hspec $ do
                 missing <- runIPCStorage (lookupByColumn "names" "name" (VStr "dave"))
                 missing `shouldBe` Right (IndexRows [])
 
-        it "range scans an indexed column over the pipe" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+        it "range scans an indexed column" $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 runIPCStorage (insert "rng" [("id", VInt 1), ("code", VInt 100)]) `shouldReturn` Right ()
                 runIPCStorage (insert "rng" [("id", VInt 2), ("code", VInt 200)]) `shouldReturn` Right ()
                 runIPCStorage (insert "rng" [("id", VInt 3), ("code", VInt 300)]) `shouldReturn` Right ()
@@ -1491,8 +1501,8 @@ main = hspec $ do
                 fmap (fmap (map (lookup "id"))) open `shouldBe` Right (Just [Just (VInt 3)])
                 runIPCStorage (scanRange "rng" "nope" Nothing Nothing) `shouldReturn` Right Nothing
 
-        it "replaceAll rebuilds the index over the pipe" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+        it "replaceAll rebuilds the index" $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 runIPCStorage (insert "rb" [("id", VInt 1)]) `shouldReturn` Right ()
                 runIPCStorage (replaceAll "rb" [[("id", VInt 9), ("name", VStr "Zoe")]]) `shouldReturn` Right ()
                 old <- runIPCStorage (lookupByColumn "rb" "id" (VInt 1))
@@ -1502,7 +1512,7 @@ main = hspec $ do
                     `shouldBe` Just (sortRow [("id", VInt 9), ("name", VStr "Zoe")])
 
         it "snapshot lists tables and scans each one to build the database" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 runIPCStorage (insert "a" [("id", VInt 1)]) `shouldReturn` Right ()
                 runIPCStorage (insert "b" [("id", VInt 2)]) `shouldReturn` Right ()
                 db <- runIPCStorage snapshot
@@ -1511,38 +1521,31 @@ main = hspec $ do
                 map (map (lookup "id") . tableRows . snd) db `shouldBe` [[Just (VInt 1)], [Just (VInt 2)]]
 
         it "doListTables returns the tables that exist" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 runIPCStorage (insert "t1" [("id", VInt 1)]) `shouldReturn` Right ()
                 runIPCStorage (insert "t2" [("id", VInt 2)]) `shouldReturn` Right ()
                 doListTables `shouldReturn` Right ["t1", "t2"]
 
         it "rows survive a restart on the same data directory" $ do
-            located <- locateServer
-            case located of
-                Left err -> pendingWith err
-                Right bin -> do
-                    srv1 <- startServer bin
-                    let dir = dataDir srv1
-                    withServerEnv srv1 $ runIPCStorage (insert "persist" [("id", VInt 42)]) `shouldReturn` Right ()
-                    stopServer srv1
-                    srv2 <- startServerAt bin dir
-                    rows <- withServerEnv srv2 $ runIPCStorage (scan "persist")
-                    stopServer srv2
-                    cleanServerDir srv1
-                    (map sortRow <$> rows) `shouldBe` Right [sortRow [("id", VInt 42)]]
+            withTestSession $ \srv -> do
+                withServerEnv srv $ runIPCStorage (insert "persist" [("id", VInt 42)]) `shouldReturn` Right ()
+                closeConnection
+                openSessionIn (dataDir srv)
+                rows <- withServerEnv srv $ runIPCStorage (scan "persist")
+                (map sortRow <$> rows) `shouldBe` Right [sortRow [("id", VInt 42)]]
 
-        it "a missing server yields Left without throwing" $ do
-            withPipeName "chusql-no-such-server" $ do
-                result <- runIPCStorage (scan "users")
-                result `shouldSatisfy` isLeft
-#if !defined(mingw32_HOST_OS)
-        it "an over-long socket path is reported instead of a raw connect failure" $ do
-            withPipeName (replicate 128 'x') $ do
-                result <- runIPCStorage (scan "users")
-                show result `shouldSatisfy` isInfixOf "socket path too long"
-#endif
-        it "INSERT then SELECT WHERE id = k via IPC" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+        it "an unusable config path yields Left without throwing" $ do
+            opened <- localStorageLink (Just "no/such/dir/chusql-core-storage.toml")
+            case opened of
+                Left err -> err `shouldSatisfy` (not . null)
+                Right _ -> expectationFailure "opening a missing config file should fail"
+
+        it "without a link the storage layer reports Left instead of throwing" $ do
+            closeConnection
+            result <- runIPCStorage (scan "users")
+            result `shouldSatisfy` isLeft
+        it "INSERT then SELECT WHERE id = k" $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 _ <-
                     runIPCStorage
                         ( runStatementM
@@ -1567,13 +1570,11 @@ main = hspec $ do
                             )
                         )
                 result `shouldBe` Right [[("name", VStr "Zoe")]]
-                stopServer srv
-                logs <- readFile (dataDir srv </> "debug.log")
-                logs `shouldContain` "lookup_by_index table=ipc_idx column=id key=42"
-                logs `shouldNotContain` "scan table="
+                -- 存储层的日志现在直接打在本进程的输出里，没有单独的 debug.log 可读；
+                -- 「走索引而不是全表扫」由下面 CREATE INDEX 那组用例与 Rust 侧 runtime 测试覆盖。
 
         it "CREATE INDEX makes a query on that column use the index" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 _ <- runIPCStorage (runStatementM (CreateTable "ix_t" [("id", TInt), ("code", TInt)]))
                 _ <-
                     runIPCStorage
@@ -1599,8 +1600,8 @@ main = hspec $ do
                 fmap sortRow (indexRow fresh)
                     `shouldBe` Just (sortRow [("id", VInt 3), ("code", VInt 502)])
 
-        it "CREATE INDEX over the pipe accepts duplicates and returns every matching row" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+        it "CREATE INDEX accepts duplicates and returns every matching row" $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 _ <- runIPCStorage (runStatementM (CreateTable "dup_ix" [("id", TInt), ("age", TInt)]))
                 _ <-
                     runIPCStorage
@@ -1614,8 +1615,8 @@ main = hspec $ do
                     Right (IndexRows rows) -> map (lookup "id") rows `shouldBe` [Just (VInt 1), Just (VInt 2)]
                     _ -> expectationFailure "expected an indexed lookup with rows"
 
-        it "DELETE removes only the matching rows over the pipe" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+        it "DELETE removes only the matching rows" $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 _ <- runIPCStorage (runStatementM (CreateTable "del_t" [("id", TInt), ("name", TStr)]))
                 _ <-
                     runIPCStorage
@@ -1632,8 +1633,8 @@ main = hspec $ do
                 gone <- runIPCStorage (lookupByColumn "del_t" "id" (VInt 2))
                 gone `shouldBe` Right (IndexRows [])
 
-        it "multi-row INSERT goes over the pipe in one statement" $ do
-            withTestServer $ \srv -> withServerEnv srv $ do
+        it "multi-row INSERT goes in one statement" $ do
+            withTestSession $ \srv -> withServerEnv srv $ do
                 _ <- runIPCStorage (runStatementM (CreateTable "many_t" [("id", TInt)]))
                 _ <-
                     runIPCStorage
@@ -1676,7 +1677,7 @@ main = hspec $ do
             parseStatement "CREATE TABLE t (id)"
                 `shouldSatisfy` isLeft
 
-    describe "ChuSQL.Engine (CREATE TABLE)" $ do
+    describe "ChuSQL.Core.Engine (CREATE TABLE)" $ do
         it "creates a table in memory" $ do
             case runStatement testDB (CreateTable "newt" [("id", TInt), ("name", TStr)]) of
                 Left err -> expectationFailure err
@@ -1710,8 +1711,10 @@ main = hspec $ do
             runStatement testDB (DropTable "nope")
                 `shouldSatisfy` isLeft
 
-    describe "ChuSQL.Engine (NULL)" $ do
+    describe "ChuSQL.Core.Engine (NULL)" $ do
+        -- rows：在给定库上跑 SQL 取结果行
         let rows db input = parseStatement input >>= rowsOf . runStatement db
+            -- vals：只取结果里的值
             vals db input = fmap (map (map snd)) (rows db input)
             seeded = either (const testDB) fst (parseStatement "INSERT INTO users (id, name) VALUES (9, 'Nine')" >>= runStatement testDB)
 
@@ -1743,8 +1746,10 @@ main = hspec $ do
             vals seeded "SELECT age + 1 FROM users WHERE name = 'Nine'" `shouldBe` Right [[VNull]]
             vals seeded "SELECT age * 2 FROM users WHERE name = 'Nine'" `shouldBe` Right [[VNull]]
 
-    describe "ChuSQL.Engine (TYPES)" $ do
+    describe "ChuSQL.Core.Engine (TYPES)" $ do
+        -- vals：在给定库上跑 SQL 只取值
         let vals db input = fmap (map (map snd)) (parseStatement input >>= rowsOf . runStatement db)
+            -- withTable：先建表，返回新库
             withTable ddl = either (const testDB) fst (parseStatement ddl >>= runStatement testDB)
 
         it "parses every column type" $ do
@@ -1788,9 +1793,12 @@ main = hspec $ do
             runStatement db (Insert "sized" ["d"] [[LitInt 5]])
                 `shouldSatisfy` isLeft
 
-    describe "ChuSQL.Engine (CONSTRAINTS)" $ do
+    describe "ChuSQL.Core.Engine (CONSTRAINTS)" $ do
+        -- vals：在给定库上跑 SQL 只取值
         let vals db input = fmap (map (map snd)) (parseStatement input >>= rowsOf . runStatement db)
+            -- withTable：先建表，返回新库
             withTable ddl = either (const testDB) fst (parseStatement ddl >>= runStatement testDB)
+            -- step：执行一条语句，失败就返回原库
             step db input = either (const db) fst (parseStatement input >>= runStatement db)
 
         it "rejects omitting a NOT NULL column without a default" $ do
@@ -1819,10 +1827,14 @@ main = hspec $ do
                 `shouldSatisfy` either (isInfixOf "CHECK") (const False)
             vals (step db "INSERT INTO ck (age) VALUES (5)") "SELECT age FROM ck" `shouldBe` Right [[VInt 5]]
 
-    describe "ChuSQL.Engine (ALTER TABLE)" $ do
+    describe "ChuSQL.Core.Engine (ALTER TABLE)" $ do
+        -- vals：在给定库上跑 SQL 只取值
         let vals db input = fmap (map (map snd)) (parseStatement input >>= rowsOf . runStatement db)
+            -- run：在给定库上执行语句
             run db input = parseStatement input >>= runStatement db
+            -- withTable：先建表，返回新库
             withTable ddl = either (const testDB) fst (parseStatement ddl >>= runStatement testDB)
+            -- step：执行一条语句，失败就返回原库
             step db input = either (const db) fst (run db input)
 
         it "ADD COLUMN fills existing rows with the default or NULL" $ do
@@ -1865,77 +1877,18 @@ main = hspec $ do
             run nulls "ALTER TABLE nl ALTER COLUMN tag DROP NOT NULL" `shouldSatisfy` isRight
             run strict "ALTER TABLE nl2 ALTER COLUMN tag DROP NOT NULL" `shouldSatisfy` isRight
 
+-- | 每个测试表都清空行后的库
 emptyDB :: Database
 emptyDB = [(n, t{tableRows = []}) | (n, t) <- testDB]
 
-data IPCServer = IPCServer
-    { pipeName :: String
-    , dataDir :: FilePath
-    , processHandle :: ProcessHandle
+-- | 一次进程内存储会话：进程内直连存储动态库
+data StorageSession = StorageSession
+    { dataDir :: FilePath
     }
 
-locateServer :: IO (Either String FilePath)
-locateServer = do
-    mdir <- firstDir [".." </> "chusql-storage", "chusql-storage"]
-    case mdir of
-        Nothing -> pure (Left "chusql-storage directory not found (run these tests inside the repository)")
-        Just dir -> do
-            built <-
-                try (createProcess (proc "cargo" ["build", "--bin", "chusql-storage"]){cwd = Just dir, std_out = NoStream, std_err = NoStream}) ::
-                    IO (Either IOException (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle))
-            case built of
-                Left e -> pure (Left ("cannot run cargo (Rust is required for the IPC tests): " ++ show e))
-                Right (_, _, _, ph) -> do
-                    ec <- waitForProcess ph
-                    case ec of
-                        ExitFailure n -> pure (Left ("cargo build --bin chusql-storage failed with exit code " ++ show n))
-                        ExitSuccess -> do
-                            -- 二进制名跟平台走：Linux 上没有 .exe，而 target/debug 里可能
-                            -- 残留一份别处交叉编译出来的 .exe。误选它会以 Windows 的视角
-                            -- 读配置（/tmp/x.toml 变成 C:\tmp\x.toml），报 config file not found。
-#if defined(mingw32_HOST_OS)
-                            let candidate = dir </> "target" </> "debug" </> "chusql-storage.exe"
-#else
-                            let candidate = dir </> "target" </> "debug" </> "chusql-storage"
-#endif
-                            ok <- doesFileExist candidate
-                            pure
-                                ( if ok
-                                    then Right candidate
-                                    else Left ("cargo build finished but no storage executable was found at " ++ candidate)
-                                )
-  where
-    firstDir [] = pure Nothing
-    firstDir (d : ds) = do
-        ok <- doesDirectoryExist d
-        if ok then pure (Just d) else firstDir ds
-
-startServer :: FilePath -> IO IPCServer
-startServer bin = do
-    stamp <- uniqueStamp
-    tmp <- getTemporaryDirectory
-    let dir = tmp </> "chusql-hs-IPC" </> stamp
-    createDirectoryIfMissing True dir
-    startServerAt bin dir
-
-startServerAt :: FilePath -> FilePath -> IO IPCServer
-startServerAt bin dir = do
-    stamp <- uniqueStamp
-    let name = "chusql-hs-test-" ++ stamp
-    cfgPath <- writeServerConfig dir name
-    (_, _, _, ph) <- withFile (dir </> "debug.log") WriteMode $ \logHandle ->
-        createProcess
-            (proc bin ["--config", cfgPath])
-                { std_out = UseHandle logHandle
-                , std_err = UseHandle logHandle
-                }
-    let srv = IPCServer name dir ph
-    waitUntilReady srv 100
-    pure srv
-
--- | 给存储进程写一份顺手可用的配置：管名、数据目录与日志级别都从文件走
-writeServerConfig :: FilePath -> String -> IO FilePath
-writeServerConfig dir name = do
+-- | 写一份只属于这次会话的配置：数据目录与日志级别都从文件走
+writeSessionConfig :: FilePath -> IO FilePath
+writeSessionConfig dir = do
     let cfgPath = dir ++ ".toml"
         -- TOML 的普通字符串会吃反斜杠，路径统一用正斜杠
         slashed = map (\c -> if c == '\\' then '/' else c) dir
@@ -1944,14 +1897,27 @@ writeServerConfig dir name = do
         ( unlines
             [ "[storage]"
             , "data_dir = \"" ++ slashed ++ "\""
-            , "[server]"
-            , "pipe_name = \"" ++ name ++ "\""
             , "[log]"
             , "level = \"debug\""
             ]
         )
     pure cfgPath
 
+-- | 打开一份存储，并把它装成引擎当前用的链路
+openSessionAt :: FilePath -> IO (Either String StorageSession)
+openSessionAt dir = do
+    cfgPath <- writeSessionConfig dir
+    opened <- localStorageLink (Just cfgPath)
+    case opened of
+        Left e -> pure (Left ("cannot open the chusql_core_storage library: " ++ e))
+        Right link -> do
+            setStorageLink link
+            pure (Right (StorageSession dir))
+
+-- | 用同一份数据目录再开一次（模拟重启）
+openSessionIn :: FilePath -> IO ()
+openSessionIn dir = openSessionAt dir >>= either fail (const (pure ()))
+
 -- | 每次调用都不同的后缀：CPU 时间加唯一编号
 uniqueStamp :: IO String
 uniqueStamp = do
@@ -1959,50 +1925,52 @@ uniqueStamp = do
     u <- hashUnique <$> newUnique
     pure (show cpu ++ "-" ++ show u)
 
-waitUntilReady :: IPCServer -> Int -> IO ()
-waitUntilReady srv tries = do
-    probe <- try (withServerEnv srv (sendRequest ReqPing)) :: IO (Either IOException Response)
-    case probe of
-        Right RespPong -> pure ()
-        _ | tries > 0 -> threadDelay 50000 >> waitUntilReady srv (tries - 1)
-        Right _ -> ioError (userError "server is up but the ping answer was not pong")
-        Left e -> ioError e
-
-stopServer :: IPCServer -> IO ()
-stopServer srv = do
-    _ <- try (terminateProcess (processHandle srv)) :: IO (Either IOException ())
-    _ <- try (waitForProcess (processHandle srv)) :: IO (Either IOException ExitCode)
+-- | 删掉会话的数据目录与配置文件
+cleanSessionDir :: FilePath -> IO ()
+cleanSessionDir dir = do
+    _ <- try (removePathForcibly dir) :: IO (Either IOException ())
+    _ <- try (removePathForcibly (dir ++ ".toml")) :: IO (Either IOException ())
     pure ()
 
-cleanServerDir :: IPCServer -> IO ()
-cleanServerDir srv = do
-    _ <- try (removePathForcibly (dataDir srv)) :: IO (Either IOException ())
-    _ <- try (removePathForcibly (dataDir srv ++ ".toml")) :: IO (Either IOException ())
-    pure ()
+-- | 一个用例一份干净数据目录；动态库打不开则 pending
+withTestSession :: (StorageSession -> IO ()) -> IO ()
+withTestSession act = do
+    tmp <- getTemporaryDirectory
+    stamp <- uniqueStamp
+    let dir = tmp </> "chusql-hs-IPC" </> stamp
+    createDirectoryIfMissing True dir
+    opened <- openSessionAt dir
+    case opened of
+        Left err -> cleanSessionDir dir >> pendingWith err
+        Right session -> act session `finally` (closeConnection >> cleanSessionDir dir)
 
-withTestServer :: (IPCServer -> IO ()) -> IO ()
-withTestServer act = do
-    located <- locateServer
-    case located of
-        Left err
-            | "cannot run cargo" `isInfixOf` err -> pendingWith err
-            | otherwise -> expectationFailure err
-        Right bin -> bracket (startServer bin) (\s -> stopServer s >> cleanServerDir s) act
+-- | 语句不带库名，先建好测试库再切进去
+withServerEnv :: StorageSession -> IO a -> IO a
+withServerEnv _srv act = do
+    oldDb <- getDatabaseName
+    ensureTestDatabase
+    setDatabaseName (Just testDatabase)
+    act `finally` setDatabaseName oldDb
 
-withServerEnv :: IPCServer -> IO a -> IO a
-withServerEnv srv act = do
-    old <- getPipeName
-    setPipeName (pipeName srv)
-    act `finally` setPipeName old
+-- | IPC 用例使用的库名
+testDatabase :: String
+testDatabase = "ipctest"
 
-withPipeName :: String -> IO a -> IO a
-withPipeName name act = do
-    old <- getPipeName
-    setPipeName name
-    r <- act
-    setPipeName old
-    pure r
+-- | 保证测试库已存在
+ensureTestDatabase :: IO ()
+ensureTestDatabase = do
+    listed <- runIPCStorage listDatabases
+    case listed of
+        Left e -> fail ("cannot list databases through the storage library: " ++ e)
+        Right names
+            | testDatabase `elem` names -> pure ()
+            | otherwise -> do
+                created <- runIPCStorage (createDatabase testDatabase)
+                case created of
+                    Right () -> pure ()
+                    Left e -> fail ("cannot create the test database: " ++ e)
 
+-- | 按列名把一行排序
 sortRow :: Row -> Row
 sortRow = sortOn fst
 
@@ -2011,14 +1979,17 @@ indexRow :: Either String IndexResult -> Maybe Row
 indexRow (Right (IndexRows (r : _))) = Just r
 indexRow _ = Nothing
 
+-- | 判断 Either 是 Left
 isLeft :: Either a b -> Bool
 isLeft (Left _) = True
 isLeft (Right _) = False
 
+-- | 判断 Either 是 Right
 isRight :: Either a b -> Bool
 isRight (Right _) = True
 isRight (Left _) = False
 
+-- | 断言优化前后执行结果一致
 sameResultAsUnoptimized :: String -> Expectation
 sameResultAsUnoptimized sql =
     case parseStatement sql >>= prepare testDB of
@@ -2029,6 +2000,7 @@ sameResultAsUnoptimized sql =
                 Right relOp ->
                     evalRelOp testDB (optimize testDB relOp) `shouldBe` evalRelOp testDB relOp
 
+-- | 判断谓词是否下推到 Join 左子树
 filterPushedIntoLeft :: RelOp -> Bool
 filterPushedIntoLeft (Project _ (Join _ l _ _)) = pushedIntoLeft l
 filterPushedIntoLeft _ = False
@@ -2040,6 +2012,7 @@ pushedIntoLeft (Range _ _ _ _ _) = True
 pushedIntoLeft (Project _ x) = pushedIntoLeft x
 pushedIntoLeft _ = False
 
+-- | 解析并优化 SQL，返回计划
 optimizedPlan :: String -> Either String RelOp
 optimizedPlan sql = do
     q <- parseStatement sql
@@ -2056,6 +2029,7 @@ leftJoinKinds (Sort _ x) = leftJoinKinds x
 leftJoinKinds (Limit _ x) = leftJoinKinds x
 leftJoinKinds _ = []
 
+-- | 取计划里第一个过滤条件
 firstFilterCond :: RelOp -> Maybe Expr
 firstFilterCond (Filter p _) = Just p
 firstFilterCond (Project _ x) = firstFilterCond x
@@ -2071,6 +2045,7 @@ firstFilterCond (Scan _ _ _) = Nothing
 firstFilterCond (Lookup _ _ _ _) = Nothing
 firstFilterCond (Range _ _ _ _ _) = Nothing
 
+-- | 判断计划里是否还有过滤节点
 anyFilter :: RelOp -> Bool
 anyFilter (Filter _ _) = True
 anyFilter (Project _ x) = anyFilter x
@@ -2084,6 +2059,7 @@ anyFilter (Scan _ _ _) = False
 anyFilter (Lookup _ _ _ _) = False
 anyFilter (Range _ _ _ _ _) = False
 
+-- | 去掉计划里的投影节点
 stripProjects :: RelOp -> RelOp
 stripProjects (Project _ x) = stripProjects x
 stripProjects (Compute items x) = Compute items (stripProjects x)
@@ -2097,29 +2073,35 @@ stripProjects (Scan a t _) = Scan a t Nothing
 stripProjects (Lookup a t c k) = Lookup a t c k
 stripProjects (Range a t c lo hi) = Range a t c lo hi
 
+-- | 解析并做投影下推，返回计划
 projectedPlan :: String -> Either String RelOp
 projectedPlan sql = do
     q <- parseStatement sql
     plan <- translate q
     Right (pushProject testDB ["*"] plan)
 
+-- | 取节点输出的列名
 sideCols :: RelOp -> Maybe [String]
 sideCols (Project cols _) = Just cols
 sideCols (Scan a _ cols) = fmap (map (qualify a)) cols
 sideCols _ = Nothing
 
+-- | 取 Join 左右两侧的输出列名
 joinSideCols :: RelOp -> (Maybe [String], Maybe [String])
 joinSideCols (Project _ (Join _ l r _)) = (sideCols l, sideCols r)
 joinSideCols _ = (Nothing, Nothing)
 
+-- | 数左子树里过滤节点的个数
 countFilters :: RelOp -> Int
 countFilters (Filter _ x) = 1 + countFilters x
 countFilters _ = 0
 
+-- | 取 Join 左侧过滤节点数
 leftSideFilters :: RelOp -> Maybe Int
 leftSideFilters (Project _ (Join _ l _ _)) = Just (countFilters l)
 leftSideFilters _ = Nothing
 
+-- | 去掉外层投影，返回真正的根节点
 planRoot :: RelOp -> RelOp
 planRoot (Project _ x) = planRoot x
 planRoot x = x
diff --git a/chusql-core/model/chusql-core-model.cabal b/chusql-core/model/chusql-core-model.cabal
new file mode 100644
index 0000000..355b1e7
--- /dev/null
+++ b/chusql-core/model/chusql-core-model.cabal
@@ -0,0 +1,21 @@
+cabal-version: 2.4
+
+name:           chusql-core-model
+version:        1.0.0
+synopsis:       ChuSQL 共用数据模型与线上协议类型
+description:    ChuSQL 各进程共用的纯数据类型：列与值的模型、存储层线上协议
+                （请求/响应/表结构与账号）以及查询结果集。这里不放任何执行
+                逻辑，前端只依赖这个包就不会把引擎链进自己的二进制。
+build-type:     Simple
+
+library
+    hs-source-dirs:   src
+    exposed-modules:  ChuSQL.Core.Model
+                      ChuSQL.Core.Protocol
+    build-depends:    base >= 4.14 && < 5
+                    , aeson
+                    , hashable
+                    , scientific
+                    , text
+    default-language: Haskell2010
+    ghc-options:      -Wall
diff --git a/chusql-engine/src/ChuSQL/Model.hs b/chusql-core/model/src/ChuSQL/Core/Model.hs
similarity index 92%
rename from chusql-engine/src/ChuSQL/Model.hs
rename to chusql-core/model/src/ChuSQL/Core/Model.hs
index 0e77940..4be7cd0 100644
--- a/chusql-engine/src/ChuSQL/Model.hs
+++ b/chusql-core/model/src/ChuSQL/Core/Model.hs
@@ -1,6 +1,6 @@
 {-# LANGUAGE PatternSynonyms #-}
 
-module ChuSQL.Model
+module ChuSQL.Core.Model
     ( ColumnType (..)
     , Column (..)
     , pattern TInt
@@ -35,7 +35,7 @@ import Data.Hashable (Hashable (..))
 import Data.List (isSuffixOf, stripPrefix)
 import Data.Maybe (fromMaybe)
 
--- 数据模型：列类型、列约束、值、行、表、数据库，外加几个查表小工具。
+-- 数据模型：列类型、列约束、值、行、表、数据库，外加查表小工具。
 
 -- | 列的基础类型
 data ColumnType
@@ -70,16 +70,19 @@ data Column = Column
 plainColumn :: ColumnType -> Column
 plainColumn t = Column t True Nothing False False False Nothing
 
+-- | 普通整型列的匹配模式
 pattern TInt :: Column
 pattern TInt <- Column CInt _ _ _ _ _ _
   where
     TInt = plainColumn CInt
 
+-- | 普通字符串列的匹配模式
 pattern TStr :: Column
 pattern TStr <- Column CStr _ _ _ _ _ _
   where
     TStr = plainColumn CStr
 
+-- | 普通布尔列的匹配模式
 pattern TBool :: Column
 pattern TBool <- Column CBool _ _ _ _ _ _
   where
@@ -146,8 +149,11 @@ parseColumnType raw = case (base, args) of
     ("blob", []) -> Just CBlob
     _ -> Nothing
   where
+    -- | 去掉空白的类型名
     cleaned = map toLower (filter (not . isSpace) raw)
+    -- | 基础名与参数段
     (base, rest) = span (/= '(') cleaned
+    -- | 括号里的参数表
     args = case stripSuffixMaybe ")" (drop 1 rest) of
         Nothing -> []
         Just inner -> map (filter (not . isSpace)) (splitOn ',' inner)
@@ -193,6 +199,7 @@ data TypeClass
     | BooleanClass
     deriving (Show, Eq)
 
+-- | 整型大类判断
 typeClassOf :: ColumnType -> TypeClass
 typeClassOf CInt = NumericClass
 typeClassOf CBigInt = NumericClass
@@ -216,12 +223,14 @@ assignable target source
     | typeClassOf target == TemporalClass && typeClassOf source == TextClass = True
     | otherwise = False
 
+-- | 是不是整数类型
 integerType :: ColumnType -> Bool
 integerType CInt = True
 integerType CBigInt = True
 integerType CSmallInt = True
 integerType _ = False
 
+-- | 是不是数值类型
 numericType :: ColumnType -> Bool
 numericType t = typeClassOf t == NumericClass
 
@@ -264,6 +273,7 @@ coerceValue t v = case t of
     CTimestamp -> toTimestamp v
     CBlob -> toText t v
 
+-- | 整数收进整型列
 toInt :: ColumnType -> Value -> Either String Value
 toInt _ (VInt n) = Right (VInt n)
 toInt t (VFloat d) = case properFraction d :: (Int, Double) of
@@ -272,6 +282,7 @@ toInt t (VFloat d) = case properFraction d :: (Int, Double) of
         | otherwise -> Left ("cannot put a fractional number into " ++ typeLabel t)
 toInt t _ = Left ("cannot put this value into " ++ typeLabel t)
 
+-- | 数值收进浮点列
 toFloat :: ColumnType -> Value -> Either String Value
 toFloat _ (VInt n) = Right (VFloat (fromIntegral n))
 toFloat _ (VFloat d) = Right (VFloat d)
@@ -284,29 +295,36 @@ toDecimal p s v = case v of
     VFloat d -> rounded d
     _ -> Left ("cannot put this value into " ++ typeLabel (CDecimal p s))
   where
+    -- | 缩放因子
     scale = (10 :: Double) ^ max 0 s
+    -- | 按比例四舍五入
     rounded d = Right (VFloat (fromIntegral (round (d * scale) :: Integer) / scale))
 
+-- | 字符串收进文本列
 toText :: ColumnType -> Value -> Either String Value
 toText _ (VStr s) = Right (VStr s)
 toText t _ = Left ("cannot put this value into " ++ typeLabel t)
 
+-- | 按列长度限制收字符串
 toSized :: Int -> Value -> Either String Value
 toSized n (VStr s)
     | length s <= n = Right (VStr s)
     | otherwise = Left ("value is longer than " ++ show n ++ " characters")
 toSized _ _ = Left "cannot put this value into a character column"
 
+-- | 布尔收进布尔列
 toBool :: ColumnType -> Value -> Either String Value
 toBool _ (VBool b) = Right (VBool b)
 toBool t _ = Left ("cannot put this value into " ++ typeLabel t)
 
+-- | 字符串收进日期列
 toDate :: Value -> Either String Value
 toDate (VStr s)
     | validDateText s = Right (VStr s)
     | otherwise = Left "date must look like YYYY-MM-DD"
 toDate _ = Left "date must be a string"
 
+-- | 字符串收进时间戳列
 toTimestamp :: Value -> Either String Value
 toTimestamp (VStr s)
     | validTimestampText s = Right (VStr s)
@@ -319,7 +337,7 @@ validDateText s = case splitOn '-' s of
     [y, m, d] -> allOf 4 y && allOf 2 m && allOf 2 d
     _ -> False
 
--- | YYYY-MM-DD HH:MM:SS，日期与时间之间允许空格或 T
+-- | 日期时间格式；中间允许空格或 T
 validTimestampText :: String -> Bool
 validTimestampText s = case break (\c -> c == ' ' || c == 'T') s of
     (d, _ : tm) -> validDateText d && validTimeText tm
@@ -331,10 +349,12 @@ validTimeText t = case splitOn ':' t of
     [h, m, sec] -> allOf 2 h && allOf 2 m && allOf 2 sec
     _ -> False
 
+-- | 一段字符串是不是固定长度的数字
 allOf :: Int -> String -> Bool
 allOf n s = length s == n && all isDigit s
 
 
+-- | 引擎里的一行值
 data Value
     = VNull
     | VInt Int
@@ -343,6 +363,7 @@ data Value
     | VBool Bool
     deriving (Show, Eq)
 
+-- | 值按类型打散搅拌
 instance Hashable Value where
     hashWithSalt s VNull = hashWithSalt (hashWithSalt s (0 :: Int)) ()
     hashWithSalt s (VInt n) = hashWithSalt (hashWithSalt s (1 :: Int)) n
@@ -350,8 +371,10 @@ instance Hashable Value where
     hashWithSalt s (VStr t) = hashWithSalt (hashWithSalt s (3 :: Int)) t
     hashWithSalt s (VBool b) = hashWithSalt (hashWithSalt s (4 :: Int)) b
 
+-- | 一行数据
 type Row = [(String, Value)]
 
+-- | 一张表：名字、列定义与全部行
 data Table = Table
     { tableName :: String
     , tableCols :: [(String, Column)]
@@ -359,6 +382,7 @@ data Table = Table
     }
     deriving (Show)
 
+-- | 库：库名到表的映射
 type Database = [(String, Table)]
 
 -- | 取表的列名
@@ -373,6 +397,7 @@ colType t c = lookup c (tableCols t)
 lookupTable :: Database -> String -> Either String Table
 lookupTable db t = maybe (Left ("unknown table: " ++ t)) Right (lookup t db)
 
+-- | 通配列名
 allColumns :: String
 allColumns = "*"
 
@@ -393,4 +418,5 @@ resolveColumn name env = case [(k, v) | (k, v) <- env, matches k] of
     [] -> Left ("unknown column: " ++ name)
     _ -> Left ("ambiguous column: " ++ name)
   where
+    -- | 裸名或带后缀的名称
     matches k = k == name || ('.' : name) `isSuffixOf` k
diff --git a/chusql-core/model/src/ChuSQL/Core/Protocol.hs b/chusql-core/model/src/ChuSQL/Core/Protocol.hs
new file mode 100644
index 0000000..a6bdddd
--- /dev/null
+++ b/chusql-core/model/src/ChuSQL/Core/Protocol.hs
@@ -0,0 +1,357 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module ChuSQL.Core.Protocol (
+    SchemaColumn (..),
+    Request (..),
+    Response (..),
+    TableInfo (..),
+    Account (..),
+    QueryResult (..),
+    valueToJSON,
+    valueFromJSON,
+    rowToJSON,
+    rowFromJSON,
+    queryResultJson,
+) where
+
+import ChuSQL.Core.Model (Row, Value (..))
+import Data.Aeson (FromJSON (..), ToJSON (..), object, withObject, (.:), (.:?), (.!=), (.=))
+import qualified Data.Aeson as A
+import qualified Data.Aeson.Key as K
+import qualified Data.Aeson.KeyMap as KM
+import Data.Aeson.Types (Parser)
+import Data.Scientific (floatingOrInteger, fromFloatDigits)
+import qualified Data.Text as T
+import Data.Text (Text)
+
+-- 线上协议类型：存储层请求/响应与查询结果集。
+
+-- | 数据字典里一列的线上形状
+data SchemaColumn = SchemaColumn
+    { scName :: String
+    , scType :: String
+    , scNullable :: Bool
+    , scDefault :: Maybe Value
+    , scAutoIncrement :: Bool
+    , scPrimaryKey :: Bool
+    , scUnique :: Bool
+    , scCheck :: Maybe String
+    }
+    deriving (Show, Eq)
+
+-- | 列编码成 JSON
+instance ToJSON SchemaColumn where
+    toJSON sc =
+        object
+            [ "name" .= scName sc
+            , "ty" .= scType sc
+            , "nullable" .= scNullable sc
+            , "default" .= fmap valueToJSON (scDefault sc)
+            , "auto_increment" .= scAutoIncrement sc
+            , "primary_key" .= scPrimaryKey sc
+            , "unique" .= scUnique sc
+            , "check" .= scCheck sc
+            ]
+
+-- | JSON 解回列
+instance FromJSON SchemaColumn where
+    parseJSON = withObject "SchemaColumn" $ \o -> do
+        n <- o .: "name"
+        t <- o .: "ty"
+        nullable <- o .:? "nullable" .!= True
+        defJson <- o .:? "default"
+        def <- mapM valueFromJSON defJson
+        auto <- o .:? "auto_increment" .!= False
+        pk <- o .:? "primary_key" .!= False
+        uniq <- o .:? "unique" .!= False
+        chk <- o .:? "check"
+        pure (SchemaColumn n t nullable def auto pk uniq chk)
+
+-- | 存储层请求
+data Request
+    = ReqPing
+    | ReqDatabase String String
+    | ReqAllCatalog
+    | ReqInDatabase String Request
+    | ReqAccountsList
+    | ReqAccountCreate T.Text T.Text
+    | ReqAccountReset T.Text T.Text
+    | ReqAccountLogin T.Text (Maybe T.Text)
+    | ReqAccountDrop T.Text
+    | ReqScan String
+    | ReqScanColumns String [String]
+    | ReqInsert String Row
+    | ReqInsertBatch String [Row]
+    | ReqDeleteKeys String [Int]
+    | ReqReplaceAll String [Row]
+    | ReqListTables
+    | ReqLookupByColumn String String Value
+    | ReqRangeByIndex String String (Maybe (Value, Bool)) (Maybe (Value, Bool))
+    | ReqDescribeTable String
+    | ReqCreateTable String [SchemaColumn]
+    | ReqDropTable String
+    | ReqCreateIndex String String
+    | ReqDropIndex String String
+    | ReqDropColumn String String
+    | ReqReplaceSchema String [SchemaColumn] [Row]
+    | ReqListCatalog
+
+-- | 请求编码成 JSON
+instance ToJSON Request where
+    toJSON (ReqDatabase method name) = object ["method" .= method, "database" .= name]
+    toJSON ReqAllCatalog = object ["method" .= ("all_catalogs" :: T.Text)]
+    toJSON (ReqInDatabase name req) = case toJSON req of
+        A.Object fields -> A.Object (KM.insert "database" (A.String (T.pack name)) fields)
+        other -> other
+    toJSON ReqAccountsList = object ["method" .= ("accounts_list" :: T.Text)]
+    toJSON (ReqAccountCreate u h) = object ["method" .= ("account_create" :: T.Text), "user" .= u, "password_hash" .= h]
+    toJSON (ReqAccountReset u h) = object ["method" .= ("account_reset" :: T.Text), "user" .= u, "password_hash" .= h]
+    toJSON (ReqAccountLogin u at) = object ["method" .= ("account_login" :: T.Text), "user" .= u, "at" .= at]
+    toJSON (ReqAccountDrop u) = object ["method" .= ("account_drop" :: T.Text), "user" .= u]
+    toJSON ReqPing = object ["method" .= ("ping" :: T.Text)]
+    toJSON (ReqScan t) = object ["method" .= ("scan" :: T.Text), "table" .= t]
+    toJSON (ReqScanColumns t cols) = object ["method" .= ("scan" :: T.Text), "table" .= t, "columns" .= cols]
+    toJSON (ReqInsert t r) =
+        object
+            [ "method" .= ("insert" :: T.Text)
+            , "table" .= t
+            , "row" .= rowToJSON r
+            ]
+    toJSON (ReqInsertBatch t rs) =
+        object
+            [ "method" .= ("insert_batch" :: T.Text)
+            , "table" .= t
+            , "rows" .= map rowToJSON rs
+            ]
+    toJSON (ReqDeleteKeys t ks) =
+        object
+            [ "method" .= ("delete_keys" :: T.Text)
+            , "table" .= t
+            , "keys" .= ks
+            ]
+    toJSON (ReqReplaceAll t rs) =
+        object
+            [ "method" .= ("replace_all" :: T.Text)
+            , "table" .= t
+            , "rows" .= map rowToJSON rs
+            ]
+    toJSON ReqListTables = object ["method" .= ("list_tables" :: T.Text)]
+    toJSON (ReqLookupByColumn t c k) =
+        object
+            [ "method" .= ("lookup_by_index" :: T.Text)
+            , "table" .= t
+            , "column" .= c
+            , "key" .= valueToJSON k
+            ]
+    toJSON (ReqRangeByIndex t c lo hi) =
+        object
+            [ "method" .= ("range_by_index" :: T.Text)
+            , "table" .= t
+            , "column" .= c
+            , "lo" .= fmap (valueToJSON . fst) lo
+            , "lo_inclusive" .= maybe True snd lo
+            , "hi" .= fmap (valueToJSON . fst) hi
+            , "hi_inclusive" .= maybe True snd hi
+            ]
+    toJSON (ReqDescribeTable t) =
+        object
+            [ "method" .= ("describe_table" :: T.Text)
+            , "table" .= t
+            ]
+    toJSON (ReqCreateTable t cols) =
+        object
+            [ "method" .= ("create_table" :: T.Text)
+            , "table" .= t
+            , "columns" .= cols
+            ]
+    toJSON (ReqDropTable t) =
+        object ["method" .= ("drop_table" :: T.Text), "table" .= t]
+    toJSON (ReqCreateIndex t c) =
+        object
+            [ "method" .= ("create_index" :: T.Text)
+            , "table" .= t
+            , "column" .= c
+            ]
+    toJSON (ReqDropIndex t c) =
+        object
+            [ "method" .= ("drop_index" :: T.Text)
+            , "table" .= t
+            , "column" .= c
+            ]
+    toJSON (ReqDropColumn t c) =
+        object
+            [ "method" .= ("drop_column" :: T.Text)
+            , "table" .= t
+            , "column" .= c
+            ]
+    toJSON (ReqReplaceSchema t cols rs) =
+        object
+            [ "method" .= ("replace_schema" :: T.Text)
+            , "table" .= t
+            , "columns" .= cols
+            , "rows" .= map rowToJSON rs
+            ]
+    toJSON ReqListCatalog = object ["method" .= ("list_catalog" :: T.Text)]
+
+-- | 一张表的梗概：列、行数、索引与列统计
+data TableInfo = TableInfo
+    { tiTable :: String
+    , tiColumns :: [SchemaColumn]
+    , tiRows :: Int
+    , tiIndexes :: [String]
+    , tiStats :: [(String, Int, Bool)]
+    }
+    deriving (Show, Eq)
+
+-- | 表信息编码成 JSON
+instance ToJSON TableInfo where
+    toJSON info =
+        object
+            [ "table" .= tiTable info
+            , "columns" .= tiColumns info
+            , "row_count" .= tiRows info
+            , "indexes" .= map (\name -> object ["column" .= name]) (tiIndexes info)
+            , "stats" .= map statJson (tiStats info)
+            ]
+      where
+        statJson (name, distinct, capped) =
+            object ["name" .= name, "distinct" .= distinct, "capped" .= capped]
+
+-- | JSON 解回表信息
+instance FromJSON TableInfo where
+    parseJSON = withObject "TableInfo" $ \o -> do
+        table <- o .: "table"
+        columns <- o .: "columns"
+        count <- o .: "row_count"
+        indexes <- o .:? "indexes" .!= []
+        stats <- o .:? "stats" .!= []
+        indexColumns <- mapM (\v -> withObject "IndexWire" (.: "column") v) (indexes :: [A.Value])
+        parsedStats <- mapM parseStat (stats :: [A.Value])
+        pure (TableInfo table columns count indexColumns parsedStats)
+      where
+        parseStat = withObject "ColumnStat" $ \o -> do
+            name <- o .: "name"
+            distinct <- o .: "distinct"
+            capped <- o .:? "capped" .!= False
+            pure (name, distinct, capped)
+
+-- | 一条账号记录
+data Account = Account
+    { accountId :: Integer
+    , accountUser :: T.Text
+    , accountHash :: T.Text
+    , accountRevision :: Integer
+    , accountRegisteredAt :: T.Text
+    , accountLastLoginAt :: Maybe T.Text
+    } deriving (Eq)
+
+-- | 账号的展示：只露账号名与版本号
+instance Show Account where
+    show a = "Account " ++ show (accountUser a) ++ " revision=" ++ show (accountRevision a)
+
+-- | JSON 解回账号
+instance FromJSON Account where
+    parseJSON = withObject "Account" $ \o -> Account <$> o .: "id" <*> o .: "user"
+        <*> o .: "password_hash" <*> o .: "revision"
+        <*> o .:? "registered_at" .!= "" <*> o .:? "last_login_at"
+
+-- | 账号编码成 JSON
+instance ToJSON Account where
+    toJSON a = object ["id" .= accountId a, "user" .= accountUser a,
+        "password_hash" .= accountHash a, "revision" .= accountRevision a,
+        "registered_at" .= accountRegisteredAt a, "last_login_at" .= accountLastLoginAt a]
+
+-- | 存储层响应
+data Response
+    = RespPong
+    | RespAccounts [Account]
+    | RespRows [Row]
+    | RespTables [String]
+    | RespSchema TableInfo
+    | RespNoIndex
+    | RespOk
+    | RespError String
+    | RespCatalog [TableInfo]
+
+-- | JSON 解回响应
+instance FromJSON Response where
+    parseJSON = withObject "Response" $ \o -> do
+        status <- o .: "status"
+        case status :: T.Text of
+            "accounts" -> RespAccounts <$> o .: "accounts"
+            "pong" -> pure RespPong
+            "ok" -> pure RespOk
+            "no_index" -> pure RespNoIndex
+            "rows" -> RespRows <$> (o .: "rows" >>= mapM rowFromJSON)
+            "tables" -> RespTables <$> o .: "tables"
+            "error" -> RespError <$> o .: "message"
+            "schema" -> RespSchema <$> parseJSON (A.Object o)
+            "catalog" -> do
+                xs <- o .: "schemas" :: Parser [A.Value]
+                RespCatalog <$> mapM parseJSON xs
+            other -> fail ("unknown status: " ++ T.unpack other)
+
+-- | 值编码成 JSON
+valueToJSON :: Value -> A.Value
+valueToJSON VNull = A.Null
+valueToJSON (VInt n) = A.Number (fromIntegral n)
+valueToJSON (VFloat d) = A.Number (fromFloatDigits d)
+valueToJSON (VStr s) = A.String (T.pack s)
+valueToJSON (VBool b) = A.Bool b
+
+-- | JSON 解回值
+valueFromJSON :: A.Value -> Parser Value
+valueFromJSON A.Null = pure VNull
+valueFromJSON (A.Number n) =
+    case floatingOrInteger n :: Either Double Integer of
+        Right i -> pure (VInt (fromIntegral i))
+        Left d -> pure (VFloat d)
+valueFromJSON (A.String s) = pure (VStr (T.unpack s))
+valueFromJSON (A.Bool b) = pure (VBool b)
+valueFromJSON _ = fail "unsupported value type"
+
+-- | 一行编码成 JSON
+rowToJSON :: Row -> A.Value
+rowToJSON r =
+    A.Object (KM.fromList [(K.fromString k, valueToJSON v) | (k, v) <- r])
+
+-- | JSON 解回一行
+rowFromJSON :: A.Value -> Parser Row
+rowFromJSON (A.Object o) = mapM toPair (KM.toList o)
+  where
+    -- | 键值对解成一个字段
+    toPair (k, v) = do
+        val <- valueFromJSON v
+        pure (K.toString k, val)
+rowFromJSON _ = fail "row must be a JSON object"
+
+-- | 一条语句的结果集：列名与排好的行
+data QueryResult = QueryResult
+    { qrColumns :: [Text]
+    , qrRows :: [[Value]]
+    , qrRowCount :: Int
+    , qrTruncated :: Bool
+    , qrDatabase :: Maybe Text
+    }
+    deriving (Eq, Show)
+
+-- | JSON 解回结果集
+instance FromJSON QueryResult where
+    parseJSON = withObject "QueryResult" $ \o -> do
+        cols <- o .: "columns"
+        rows <- o .: "rows"
+        QueryResult cols <$> mapM (mapM valueFromJSON) rows
+            <*> o .:? "rowCount" .!= 0
+            <*> o .:? "truncated" .!= False
+            <*> o .:? "database"
+
+-- | 结果还原成 JSON（JSON 输出与 TCP 结果集共用）
+queryResultJson :: QueryResult -> A.Value
+queryResultJson result =
+    object
+        [ "columns" .= qrColumns result
+        , "rows" .= map (map valueToJSON) (qrRows result)
+        , "rowCount" .= qrRowCount result
+        , "truncated" .= qrTruncated result
+        , "database" .= qrDatabase result
+        ]
diff --git a/chusql-engine/stack.yaml b/chusql-core/model/stack.yaml
similarity index 100%
rename from chusql-engine/stack.yaml
rename to chusql-core/model/stack.yaml
diff --git a/chusql-core/model/stack.yaml.lock b/chusql-core/model/stack.yaml.lock
new file mode 100644
index 0000000..e3f9041
--- /dev/null
+++ b/chusql-core/model/stack.yaml.lock
@@ -0,0 +1,12 @@
+# This file was autogenerated by Stack.
+# You should not edit this file by hand.
+# For more information, please see the documentation at:
+#   https://docs.haskellstack.org/en/stable/topics/lock_files
+
+packages: []
+snapshots:
+- completed:
+    sha256: 0f728e30e843d7f00460ad56858b995a3b227fca683659c7df9f2fc3988a3ce1
+    size: 732465
+    url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/24/59.yaml
+  original: lts-24.59
diff --git a/chusql-storage/Cargo.lock b/chusql-core/storage/Cargo.lock
similarity index 89%
rename from chusql-storage/Cargo.lock
rename to chusql-core/storage/Cargo.lock
index f1473e8..d552896 100644
--- a/chusql-storage/Cargo.lock
+++ b/chusql-core/storage/Cargo.lock
@@ -15,22 +15,15 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
 
 [[package]]
-name = "chusql-storage"
+name = "chusql-core-storage"
 version = "0.1.0"
 dependencies = [
- "interprocess",
  "serde",
  "serde_json",
  "tempfile",
  "toml",
 ]
 
-[[package]]
-name = "doctest-file"
-version = "1.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c2db04e74f0a9a93103b50e90b96024c9b2bdca8bce6a632ec71b88736d3d359"
-
 [[package]]
 name = "equivalent"
 version = "1.0.2"
@@ -80,19 +73,6 @@ dependencies = [
  "hashbrown",
 ]
 
-[[package]]
-name = "interprocess"
-version = "2.4.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6cb02ffbf25e8ef0f4a95bff054eef75f6d1bf16919474cf2caa63b21997478a"
-dependencies = [
- "doctest-file",
- "libc",
- "recvmsg",
- "widestring",
- "windows-sys",
-]
-
 [[package]]
 name = "itoa"
 version = "1.0.18"
@@ -147,12 +127,6 @@ version = "6.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
 
-[[package]]
-name = "recvmsg"
-version = "1.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d3edd4d5d42c92f0a659926464d4cce56b562761267ecf0f469d85b7de384175"
-
 [[package]]
 name = "rustix"
 version = "1.1.5"
@@ -289,12 +263,6 @@ version = "1.0.26"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
 
-[[package]]
-name = "widestring"
-version = "1.2.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "72069c3113ab32ab29e5584db3c6ec55d416895e60715417b5b883a357c3e471"
-
 [[package]]
 name = "windows-link"
 version = "0.2.1"
diff --git a/chusql-storage/Cargo.toml b/chusql-core/storage/Cargo.toml
similarity index 64%
rename from chusql-storage/Cargo.toml
rename to chusql-core/storage/Cargo.toml
index 9a2db8e..37b98d1 100644
--- a/chusql-storage/Cargo.toml
+++ b/chusql-core/storage/Cargo.toml
@@ -1,12 +1,15 @@
 [package]
-name = "chusql-storage"
+name = "chusql-core-storage"
 version = "0.1.0"
 edition = "2024"
 
+[lib]
+name = "chusql_core_storage"
+crate-type = ["cdylib", "rlib"]
+
 [dependencies]
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
-interprocess = "2"
 toml = "0.8"
 
 [dev-dependencies]
diff --git a/chusql-storage/chusql-storage.toml.example b/chusql-core/storage/chusql-core-storage.toml.example
similarity index 92%
rename from chusql-storage/chusql-storage.toml.example
rename to chusql-core/storage/chusql-core-storage.toml.example
index a45fb40..7305ba6 100644
--- a/chusql-storage/chusql-storage.toml.example
+++ b/chusql-core/storage/chusql-core-storage.toml.example
@@ -29,14 +29,10 @@ pool_size = 1024
 # 要固定就写绝对路径，例如：
 # data_dir = "/srv/chusql/data"
 
-[server]
-# 命名管道名（Windows 上实际是 \\.\pipe\<这个名字>）。
-pipe_name = "chusql-joint"
-
 [log]
 # 日志等级：off / error / warn / info / debug。debug 会多打每个请求和连接。
 level = "info"
 
 # 颜色没有配置项也没有环境变量：要写的那条流是终端就着色，重定向到文件就不着色。
-# 行格式：[等级 本地日期时间] [来源] 消息；来源 core=服务自身、pipe=由管道请求触发
+# 行格式：[等级 本地日期时间] [来源] 消息；来源 core=服务自身、request=由存储请求触发
 # ERROR 加粗红、WARN 加粗橙、DEBUG 加粗不变色、INFO 不加样式
diff --git a/chusql-storage/src/btree.rs b/chusql-core/storage/src/btree.rs
similarity index 97%
rename from chusql-storage/src/btree.rs
rename to chusql-core/storage/src/btree.rs
index 2bf7131..20295ac 100644
--- a/chusql-storage/src/btree.rs
+++ b/chusql-core/storage/src/btree.rs
@@ -44,36 +44,44 @@ pub fn max_order(page_size: usize) -> usize {
     page_size.saturating_sub(HEADER) / (SLOT + max_cell_bytes()) + 1
 }
 
+/// 读一个 u8
 fn read_u8(p: &Page, off: usize) -> u8 {
     p.data[off]
 }
 
+/// 写一个 u8
 fn write_u8(p: &mut Page, off: usize, v: u8) {
     p.data[off] = v;
 }
 
+/// 读一个小端 u16
 fn read_u16(p: &Page, off: usize) -> u16 {
     u16::from_le_bytes([p.data[off], p.data[off + 1]])
 }
 
+/// 写一个小端 u16
 fn write_u16(p: &mut Page, off: usize, v: u16) {
     p.data[off..off + 2].copy_from_slice(&v.to_le_bytes());
 }
 
+/// 读一个小端 u32
 fn read_u32(p: &Page, off: usize) -> u32 {
     u32::from_le_bytes([p.data[off], p.data[off + 1], p.data[off + 2], p.data[off + 3]])
 }
 
+/// 写一个小端 u32
 fn write_u32(p: &mut Page, off: usize, v: u32) {
     p.data[off..off + 4].copy_from_slice(&v.to_le_bytes());
 }
 
+/// 读一个小端 u64
 fn read_u64(p: &Page, off: usize) -> u64 {
     let mut b = [0u8; 8];
     b.copy_from_slice(&p.data[off..off + 8]);
     u64::from_le_bytes(b)
 }
 
+/// 写一个小端 u64
 fn write_u64(p: &mut Page, off: usize, v: u64) {
     p.data[off..off + 8].copy_from_slice(&v.to_le_bytes());
 }
@@ -269,16 +277,19 @@ impl DiskBTree {
         Ok(())
     }
 
+    /// 读根页页号；空树是 None
     fn root(&mut self) -> io::Result<Option<PageId>> {
         let r = self.file.with_page(META_PAGE, |p| read_u64(p, OFF_ROOT))?;
         Ok(if r == 0 { None } else { Some(r) })
     }
 
+    /// 写根页页号
     fn set_root(&mut self, r: Option<PageId>) -> io::Result<()> {
         self.file
             .update_page(META_PAGE, |p| write_u64(p, OFF_ROOT, r.unwrap_or(0)))
     }
 
+    /// 追加一个新节点页
     fn alloc(&mut self, node: &Node) -> io::Result<PageId> {
         let page = self.file.append_page()?;
         let id = page.id;
@@ -286,10 +297,12 @@ impl DiskBTree {
         Ok(id)
     }
 
+    /// 按页号读节点
     fn load(&mut self, id: PageId) -> io::Result<Node> {
         self.file.with_page(id, get_node)
     }
 
+    /// 按页号写节点
     fn store(&mut self, id: PageId, node: &Node) -> io::Result<()> {
         self.file.update_page(id, |p| put_node(p, node))?
     }
@@ -417,6 +430,7 @@ impl DiskBTree {
         self.delete_rec(root, key, value)
     }
 
+    /// 递归删一个 (key, value)
     fn delete_rec(&mut self, id: PageId, key: &[u8], value: u64) -> io::Result<bool> {
         let mut node = self.load(id)?;
         if node.kind == NODE_LEAF {
@@ -438,7 +452,7 @@ impl DiskBTree {
         self.scan(None, None)
     }
 
-    /// 范围扫描：lo / hi 都是闭区间，None 表示这一侧不限
+    /// 范围扫描：lo / hi 都是闭区间，None 表示不限
     pub fn scan(
         &mut self,
         lo: Option<&[u8]>,
diff --git a/chusql-storage/src/catalog.rs b/chusql-core/storage/src/catalog.rs
similarity index 98%
rename from chusql-storage/src/catalog.rs
rename to chusql-core/storage/src/catalog.rs
index fbe952d..bb38dfd 100644
--- a/chusql-storage/src/catalog.rs
+++ b/chusql-core/storage/src/catalog.rs
@@ -250,7 +250,7 @@ impl Catalog {
         Ok(had_column)
     }
 
-    /// 整理完成：记住这一版已经重写过（隐藏列名要留住，防止被重新写进来）
+    /// 记住这一版已整理过（隐藏列名要留住）
     pub fn mark_compacted(&mut self, table: &str) -> io::Result<()> {
         let entry = self
             .tables
@@ -336,7 +336,7 @@ fn infer_type(v: &serde_json::Value) -> Option<String> {
     }
 }
 
-/// 旧写法与新别名都并到规范名字，参数（varchar(20)）原样保留；不认识的原样返回
+/// 类型别名统一成规范名，参数原样保留
 pub fn normalize_type(ty: &str) -> String {
     let trimmed = ty.trim();
     let (base, args) = match trimmed.find('(') {
diff --git a/chusql-storage/src/config.rs b/chusql-core/storage/src/config.rs
similarity index 79%
rename from chusql-storage/src/config.rs
rename to chusql-core/storage/src/config.rs
index 56d2e5b..0aad309 100644
--- a/chusql-storage/src/config.rs
+++ b/chusql-core/storage/src/config.rs
@@ -4,15 +4,8 @@ use serde::Deserialize;
 
 use crate::log::Level;
 
-// 全局配置：只从 TOML 文件读，没写的项回退内置默认值。
-//
-// 这个文件是整条链路的唯一配置文件，按分区各管各的：
-// 存储只看 [page]/[btree]/[buffer]/[storage]/[server]/[log]，
-// 其他分区（例如 web 的 [web]）由对应的层自己读，这里既不校验也不关心。
-// 位置是安装时定下的固定路径，只有命令行 --config 能覆盖；没有任何环境变量通道。
-// （唯一跟环境变量有关的是路径的默认值：配置文件和默认数据目录都按平台惯例算，
-//   见 default_config_path / default_data_dir，它们只是算默认位置，不是配置通道。）
-// 读一次就关，不长期占着文件句柄。
+// 全局配置：只从 TOML 文件读，缺项回退内置默认值；
+// 存储相关分区由本模块解析校验，其它层的分区一概不碰。
 
 /// 配置文件名
 pub const CONFIG_FILE_NAME: &str = "chusql.toml";
@@ -26,15 +19,13 @@ pub const DATA_DIR_NAME: &str = "data";
 pub const DEFAULT_POOL_SIZE: usize = 1024;
 pub const DEFAULT_PAGE_SIZE: usize = 4096;
 pub const DEFAULT_BTREE_ORDER: usize = 4;
-pub const DEFAULT_PIPE_NAME: &str = "chusql-joint";
 pub const DEFAULT_LOG_LEVEL: &str = "info";
 
 const MIN_PAGE_SIZE: usize = 512;
 const MAX_PAGE_SIZE: usize = 65536;
 const MIN_BTREE_ORDER: usize = 3;
 
-/// 安装后的固定配置路径：Windows 用 %APPDATA%，其它平台用 XDG 惯例。
-/// 环境变量缺失时退回相对路径 ChuSQL/chusql.toml。
+/// 默认配置文件路径（按平台惯例）
 pub fn default_config_path() -> PathBuf {
     #[cfg(windows)]
     {
@@ -60,14 +51,7 @@ pub fn default_config_path() -> PathBuf {
     PathBuf::from(APP_DIR_NAME).join(CONFIG_FILE_NAME)
 }
 
-/// [storage] data_dir 没写时的默认数据目录，按各平台惯例自动切换：
-///
-///   Windows  %LOCALAPPDATA%\ChuSQL\data（没设就退 %APPDATA%）
-///   Unix     $XDG_DATA_HOME/chusql/data（没设就是 ~/.local/share/chusql/data）
-///
-/// 跟安装脚本的默认数据目录是同一处：install.ps1 默认装到 %LOCALAPPDATA%\ChuSQL、
-/// 数据放它下面的 data\；install.sh 默认装到 ~/.local/share/chusql、数据放它下面的 data/。
-/// 环境变量都缺时才退回相对路径（跟 default_config_path 的兜底风格一致）。
+/// Windows 默认数据目录
 #[cfg(windows)]
 pub fn default_data_dir() -> PathBuf {
     let local = std::env::var_os("LOCALAPPDATA").filter(|v| !v.is_empty());
@@ -81,7 +65,7 @@ pub fn default_data_dir() -> PathBuf {
     PathBuf::from(APP_DIR_NAME).join(DATA_DIR_NAME)
 }
 
-/// 见 Windows 版本的注释：这里走 XDG 惯例。
+/// Unix 默认数据目录（XDG 惯例）
 #[cfg(not(windows))]
 pub fn default_data_dir() -> PathBuf {
     let xdg = std::env::var_os("XDG_DATA_HOME").filter(|v| !v.is_empty());
@@ -107,18 +91,17 @@ pub struct Config {
     pub btree_order: usize,
     pub pool_size: usize,
     pub data_dir: PathBuf,
-    pub pipe_name: String,
     pub log_level: Level,
 }
 
 impl Default for Config {
+    /// 内置默认配置
     fn default() -> Self {
         Config {
             page_size: DEFAULT_PAGE_SIZE,
             btree_order: DEFAULT_BTREE_ORDER,
             pool_size: DEFAULT_POOL_SIZE,
             data_dir: default_data_dir(),
-            pipe_name: DEFAULT_PIPE_NAME.to_string(),
             log_level: Level::Info,
         }
     }
@@ -153,7 +136,6 @@ struct FileConfig {
     btree: Option<FileBtree>,
     buffer: Option<FileBuffer>,
     storage: Option<FileStorage>,
-    server: Option<FileServer>,
     log: Option<FileLog>,
 }
 
@@ -181,19 +163,13 @@ struct FileStorage {
     data_dir: Option<String>,
 }
 
-#[derive(Debug, Default, Deserialize)]
-#[serde(deny_unknown_fields)]
-struct FileServer {
-    pipe_name: Option<String>,
-}
-
 #[derive(Debug, Default, Deserialize)]
 #[serde(deny_unknown_fields)]
 struct FileLog {
     level: Option<String>,
 }
 
-/// 加载配置：explicit 有值就用它（读不到要报错），否则用固定安装路径（存在才读）
+/// 加载配置：显式路径优先，其次默认位置
 pub fn load(explicit: Option<&str>) -> Result<Loaded, String> {
     let explicit = explicit.map(str::trim).filter(|p| !p.is_empty());
     let path = match explicit {
@@ -249,15 +225,11 @@ pub fn resolve(text: Option<&str>, path: Option<PathBuf>) -> Result<Loaded, Stri
         &file_origin,
     );
     let (data_dir, dir_origin) = pick(
-        file.storage.and_then(|s| s.data_dir),
+        file.storage.as_ref().and_then(|s| s.data_dir.clone()),
         default_data_dir().to_string_lossy().into_owned(),
         &file_origin,
     );
-    let (pipe_name, pipe_origin) = pick(
-        file.server.and_then(|s| s.pipe_name),
-        DEFAULT_PIPE_NAME.to_string(),
-        &file_origin,
-    );
+    // 管名已经没有了：存储不再是独立进程，管道/套接字那一层随 FFI 一起删掉
     let (log_level, log_origin) = pick(
         file.log.and_then(|l| l.level),
         DEFAULT_LOG_LEVEL.to_string(),
@@ -265,7 +237,6 @@ pub fn resolve(text: Option<&str>, path: Option<PathBuf>) -> Result<Loaded, Stri
     );
 
     let data_dir = data_dir.trim().to_string();
-    let pipe_name = pipe_name.trim().to_string();
     let log_level = log_level.trim().to_string();
 
     let log_level = Level::parse(&log_level)
@@ -274,9 +245,6 @@ pub fn resolve(text: Option<&str>, path: Option<PathBuf>) -> Result<Loaded, Stri
     if data_dir.is_empty() {
         return Err("storage.data_dir must not be empty".to_string());
     }
-    if pipe_name.is_empty() {
-        return Err("server.pipe_name must not be empty".to_string());
-    }
     validate_layout(page_size, btree_order)?;
     if pool_size == 0 {
         return Err("buffer.pool_size must be at least 1".to_string());
@@ -286,7 +254,6 @@ pub fn resolve(text: Option<&str>, path: Option<PathBuf>) -> Result<Loaded, Stri
         ("btree.order", btree_order.to_string(), order_origin),
         ("buffer.pool_size", pool_size.to_string(), pool_origin),
         ("storage.data_dir", data_dir.clone(), dir_origin),
-        ("server.pipe_name", pipe_name.clone(), pipe_origin),
         ("log.level", log_level.name().to_string(), log_origin),
     ];
 
@@ -296,7 +263,6 @@ pub fn resolve(text: Option<&str>, path: Option<PathBuf>) -> Result<Loaded, Stri
             btree_order,
             pool_size,
             data_dir: PathBuf::from(data_dir),
-            pipe_name,
             log_level,
         },
         config_path: if text.is_some() { path } else { None },
@@ -341,7 +307,7 @@ fn validate_layout(page_size: usize, btree_order: usize) -> Result<(), String> {
 mod tests {
     use super::*;
 
-    /// 全局配置里别的层（例如 web）的分区不能被存储层当成错误
+    /// 别的层的分区不能被当成错误
     #[test]
     fn ignores_sections_owned_by_other_layers() {
         let text = r#"
@@ -351,8 +317,13 @@ size = 8192
 [storage]
 data_dir = "../data"
 
-[web]
+[server]
+host = "127.0.0.1"
 port = 7777
+max_message = 1048576
+
+[web]
+port = 7778
 user = "root"
 "#;
         let loaded = resolve(Some(text), Some(PathBuf::from("chusql.toml"))).unwrap();
diff --git a/chusql-core/storage/src/ffi.rs b/chusql-core/storage/src/ffi.rs
new file mode 100644
index 0000000..83ee5a2
--- /dev/null
+++ b/chusql-core/storage/src/ffi.rs
@@ -0,0 +1,154 @@
+use std::cell::RefCell;
+use std::ffi::{c_char, CStr};
+use std::panic::{catch_unwind, AssertUnwindSafe};
+use std::ptr;
+use std::slice;
+
+use crate::runtime::Storage;
+
+// C ABI：Haskell 侧唯一存储入口，请求与响应都是 UTF-8 JSON。
+// 不 panic 穿过边界，失败走线程局部 last_error。
+
+const OK: i32 = 0;
+const ERR: i32 = -1;
+
+thread_local! {
+    static LAST_ERROR: RefCell<Vec<u8>> = const { RefCell::new(Vec::new()) };
+}
+
+/// 记下本线程最近的失败信息
+fn set_error(message: impl AsRef<str>) {
+    let text = message.as_ref().as_bytes().to_vec();
+    LAST_ERROR.with(|slot| *slot.borrow_mut() = text);
+}
+
+/// 版本号字符串（静态常量，调用方不要释放）。
+#[unsafe(no_mangle)]
+pub extern "C" fn chusql_storage_version() -> *const c_char {
+    const VERSION: &str = concat!(env!("CARGO_PKG_VERSION"), "\0");
+    VERSION.as_ptr() as *const c_char
+}
+
+/// 打开数据目录；失败返回 NULL
+///
+/// # Safety
+/// `config_path` 要么是 NULL，要么指向以 NUL 结尾的有效字符串。
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn chusql_storage_open(config_path: *const c_char) -> *mut Storage {
+    let opened = catch_unwind(AssertUnwindSafe(|| {
+        let path = if config_path.is_null() {
+            None
+        } else {
+            let text = unsafe { CStr::from_ptr(config_path) }
+                .to_str()
+                .map_err(|_| "config path is not valid UTF-8".to_string())?;
+            if text.is_empty() { None } else { Some(text.to_string()) }
+        };
+        Storage::open(path.as_deref()).map(Box::new)
+    }));
+    match opened {
+        Ok(Ok(storage)) => Box::into_raw(storage),
+        Ok(Err(e)) => {
+            set_error(e);
+            ptr::null_mut()
+        }
+        Err(_) => {
+            set_error("panic in chusql_storage_open");
+            ptr::null_mut()
+        }
+    }
+}
+
+/// 关闭句柄（NULL 安全）
+///
+/// # Safety
+/// `handle` 必须是 chusql_storage_open 返回且未被关闭过的句柄。
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn chusql_storage_close(handle: *mut Storage) {
+    if handle.is_null() {
+        return;
+    }
+    let _ = catch_unwind(AssertUnwindSafe(|| unsafe { drop(Box::from_raw(handle)) }));
+}
+
+/// 处理一条请求，响应缓冲须归还
+///
+/// # Safety
+/// `handle` 必须是有效句柄；`request` 指向 `request_len` 个字节；`out`/`out_len` 可写。
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn chusql_storage_request(
+    handle: *const Storage,
+    request: *const u8,
+    request_len: usize,
+    out: *mut *mut u8,
+    out_len: *mut usize,
+) -> i32 {
+    if !out.is_null() {
+        unsafe { *out = ptr::null_mut() };
+    }
+    if !out_len.is_null() {
+        unsafe { *out_len = 0 };
+    }
+    if handle.is_null() || request.is_null() || out.is_null() || out_len.is_null() {
+        set_error("invalid argument");
+        return ERR;
+    }
+
+    let storage = unsafe { &*handle };
+    let bytes = unsafe { slice::from_raw_parts(request, request_len) };
+    let text = match std::str::from_utf8(bytes) {
+        Ok(text) => text,
+        Err(e) => {
+            set_error(format!("request is not valid UTF-8: {}", e));
+            return ERR;
+        }
+    };
+
+    let response = match catch_unwind(AssertUnwindSafe(|| storage.request_line(text))) {
+        Ok(response) => response,
+        Err(_) => {
+            set_error("panic in chusql_storage_request");
+            return ERR;
+        }
+    };
+
+    let mut buffer = response.into_bytes().into_boxed_slice();
+    let ptr = buffer.as_mut_ptr();
+    let len = buffer.len();
+    std::mem::forget(buffer);
+    unsafe {
+        *out = ptr;
+        *out_len = len;
+    }
+    OK
+}
+
+/// 归还响应缓冲
+///
+/// # Safety
+/// `data`/`len` 必须是 chusql_storage_request 原样返回且未被释放过的一对值。
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn chusql_storage_free(data: *mut u8, len: usize) {
+    if data.is_null() {
+        return;
+    }
+    let _ = catch_unwind(AssertUnwindSafe(|| unsafe {
+        let slice = ptr::slice_from_raw_parts_mut(data, len);
+        let _owned: Box<[u8]> = Box::from_raw(slice);
+    }));
+}
+
+/// 取本线程最近的失败信息
+///
+/// # Safety
+/// `out_len` 可写，或为 NULL。
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn chusql_storage_last_error(out_len: *mut usize) -> *const u8 {
+    LAST_ERROR.with(|slot| {
+        let bytes = slot.borrow();
+        if !out_len.is_null() {
+            unsafe { *out_len = bytes.len() };
+        }
+        if bytes.is_empty() { ptr::null() } else { bytes.as_ptr() }
+    })
+}
diff --git a/chusql-storage/src/heap.rs b/chusql-core/storage/src/heap.rs
similarity index 98%
rename from chusql-storage/src/heap.rs
rename to chusql-core/storage/src/heap.rs
index 887d443..77ff28a 100644
--- a/chusql-storage/src/heap.rs
+++ b/chusql-core/storage/src/heap.rs
@@ -20,9 +20,11 @@ fn decode_row(bytes: &[u8], columns: Option<&[String]>, hidden: &HashSet<String>
     struct RowVisitor<'a>(Option<&'a [String]>, &'a HashSet<String>);
     impl<'de> Visitor<'de> for RowVisitor<'_> {
         type Value = Row;
+        /// 说明期望的输入形态
         fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
             f.write_str("a row object")
         }
+        /// 逐字段解出一行
         fn visit_map<M: MapAccess<'de>>(self, mut map: M) -> Result<Row, M::Error> {
             let mut row = Row::new();
             while let Some(key) = map.next_key::<String>()? {
@@ -284,7 +286,7 @@ impl HeapTable {
         self.indexes.iter().any(|i| i.column == column)
     }
 
-    /// 建索引：要求这一列取值唯一
+    /// 建索引：id 列必须唯一，其余列可重复
     pub fn build_index(
         &mut self,
         column: &str,
@@ -360,10 +362,12 @@ impl HeapTable {
         }
     }
 
+    /// 设置隐藏列集合
     pub fn set_hidden_columns(&mut self, columns: HashSet<String>) {
         self.hidden_columns = columns;
     }
 
+    /// 隐藏一列并摘掉它的索引
     pub fn hide_column(&mut self, column: &str) {
         self.detach_index(column);
         self.hidden_columns.insert(column.to_string());
@@ -487,7 +491,7 @@ impl HeapTable {
         Ok(rows)
     }
 
-    /// 范围扫描：某一列有索引就走叶子链，没有索引返回 None（上层退回全表扫描）
+    /// 按索引做范围扫描；没索引返回 None
     pub fn scan_range(
         &mut self,
         column: &str,
@@ -595,6 +599,7 @@ impl HeapTable {
         self.scan_columns(None)
     }
 
+    /// 全表扫描，只解码指定列
     pub fn scan_columns(&mut self, columns: Option<&[String]>) -> io::Result<Vec<Row>> {
         Ok(self
             .scan_projected_with_positions(columns)?
@@ -608,6 +613,7 @@ impl HeapTable {
         self.scan_projected_with_positions(None)
     }
 
+    /// 全表扫描，带位置与列投影
     fn scan_projected_with_positions(&mut self, columns: Option<&[String]>) -> io::Result<Vec<(PageId, u16, Row)>> {
         let n = self.file.num_pages()?;
         let mut out = Vec::new();
diff --git a/chusql-storage/src/initsql.rs b/chusql-core/storage/src/initsql.rs
similarity index 94%
rename from chusql-storage/src/initsql.rs
rename to chusql-core/storage/src/initsql.rs
index 035b903..13c2037 100644
--- a/chusql-storage/src/initsql.rs
+++ b/chusql-core/storage/src/initsql.rs
@@ -1,8 +1,8 @@
-//! `scripts/init.sql` 的最小读取：只认 CREATE TABLE 与 CREATE INDEX。
-//! 系统库的 schema 由这份脚本声明，存储进程按它建系统表。
-
 use crate::protocol::SchemaColumn;
 
+// 读取 scripts/init.sql，只认 CREATE TABLE 与 CREATE INDEX。
+// 系统库的 schema 由这份脚本声明，进程按它建系统表。
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct InitColumn {
     pub name: String,
@@ -68,7 +68,7 @@ pub fn parse(text: &str) -> Result<Vec<InitTable>, String> {
     Ok(tables)
 }
 
-/// 一行一列：`name type [NOT NULL] [AUTO_INCREMENT] [PRIMARY KEY] [UNIQUE]`
+/// 解析表定义里的列清单
 fn columns(body: &str) -> Result<Vec<InitColumn>, String> {
     let mut out = Vec::new();
     for part in split_top_level(body) {
@@ -166,8 +166,9 @@ mod tests {
     use super::*;
 
     /// 仓库里的系统库脚本必须始终能解析
-    const SYSTEM_SCHEMA: &str = include_str!("../../scripts/init.sql");
+    const SYSTEM_SCHEMA: &str = include_str!("../../../scripts/init.sql");
 
+    /// 仓库自带脚本必须能解析出账号表
     #[test]
     fn parses_the_repository_init_script() {
         let tables = parse(SYSTEM_SCHEMA).expect("scripts/init.sql must parse");
@@ -186,6 +187,7 @@ mod tests {
         assert_eq!(users.indexes, ["user"]);
     }
 
+    /// 未知语句与表级约束要报错
     #[test]
     fn rejects_unknown_statements_and_table_level_constraints() {
         assert!(parse("DROP TABLE users;").is_err());
@@ -193,6 +195,7 @@ mod tests {
         assert!(parse("CREATE INDEX missing (user);").is_err());
     }
 
+    /// 注释与空语句要被跳过
     #[test]
     fn ignores_comments_and_blank_statements() {
         let tables = parse("-- note\nCREATE TABLE t (a int NOT NULL);\n\n/* done */\n").unwrap();
diff --git a/chusql-storage/src/lib.rs b/chusql-core/storage/src/lib.rs
similarity index 88%
rename from chusql-storage/src/lib.rs
rename to chusql-core/storage/src/lib.rs
index a459a57..e1e58f9 100644
--- a/chusql-storage/src/lib.rs
+++ b/chusql-core/storage/src/lib.rs
@@ -1,12 +1,13 @@
 // 存储层库入口：对外暴露下面这些模块，服务与集成测试都从这里引。
 
 pub mod btree;
+pub mod catalog;
 pub mod config;
-pub mod endpoint;
+pub mod ffi;
 pub mod heap;
 pub mod initsql;
 pub mod log;
 pub mod page;
 pub mod protocol;
-pub mod catalog;
+pub mod runtime;
 pub mod wal;
diff --git a/chusql-storage/src/log.rs b/chusql-core/storage/src/log.rs
similarity index 89%
rename from chusql-storage/src/log.rs
rename to chusql-core/storage/src/log.rs
index 7013fab..8b9a159 100644
--- a/chusql-storage/src/log.rs
+++ b/chusql-core/storage/src/log.rs
@@ -22,7 +22,7 @@ pub enum Level {
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Channel {
     Core,
-    Pipe,
+    Request,
 }
 
 impl Channel {
@@ -30,7 +30,7 @@ impl Channel {
     fn tag(self) -> &'static str {
         match self {
             Channel::Core => "core",
-            Channel::Pipe => "pipe",
+            Channel::Request => "request",
         }
     }
 }
@@ -102,7 +102,7 @@ pub fn init() {
     enable_vt();
 }
 
-/// 写出一行：warn / error 走 stderr，info / debug 走 stdout。
+/// 写出一行日志，按等级选流向
 pub fn write(channel: Channel, level: Level, args: fmt::Arguments) {
     let msg = args.to_string();
     let to_stderr = streams_to_stderr(level);
@@ -116,12 +116,12 @@ pub fn write(channel: Channel, level: Level, args: fmt::Arguments) {
     }
 }
 
-/// 这个等级写 stderr 吗：warn / error 是，info / debug 写 stdout
+/// 这个等级是否写 stderr
 fn streams_to_stderr(level: Level) -> bool {
     matches!(level, Level::Error | Level::Warn)
 }
 
-/// 是否着色：只按要写的那条流是不是终端判断，没有环境变量开关
+/// 按目标流是否终端决定是否着色
 fn color_enabled(to_stderr: bool) -> bool {
     let cached = if to_stderr { &COLOR_STDERR } else { &COLOR_STDOUT };
     *cached.get_or_init(|| if to_stderr { std::io::stderr().is_terminal() } else { std::io::stdout().is_terminal() })
@@ -151,6 +151,7 @@ pub struct Stamp {
 }
 
 impl fmt::Display for Stamp {
+    /// 格式化成时间戳文本
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(
             f,
@@ -266,8 +267,8 @@ macro_rules! log_debug {
     (core, $($arg:tt)*) => {
         $crate::log_line!($crate::log::Channel::Core, $crate::log::Level::Debug, $($arg)*)
     };
-    (pipe, $($arg:tt)*) => {
-        $crate::log_line!($crate::log::Channel::Pipe, $crate::log::Level::Debug, $($arg)*)
+    (request, $($arg:tt)*) => {
+        $crate::log_line!($crate::log::Channel::Request, $crate::log::Level::Debug, $($arg)*)
     };
 }
 
@@ -276,8 +277,8 @@ macro_rules! log_info {
     (core, $($arg:tt)*) => {
         $crate::log_line!($crate::log::Channel::Core, $crate::log::Level::Info, $($arg)*)
     };
-    (pipe, $($arg:tt)*) => {
-        $crate::log_line!($crate::log::Channel::Pipe, $crate::log::Level::Info, $($arg)*)
+    (request, $($arg:tt)*) => {
+        $crate::log_line!($crate::log::Channel::Request, $crate::log::Level::Info, $($arg)*)
     };
 }
 
@@ -286,8 +287,8 @@ macro_rules! log_warn {
     (core, $($arg:tt)*) => {
         $crate::log_line!($crate::log::Channel::Core, $crate::log::Level::Warn, $($arg)*)
     };
-    (pipe, $($arg:tt)*) => {
-        $crate::log_line!($crate::log::Channel::Pipe, $crate::log::Level::Warn, $($arg)*)
+    (request, $($arg:tt)*) => {
+        $crate::log_line!($crate::log::Channel::Request, $crate::log::Level::Warn, $($arg)*)
     };
 }
 
@@ -296,8 +297,8 @@ macro_rules! log_error {
     (core, $($arg:tt)*) => {
         $crate::log_line!($crate::log::Channel::Core, $crate::log::Level::Error, $($arg)*)
     };
-    (pipe, $($arg:tt)*) => {
-        $crate::log_line!($crate::log::Channel::Pipe, $crate::log::Level::Error, $($arg)*)
+    (request, $($arg:tt)*) => {
+        $crate::log_line!($crate::log::Channel::Request, $crate::log::Level::Error, $($arg)*)
     };
 }
 
@@ -315,6 +316,7 @@ macro_rules! log_line {
 mod tests {
     use super::*;
 
+    /// 已知日期换算要正确
     #[test]
     fn civil_from_days_known_dates() {
         assert_eq!(civil_from_days(0), (1970, 1, 1));
@@ -324,6 +326,7 @@ mod tests {
         assert_eq!(civil_from_days(19_782), (2024, 2, 29));
     }
 
+    /// 行里要有等级、时间与来源
     #[test]
     fn render_has_time_channel_and_colors() {
         let stamp = Stamp {
@@ -337,16 +340,16 @@ mod tests {
         };
 
         assert_eq!(
-            render(Level::Error, Channel::Pipe, true, &stamp, "boom"),
-            "[\u{1b}[1m\u{1b}[31mERROR\u{1b}[0m 2026-09-24 13:45:12.130] [pipe] boom"
+            render(Level::Error, Channel::Request, true, &stamp, "boom"),
+            "[\u{1b}[1m\u{1b}[31mERROR\u{1b}[0m 2026-09-24 13:45:12.130] [request] boom"
         );
         assert_eq!(
             render(Level::Warn, Channel::Core, true, &stamp, "careful"),
             "[\u{1b}[1m\u{1b}[38;5;208mWARN \u{1b}[0m 2026-09-24 13:45:12.130] [core] careful"
         );
         assert_eq!(
-            render(Level::Debug, Channel::Pipe, true, &stamp, "detail"),
-            "[\u{1b}[1mDEBUG\u{1b}[0m 2026-09-24 13:45:12.130] [pipe] detail"
+            render(Level::Debug, Channel::Request, true, &stamp, "detail"),
+            "[\u{1b}[1mDEBUG\u{1b}[0m 2026-09-24 13:45:12.130] [request] detail"
         );
         assert_eq!(
             render(Level::Info, Channel::Core, true, &stamp, "hello"),
@@ -354,6 +357,7 @@ mod tests {
         );
     }
 
+    /// warn 与 error 走 stderr
     #[test]
     fn warnings_and_errors_go_to_stderr() {
         assert!(streams_to_stderr(Level::Error));
diff --git a/chusql-storage/src/page.rs b/chusql-core/storage/src/page.rs
similarity index 99%
rename from chusql-storage/src/page.rs
rename to chusql-core/storage/src/page.rs
index 72316ad..02dfe6f 100644
--- a/chusql-storage/src/page.rs
+++ b/chusql-core/storage/src/page.rs
@@ -282,6 +282,7 @@ impl PageFile {
 }
 
 impl Drop for PageFile {
+    /// 析构时把脏页写回
     fn drop(&mut self) {
         let _ = self.flush();
     }
diff --git a/chusql-storage/src/protocol.rs b/chusql-core/storage/src/protocol.rs
similarity index 98%
rename from chusql-storage/src/protocol.rs
rename to chusql-core/storage/src/protocol.rs
index 6ea5c24..bc20fd4 100644
--- a/chusql-storage/src/protocol.rs
+++ b/chusql-core/storage/src/protocol.rs
@@ -38,6 +38,7 @@ pub struct SchemaColumn {
 }
 
 impl Default for SchemaColumn {
+    /// 列定义的默认值
     fn default() -> Self {
         SchemaColumn {
             name: String::new(),
@@ -52,6 +53,7 @@ impl Default for SchemaColumn {
     }
 }
 
+/// serde 里缺省为真
 fn default_true() -> bool {
     true
 }
@@ -188,6 +190,7 @@ impl Request {
     }
 }
 
+/// 是不是保留系统表名
 pub fn reserved_table(table: &str) -> bool {
     table.to_ascii_lowercase().starts_with("__chusql_")
 }
diff --git a/chusql-storage/src/bin/chusql-storage.rs b/chusql-core/storage/src/runtime.rs
similarity index 87%
rename from chusql-storage/src/bin/chusql-storage.rs
rename to chusql-core/storage/src/runtime.rs
index 6764567..b299d0f 100644
--- a/chusql-storage/src/bin/chusql-storage.rs
+++ b/chusql-core/storage/src/runtime.rs
@@ -1,26 +1,21 @@
 use std::collections::HashMap;
-use std::io::{BufRead, BufReader, Write};
 use std::path::PathBuf;
-use std::sync::{Arc, Mutex};
 use std::sync::atomic::{AtomicBool, Ordering};
-use std::thread;
+use std::sync::{Arc, Mutex};
 
-use chusql_storage::catalog::Catalog;
-use chusql_storage::config::{self, Config, Loaded};
-use chusql_storage::endpoint;
-use chusql_storage::heap::HeapTable;
-use chusql_storage::initsql::{self, InitColumn, InitTable};
-use chusql_storage::log;
-use chusql_storage::protocol::{
+use crate::catalog::Catalog;
+use crate::config::{self, Config, Loaded};
+use crate::heap::HeapTable;
+use crate::initsql::{self, InitColumn, InitTable};
+use crate::log;
+use crate::protocol::{
     reserved_table, Account, ColumnStatWire, IndexWire, Request, Response, Row, SchemaColumn, TableSchemaWire, USERS_TABLE,
 };
-use chusql_storage::wal::{Wal, WalOp};
-use chusql_storage::{log_debug, log_error, log_info, log_warn};
-use interprocess::local_socket::prelude::*;
-use interprocess::TryClone;
+use crate::wal::{Wal, WalOp};
+use crate::{log_debug, log_error, log_info, log_warn};
 
-// 本地套接字服务：按行读写 JSON。端点地址由 endpoint 模块给出：
-// Windows 是具名管道 \\.\pipe\<name>，Unix 是文件系统套接字 <dir>/<name>.sock。
+// 进程内存储运行时：Haskell 侧经 ffi.rs 调进来。
+// request_line 的语义等同原来的「一行 JSON 请求 → 一行 JSON 响应」套接字协议。
 
 struct Server {
     cfg: Config,
@@ -360,7 +355,7 @@ impl Server {
         Ok(())
     }
 
-    /// 旧类型系统留下的数据升级到新格式：列类型名规范化、缺列的行补 null
+    /// 老数据迁移：类型名规范、缺列补 null
     fn migrate_data(&self) -> std::io::Result<()> {
         let names: Vec<String> = self
             .catalog
@@ -647,12 +642,12 @@ impl Server {
                 }
             }
             Request::Ping => {
-                log_debug!(pipe, "ping");
+                log_debug!(request, "ping");
                 Response::Pong
             }
 
             Request::Scan { table, columns } => {
-                log_debug!(pipe, "scan table={}", table);
+                log_debug!(request, "scan table={}", table);
 
                 let result = (|| {
                     if let Some(cols) = &columns {
@@ -670,7 +665,7 @@ impl Server {
                 match result {
                     Ok(rows) => Response::Rows { rows },
                     Err(e) => {
-                        log_warn!(pipe, "scan {}: {}", table, e);
+                        log_warn!(request, "scan {}: {}", table, e);
                         Response::Error {
                             message: format!("scan {}: {}", table, e),
                         }
@@ -679,13 +674,13 @@ impl Server {
             }
 
             Request::Insert { table, row } => {
-                log_debug!(pipe, "insert table={}", table);
+                log_debug!(request, "insert table={}", table);
                 let tname = table.clone();
                 let op = WalOp::Insert { table, row };
                 match self.write_via_wal(&op) {
                     Ok(()) => Response::Ok,
                     Err(e) => {
-                        log_warn!(pipe, "insert {}: {}", tname, e);
+                        log_warn!(request, "insert {}: {}", tname, e);
                         Response::Error {
                             message: format!("insert {}: {}", tname, e),
                         }
@@ -694,13 +689,13 @@ impl Server {
             }
 
             Request::InsertBatch { table, rows } => {
-                log_debug!(pipe, "insert_batch table={} rows={}", table, rows.len());
+                log_debug!(request, "insert_batch table={} rows={}", table, rows.len());
                 let tname = table.clone();
                 let op = WalOp::InsertBatch { table, rows };
                 match self.write_via_wal(&op) {
                     Ok(()) => Response::Ok,
                     Err(e) => {
-                        log_warn!(pipe, "insert_batch {}: {}", tname, e);
+                        log_warn!(request, "insert_batch {}: {}", tname, e);
                         Response::Error {
                             message: format!("insert_batch {}: {}", tname, e),
                         }
@@ -709,13 +704,13 @@ impl Server {
             }
 
             Request::DeleteKeys { table, keys } => {
-                log_debug!(pipe, "delete_keys table={} keys={}", table, keys.len());
+                log_debug!(request, "delete_keys table={} keys={}", table, keys.len());
                 let tname = table.clone();
                 let op = WalOp::DeleteKeys { table, keys };
                 match self.write_via_wal(&op) {
                     Ok(()) => Response::Ok,
                     Err(e) => {
-                        log_warn!(pipe, "delete_keys {}: {}", tname, e);
+                        log_warn!(request, "delete_keys {}: {}", tname, e);
                         Response::Error {
                             message: format!("delete_keys {}: {}", tname, e),
                         }
@@ -724,12 +719,12 @@ impl Server {
             }
 
             Request::LookupByIndex { table, column, key } => {
-                log_debug!(pipe, "lookup_by_index table={} column={} key={}", table, column, key);
+                log_debug!(request, "lookup_by_index table={} column={} key={}", table, column, key);
                 let indexed =
                     match self.with_existing_table(&table, |t| Ok(t.has_index(&column))) {
                         Ok(v) => v,
                         Err(e) => {
-                            log_warn!(pipe, "lookup_by_index {}: {}", table, e);
+                            log_warn!(request, "lookup_by_index {}: {}", table, e);
                             return Response::Error {
                                 message: format!("lookup_by_index {}: {}", table, e),
                             };
@@ -752,7 +747,7 @@ impl Server {
                 match found {
                     Ok(rows) => Response::Rows { rows },
                     Err(e) => {
-                        log_warn!(pipe, "lookup_by_index {}: {}", table, e);
+                        log_warn!(request, "lookup_by_index {}: {}", table, e);
                         Response::Error {
                             message: format!("lookup_by_index {}: {}", table, e),
                         }
@@ -761,12 +756,12 @@ impl Server {
             }
 
             Request::RangeByIndex { table, column, lo, lo_inclusive, hi, hi_inclusive } => {
-                log_debug!(pipe, "range_by_index table={} column={}", table, column);
+                log_debug!(request, "range_by_index table={} column={}", table, column);
                 let indexed =
                     match self.with_existing_table(&table, |t| Ok(t.has_index(&column))) {
                         Ok(v) => v,
                         Err(e) => {
-                            log_warn!(pipe, "range_by_index {}: {}", table, e);
+                            log_warn!(request, "range_by_index {}: {}", table, e);
                             return Response::Error {
                                 message: format!("range_by_index {}: {}", table, e),
                             };
@@ -781,7 +776,7 @@ impl Server {
                     Ok(Some(rows)) => Response::Rows { rows },
                     Ok(None) => Response::NoIndex,
                     Err(e) => {
-                        log_warn!(pipe, "range_by_index {}: {}", table, e);
+                        log_warn!(request, "range_by_index {}: {}", table, e);
                         Response::Error {
                             message: format!("range_by_index {}: {}", table, e),
                         }
@@ -790,13 +785,13 @@ impl Server {
             }
 
             Request::ReplaceAll { table, rows } => {
-                log_debug!(pipe, "replace_all table={} rows={}", table, rows.len());
+                log_debug!(request, "replace_all table={} rows={}", table, rows.len());
                 let tname = table.clone();
                 let op = WalOp::ReplaceAll { table, rows };
                 match self.write_via_wal(&op) {
                     Ok(()) => Response::Ok,
                     Err(e) => {
-                        log_warn!(pipe, "replace_all {}: {}", tname, e);
+                        log_warn!(request, "replace_all {}: {}", tname, e);
                         Response::Error {
                             message: format!("replace_all {}: {}", tname, e),
                         }
@@ -805,11 +800,11 @@ impl Server {
             }
 
             Request::ListTables => {
-                log_debug!(pipe, "list_tables");
+                log_debug!(request, "list_tables");
                 match self.list_tables() {
                     Ok(tables) => Response::Tables { tables },
                     Err(e) => {
-                        log_warn!(pipe, "list_tables: {}", e);
+                        log_warn!(request, "list_tables: {}", e);
                         Response::Error {
                             message: format!("list_tables: {}", e),
                         }
@@ -818,7 +813,7 @@ impl Server {
             }
 
             Request::ListCatalog => {
-                log_debug!(pipe, "list_catalog");
+                log_debug!(request, "list_catalog");
                 let c = self.catalog.lock().unwrap();
                 let schemas: Vec<TableSchemaWire> = c
                     .all_tables()
@@ -836,7 +831,7 @@ impl Server {
             }
 
             Request::DescribeTable { table } => {
-                log_debug!(pipe, "describe_table table={}", table);
+                log_debug!(request, "describe_table table={}", table);
                 match self.describe_table(&table) {
                     Ok((cols, count, indexes, stats)) => Response::Schema {
                         table,
@@ -846,7 +841,7 @@ impl Server {
                         stats,
                     },
                     Err(e) => {
-                        log_warn!(pipe, "describe_table {}: {}", table, e);
+                        log_warn!(request, "describe_table {}: {}", table, e);
                         Response::Error {
                             message: format!("describe_table {}: {}", table, e),
                         }
@@ -855,7 +850,7 @@ impl Server {
             }
 
             Request::CreateTable { table, columns } => {
-                log_debug!(pipe, "create_table table={} cols={}", table, columns.len());
+                log_debug!(request, "create_table table={} cols={}", table, columns.len());
 
                 {
                     let c = self.catalog.lock().unwrap();
@@ -887,7 +882,7 @@ impl Server {
             }
 
             Request::DropTable { table } => {
-                log_debug!(pipe, "drop_table table={}", table);
+                log_debug!(request, "drop_table table={}", table);
 
                 let dropped_indexes: Vec<String> = {
                     let mut c = self.catalog.lock().unwrap();
@@ -919,11 +914,11 @@ impl Server {
             }
 
             Request::CreateIndex { table, column } => {
-                log_debug!(pipe, "create_index table={} column={}", table, column);
+                log_debug!(request, "create_index table={} column={}", table, column);
                 match self.create_index(&table, &column) {
                     Ok(()) => Response::Ok,
                     Err(e) => {
-                        log_warn!(pipe, "create_index {}({}): {}", table, column, e);
+                        log_warn!(request, "create_index {}({}): {}", table, column, e);
                         Response::Error {
                             message: format!("create_index {}({}): {}", table, column, e),
                         }
@@ -932,11 +927,11 @@ impl Server {
             }
 
             Request::DropIndex { table, column } => {
-                log_debug!(pipe, "drop_index table={} column={}", table, column);
+                log_debug!(request, "drop_index table={} column={}", table, column);
                 match self.drop_index(&table, &column) {
                     Ok(()) => Response::Ok,
                     Err(e) => {
-                        log_warn!(pipe, "drop_index {}({}): {}", table, column, e);
+                        log_warn!(request, "drop_index {}({}): {}", table, column, e);
                         Response::Error {
                             message: format!("drop_index {}({}): {}", table, column, e),
                         }
@@ -945,11 +940,11 @@ impl Server {
             }
 
             Request::DropColumn { table, column } => {
-                log_debug!(pipe, "drop_column table={} column={}", table, column);
+                log_debug!(request, "drop_column table={} column={}", table, column);
                 match self.drop_column(&table, &column) {
                     Ok(()) => Response::Ok,
                     Err(e) => {
-                        log_warn!(pipe, "drop_column {}({}): {}", table, column, e);
+                        log_warn!(request, "drop_column {}({}): {}", table, column, e);
                         Response::Error {
                             message: format!("drop_column {}({}): {}", table, column, e),
                         }
@@ -958,11 +953,11 @@ impl Server {
             }
 
             Request::Compact { table } => {
-                log_debug!(pipe, "compact table={}", table);
+                log_debug!(request, "compact table={}", table);
                 match self.compact_table(&table) {
                     Ok(()) => Response::Ok,
                     Err(e) => {
-                        log_warn!(pipe, "compact {}: {}", table, e);
+                        log_warn!(request, "compact {}: {}", table, e);
                         Response::Error {
                             message: format!("compact {}: {}", table, e),
                         }
@@ -971,13 +966,13 @@ impl Server {
             }
 
             Request::ReplaceSchema { table, columns, rows } => {
-                log_debug!(pipe, "replace_schema table={} cols={}", table, columns.len());
+                log_debug!(request, "replace_schema table={} cols={}", table, columns.len());
                 let tname = table.clone();
                 let op = WalOp::ReplaceSchema { table, columns, rows };
                 match self.write_via_wal(&op) {
                     Ok(()) => Response::Ok,
                     Err(e) => {
-                        log_warn!(pipe, "replace_schema {}: {}", tname, e);
+                        log_warn!(request, "replace_schema {}: {}", tname, e);
                         Response::Error {
                             message: format!("replace_schema {}: {}", tname, e),
                         }
@@ -1015,6 +1010,7 @@ impl Server {
     }
 }
 
+/// 账号列表转成行
 fn account_rows(accounts: &[Account]) -> std::io::Result<Vec<Row>> {
     accounts.iter().map(|a| Ok(HashMap::from([
         ("id".into(), serde_json::json!(a.id)),
@@ -1029,7 +1025,7 @@ fn account_rows(accounts: &[Account]) -> std::io::Result<Vec<Row>> {
     ]))).collect()
 }
 
-/// 系统表：列定义与索引都按 scripts/init.sql 写进数据字典
+/// 按 init.sql 把系统表写进字典
 fn declare_system_schema(catalog: &mut Catalog, rows: &[Row]) -> std::io::Result<()> {
     for table in system_schema() {
         let stats: &[Row] = if table.name == USERS_TABLE { rows } else { &[] };
@@ -1044,7 +1040,7 @@ fn declare_system_schema(catalog: &mut Catalog, rows: &[Row]) -> std::io::Result
     Ok(())
 }
 
-/// 读一行账号：新格式是平铺的列，老格式是 {id, account:"<json>"}
+/// 读一行账号（兼容老格式）
 fn decode_account_row(row: &Row) -> std::io::Result<Account> {
     if let Some(encoded) = row.get("account").and_then(serde_json::Value::as_str) {
         return serde_json::from_str(encoded).map_err(|_| std::io::Error::other("invalid account record"));
@@ -1081,7 +1077,7 @@ fn now_stamp() -> String {
     format_timestamp(seconds)
 }
 
-/// Unix 秒 → YYYY-MM-DD HH:MM:SS（UTC）
+/// Unix 秒转时间戳文本
 fn format_timestamp(seconds: i64) -> String {
     let days = seconds.div_euclid(86_400);
     let rest = seconds.rem_euclid(86_400);
@@ -1106,6 +1102,7 @@ fn civil_from_days(days: i64) -> (i64, u32, u32) {
     (if month <= 2 { year + 1 } else { year }, month, day)
 }
 
+/// 规范化并校验账号名
 fn account_name(user: &str) -> std::io::Result<String> {
     if user.is_empty() || user.len() > 64 || !user.bytes().all(|c| c.is_ascii_alphanumeric() || b"_.-".contains(&c)) {
         return Err(std::io::Error::other("invalid account name"));
@@ -1113,6 +1110,7 @@ fn account_name(user: &str) -> std::io::Result<String> {
     Ok(user.to_ascii_lowercase())
 }
 
+/// 校验口令哈希长度
 fn validate_account_hash(hash: &str) -> std::io::Result<()> {
     if hash.is_empty() || hash.len() > 256 {
         return Err(std::io::Error::other("invalid account credential"));
@@ -1120,6 +1118,7 @@ fn validate_account_hash(hash: &str) -> std::io::Result<()> {
     Ok(())
 }
 
+/// 造一条新账号记录
 fn new_account(id: i64, user: &str, password_hash: String) -> std::io::Result<Account> {
     validate_account_hash(&password_hash)?;
     Ok(Account {
@@ -1133,7 +1132,7 @@ fn new_account(id: i64, user: &str, password_hash: String) -> std::io::Result<Ac
 }
 
 /// 一张表的索引定义转线上格式
-fn index_wires(schema: &chusql_storage::catalog::TableSchema) -> Vec<IndexWire> {
+fn index_wires(schema: &crate::catalog::TableSchema) -> Vec<IndexWire> {
     let mut out = vec![IndexWire {
         column: "id".to_string(),
     }];
@@ -1148,7 +1147,7 @@ fn index_wires(schema: &chusql_storage::catalog::TableSchema) -> Vec<IndexWire>
 }
 
 /// 一张表的列统计 -> 线上格式
-fn stat_wires(schema: &chusql_storage::catalog::TableSchema) -> Vec<ColumnStatWire> {
+fn stat_wires(schema: &crate::catalog::TableSchema) -> Vec<ColumnStatWire> {
     schema
         .stats
         .iter()
@@ -1161,6 +1160,7 @@ fn stat_wires(schema: &chusql_storage::catalog::TableSchema) -> Vec<ColumnStatWi
 }
 
 impl Drop for Server {
+    /// 析构时保存数据字典
     fn drop(&mut self) {
         if let Ok(c) = self.catalog.lock() {
             let _ = c.save(self.catalog_path());
@@ -1194,6 +1194,7 @@ struct Databases {
 }
 
 impl Databases {
+    /// 装载系统库与已有的具名库
     fn new(cfg: Config) -> std::io::Result<Self> {
         // 系统库按需创建：目录、字典与系统表缺失时自动补齐。
         // 其余库只在 data/databases/<name>/ 下已存在时才装载，启动不会凭空建库。
@@ -1226,7 +1227,7 @@ impl Databases {
         Ok(Self { root: cfg, system, named: Mutex::new(named) })
     }
 
-    /// 在 data_dir/<name>/ 下开一个保留库（目录与字典、WAL 一起建起来）
+    /// 按名字打开或新建一个库
     fn open(cfg: &Config, name: &str) -> std::io::Result<Server> {
         let mut config = cfg.clone();
         config.data_dir = cfg.data_dir.join(name);
@@ -1241,6 +1242,7 @@ impl Databases {
         Ok(server)
     }
 
+    /// 库级分发：先处理库管理，再转给选中的库
     fn request(&self, mut value: serde_json::Value) -> std::io::Result<Response> {
         use std::io::Error;
         let method = value.get("method").and_then(|v| v.as_str()).unwrap_or("").to_string();
@@ -1329,6 +1331,7 @@ impl Databases {
     }
 }
 
+/// 校验库名是否合法
 fn valid_database(name: &str) -> bool {
     let lower = name.to_ascii_lowercase();
     let device = matches!(lower.as_str(), "con" | "prn" | "aux" | "nul")
@@ -1339,37 +1342,6 @@ fn valid_database(name: &str) -> bool {
         && name.as_bytes().first().is_some_and(|c| c.is_ascii_alphabetic() || *c == b'_')
 }
 
-/// 处理一条连接
-fn handle(server: &Databases, conn: LocalSocketStream) -> std::io::Result<()> {
-    let mut writer = conn.try_clone()?;
-    let reader = BufReader::new(conn);
-
-    for line in reader.lines() {
-        let line = line?;
-        if line.trim().is_empty() {
-            continue;
-        }
-
-        let resp = match serde_json::from_str::<serde_json::Value>(&line) {
-            Ok(req) => match server.request(req) {
-                Ok(response) => response,
-                Err(e) => Response::Error { message: e.to_string() },
-            },
-            Err(e) => {
-                log_warn!(pipe, "bad request line: {}", e);
-                Response::Error {
-                    message: format!("parse error: {}", e),
-                }
-            }
-        };
-
-        writeln!(writer, "{}", serde_json::to_string(&resp).unwrap())?;
-        writer.flush()?;
-    }
-    log_debug!(pipe, "connection closed");
-    Ok(())
-}
-
 /// 把配置来源打进日志
 fn log_config(loaded: &Loaded) {
     match &loaded.config_path {
@@ -1381,92 +1353,44 @@ fn log_config(loaded: &Loaded) {
     }
 }
 
-/// 命令行用法
-fn print_usage() {
-    println!("chusql-storage: ChuSQL 存储服务");
-    println!();
-    println!("用法: chusql-storage [--config <path>]");
-    println!();
-    println!("配置文件固定位置（安装时确定，按系统惯例）:");
-    println!("  {}", config::default_config_path().display());
-    println!("该文件存在才读，不存在就用内置默认值（不是错误）。");
-    println!("--config <path> 是唯一的显式覆盖手段；文件不存在或读不了会报错退出。");
-    println!("配置分区: [page] [btree] [buffer] [storage] [server] [log]");
-    println!("--help, -h 显示本帮助。");
+/// 进程内存储句柄：一个数据目录一份状态，跨线程共享（内部各自加锁）。
+pub struct Storage {
+    databases: Databases,
 }
 
-/// 解析命令行：只认 --config <path> / --config=<path> / --help / -h
-fn parse_args(args: &[String]) -> Result<Option<String>, String> {
-    let mut explicit = None;
-    let mut i = 0;
-    while i < args.len() {
-        let arg = args[i].as_str();
-        if arg == "--config" {
-            let value = args.get(i + 1).ok_or("--config needs a path")?;
-            if value.trim().is_empty() {
-                return Err("--config needs a path".to_string());
+impl Storage {
+    /// 打开数据目录并初始化存储
+    pub fn open(config_path: Option<&str>) -> Result<Storage, String> {
+        let loaded = config::load(config_path)?;
+        log::init();
+        log::set_level(loaded.config.log_level);
+        log_info!(core, "chusql-core-storage {} starting", env!("CARGO_PKG_VERSION"));
+        log_config(&loaded);
+        let databases = Databases::new(loaded.config).map_err(|e| e.to_string())?;
+        Ok(Storage { databases })
+    }
+
+    /// 一行请求 JSON 换一行响应 JSON
+    pub fn request_line(&self, line: &str) -> String {
+        let response = match serde_json::from_str::<serde_json::Value>(line) {
+            Ok(value) => match self.databases.request(value) {
+                Ok(response) => response,
+                Err(e) => Response::Error { message: e.to_string() },
+            },
+            Err(e) => {
+                log_warn!(core, "bad request line: {}", e);
+                Response::Error {
+                    message: format!("parse error: {}", e),
+                }
             }
-            explicit = Some(value.clone());
-            i += 2;
-        } else if let Some(value) = arg.strip_prefix("--config=") {
-            if value.trim().is_empty() {
-                return Err("--config needs a path".to_string());
+        };
+        match serde_json::to_string(&response) {
+            Ok(text) => text,
+            Err(e) => {
+                log_error!(core, "response encode failed: {}", e);
+                "{\"status\":\"error\",\"message\":\"response encode failed\"}".to_string()
             }
-            explicit = Some(value.to_string());
-            i += 1;
-        } else if arg == "--help" || arg == "-h" {
-            print_usage();
-            std::process::exit(0);
-        } else {
-            return Err(format!("unknown argument: {}", arg));
         }
     }
-    Ok(explicit)
 }
 
-/// 进程入口
-fn main() -> std::io::Result<()> {
-    let args: Vec<String> = std::env::args().skip(1).collect();
-    let explicit = match parse_args(&args) {
-        Ok(p) => p,
-        Err(e) => {
-            eprintln!("chusql-storage: {}", e);
-            eprintln!("用法: chusql-storage [--config <path>]，--help 看帮助");
-            std::process::exit(2);
-        }
-    };
-    let loaded = match config::load(explicit.as_deref()) {
-        Ok(l) => l,
-        Err(e) => {
-            log_error!(core, "config error: {}", e);
-            return Err(std::io::Error::new(std::io::ErrorKind::InvalidInput, e));
-        }
-    };
-    log::init();
-    log::set_level(loaded.config.log_level);
-
-    log_info!(core, "chusql-storage {} starting", env!("CARGO_PKG_VERSION"));
-    log_config(&loaded);
-
-    let server = Arc::new(Databases::new(loaded.config)?);
-
-    let listener = endpoint::listen(&server.root.pipe_name)?;
-
-    log_info!(
-        core,
-        "listening on {}",
-        endpoint::display(&server.root.pipe_name)
-    );
-
-    for conn in listener.incoming() {
-        let conn = conn?;
-        let server = Arc::clone(&server);
-        thread::spawn(move || {
-            log_debug!(pipe, "connection accepted");
-            if let Err(e) = handle(&server, conn) {
-                log_error!(pipe, "connection error: {}", e);
-            }
-        });
-    }
-    Ok(())
-}
diff --git a/chusql-storage/src/wal.rs b/chusql-core/storage/src/wal.rs
similarity index 100%
rename from chusql-storage/src/wal.rs
rename to chusql-core/storage/src/wal.rs
diff --git a/chusql-storage/tests/btree_test.rs b/chusql-core/storage/tests/btree_test.rs
similarity index 97%
rename from chusql-storage/tests/btree_test.rs
rename to chusql-core/storage/tests/btree_test.rs
index 7f5fa52..ca9aecf 100644
--- a/chusql-storage/tests/btree_test.rs
+++ b/chusql-core/storage/tests/btree_test.rs
@@ -1,9 +1,10 @@
-use chusql_storage::btree::{fits_in_page, DiskBTree, MAX_KEY_BYTES};
-use chusql_storage::config::{DEFAULT_BTREE_ORDER, DEFAULT_PAGE_SIZE};
-use chusql_storage::page::DEFAULT_POOL_SIZE;
+use chusql_core_storage::btree::{fits_in_page, DiskBTree, MAX_KEY_BYTES};
+use chusql_core_storage::config::{DEFAULT_BTREE_ORDER, DEFAULT_PAGE_SIZE};
+use chusql_core_storage::page::DEFAULT_POOL_SIZE;
 
 // B+ 树测试：字节键、重复键、范围扫描、重开与配置校验。
 
+/// 按默认参数打开指定索引文件
 fn open(dir: &std::path::Path, name: &str) -> DiskBTree {
     DiskBTree::open(dir.join(name), DEFAULT_PAGE_SIZE, DEFAULT_BTREE_ORDER, DEFAULT_POOL_SIZE).unwrap()
 }
diff --git a/chusql-storage/tests/catalog_test.rs b/chusql-core/storage/tests/catalog_test.rs
similarity index 96%
rename from chusql-storage/tests/catalog_test.rs
rename to chusql-core/storage/tests/catalog_test.rs
index d83decf..1a60f54 100644
--- a/chusql-storage/tests/catalog_test.rs
+++ b/chusql-core/storage/tests/catalog_test.rs
@@ -1,11 +1,12 @@
-use chusql_storage::catalog::Catalog;
-use chusql_storage::protocol::Row;
+use chusql_core_storage::catalog::Catalog;
+use chusql_core_storage::protocol::Row;
 use serde_json::json;
 
 // 数据字典测试：补列、去重、未知表。
 
 
 
+/// 用键值对构造一行
 fn row(pairs: &[(&str, serde_json::Value)]) -> Row {
     let mut m = Row::new();
     for (k, v) in pairs {
@@ -85,7 +86,7 @@ fn remove_column_drops_definition_stats_and_index() {
 /// 老类型名并到新写法，参数保留，未知类型原样
 #[test]
 fn normalize_type_maps_legacy_names() {
-    use chusql_storage::catalog::normalize_type;
+    use chusql_core_storage::catalog::normalize_type;
     assert_eq!(normalize_type("integer"), "int");
     assert_eq!(normalize_type("TEXT"), "str");
     assert_eq!(normalize_type("BOOLEAN"), "bool");
diff --git a/chusql-storage/tests/config_test.rs b/chusql-core/storage/tests/config_test.rs
similarity index 89%
rename from chusql-storage/tests/config_test.rs
rename to chusql-core/storage/tests/config_test.rs
index 5b8900a..cb5a2c5 100644
--- a/chusql-storage/tests/config_test.rs
+++ b/chusql-core/storage/tests/config_test.rs
@@ -1,10 +1,8 @@
 use std::path::PathBuf;
 use std::sync::Mutex;
 
-use chusql_storage::config::{
-    self, Config, DEFAULT_BTREE_ORDER, DEFAULT_PAGE_SIZE, DEFAULT_PIPE_NAME, Origin,
-};
-use chusql_storage::log::Level;
+use chusql_core_storage::config::{self, Config, DEFAULT_BTREE_ORDER, DEFAULT_PAGE_SIZE, Origin};
+use chusql_core_storage::log::Level;
 
 // 配置测试：默认值、文件覆盖、环境变量彻底无效、非法值报错。
 
@@ -27,7 +25,6 @@ fn defaults_without_file() {
     assert_eq!(loaded.config.page_size, DEFAULT_PAGE_SIZE);
     assert_eq!(loaded.config.btree_order, DEFAULT_BTREE_ORDER);
     assert_eq!(loaded.config.data_dir, config::default_data_dir());
-    assert_eq!(loaded.config.pipe_name, DEFAULT_PIPE_NAME);
     assert_eq!(loaded.config.log_level, Level::Info);
 }
 
@@ -50,11 +47,11 @@ fn file_overrides_only_written_keys() {
     assert_eq!(order.2, Origin::Default);
 }
 
-/// 六项全写都生效
+/// 五项全写都生效
 #[test]
 fn file_all_keys() {
     let _guard = env_guard();
-    let text = "[page]\nsize = 8192\n[btree]\norder = 32\n[buffer]\npool_size = 128\n[storage]\ndata_dir = \"mydata\"\n[server]\npipe_name = \"mypipe\"\n[log]\nlevel = \"debug\"\n";
+    let text = "[page]\nsize = 8192\n[btree]\norder = 32\n[buffer]\npool_size = 128\n[storage]\ndata_dir = \"mydata\"\n[log]\nlevel = \"debug\"\n";
     let path = PathBuf::from("t.toml");
     let loaded = config::resolve(Some(text), Some(path.clone())).unwrap();
 
@@ -62,7 +59,6 @@ fn file_all_keys() {
     assert_eq!(loaded.config.btree_order, 32);
     assert_eq!(loaded.config.pool_size, 128);
     assert_eq!(loaded.config.data_dir, PathBuf::from("mydata"));
-    assert_eq!(loaded.config.pipe_name, "mypipe");
     assert_eq!(loaded.config.log_level, Level::Debug);
     assert!(
         loaded
@@ -72,7 +68,7 @@ fn file_all_keys() {
     );
 }
 
-/// 环境变量完全无效：这条通道已经删掉，设了 CHUSQL_* 也只认文件/内置默认
+/// 设了 CHUSQL_* 环境变量也不生效
 #[test]
 fn env_vars_are_ignored_entirely() {
     let _guard = env_guard();
@@ -102,7 +98,7 @@ fn env_vars_are_ignored_entirely() {
     }
 }
 
-/// 固定路径按系统惯例：<配置目录>/ChuSQL/chusql.toml
+/// 固定配置路径在系统配置目录的 ChuSQL 下
 #[test]
 fn default_config_path_follows_system_convention() {
     let _guard = env_guard();
@@ -121,7 +117,7 @@ fn default_config_path_follows_system_convention() {
     }
 }
 
-/// 默认数据目录也按系统惯例：Windows 落 %LOCALAPPDATA%\ChuSQL\data，Unix 落 XDG 数据目录
+/// 默认数据目录落地按系统惯例
 #[test]
 fn default_data_dir_follows_system_convention() {
     let _guard = env_guard();
@@ -170,7 +166,7 @@ fn explicit_missing_path_is_an_error() {
     assert!(err.contains("chusql-no-such-config-9f21.toml"), "got {}", err);
 }
 
-/// 不给 --config：固定路径没有文件时全用内置默认，且不报错
+/// 不给 --config 且无配置文件时用内置默认
 #[test]
 fn load_without_explicit_path_uses_builtin_defaults() {
     let _guard = env_guard();
@@ -181,12 +177,23 @@ fn load_without_explicit_path_uses_builtin_defaults() {
     } else {
         assert_eq!(loaded.config, Config::default());
         assert_eq!(loaded.config.data_dir, config::default_data_dir());
-        assert_eq!(loaded.config.pipe_name, DEFAULT_PIPE_NAME);
         assert!(loaded.origins.iter().all(|(_, _, o)| *o == Origin::Default));
         assert!(loaded.config_path.is_none());
     }
 }
 
+/// [server] 分区归别的层管；本层拼写错误要报错
+#[test]
+fn server_section_belongs_to_another_layer() {
+    let _guard = env_guard();
+    let db_server = "[server]\nhost = \"0.0.0.0\"\nport = 7778\nmax_rows = 10\n";
+    let loaded = config::resolve(Some(db_server), None).unwrap();
+    assert_eq!(loaded.config.data_dir, config::default_data_dir());
+
+    let typo = "[storage]\ndata_dirs = \"oops\"\n";
+    assert!(config::resolve(Some(typo), None).is_err());
+}
+
 /// 日志等级非法要报错
 #[test]
 fn rejects_bad_log_level() {
diff --git a/chusql-storage/tests/heap_test.rs b/chusql-core/storage/tests/heap_test.rs
similarity index 93%
rename from chusql-storage/tests/heap_test.rs
rename to chusql-core/storage/tests/heap_test.rs
index 32af9a1..7af1288 100644
--- a/chusql-storage/tests/heap_test.rs
+++ b/chusql-core/storage/tests/heap_test.rs
@@ -1,11 +1,12 @@
-use chusql_storage::config::DEFAULT_PAGE_SIZE;
-use chusql_storage::heap::HeapTable;
-use chusql_storage::page::DEFAULT_POOL_SIZE;
-use chusql_storage::protocol::Row;
+use chusql_core_storage::config::DEFAULT_PAGE_SIZE;
+use chusql_core_storage::heap::HeapTable;
+use chusql_core_storage::page::DEFAULT_POOL_SIZE;
+use chusql_core_storage::protocol::Row;
 use serde_json::json;
 
 // 堆表测试：插查、跨页、大行、重开、索引重建。
 
+/// 用键值对构造一行
 fn row(pairs: &[(&str, serde_json::Value)]) -> Row {
     let mut m = Row::new();
     for (k, v) in pairs {
@@ -144,7 +145,7 @@ fn replace_all_rebuilds_index() {
         dir.path().join("t.db"),
         dir.path().join("t.idx"),
         DEFAULT_PAGE_SIZE,
-        chusql_storage::config::DEFAULT_BTREE_ORDER,
+        chusql_core_storage::config::DEFAULT_BTREE_ORDER,
         DEFAULT_POOL_SIZE,
     )
     .unwrap();
@@ -176,7 +177,7 @@ fn delete_by_keys_removes_rows() {
         dir.path().join("t.db"),
         dir.path().join("t.idx"),
         DEFAULT_PAGE_SIZE,
-        chusql_storage::config::DEFAULT_BTREE_ORDER,
+        chusql_core_storage::config::DEFAULT_BTREE_ORDER,
         DEFAULT_POOL_SIZE,
     )
     .unwrap();
@@ -214,7 +215,7 @@ fn insert_rows_batch() {
         dir.path().join("t.db"),
         dir.path().join("t.idx"),
         DEFAULT_PAGE_SIZE,
-        chusql_storage::config::DEFAULT_BTREE_ORDER,
+        chusql_core_storage::config::DEFAULT_BTREE_ORDER,
         DEFAULT_POOL_SIZE,
     )
     .unwrap();
@@ -234,7 +235,7 @@ fn insert_rows_batch() {
     assert!(t.insert_rows(&dup).is_err());
 }
 
-/// 第二列索引：建索引时要求唯一，建完之后插入/删除都跟着维护
+/// 第二列索引：建完插入/删除都跟着维护，值可重复
 #[test]
 fn secondary_index_is_maintained() {
     let dir = tempfile::tempdir().unwrap();
@@ -242,7 +243,7 @@ fn secondary_index_is_maintained() {
         dir.path().join("t.db"),
         dir.path().join("t.idx"),
         DEFAULT_PAGE_SIZE,
-        chusql_storage::config::DEFAULT_BTREE_ORDER,
+        chusql_core_storage::config::DEFAULT_BTREE_ORDER,
         DEFAULT_POOL_SIZE,
     )
     .unwrap();
@@ -258,7 +259,7 @@ fn secondary_index_is_maintained() {
         "code",
         &dir.path().join("t.code.idx"),
         DEFAULT_PAGE_SIZE,
-        chusql_storage::config::DEFAULT_BTREE_ORDER,
+        chusql_core_storage::config::DEFAULT_BTREE_ORDER,
         DEFAULT_POOL_SIZE,
     )
     .unwrap();
@@ -292,7 +293,7 @@ fn secondary_index_is_maintained() {
         "age",
         &dir.path().join("d.age.idx"),
         DEFAULT_PAGE_SIZE,
-        chusql_storage::config::DEFAULT_BTREE_ORDER,
+        chusql_core_storage::config::DEFAULT_BTREE_ORDER,
         DEFAULT_POOL_SIZE,
     )
     .unwrap();
diff --git a/chusql-storage/tests/page_test.rs b/chusql-core/storage/tests/page_test.rs
similarity index 97%
rename from chusql-storage/tests/page_test.rs
rename to chusql-core/storage/tests/page_test.rs
index bda3293..f73424a 100644
--- a/chusql-storage/tests/page_test.rs
+++ b/chusql-core/storage/tests/page_test.rs
@@ -1,5 +1,5 @@
-use chusql_storage::config::DEFAULT_PAGE_SIZE;
-use chusql_storage::page::{Page, PageFile};
+use chusql_core_storage::config::DEFAULT_PAGE_SIZE;
+use chusql_core_storage::page::{Page, PageFile};
 
 // 页文件测试：读写、追加、覆写、页大小校验与页缓存。
 
diff --git a/chusql-storage/tests/pipe_test.rs b/chusql-core/storage/tests/runtime_test.rs
similarity index 79%
rename from chusql-storage/tests/pipe_test.rs
rename to chusql-core/storage/tests/runtime_test.rs
index 528375e..11fec16 100644
--- a/chusql-storage/tests/pipe_test.rs
+++ b/chusql-core/storage/tests/runtime_test.rs
@@ -1,18 +1,23 @@
-use std::io::{BufRead, BufReader, Write};
-use std::process::{Child, Command, Stdio};
-use std::thread;
-use std::time::Duration;
+use std::cell::RefCell;
+use std::sync::Arc;
 
-use interprocess::local_socket::prelude::*;
-use interprocess::TryClone;
+use chusql_core_storage::runtime::Storage;
 
-// 端点集成测试：起真 server，跑协议、索引与配置（端点由 endpoint 模块统一算）。
+// 进程内存储集成测试：协议请求、索引、账号与配置。
 
+thread_local! {
+    /// 当前线程的存储实例：一个用例一个线程，用例内部按顺序起/停
+    static CURRENT: RefCell<Option<Arc<Storage>>> = const { RefCell::new(None) };
+}
+
+/// 一次会话就是当前线程的存储句柄
+struct Conn(Arc<Storage>);
+
+/// 扫描能按列投影，空列返回空行
 #[test]
 fn scan_projects_columns_and_preserves_empty_rows() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (_srv, _data) = start_server();
+    let mut c = connect()?;
     request_ok(&mut c, serde_json::json!({"method":"create_table","table":"items","columns":[{"name":"id","ty":"int"},{"name":"name","ty":"str"}]}))?;
     request_ok(&mut c, serde_json::json!({"method":"insert_batch","table":"items","rows":[{"id":1,"name":"one"},{"id":2,"name":null}]}))?;
     for (columns, expected) in [
@@ -27,11 +32,11 @@ fn scan_projects_columns_and_preserves_empty_rows() -> Result<(), Box<dyn std::e
     Ok(())
 }
 
+/// 删列不改堆字节，重启后不再暴露该列
 #[test]
 fn drop_column_keeps_heap_bytes_and_hides_values_after_restart() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (server, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (server, data) = start_server();
+    let mut c = connect()?;
     request_ok(&mut c, serde_json::json!({"method":"create_table","table":"items","columns":[{"name":"id","ty":"int"},{"name":"name","ty":"str"},{"name":"age","ty":"int"}]}))?;
     request_ok(&mut c, serde_json::json!({"method":"insert_batch","table":"items","rows":[{"id":1,"name":"old","age":20},{"id":2,"name":"secret","age":30}]}))?;
     for column in ["name", "age"] {
@@ -43,8 +48,8 @@ fn drop_column_keeps_heap_bytes_and_hides_values_after_restart() -> Result<(), B
     assert_eq!(std::fs::read(&heap)?, before, "DROP COLUMN must not rewrite heap pages");
     drop(c);
     drop(server);
-    let _server = start_server_in(&pipe, data.path());
-    let mut c = connect(&pipe)?;
+    let _server = start_server_in(data.path());
+    let mut c = connect()?;
     for request in [
         serde_json::json!({"method":"scan","table":"items"}),
         serde_json::json!({"method":"range_by_index","table":"items","column":"age","lo":0}),
@@ -64,12 +69,12 @@ fn drop_column_keeps_heap_bytes_and_hides_values_after_restart() -> Result<(), B
     Ok(())
 }
 
+/// 各库字典与行互相隔离，删库不影响别库
 #[test]
 fn databases_isolate_catalog_and_rows() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (_srv, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
-    let request = |c: &mut LocalSocketStream, value: serde_json::Value| -> Result<serde_json::Value, serde_json::Error> {
+    let (_srv, data) = start_server();
+    let mut c = connect()?;
+    let request = |c: &mut Conn, value: serde_json::Value| -> Result<serde_json::Value, serde_json::Error> {
         serde_json::from_str(&send(c, &value.to_string()))
     };
     for database in ["alpha", "beta"] {
@@ -90,12 +95,12 @@ fn databases_isolate_catalog_and_rows() -> Result<(), Box<dyn std::error::Error>
 }
 
 
+/// 隐藏列的 WAL 重放两次幂等，且不动堆文件
 #[test]
 fn hidden_column_wal_replays_twice_without_touching_heap() -> Result<(), Box<dyn std::error::Error>> {
-    use chusql_storage::wal::{Wal, WalOp};
-    let pipe = unique_pipe_name();
-    let (server, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    use chusql_core_storage::wal::{Wal, WalOp};
+    let (server, data) = start_server();
+    let mut c = connect()?;
     request_ok(&mut c, serde_json::json!({"method":"insert","table":"items","row":{"id":1,"secret":"old"}}))?;
     drop(c);
     drop(server);
@@ -109,8 +114,8 @@ fn hidden_column_wal_replays_twice_without_touching_heap() -> Result<(), Box<dyn
         assert_eq!(wal.read()?, Some(op));
         assert!(std::fs::metadata(wal.path())?.len() < 100);
         drop(wal);
-        let server = start_server_in(&pipe, data.path());
-        let mut c = connect(&pipe)?;
+        let server = start_server_in(data.path());
+        let mut c = connect()?;
         let result: serde_json::Value = serde_json::from_str(&send(&mut c, r#"{"method":"scan","table":"items"}"#))?;
         assert_eq!(result["rows"], serde_json::json!([{"id":1}]));
         let after = std::fs::read(&heap)?;
@@ -129,11 +134,11 @@ fn hidden_column_wal_replays_twice_without_touching_heap() -> Result<(), Box<dyn
     Ok(())
 }
 
+/// 删列失败时保留 WAL，重启后补做并放行
 #[test]
 fn hidden_column_failure_preserves_wal_until_recovery() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (server, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (server, data) = start_server();
+    let mut c = connect()?;
     request_ok(&mut c, serde_json::json!({"method":"insert","table":"items","row":{"id":1,"secret":"old"}}))?;
     let index = data.path().join("databases/main/items.secret.idx");
     std::fs::create_dir(&index)?;
@@ -146,18 +151,18 @@ fn hidden_column_failure_preserves_wal_until_recovery() -> Result<(), Box<dyn st
     drop(c);
     drop(server);
     std::fs::remove_dir(index)?;
-    let _server = start_server_in(&pipe, data.path());
-    let mut c = connect(&pipe)?;
+    let _server = start_server_in(data.path());
+    let mut c = connect()?;
     let rows: serde_json::Value = serde_json::from_str(&send(&mut c, r#"{"method":"scan","table":"items"}"#))?;
     assert_eq!(rows["rows"], serde_json::json!([{"id":1}]));
     Ok(())
 }
 
+/// 删带索引的列会连索引文件一起删掉
 #[test]
 fn drop_column_with_a_live_index_removes_the_index_file() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (_srv, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (_srv, data) = start_server();
+    let mut c = connect()?;
     request_ok(&mut c, serde_json::json!({"method":"insert","table":"items","row":{"id":1,"code":7}}))?;
     request_ok(&mut c, serde_json::json!({"method":"create_index","table":"items","column":"code"}))?;
     let index = data.path().join("databases/main/items.code.idx");
@@ -176,11 +181,11 @@ fn drop_column_with_a_live_index_removes_the_index_file() -> Result<(), Box<dyn
     Ok(())
 }
 
+/// 整理表会重写页面，清掉隐藏列字节
 #[test]
 fn compact_reclaims_hidden_column_bytes() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (server, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (server, data) = start_server();
+    let mut c = connect()?;
     for id in 1..=3 {
         request_ok(&mut c, serde_json::json!({"method":"insert","table":"items","row":{"id":id,"secret":"padding","note":"n"}}))?;
     }
@@ -200,18 +205,18 @@ fn compact_reclaims_hidden_column_bytes() -> Result<(), Box<dyn std::error::Erro
     request_ok(&mut c, serde_json::json!({"method":"insert","table":"items","row":{"id":4,"note":"x"}}))?;
     drop(c);
     drop(server);
-    let _server = start_server_in(&pipe, data.path());
-    let mut c = connect(&pipe)?;
+    let _server = start_server_in(data.path());
+    let mut c = connect()?;
     let rows: serde_json::Value = serde_json::from_str(&send(&mut c, r#"{"method":"scan","table":"items"}"#))?;
     assert_eq!(rows["rows"].as_array().map(Vec::len), Some(4), "rows survive compaction: {}", rows);
     Ok(())
 }
 
+/// 启动时自动整理带隐藏列的表
 #[test]
 fn startup_compaction_reclaims_dropped_columns() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (server, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (server, data) = start_server();
+    let mut c = connect()?;
     request_ok(&mut c, serde_json::json!({"method":"insert","table":"items","row":{"id":1,"secret":"padding"}}))?;
     request_ok(&mut c, serde_json::json!({"method":"drop_column","table":"items","column":"secret"}))?;
     let heap = data.path().join("databases/main/items.db");
@@ -219,8 +224,8 @@ fn startup_compaction_reclaims_dropped_columns() -> Result<(), Box<dyn std::erro
     drop(c);
     drop(server);
 
-    let _server = start_server_in(&pipe, data.path());
-    let mut c = connect(&pipe)?;
+    let _server = start_server_in(data.path());
+    let mut c = connect()?;
     assert!(
         !std::fs::read(&heap)?.windows(6).any(|w| w == &b"secret"[..]),
         "startup must compact tables that still carry hidden columns"
@@ -230,11 +235,11 @@ fn startup_compaction_reclaims_dropped_columns() -> Result<(), Box<dyn std::erro
     Ok(())
 }
 
+/// 非法库名被拒；system 是唯一保留库
 #[test]
 fn databases_reject_unsafe_names_and_keep_only_system_reserved() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (_srv, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (_srv, data) = start_server();
+    let mut c = connect()?;
     for database in ["", "../escape", "a/b", "a.b", "CON", "__chusql_users"] {
         let response: serde_json::Value = serde_json::from_str(&send(&mut c, &serde_json::json!({"method":"create_database","database":database}).to_string()))?;
         assert_eq!(response["status"], "error", "{database}: {response}");
@@ -255,11 +260,11 @@ fn databases_reject_unsafe_names_and_keep_only_system_reserved() -> Result<(), B
     Ok(())
 }
 
+/// 账号只存在 system 库，默认工作库不存在
 #[test]
 fn system_database_owns_accounts_and_nothing_is_default() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (_srv, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (_srv, data) = start_server();
+    let mut c = connect()?;
     // 启动只建 system，另一个是测试自己建的 main
     let listed: serde_json::Value = serde_json::from_str(&send(&mut c, r#"{"method":"list_databases"}"#))?;
     assert_eq!(listed["tables"], serde_json::json!(["main", "system"]));
@@ -278,12 +283,11 @@ fn system_database_owns_accounts_and_nothing_is_default() -> Result<(), Box<dyn
     Ok(())
 }
 
-/// 没选库的裸表名请求会被拒；限定名（db.table）不用选库
+/// 裸表名没选库会被拒；限定名不用选库
 #[test]
 fn unqualified_requests_need_a_selected_database() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (_srv, _data) = start_server();
+    let mut c = connect()?;
     let response: serde_json::Value = serde_json::from_str(&send_raw(&mut c, r#"{"method":"scan","table":"items"}"#))?;
     assert_eq!(response["status"], "error", "{response}");
     assert!(response["message"].as_str().unwrap_or("").contains("no database selected"), "{response}");
@@ -298,85 +302,59 @@ fn unqualified_requests_need_a_selected_database() -> Result<(), Box<dyn std::er
 }
 
 /// 发一条请求并断言状态是 ok
-fn request_ok(c: &mut LocalSocketStream, value: serde_json::Value) -> Result<(), Box<dyn std::error::Error>> {
+fn request_ok(c: &mut Conn, value: serde_json::Value) -> Result<(), Box<dyn std::error::Error>> {
     let response: serde_json::Value = serde_json::from_str(&send(c, &value.to_string()))?;
     assert_eq!(response["status"], "ok", "{value}: {response}");
     Ok(())
 }
 
-/// 唯一管道名，避免测试互抢
-fn unique_pipe_name() -> String {
-    let id = std::process::id();
-    let ns = std::time::SystemTime::now()
-        .duration_since(std::time::UNIX_EPOCH)
-        .unwrap()
-        .as_nanos();
-    format!("chusql-test-{}-{}", id, ns)
-}
-
-struct ServerProc(Child);
+/// 一次存储实例的持有者
+struct ServerProc;
 
 impl Drop for ServerProc {
-    /// 测试结束杀掉子进程
-    fn drop(&mut self) {
-        let _ = self.0.kill();
-        let _ = self.0.wait();
-    }
+    /// 实例由本线程 CURRENT 管，这里不用清理
+    fn drop(&mut self) {}
 }
 
-/// 起 server，等管道可连
-fn start_server(pipe: &str) -> (ServerProc, tempfile::TempDir) {
+/// 起存储，返回句柄与数据目录
+fn start_server() -> (ServerProc, tempfile::TempDir) {
     let data = tempfile::tempdir().unwrap();
-    let server = start_server_in(pipe, data.path());
+    let server = start_server_in(data.path());
     (server, data)
 }
 
-fn start_server_in(pipe: &str, data: &std::path::Path) -> ServerProc {
-    let config = write_config(data, pipe);
-    let child = Command::new(env!("CARGO_BIN_EXE_chusql-storage"))
-        .arg("--config")
-        .arg(&config)
-        .stdout(Stdio::null())
-        .stderr(Stdio::null())
-        .spawn()
-        .expect("failed to spawn server");
-
-    let srv = ServerProc(child);
-
-    for _ in 0..100 {
-        if connect(pipe).is_ok() {
-            // 服务启动只建 system 库，测试库在这里显式建
-            create_fixture_database(pipe);
-            return srv;
-        }
-        thread::sleep(Duration::from_millis(50));
-    }
-    panic!("server did not start within 5s");
+/// 在指定数据目录起存储并建测试库
+fn start_server_in(data: &std::path::Path) -> ServerProc {
+    open_storage(&write_config(data));
+    create_fixture_database();
+    ServerProc
 }
 
-/// 写一份配置给子进程：管名与数据目录都走 TOML，
-/// 路径用单引号字面量串，免得 Windows 反斜杠要转义。
-fn write_config(data: &std::path::Path, pipe: &str) -> std::path::PathBuf {
+/// 按配置文件打开存储，替换本线程上一个实例
+fn open_storage(config: &std::path::Path) {
+    CURRENT.with(|slot| *slot.borrow_mut() = None);
+    let storage = Arc::new(Storage::open(Some(config.to_str().unwrap())).expect("open storage"));
+    CURRENT.with(|slot| *slot.borrow_mut() = Some(storage));
+}
+
+/// 生成只写数据目录的临时配置文件
+fn write_config(data: &std::path::Path) -> std::path::PathBuf {
     let id = std::process::id();
     let ns = std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)
         .unwrap()
         .as_nanos();
     let path = data.join(format!("chusql-{}-{}.toml", id, ns));
-    let text = format!(
-        "[server]\npipe_name = '{}'\n[storage]\ndata_dir = '{}'\n",
-        pipe,
-        data.display()
-    );
+    let text = format!("[storage]\ndata_dir = '{}'\n", data.display());
     std::fs::write(&path, text).unwrap();
     path
 }
 
+/// 命名库重启后仍在，账号仍是全局的
 #[test]
 fn named_database_survives_restart_and_accounts_stay_global() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (server, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (server, data) = start_server();
+    let mut c = connect()?;
     for request in [
         serde_json::json!({"method":"create_database","database":"sales"}),
         serde_json::json!({"method":"create_table","database":"sales","table":"items","columns":[{"name":"id","ty":"int"}]}),
@@ -387,8 +365,8 @@ fn named_database_survives_restart_and_accounts_stay_global() -> Result<(), Box<
     }
     drop(c);
     drop(server);
-    let _restarted = start_server_in(&pipe, data.path());
-    let mut c = connect(&pipe)?;
+    let _restarted = start_server_in(data.path());
+    let mut c = connect()?;
     let rows: serde_json::Value = serde_json::from_str(&send(&mut c, r#"{"method":"scan","table":"sales.items"}"#))?;
     assert_eq!(rows["rows"], serde_json::json!([{"id":7}]));
     let accounts: serde_json::Value = serde_json::from_str(&send(&mut c, r#"{"method":"accounts_list","database":"sales"}"#))?;
@@ -398,16 +376,17 @@ fn named_database_survives_restart_and_accounts_stay_global() -> Result<(), Box<
     Ok(())
 }
 
-/// 连到指定端点的存储进程。端点规则与 server 侧共用 endpoint 模块，
-/// 所以 Windows 的具名管道与 Unix 的套接字文件都由同一处决定。
-fn connect(pipe: &str) -> std::io::Result<LocalSocketStream> {
-    chusql_storage::endpoint::connect(pipe)
+/// 连到本线程当前的存储：进程内实现就是本线程当前句柄
+fn connect() -> std::io::Result<Conn> {
+    CURRENT.with(|slot| slot.borrow().clone())
+        .map(Conn)
+        .ok_or_else(|| std::io::Error::other("storage not started"))
 }
 
-/// 测试自己的库名：服务启动只建 system 库，测试显式建这一个
+/// 测试用的库名：system 之外的库由测试自建
 const FIXTURE_DATABASE: &str = "main";
 
-/// 请求里没写库名就补上测试库：服务不再自带默认库，裸表名必须先选库
+/// 请求没写库名时补上测试库
 fn with_default_database(line: &str) -> String {
     match serde_json::from_str::<serde_json::Value>(line) {
         Ok(serde_json::Value::Object(mut object)) => {
@@ -419,36 +398,28 @@ fn with_default_database(line: &str) -> String {
 }
 
 /// 连通后显式建测试库；重启时库已存在，报错忽略
-fn create_fixture_database(pipe: &str) {
-    if let Ok(mut stream) = connect(pipe) {
-        let _ = send_raw(&mut stream, &format!(r#"{{"method":"create_database","database":"{FIXTURE_DATABASE}"}}"#));
+fn create_fixture_database() {
+    if let Ok(mut c) = connect() {
+        let _ = send_raw(&mut c, &format!(r#"{{"method":"create_database","database":"{FIXTURE_DATABASE}"}}"#));
     }
 }
 
 /// 发一行请求读一行响应（没写库名就补测试库）
-fn send(stream: &mut LocalSocketStream, line: &str) -> String {
-    send_raw(stream, &with_default_database(line))
+fn send(c: &mut Conn, line: &str) -> String {
+    send_raw(c, &with_default_database(line))
 }
 
 /// 原样发一行请求，不补库名——用来验证"没选库"的行为
-fn send_raw(stream: &mut LocalSocketStream, line: &str) -> String {
-    stream.write_all(line.as_bytes()).unwrap();
-    stream.write_all(b"\n").unwrap();
-    stream.flush().unwrap();
-
-    let mut reader = BufReader::new(stream.try_clone().unwrap());
-    let mut buf = String::new();
-    reader.read_line(&mut buf).unwrap();
-    buf.trim().to_string()
+fn send_raw(c: &mut Conn, line: &str) -> String {
+    c.0.request_line(line).trim().to_string()
 }
 
-/// ping 回 pong
+/// 只有字典登记的表才算存在，孤儿文件不算
 #[test]
 fn catalog_is_the_only_table_authority() -> std::io::Result<()> {
-    let pipe = unique_pipe_name();
-    let (_srv, data) = start_server(&pipe);
+    let (_srv, data) = start_server();
     std::fs::write(data.path().join("databases/main/orphan.db"), b"orphan")?;
-    let mut c = connect(&pipe)?;
+    let mut c = connect()?;
     for method in ["scan", "describe_table"] {
         let result = send(&mut c, &format!(r#"{{"method":"{method}","table":"orphan"}}"#));
         assert!(result.contains("unknown table"), "{result}");
@@ -458,11 +429,11 @@ fn catalog_is_the_only_table_authority() -> std::io::Result<()> {
     Ok(())
 }
 
+/// 保留系统表拒绝所有通用操作
 #[test]
 fn reserved_tables_reject_every_generic_operation() -> std::io::Result<()> {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (_srv, _data) = start_server();
+    let mut c = connect()?;
     for method in ["scan", "insert", "insert_batch", "delete_keys", "lookup_by_index",
         "replace_all", "describe_table", "create_table", "drop_table", "create_index",
         "drop_index", "drop_column"] {
@@ -474,11 +445,11 @@ fn reserved_tables_reject_every_generic_operation() -> std::io::Result<()> {
     Ok(())
 }
 
+/// 通用接口拒绝表名与列名里的路径别名
 #[test]
 fn generic_ipc_rejects_path_aliases() -> std::io::Result<()> {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (_srv, _data) = start_server();
+    let mut c = connect()?;
     for table in ["../__chusql_users", "__CHUSQL_USERS", "__chusql_users."] {
         let result = send(&mut c, &serde_json::json!({"method":"scan", "table":table}).to_string());
         assert!(result.contains("error"), "{result}");
@@ -488,11 +459,11 @@ fn generic_ipc_rejects_path_aliases() -> std::io::Result<()> {
     Ok(())
 }
 
+/// 账号增改删，且普通列表接口看不到账号表
 #[test]
 fn account_create_reset_drop_and_hidden_from_ordinary_api() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (_srv, _data) = start_server();
+    let mut c = connect()?;
     assert_eq!(serde_json::from_str::<serde_json::Value>(&send(&mut c, r#"{"method":"accounts_list"}"#))?["accounts"], serde_json::json!([]));
     let create = r#"{"method":"account_create","user":"Alice","password_hash":"hash-one"}"#;
     let created: serde_json::Value = serde_json::from_str(&send(&mut c, create))?;
@@ -518,28 +489,19 @@ fn account_create_reset_drop_and_hidden_from_ordinary_api() -> Result<(), Box<dy
     Ok(())
 }
 
-fn restart_at(pipe: &str, data: &std::path::Path) -> std::io::Result<ServerProc> {
-    let child = Command::new(env!("CARGO_BIN_EXE_chusql-storage"))
-        .arg("--config")
-        .arg(write_config(data, pipe))
-        .stdout(Stdio::null()).stderr(Stdio::null()).spawn()?;
-    let server = ServerProc(child);
-    for _ in 0..100 {
-        if connect(pipe).is_ok() {
-            create_fixture_database(pipe);
-            return Ok(server);
-        }
-        thread::sleep(Duration::from_millis(50));
-    }
-    Err(std::io::Error::other("server restart timed out"))
+/// 用同一份数据目录重开一次存储
+fn restart_at(data: &std::path::Path) -> std::io::Result<ServerProc> {
+    open_storage(&write_config(data));
+    create_fixture_database();
+    Ok(ServerProc)
 }
 
+/// 账号快照 WAL 重放两次不产生重复账号
 #[test]
 fn account_snapshot_replays_twice_without_duplicating_accounts() -> Result<(), Box<dyn std::error::Error>> {
-    use chusql_storage::{protocol::Account, wal::{Wal, WalOp}};
-    let pipe = unique_pipe_name();
-    let (server, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    use chusql_core_storage::{protocol::Account, wal::{Wal, WalOp}};
+    let (server, data) = start_server();
+    let mut c = connect()?;
     let initial = send(&mut c, r#"{"method":"account_create","user":"alice","password_hash":"hash-one"}"#);
     assert!(initial.contains("accounts"), "{initial}");
     let changed: serde_json::Value = serde_json::from_str(&send(&mut c,
@@ -554,8 +516,8 @@ fn account_snapshot_replays_twice_without_duplicating_accounts() -> Result<(), B
         drop(wal);
         std::fs::write(data.path().join("system/__chusql_users.idx"), b"torn index")?;
         std::fs::write(data.path().join("system/__chusql_users.db"), b"torn heap")?;
-        let restarted = restart_at(&pipe, data.path())?;
-        let mut connection = connect(&pipe)?;
+        let restarted = restart_at(data.path())?;
+        let mut connection = connect()?;
         let actual: serde_json::Value = serde_json::from_str(&send(&mut connection, r#"{"method":"accounts_list"}"#))?;
         assert_eq!(actual, changed);
         assert_eq!(std::fs::metadata(data.path().join("system/wal.log"))?.len(), 0);
@@ -565,11 +527,11 @@ fn account_snapshot_replays_twice_without_duplicating_accounts() -> Result<(), B
     Ok(())
 }
 
+/// 账号操作失败时保留 WAL 并挡住写入
 #[test]
 fn account_failure_preserves_wal_and_blocks_writes() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (server, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (server, data) = start_server();
+    let mut c = connect()?;
     std::fs::create_dir(data.path().join("system/catalog.json.pending"))?;
     let result = send(&mut c, r#"{"method":"account_create","user":"alice","password_hash":"hash-one"}"#);
     assert!(result.contains("error"), "{result}");
@@ -583,30 +545,30 @@ fn account_failure_preserves_wal_and_blocks_writes() -> Result<(), Box<dyn std::
     drop(c);
     drop(server);
     std::fs::remove_dir(data.path().join("system/catalog.json.pending"))?;
-    let _restarted = restart_at(&pipe, data.path())?;
-    let mut c = connect(&pipe)?;
+    let _restarted = restart_at(data.path())?;
+    let mut c = connect()?;
     let recovered = send(&mut c, r#"{"method":"accounts_list"}"#);
     assert!(recovered.contains("hash-one"), "{recovered}");
     Ok(())
 }
 
+/// 账号文件已存在时拒绝建账号
 #[test]
 fn account_create_rejects_reserved_file_collision() -> std::io::Result<()> {
-    let pipe = unique_pipe_name();
-    let (_server, data) = start_server(&pipe);
+    let (_server, data) = start_server();
     std::fs::write(data.path().join("system/__chusql_users.db"), b"existing")?;
-    let mut c = connect(&pipe)?;
+    let mut c = connect()?;
     let result = send(&mut c, r#"{"method":"account_create","user":"alice","password_hash":"hash-one"}"#);
     assert!(result.contains("collision"), "{result}");
     assert_eq!(std::fs::read(data.path().join("system/__chusql_users.db"))?, b"existing");
     Ok(())
 }
 
+/// 超长密码哈希在写 WAL 之前就被拒
 #[test]
 fn oversized_account_hash_is_rejected_before_wal() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (_server, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (_server, data) = start_server();
+    let mut c = connect()?;
     let result = send(&mut c, &serde_json::json!({"method":"account_create", "user":"alice",
         "password_hash":"a".repeat(300)}).to_string());
     assert!(result.contains("invalid account credential"), "{result}");
@@ -616,16 +578,16 @@ fn oversized_account_hash_is_rejected_before_wal() -> Result<(), Box<dyn std::er
     Ok(())
 }
 
+/// 字典里已有同名普通表时拒绝建账号
 #[test]
 fn account_create_rejects_existing_ordinary_catalog_entry() -> std::io::Result<()> {
     let data = tempfile::tempdir()?;
-    let mut catalog = chusql_storage::catalog::Catalog::default();
+    let mut catalog = chusql_core_storage::catalog::Catalog::default();
     catalog.create_table("__chusql_users", Vec::new())?;
     std::fs::create_dir(data.path().join("system"))?;
     catalog.save(data.path().join("system/catalog.json"))?;
-    let pipe = unique_pipe_name();
-    let _server = restart_at(&pipe, data.path())?;
-    let mut c = connect(&pipe)?;
+    let _server = restart_at(data.path())?;
+    let mut c = connect()?;
     let result = send(&mut c, r#"{"method":"account_create","user":"alice","password_hash":"hash-one"}"#);
     assert!(result.contains("collision"), "{result}");
     Ok(())
@@ -634,9 +596,8 @@ fn account_create_rejects_existing_ordinary_catalog_entry() -> std::io::Result<(
 /// 列出已建的表
 #[test]
 fn list_tables_returns_created_tables() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     send(&mut c, r#"{"method":"insert","table":"users","row":{"id":1}}"#);
     send(&mut c, r#"{"method":"insert","table":"orders","row":{"id":1}}"#);
@@ -649,9 +610,8 @@ fn list_tables_returns_created_tables() {
 /// 整表替换只剩新行
 #[test]
 fn replace_all_replaces_rows() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     send(&mut c, r#"{"method":"insert","table":"users","row":{"id":1,"name":"Alice"}}"#);
     send(&mut c, r#"{"method":"insert","table":"users","row":{"id":2,"name":"Bob"}}"#);
@@ -670,9 +630,8 @@ fn replace_all_replaces_rows() {
 /// 按 id 查（列名走默认值 `id`，老客户端不用改）
 #[test]
 fn insert_then_lookup_by_index() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     for (id, name) in [(1, "Alice"), (2, "Bob"), (3, "Carol")] {
         let req = format!(
@@ -693,9 +652,8 @@ fn insert_then_lookup_by_index() {
 /// 同一个 id 插两次要报错（索引列是唯一的）
 #[test]
 fn duplicate_id_is_rejected() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     let req = r#"{"method":"insert","table":"dup_id","row":{"id":1,"name":"A"}}"#;
     assert!(send(&mut c, req).contains(r#""status":"ok""#));
@@ -708,9 +666,8 @@ fn duplicate_id_is_rejected() {
 /// 批量插入一次全进
 #[test]
 fn insert_batch_writes_all_rows() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     let r = send(
         &mut c,
@@ -728,9 +685,8 @@ fn insert_batch_writes_all_rows() {
 /// 行级删除：行没了、索引条目也没了、别人不受影响
 #[test]
 fn delete_keys_removes_row_and_index_entry() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     for (id, name) in [(1, "Alice"), (2, "Bob"), (3, "Carol")] {
         let req = format!(
@@ -757,9 +713,8 @@ fn delete_keys_removes_row_and_index_entry() {
 /// 给第二列建索引后能按那一列查
 #[test]
 fn create_index_on_secondary_column() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     for (id, code) in [(1, 5001), (2, 5002), (3, 5003)] {
         let req = format!(
@@ -794,9 +749,8 @@ fn create_index_on_secondary_column() {
 /// 删列同时摘掉索引与行内该格
 #[test]
 fn drop_column_removes_column_index_and_values() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     for (id, code, note) in [(1, 5001, "a"), (2, 5002, "b")] {
         let req = format!(
@@ -835,12 +789,11 @@ fn drop_column_removes_column_index_and_values() {
     assert!(r.contains(r#""status":"error""#), "a missing column should error: {}", r);
 }
 
-/// 重复值列允许建索引：点查把重复的行都取回来，删一行不影响另一行；id 仍然唯一
+/// 重复值列能建索引，删一行不影响另一行；id 仍唯一
 #[test]
 fn create_index_accepts_duplicate_values() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     send(&mut c, r#"{"method":"insert","table":"dup_t","row":{"id":1,"age":30}}"#);
     send(&mut c, r#"{"method":"insert","table":"dup_t","row":{"id":2,"age":30}}"#);
@@ -865,9 +818,8 @@ fn create_index_accepts_duplicate_values() {
 /// 数据字典里的统计：不同值个数
 #[test]
 fn stats_report_distinct_values() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     for (id, age) in [(1, 30), (2, 30), (3, 41)] {
         let req = format!(
@@ -891,24 +843,11 @@ fn stats_report_distinct_values() {
 /// 重开服务后索引仍在
 #[test]
 fn lookup_survives_reopen() {
-    let pipe = unique_pipe_name();
     let data = tempfile::tempdir().unwrap();
 
     {
-        let child = Command::new(env!("CARGO_BIN_EXE_chusql-storage"))
-            .arg("--config")
-            .arg(write_config(data.path(), &pipe))
-            .stdout(Stdio::null())
-            .stderr(Stdio::null())
-            .spawn()
-            .unwrap();
-        let srv = ServerProc(child);
-        for _ in 0..100 {
-            if connect(&pipe).is_ok() { break; }
-            thread::sleep(Duration::from_millis(50));
-        }
-        create_fixture_database(&pipe);
-        let mut c = connect(&pipe).unwrap();
+        let _srv = start_server_in(data.path());
+        let mut c = connect().unwrap();
         for (id, name) in [(1, "Alice"), (2, "Bob"), (3, "Carol")] {
             let req = format!(
                 r#"{{"method":"insert","table":"persist","row":{{"id":{},"name":"{}"}},"key":{}}}"#,
@@ -916,29 +855,11 @@ fn lookup_survives_reopen() {
             );
             send(&mut c, &req);
         }
-        drop(srv);
     }
 
-    thread::sleep(Duration::from_millis(200));
+    let _srv = start_server_in(data.path());
 
-    let (_srv, _data) = {
-        let child = Command::new(env!("CARGO_BIN_EXE_chusql-storage"))
-            .arg("--config")
-            .arg(write_config(data.path(), &pipe))
-            .stdout(Stdio::null())
-            .stderr(Stdio::null())
-            .spawn()
-            .unwrap();
-        let srv = ServerProc(child);
-        for _ in 0..100 {
-            if connect(&pipe).is_ok() { break; }
-            thread::sleep(Duration::from_millis(50));
-        }
-        create_fixture_database(&pipe);
-        (srv, data)
-    };
-
-    let mut c = connect(&pipe).unwrap();
+    let mut c = connect().unwrap();
     let r = send(&mut c, r#"{"method":"lookup_by_index","table":"persist","key":2}"#);
     assert!(r.contains("Bob"), "persist lookup: {}", r);
 }
@@ -947,34 +868,19 @@ fn lookup_survives_reopen() {
 #[test]
 fn config_file_is_used() {
     let dir = tempfile::tempdir().unwrap();
-    let pipe = unique_pipe_name();
     let data_dir = dir.path().join("data");
-    let config_path = dir.path().join("chusql-storage.toml");
+    let config_path = dir.path().join("chusql-core-storage.toml");
 
     let text = format!(
-        "[server]\npipe_name = \"{}\"\n[storage]\ndata_dir = \"{}\"\n[log]\nlevel = \"debug\"\n",
-        pipe,
+        "[storage]\ndata_dir = \"{}\"\n[log]\nlevel = \"debug\"\n",
         data_dir.display().to_string().replace('\\', "/")
     );
     std::fs::write(&config_path, text).unwrap();
 
-    let child = Command::new(env!("CARGO_BIN_EXE_chusql-storage"))
-        .arg("--config")
-        .arg(&config_path)
-        .stdout(Stdio::null())
-        .stderr(Stdio::null())
-        .spawn()
-        .expect("failed to spawn server");
-    let _srv = ServerProc(child);
-    for _ in 0..100 {
-        if connect(&pipe).is_ok() {
-            break;
-        }
-        thread::sleep(Duration::from_millis(50));
-    }
-    create_fixture_database(&pipe);
+    open_storage(&config_path);
+    create_fixture_database();
 
-    let mut c = connect(&pipe).unwrap();
+    let mut c = connect().unwrap();
     assert_eq!(send(&mut c, r#"{"method":"ping"}"#), r#"{"status":"pong"}"#);
     let r = send(&mut c, r#"{"method":"insert","table":"cfg","row":{"id":1}}"#);
     assert!(r.contains(r#""status":"ok""#), "insert: {}", r);
@@ -988,9 +894,8 @@ fn config_file_is_used() {
 /// 重复建表报错
 #[test]
 fn create_table_twice_errors() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     let req = r#"{"method":"create_table","table":"dup","columns":[{"name":"id","ty":"int"}]}"#;
     let r1 = send(&mut c, req);
@@ -1004,9 +909,8 @@ fn create_table_twice_errors() {
 /// 新建空表能扫描
 #[test]
 fn scan_empty_table_after_create() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     let r = send(
         &mut c,
@@ -1019,12 +923,11 @@ fn scan_empty_table_after_create() {
     assert!(r.contains(r#""rows":[]"#), "scan: {}", r);
 }
 
-/// 建表带上约束元数据，行里能有 null；replace_schema 整表换列定义与行
+/// 约束元数据落盘；replace_schema 换列与行
 #[test]
 fn replace_schema_rewrites_columns_and_rows() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     let created = send(
         &mut c,
@@ -1061,12 +964,11 @@ fn replace_schema_rewrites_columns_and_rows() {
     assert!(r.contains(r#""tag":"a""#), "rewritten rows: {}", r);
 }
 
-/// 旧类型系统落盘的数据在启动时升级：缺的格补 null，老类型名并到新写法
+/// 启动时升级旧类型字典，缺的格补 null
 #[test]
 fn legacy_catalog_and_partial_rows_are_migrated() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (server, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (server, data) = start_server();
+    let mut c = connect()?;
     request_ok(&mut c, serde_json::json!({"method":"create_table","table":"legacy_t","columns":[{"name":"id","ty":"int"},{"name":"name","ty":"str"},{"name":"age","ty":"int"}]}))?;
     request_ok(&mut c, serde_json::json!({"method":"insert","table":"legacy_t","row":{"id":1,"name":"a"}}))?;
     drop(c);
@@ -1083,8 +985,8 @@ fn legacy_catalog_and_partial_rows_are_migrated() -> Result<(), Box<dyn std::err
     }
     std::fs::write(&catalog_path, serde_json::to_string_pretty(&catalog)?)?;
 
-    let _restarted = start_server_in(&pipe, data.path());
-    let mut c = connect(&pipe)?;
+    let _restarted = start_server_in(data.path());
+    let mut c = connect()?;
 
     let rows: serde_json::Value = serde_json::from_str(&send(&mut c, r#"{"method":"scan","table":"legacy_t"}"#))?;
     assert_eq!(rows["rows"], serde_json::json!([{"id":1,"name":"a","age":null}]), "缺的格要补 null");
@@ -1099,12 +1001,11 @@ fn legacy_catalog_and_partial_rows_are_migrated() -> Result<(), Box<dyn std::err
     Ok(())
 }
 
-/// 账号表用新类型系统落盘：id 主键、用户名索引、注册与最近登录时间
+/// 账号表落盘类型与索引，登录盖时间戳
 #[test]
 fn account_table_uses_typed_columns_and_stamps_login() -> Result<(), Box<dyn std::error::Error>> {
-    let pipe = unique_pipe_name();
-    let (_srv, data) = start_server(&pipe);
-    let mut c = connect(&pipe)?;
+    let (_srv, data) = start_server();
+    let mut c = connect()?;
 
     let created: serde_json::Value = serde_json::from_str(&send(&mut c, r#"{"method":"account_create","user":"alice","password_hash":"hash"}"#))?;
     assert_eq!(created["status"], "accounts", "{}", created);
@@ -1136,10 +1037,9 @@ fn account_table_uses_typed_columns_and_stamps_login() -> Result<(), Box<dyn std
 
 /// 字符串列也能建索引并按键点查
 #[test]
-fn string_index_lookup_over_the_pipe() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+fn string_index_lookup_in_process() {
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     send(&mut c, r#"{"method":"insert","table":"sidx","row":{"id":1,"name":"alice"}}"#);
     send(&mut c, r#"{"method":"insert","table":"sidx","row":{"id":2,"name":"bob"}}"#);
@@ -1159,12 +1059,11 @@ fn string_index_lookup_over_the_pipe() {
     assert!(r.contains(r#""id":1"#) && r.contains(r#""id":3"#), "both rows come back: {}", r);
 }
 
-/// 范围扫描走索引叶子链，两端可开可闭，没索引回 no_index
+/// 范围扫描走索引，两端可开可闭，没索引回 no_index
 #[test]
-fn range_scan_over_the_pipe() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+fn range_scan_in_process() {
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     for (id, code) in [(1, 100), (2, 200), (3, 300), (4, 400)] {
         let req = format!(
@@ -1204,10 +1103,9 @@ fn range_scan_over_the_pipe() {
 
 /// 字符串列按字节序范围扫描
 #[test]
-fn string_range_scan_over_the_pipe() {
-    let pipe = unique_pipe_name();
-    let (_srv, _data) = start_server(&pipe);
-    let mut c = connect(&pipe).unwrap();
+fn string_range_scan_in_process() {
+    let (_srv, _data) = start_server();
+    let mut c = connect().unwrap();
 
     for (id, name) in [(1, "alice"), (2, "bob"), (3, "carol"), (4, "dave")] {
         let req = format!(
diff --git a/chusql-storage/tests/wal_test.rs b/chusql-core/storage/tests/wal_test.rs
similarity index 95%
rename from chusql-storage/tests/wal_test.rs
rename to chusql-core/storage/tests/wal_test.rs
index 06c291f..38990f1 100644
--- a/chusql-storage/tests/wal_test.rs
+++ b/chusql-core/storage/tests/wal_test.rs
@@ -1,10 +1,11 @@
-use chusql_storage::protocol::Row;
-use chusql_storage::wal::{Wal, WalOp};
+use chusql_core_storage::protocol::Row;
+use chusql_core_storage::wal::{Wal, WalOp};
 use serde_json::json;
 
 // WAL 测试：追加、读取、清空、截断尾巴。
 
 
+/// 用键值对构造一行
 fn row(pairs: &[(&str, serde_json::Value)]) -> Row {
     let mut m = Row::new();
     for (k, v) in pairs {
diff --git a/chusql-engine/chusql-engine.cabal b/chusql-engine/chusql-engine.cabal
deleted file mode 100644
index 83a1a13..0000000
--- a/chusql-engine/chusql-engine.cabal
+++ /dev/null
@@ -1,58 +0,0 @@
-cabal-version: 2.4
-
-name:           chusql-engine
-version:        1.0.0
-synopsis:       ChuSQL 执行引擎：SQL 词法与语法分析、表达式求值
-description:    ChuSQL 服务端执行引擎。负责 SQL 词法分析与 AST 构建、
-                WHERE 条件表达式求值、关系代数运算与内存表管理。
-build-type:     Simple
-
-library
-    hs-source-dirs:   src
-    exposed-modules:  ChuSQL.Algebra.Eval
-                      ChuSQL.Algebra.Expr
-                      ChuSQL.Algebra.Op
-                      ChuSQL.Algebra.Optimize
-                      ChuSQL.Algebra.Planner
-                      ChuSQL.Algebra.Sort
-                      ChuSQL.Engine
-                      ChuSQL.Model
-                      ChuSQL.Semantic
-                      ChuSQL.Storage
-                      ChuSQL.Storage.IPC
-                      ChuSQL.Storage.Memory
-                      ChuSQL.Syntax.AST
-                      ChuSQL.Syntax.Parser
-    build-depends:    base >= 4.14 && < 5
-                    , aeson
-                    , bytestring
-                    , hashable
-                    , megaparsec
-                    , network
-                    , parser-combinators
-                    , scientific
-                    , text
-                    , unordered-containers
-    default-language: Haskell2010
-    ghc-options:      -Wall
-
-executable chusql-engine
-    main-is:          Main.hs
-    hs-source-dirs:   app
-    build-depends:    base
-                    , chusql-engine
-    default-language: Haskell2010
-    ghc-options:      -Wall
-
-test-suite chusql-engine-test
-    type:             exitcode-stdio-1.0
-    main-is:          Spec.hs
-    hs-source-dirs:   test
-    build-depends:    base
-                    , chusql-engine
-                    , directory
-                    , filepath
-                    , hspec
-                    , process
-    default-language: Haskell2010
-    ghc-options:      -Wall
diff --git a/chusql-engine/src/ChuSQL/Storage/IPC.hs b/chusql-engine/src/ChuSQL/Storage/IPC.hs
deleted file mode 100644
index d8f0bf1..0000000
--- a/chusql-engine/src/ChuSQL/Storage/IPC.hs
+++ /dev/null
@@ -1,665 +0,0 @@
-{-# LANGUAGE CPP #-}
-{-# LANGUAGE ImportQualifiedPost #-}
-{-# LANGUAGE OverloadedStrings #-}
-
-module ChuSQL.Storage.IPC (
-    IPCStorage (..),
-    Request (..),
-    Response (..),
-    Account (..),
-    SchemaColumn (..),
-    TableInfo (..),
-    sendRequest,
-    closeConnection,
-    defaultPipeName,
-    setPipeName,
-    getPipeName,
-    doListTables,
-    doLookupByColumn,
-    doInsert,
-    doInsertMany,
-    doDeleteKeys,
-    doDescribeTable,
-    doDropTable,
-    doListCatalog,
-) where
-
-import ChuSQL.Model
-import ChuSQL.Storage
-import Control.Concurrent.MVar (MVar, modifyMVar, modifyMVar_, newMVar, readMVar)
-import Control.Exception (IOException, try)
-#if !defined(mingw32_HOST_OS)
-import Control.Exception (onException)
-#endif
-import Data.Aeson (FromJSON (..), ToJSON (..), eitherDecodeStrict, encode, object, withObject, (.:), (.:?), (.!=), (.=))
-import Data.Aeson qualified as A
-import Data.Aeson.Key qualified as K
-import Data.Aeson.KeyMap qualified as KM
-import Data.Aeson.Types (Parser)
-import Data.ByteString.Char8 qualified as BSC
-import Data.ByteString.Lazy qualified as BL
-import Data.Maybe (fromMaybe)
-import Data.Scientific (floatingOrInteger, fromFloatDigits)
-import Data.Text qualified as T
-import System.IO
-import System.IO.Unsafe (unsafePerformIO)
-#if !defined(mingw32_HOST_OS)
-import Network.Socket (Family (AF_UNIX), SockAddr (SockAddrUnix), SocketType (Stream), close, connect, defaultProtocol, socket, socketToHandle)
-import System.Environment (lookupEnv)
-#endif
-
--- IPC 存储实现：每个存储方法翻成管道上的一条 JSON 请求。
--- 端点：Windows 是具名管道 \\.\pipe\<name>，Unix 是文件系统套接字 <dir>/<name>.sock。
-
-#if !defined(mingw32_HOST_OS)
--- | Unix 套接字路径的最大长度（Linux 108 含结尾 NUL，BSD 104，这里留余量）
-maxSocketPathLength :: Int
-maxSocketPathLength = 100
-#endif
-
-newtype IPCStorage a = IPCStorage
-    { runIPCStorage :: IO a
-    }
-
-instance Functor IPCStorage where
-    fmap f (IPCStorage m) = IPCStorage (fmap f m)
-
-instance Applicative IPCStorage where
-    pure = IPCStorage . pure
-    IPCStorage mf <*> IPCStorage ma = IPCStorage (mf <*> ma)
-
-instance Monad IPCStorage where
-    IPCStorage m >>= k = IPCStorage $ do
-        a <- m
-        runIPCStorage (k a)
-
-{-# NOINLINE connectionRef #-}
-connectionRef :: MVar (Maybe (FilePath, Handle))
-connectionRef = unsafePerformIO (newMVar Nothing)
-
--- | 打开端点连接：Windows 把管道当文件打开，Unix 连一个 AF_UNIX 套接字
-openPipe :: FilePath -> IO Handle
-#if defined(mingw32_HOST_OS)
-openPipe path = do
-    h <- openFile path ReadWriteMode
-    hSetBuffering h LineBuffering
-    hSetNewlineMode h noNewlineTranslation
-    pure h
-#else
-openPipe path = do
-    if length path > maxSocketPathLength
-        then ioError (userError ("socket path too long (" ++ show (length path) ++ " bytes): " ++ path))
-        else pure ()
-    sock <- socket AF_UNIX Stream defaultProtocol
-    connect sock (SockAddrUnix path) `onException` close sock
-    h <- socketToHandle sock ReadWriteMode
-    hSetBuffering h LineBuffering
-    hSetNewlineMode h noNewlineTranslation
-    pure h
-
--- | Unix 套接字目录：$XDG_RUNTIME_DIR → $TMPDIR → /tmp（与 Rust 侧同一规则）
-socketDir :: IO String
-socketDir = do
-    runtime <- fmap nonEmpty (lookupEnv "XDG_RUNTIME_DIR")
-    tmp <- fmap nonEmpty (lookupEnv "TMPDIR")
-    pure (fromMaybe "/tmp" (runtime <> tmp))
-  where
-    nonEmpty v = case v of
-        Just s | not (null s) -> Just s
-        _ -> Nothing
-#endif
-
--- | 关掉缓存里的句柄（没有就什么都不做）
-closeCached :: Maybe (FilePath, Handle) -> IO ()
-closeCached Nothing = pure ()
-closeCached (Just (_, h)) = hClose h
-
--- | 拿一个可用句柄；路径没变就复用，变了就换。
-getConnection :: FilePath -> IO Handle
-getConnection path = modifyMVar connectionRef $ \cached -> case cached of
-    Just (p, h)
-        | p == path -> pure (Just (p, h), h)
-    _ -> do
-        _ <- try (closeCached cached) :: IO (Either IOException ())
-        h <- openPipe path
-        pure (Just (path, h), h)
-
--- | 丢掉缓存的连接（出错后调用，下次会重连）
-dropConnection :: IO ()
-dropConnection = modifyMVar_ connectionRef $ \cached -> do
-    _ <- try (closeCached cached) :: IO (Either IOException ())
-    pure Nothing
-
--- | 关闭并清空连接。可选，进程退出前调用。
-closeConnection :: IO ()
-closeConnection = dropConnection
-
--- | 没配置管名时用的端点，与 chusql.toml 的 [server] pipe_name 默认值一致
-defaultPipeName :: String
-defaultPipeName = "chusql-joint"
-
-{-# NOINLINE pipeNameRef #-}
-pipeNameRef :: MVar String
-pipeNameRef = unsafePerformIO (newMVar defaultPipeName)
-
--- | 设定本进程要连的端点；配置从哪来由调用方决定（本层不读环境变量）
-setPipeName :: String -> IO ()
-setPipeName name = modifyMVar_ pipeNameRef (\_ -> pure name)
-
--- | 当前端点
-getPipeName :: IO String
-getPipeName = readMVar pipeNameRef
-
--- | 端点的完整路径
-pipePath :: IO String
-#if defined(mingw32_HOST_OS)
-pipePath = do
-    name <- getPipeName
-    pure ("\\\\.\\pipe\\" ++ name)
-#else
-pipePath = do
-    name <- getPipeName
-    dir <- socketDir
-    pure (dir ++ "/" ++ name ++ ".sock")
-#endif
-
--- | 发一条请求，管道不通就重连
-sendRequest :: Request -> IO Response
-sendRequest req = do
-    path <- pipePath
-    result <- try (roundTrip req path) :: IO (Either IOException Response)
-    case result of
-        Left e -> do
-            dropConnection
-            pure (RespError ("pipe error: " ++ show e))
-        Right r -> pure r
-
--- | 一条请求-响应往返（复用缓存里的句柄）
-roundTrip :: Request -> FilePath -> IO Response
-roundTrip req path = do
-    h <- getConnection path
-    BL.hPutStr h (encode req)
-    BSC.hPutStr h "\n"
-    hFlush h
-    line <- BSC.hGetLine h
-    let cleaned = BSC.dropWhileEnd (== '\r') line
-    case eitherDecodeStrict cleaned of
-        Left err -> pure (RespError ("decode: " ++ err))
-        Right r -> pure r
-
-data SchemaColumn = SchemaColumn
-    { scName :: String
-    , scType :: String
-    , scNullable :: Bool
-    , scDefault :: Maybe Value
-    , scAutoIncrement :: Bool
-    , scPrimaryKey :: Bool
-    , scUnique :: Bool
-    , scCheck :: Maybe String
-    }
-    deriving (Show, Eq)
-
-instance ToJSON SchemaColumn where
-    toJSON sc =
-        object
-            [ "name" .= scName sc
-            , "ty" .= scType sc
-            , "nullable" .= scNullable sc
-            , "default" .= fmap valueToJSON (scDefault sc)
-            , "auto_increment" .= scAutoIncrement sc
-            , "primary_key" .= scPrimaryKey sc
-            , "unique" .= scUnique sc
-            , "check" .= scCheck sc
-            ]
-
-instance FromJSON SchemaColumn where
-    parseJSON = withObject "SchemaColumn" $ \o -> do
-        n <- o .: "name"
-        t <- o .: "ty"
-        nullable <- o .:? "nullable" .!= True
-        defJson <- o .:? "default"
-        def <- mapM valueFromJSON defJson
-        auto <- o .:? "auto_increment" .!= False
-        pk <- o .:? "primary_key" .!= False
-        uniq <- o .:? "unique" .!= False
-        chk <- o .:? "check"
-        pure (SchemaColumn n t nullable def auto pk uniq chk)
-
-data Request
-    = ReqPing
-    | ReqDatabase String String
-    | ReqAllCatalog
-    | ReqInDatabase String Request
-    | ReqAccountsList
-    | ReqAccountCreate T.Text T.Text
-    | ReqAccountReset T.Text T.Text
-    | ReqAccountLogin T.Text (Maybe T.Text)
-    | ReqAccountDrop T.Text
-    | ReqScan String
-    | ReqScanColumns String [String]
-    | ReqInsert String Row
-    | ReqInsertBatch String [Row]
-    | ReqDeleteKeys String [Int]
-    | ReqReplaceAll String [Row]
-    | ReqListTables
-    | ReqLookupByColumn String String Value
-    | ReqRangeByIndex String String (Maybe (Value, Bool)) (Maybe (Value, Bool))
-    | ReqDescribeTable String
-    | ReqCreateTable String [SchemaColumn]
-    | ReqDropTable String
-    | ReqCreateIndex String String
-    | ReqDropIndex String String
-    | ReqDropColumn String String
-    | ReqReplaceSchema String [SchemaColumn] [Row]
-    | ReqListCatalog
-
-instance ToJSON Request where
-    toJSON (ReqDatabase method name) = object ["method" .= method, "database" .= name]
-    toJSON ReqAllCatalog = object ["method" .= ("all_catalogs" :: T.Text)]
-    toJSON (ReqInDatabase name req) = case toJSON req of
-        A.Object fields -> A.Object (KM.insert "database" (A.String (T.pack name)) fields)
-        other -> other
-    toJSON ReqAccountsList = object ["method" .= ("accounts_list" :: T.Text)]
-    toJSON (ReqAccountCreate u h) = object ["method" .= ("account_create" :: T.Text), "user" .= u, "password_hash" .= h]
-    toJSON (ReqAccountReset u h) = object ["method" .= ("account_reset" :: T.Text), "user" .= u, "password_hash" .= h]
-    toJSON (ReqAccountLogin u at) = object ["method" .= ("account_login" :: T.Text), "user" .= u, "at" .= at]
-    toJSON (ReqAccountDrop u) = object ["method" .= ("account_drop" :: T.Text), "user" .= u]
-    toJSON ReqPing = object ["method" .= ("ping" :: T.Text)]
-    toJSON (ReqScan t) = object ["method" .= ("scan" :: T.Text), "table" .= t]
-    toJSON (ReqScanColumns t cols) = object ["method" .= ("scan" :: T.Text), "table" .= t, "columns" .= cols]
-    toJSON (ReqInsert t r) =
-        object
-            [ "method" .= ("insert" :: T.Text)
-            , "table" .= t
-            , "row" .= rowToJSON r
-            ]
-    toJSON (ReqInsertBatch t rs) =
-        object
-            [ "method" .= ("insert_batch" :: T.Text)
-            , "table" .= t
-            , "rows" .= map rowToJSON rs
-            ]
-    toJSON (ReqDeleteKeys t ks) =
-        object
-            [ "method" .= ("delete_keys" :: T.Text)
-            , "table" .= t
-            , "keys" .= ks
-            ]
-    toJSON (ReqReplaceAll t rs) =
-        object
-            [ "method" .= ("replace_all" :: T.Text)
-            , "table" .= t
-            , "rows" .= map rowToJSON rs
-            ]
-    toJSON ReqListTables = object ["method" .= ("list_tables" :: T.Text)]
-    toJSON (ReqLookupByColumn t c k) =
-        object
-            [ "method" .= ("lookup_by_index" :: T.Text)
-            , "table" .= t
-            , "column" .= c
-            , "key" .= valueToJSON k
-            ]
-    toJSON (ReqRangeByIndex t c lo hi) =
-        object
-            [ "method" .= ("range_by_index" :: T.Text)
-            , "table" .= t
-            , "column" .= c
-            , "lo" .= fmap (valueToJSON . fst) lo
-            , "lo_inclusive" .= maybe True snd lo
-            , "hi" .= fmap (valueToJSON . fst) hi
-            , "hi_inclusive" .= maybe True snd hi
-            ]
-    toJSON (ReqDescribeTable t) =
-        object
-            [ "method" .= ("describe_table" :: T.Text)
-            , "table" .= t
-            ]
-    toJSON (ReqCreateTable t cols) =
-        object
-            [ "method" .= ("create_table" :: T.Text)
-            , "table" .= t
-            , "columns" .= cols
-            ]
-    toJSON (ReqDropTable t) =
-        object ["method" .= ("drop_table" :: T.Text), "table" .= t]
-    toJSON (ReqCreateIndex t c) =
-        object
-            [ "method" .= ("create_index" :: T.Text)
-            , "table" .= t
-            , "column" .= c
-            ]
-    toJSON (ReqDropIndex t c) =
-        object
-            [ "method" .= ("drop_index" :: T.Text)
-            , "table" .= t
-            , "column" .= c
-            ]
-    toJSON (ReqDropColumn t c) =
-        object
-            [ "method" .= ("drop_column" :: T.Text)
-            , "table" .= t
-            , "column" .= c
-            ]
-    toJSON (ReqReplaceSchema t cols rs) =
-        object
-            [ "method" .= ("replace_schema" :: T.Text)
-            , "table" .= t
-            , "columns" .= cols
-            , "rows" .= map rowToJSON rs
-            ]
-    toJSON ReqListCatalog = object ["method" .= ("list_catalog" :: T.Text)]
-
-data TableInfo = TableInfo
-    { tiTable :: String
-    , tiColumns :: [SchemaColumn]
-    , tiRows :: Int
-    , tiIndexes :: [String]
-    , tiStats :: [(String, Int, Bool)]
-    }
-    deriving (Show, Eq)
-
-data Account = Account
-    { accountId :: Integer
-    , accountUser :: T.Text
-    , accountHash :: T.Text
-    , accountRevision :: Integer
-    , accountRegisteredAt :: T.Text
-    , accountLastLoginAt :: Maybe T.Text
-    } deriving (Eq)
-
-instance Show Account where
-    show a = "Account " ++ show (accountUser a) ++ " revision=" ++ show (accountRevision a)
-
-instance FromJSON Account where
-    parseJSON = withObject "Account" $ \o -> Account <$> o .: "id" <*> o .: "user"
-        <*> o .: "password_hash" <*> o .: "revision"
-        <*> o .:? "registered_at" .!= "" <*> o .:? "last_login_at"
-
-instance ToJSON Account where
-    toJSON a = object ["id" .= accountId a, "user" .= accountUser a,
-        "password_hash" .= accountHash a, "revision" .= accountRevision a,
-        "registered_at" .= accountRegisteredAt a, "last_login_at" .= accountLastLoginAt a]
-
-data Response
-    = RespPong
-    | RespAccounts [Account]
-    | RespRows [Row]
-    | RespTables [String]
-    | RespSchema TableInfo
-    | RespNoIndex
-    | RespOk
-    | RespError String
-    | RespCatalog [TableInfo]
-
-instance FromJSON Response where
-    parseJSON = withObject "Response" $ \o -> do
-        status <- o .: "status"
-        case status :: T.Text of
-            "accounts" -> RespAccounts <$> o .: "accounts"
-            "pong" -> pure RespPong
-            "ok" -> pure RespOk
-            "no_index" -> pure RespNoIndex
-            "rows" -> RespRows <$> (o .: "rows" >>= mapM rowFromJSON)
-            "tables" -> RespTables <$> o .: "tables"
-            "error" -> RespError <$> o .: "message"
-            "schema" -> RespSchema <$> parseTable (A.Object o)
-            "catalog" -> do
-                xs <- o .: "schemas" :: Parser [A.Value]
-                RespCatalog <$> mapM parseTable xs
-            other -> fail ("unknown status: " ++ T.unpack other)
-      where
-        parseTable :: A.Value -> Parser TableInfo
-        parseTable = withObject "TableInfo" $ \o -> do
-            t <- o .: "table"
-            cols <- o .: "columns"
-            cnt <- o .: "row_count"
-            idx <- o .:? "indexes" .!= []
-            sts <- o .:? "stats" .!= []
-            idxCols <- mapM (\v -> withObject "IndexWire" (.: "column") v) (idx :: [A.Value])
-            stats <- mapM parseStat (sts :: [A.Value])
-            pure (TableInfo t cols cnt idxCols stats)
-
-        parseStat :: A.Value -> Parser (String, Int, Bool)
-        parseStat = withObject "ColumnStat" $ \o -> do
-            name <- o .: "name"
-            distinct <- o .: "distinct"
-            capped <- o .:? "capped" .!= False
-            pure (name, distinct, capped)
-
--- | 值编码成 JSON
-valueToJSON :: Value -> A.Value
-valueToJSON VNull = A.Null
-valueToJSON (VInt n) = A.Number (fromIntegral n)
-valueToJSON (VFloat d) = A.Number (fromFloatDigits d)
-valueToJSON (VStr s) = A.String (T.pack s)
-valueToJSON (VBool b) = A.Bool b
-
--- | JSON 解回值
-valueFromJSON :: A.Value -> Parser Value
-valueFromJSON A.Null = pure VNull
-valueFromJSON (A.Number n) =
-    case floatingOrInteger n :: Either Double Integer of
-        Right i -> pure (VInt (fromIntegral i))
-        Left d -> pure (VFloat d)
-valueFromJSON (A.String s) = pure (VStr (T.unpack s))
-valueFromJSON (A.Bool b) = pure (VBool b)
-valueFromJSON _ = fail "unsupported value type"
-
--- | 一行编码成 JSON
-rowToJSON :: Row -> A.Value
-rowToJSON r =
-    A.Object (KM.fromList [(K.fromString k, valueToJSON v) | (k, v) <- r])
-
--- | JSON 解回一行
-rowFromJSON :: A.Value -> Parser Row
-rowFromJSON (A.Object o) = mapM toPair (KM.toList o)
-  where
-    toPair (k, v) = do
-        val <- valueFromJSON v
-        pure (K.toString k, val)
-rowFromJSON _ = fail "row must be a JSON object"
-
--- | 发请求并把响应翻成 Either
-ask :: String -> Request -> (Response -> Maybe a) -> IO (Either String a)
-ask what req recognize = do
-    resp <- sendRequest req
-    pure $ case resp of
-        RespError e -> Left e
-        other -> case recognize other of
-            Just a -> Right a
-            Nothing -> Left ("unexpected response to " ++ what)
-
--- | 只认"成了"（多数写操作都这样）
-okOnly :: Response -> Maybe ()
-okOnly RespOk = Just ()
-okOnly _ = Nothing
-
--- | 发 Scan
-doScan :: String -> IO (Either String [Row])
-doScan t = ask "scan" (ReqScan t) $ \resp -> case resp of
-    RespRows rows -> Just rows
-    _ -> Nothing
-
--- | 发 Insert（索引由存储层维护）
-doInsert :: String -> Row -> IO (Either String ())
-doInsert t r = ask "insert" (ReqInsert t r) okOnly
-
--- | 发 InsertBatch：一批行一次请求
-doInsertMany :: String -> [Row] -> IO (Either String ())
-doInsertMany t rs = ask "insert_batch" (ReqInsertBatch t rs) okOnly
-
--- | 发 DeleteKeys
-doDeleteKeys :: String -> [Int] -> IO (Either String ())
-doDeleteKeys t ks = ask "delete_keys" (ReqDeleteKeys t ks) okOnly
-
--- | 发 ReplaceAll
-doReplaceAll :: String -> [Row] -> IO (Either String ())
-doReplaceAll t rs = ask "replace_all" (ReqReplaceAll t rs) okOnly
-
--- | 发 ListTables
-doListTables :: IO (Either String [String])
-doListTables = ask "list_tables" ReqListTables $ \resp -> case resp of
-    RespTables ts -> Just ts
-    _ -> Nothing
-
--- | 一次拿全库 schema
-doListCatalog :: IO (Either String [TableInfo])
-doListCatalog = ask "list_catalog" ReqListCatalog $ \resp -> case resp of
-    RespCatalog xs -> Just xs
-    _ -> Nothing
-
--- | 按某一列的索引取一行（键可以是整数或字符串）
-doLookupByColumn :: String -> String -> Value -> IO (Either String IndexResult)
-doLookupByColumn t c k = ask "lookup_by_index" (ReqLookupByColumn t c k) $ \resp -> case resp of
-    RespRows rows -> Just (IndexRows rows)
-    RespNoIndex -> Just NoIndex
-    _ -> Nothing
-
--- | 范围扫描：没有可用索引就回 Nothing，让上层退回扫描
-doScanRange ::
-    String ->
-    String ->
-    Maybe (Value, Bool) ->
-    Maybe (Value, Bool) ->
-    IO (Either String (Maybe [Row]))
-doScanRange t c lo hi = ask "range_by_index" (ReqRangeByIndex t c lo hi) $ \resp -> case resp of
-    RespRows rows -> Just (Just rows)
-    RespNoIndex -> Just Nothing
-    _ -> Nothing
-
--- | 发 DescribeTable
-doDescribeTable :: String -> IO (Either String TableInfo)
-doDescribeTable t = ask "describe_table" (ReqDescribeTable t) $ \resp -> case resp of
-    RespSchema info -> Just info
-    _ -> Nothing
-
--- | 给某一列建索引
-doCreateIndex :: String -> String -> IO (Either String ())
-doCreateIndex t c = ask "create_index" (ReqCreateIndex t c) okOnly
-
--- | 去掉某一列的索引
-doDropIndex :: String -> String -> IO (Either String ())
-doDropIndex t c = ask "drop_index" (ReqDropIndex t c) okOnly
-
--- | 删一列（列定义、这一列上的索引、每行里的那一格一起没）
-doDropColumn :: String -> String -> IO (Either String ())
-doDropColumn t c = ask "drop_column" (ReqDropColumn t c) okOnly
-
--- | 发 ReplaceSchema（ALTER 用）
-doReplaceSchema :: String -> [SchemaColumn] -> [Row] -> IO (Either String ())
-doReplaceSchema t cols rs = ask "replace_schema" (ReqReplaceSchema t cols rs) okOnly
-
--- | 发 CreateTable
-doCreateTable :: String -> [SchemaColumn] -> IO (Either String ())
-doCreateTable t cols = ask "create_table" (ReqCreateTable t cols) okOnly
-
--- | 发 DropTable
-doDropTable :: String -> IO (Either String ())
-doDropTable t = ask "drop_table" (ReqDropTable t) okOnly
-
--- | 线上 schema 转本地列
-schemaToColumns :: [SchemaColumn] -> [(String, Column)]
-schemaToColumns = map toColumn
-
-toColumn :: SchemaColumn -> (String, Column)
-toColumn sc =
-    ( scName sc
-    , Column
-        { columnType = fromMaybe CStr (parseColumnType (scType sc))
-        , columnNullable = scNullable sc
-        , columnDefault = scDefault sc
-        , columnAutoIncrement = scAutoIncrement sc
-        , columnUnique = scUnique sc
-        , columnPrimaryKey = scPrimaryKey sc
-        , columnCheck = scCheck sc
-        }
-    )
-
--- | 本地列转线上 schema
-toWire :: (String, Column) -> SchemaColumn
-toWire (n, c) =
-    SchemaColumn
-        { scName = n
-        , scType = typeName (columnType c)
-        , scNullable = columnNullable c
-        , scDefault = columnDefault c
-        , scAutoIncrement = columnAutoIncrement c
-        , scPrimaryKey = columnPrimaryKey c
-        , scUnique = columnUnique c
-        , scCheck = columnCheck c
-        }
-
-instance MonadStorage IPCStorage where
-    createDatabase name = IPCStorage (ask "create_database" (ReqDatabase "create_database" name) okOnly)
-    dropDatabase name = IPCStorage (ask "drop_database" (ReqDatabase "drop_database" name) okOnly)
-    useDatabase name = IPCStorage (ask "use_database" (ReqDatabase "use_database" name) okOnly)
-    listDatabases = IPCStorage $ ask "list_databases" (ReqDatabase "list_databases" "") $ \resp -> case resp of
-        RespTables names -> Just names
-        _ -> Nothing
-    -- \| 发 Scan
-    scan t = IPCStorage (doScan t)
-    scanColumns t cols = IPCStorage $ ask "scan" (ReqScanColumns t cols) $ \resp -> case resp of
-        RespRows rows -> Just [[(c, v) | c <- cols, Just v <- [lookup c row]] | row <- rows]
-        _ -> Nothing
-
-    -- \| 发 Insert（索引由存储层自己维护）
-    insert t r = IPCStorage (doInsert t r)
-
-    -- \| 一批行一次请求：N 行只落一次盘
-    insertMany t rs = IPCStorage (doInsertMany t rs)
-
-    -- \| 按 id 批量删行
-    deleteKeys t ks = IPCStorage (doDeleteKeys t ks)
-
-    -- \| 发 ReplaceAll
-    replaceAll t rs = IPCStorage (doReplaceAll t rs)
-
-    -- \| 按某一列的索引取一行（没有索引就回 NoIndex）
-    lookupByColumn t c k = IPCStorage (doLookupByColumn t c k)
-
-    -- \| 范围扫描（没有索引就回 Nothing）
-    scanRange t c lo hi = IPCStorage (doScanRange t c lo hi)
-
-    -- \| 发 CreateTable
-    createTable name cols = IPCStorage (doCreateTable name (map toWire cols))
-
-    -- \| ALTER：整表换列定义与全部行
-    replaceSchema name cols rows = IPCStorage (doReplaceSchema name (map toWire cols) rows)
-
-    -- \| 发 DropTable
-    dropTable name = IPCStorage (doDropTable name)
-
-    -- \| 建索引
-    createIndex t c = IPCStorage (doCreateIndex t c)
-
-    -- \| 删索引
-    dropIndex t c = IPCStorage (doDropIndex t c)
-
-    -- \| 删一列
-    dropColumn t c = IPCStorage (doDropColumn t c)
-
-    -- \| 列表 + 逐表扫描拼库
-    snapshot = IPCStorage $ do
-        result <- doListCatalog
-        case result of
-            Left _ -> pure []
-            Right xs -> mapM loadEntry xs
-      where
-        loadEntry info = do
-            rows <- doScan (tiTable info)
-            pure
-                ( tiTable info
-                , Table (tiTable info) (schemaToColumns (tiColumns info)) (either (const []) id rows)
-                )
-
-    -- \| 只问数据字典要结构，一行数据都不拉过来
-    schema = IPCStorage $ do
-        result <- ask "all_catalogs" ReqAllCatalog $ \resp -> case resp of
-            RespCatalog infos -> Just infos
-            _ -> Nothing
-        pure $ case result of
-            Left _ -> []
-            Right xs ->
-                [ (tiTable i, Table (tiTable i) (schemaToColumns (tiColumns i)) [])
-                | i <- xs
-                ]
diff --git a/chusql-interface/chusql-interface.cabal b/chusql-interface/chusql-interface.cabal
new file mode 100644
index 0000000..5fde5aa
--- /dev/null
+++ b/chusql-interface/chusql-interface.cabal
@@ -0,0 +1,39 @@
+cabal-version: 2.4
+
+name:           chusql-interface
+version:        1.0.0
+synopsis:       ChuSQL 接口层：配置、口令、语句构造与 TCP 客户端
+description:    引擎无关的接口层。Web 管理端与命令行客户端都只依赖这层：
+                读同一份 chusql.toml、用同一个线上协议连到拥有存储库的
+                chusql-server，然后在客户端会话上跑 SQL、看数据字典与角色。
+                存储引擎与存储动态库一概不在这层。
+build-type:     Simple
+
+library
+    hs-source-dirs:   src
+    exposed-modules:  ChuSQL.Interface.AccountTable
+                      ChuSQL.Interface.Actions
+                      ChuSQL.Interface.Auth
+                      ChuSQL.Interface.Config
+                      ChuSQL.Interface.Link
+                      ChuSQL.Interface.Policy
+                      ChuSQL.Interface.Protocol
+                      ChuSQL.Interface.RateLimit
+                      ChuSQL.Interface.Session
+                      ChuSQL.Interface.Settings
+                      ChuSQL.Interface.TOML
+    build-depends:    base >= 4.14 && < 5
+                    , aeson
+                    , bytestring
+                    , chusql-core-model
+                    , containers
+                    , crypton
+                    , directory
+                    , filepath
+                    , memory
+                    , network
+                    , scientific
+                    , text
+                    , time
+    default-language: Haskell2010
+    ghc-options:      -Wall
diff --git a/chusql-interface/src/ChuSQL/Interface/AccountTable.hs b/chusql-interface/src/ChuSQL/Interface/AccountTable.hs
new file mode 100644
index 0000000..97f7d1d
--- /dev/null
+++ b/chusql-interface/src/ChuSQL/Interface/AccountTable.hs
@@ -0,0 +1,46 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module ChuSQL.Interface.AccountTable (
+    accountTableName,
+    isAccountTable,
+    passwordColumn,
+    accountColumns,
+    systemTableInfo,
+) where
+
+import ChuSQL.Core.Protocol (SchemaColumn (..), TableInfo (..))
+import Data.Text (Text)
+import qualified Data.Text as T
+
+-- 账号表（系统表 __chusql_users）的结构定义，SQL 会话与 Web 管理端共用。
+
+-- | 账号表的名字：网页里像普通表一样浏览与编辑，但写入走账号命令
+accountTableName :: String
+accountTableName = "__chusql_users"
+
+-- | 这张表是不是账号表
+isAccountTable :: Text -> Bool
+isAccountTable name = T.toLower name == T.pack accountTableName
+
+-- | 口令列：密文只在服务端产生，界面不支持排序与筛选
+passwordColumn :: String
+passwordColumn = "password"
+
+-- | 账号表的列定义与约束
+accountColumns :: [SchemaColumn]
+accountColumns =
+    [ accountColumnSpec "id" "int" False True True False
+    , accountColumnSpec "user" "varchar(64)" False False False True
+    , accountColumnSpec passwordColumn "varchar(256)" False False False False
+    , accountColumnSpec "registered_at" "timestamp" False False False False
+    , accountColumnSpec "last_login_at" "timestamp" True False False False
+    ]
+
+-- | 账号表的列（约束由账号服务管）
+accountColumnSpec :: String -> String -> Bool -> Bool -> Bool -> Bool -> SchemaColumn
+accountColumnSpec name ty nullable autoIncrement primary unique =
+    SchemaColumn name ty nullable Nothing autoIncrement primary unique Nothing
+
+-- | 账号表的结构（排序校验用）
+systemTableInfo :: TableInfo
+systemTableInfo = TableInfo accountTableName accountColumns 0 [] []
diff --git a/chusql-web/src/ChuSQL/Web/Actions.hs b/chusql-interface/src/ChuSQL/Interface/Actions.hs
similarity index 72%
rename from chusql-web/src/ChuSQL/Web/Actions.hs
rename to chusql-interface/src/ChuSQL/Interface/Actions.hs
index 38fbf23..1456659 100644
--- a/chusql-web/src/ChuSQL/Web/Actions.hs
+++ b/chusql-interface/src/ChuSQL/Interface/Actions.hs
@@ -1,6 +1,6 @@
 {-# LANGUAGE OverloadedStrings #-}
 
-module ChuSQL.Web.Actions (
+module ChuSQL.Interface.Actions (
     ColumnSpec (..),
     CreateTableSpec (..),
     isIdentifier,
@@ -24,10 +24,16 @@ module ChuSQL.Web.Actions (
     createUserSql,
     alterUserSql,
     dropUserSql,
+    createRoleSql,
+    dropRoleSql,
+    grantPrivilegesSql,
+    revokePrivilegesSql,
+    grantRoleSql,
+    revokeRoleSql,
 ) where
 
-import ChuSQL.Model (Column (..), ColumnType (..), Value (..), integerType, numericType, parseColumnType, plainColumn, typeName)
-import qualified ChuSQL.Model as M
+import ChuSQL.Core.Model (Column (..), ColumnType (..), Value (..), integerType, numericType, parseColumnType, plainColumn, typeName)
+import qualified ChuSQL.Core.Model as M
 import qualified Data.Aeson as A
 import Data.Char (isAsciiLower, isAsciiUpper, isDigit)
 import Data.List (intercalate)
@@ -38,12 +44,14 @@ import Text.Read (readMaybe)
 
 -- 把界面上的一键操作翻译成安全 SQL：标识符过白名单，值一律转义。
 
+-- | 界面上传来的一列：名字与类型名
 data ColumnSpec = ColumnSpec
     { csName :: Text
     , csType :: Text
     }
     deriving (Show, Eq)
 
+-- | 建表请求：表名 + 列
 data CreateTableSpec = CreateTableSpec
     { ctsTable :: Text
     , ctsColumns :: [ColumnSpec]
@@ -59,6 +67,7 @@ isIdentifier t =
             (c : cs) -> (isAsciiLower c || isAsciiUpper c || c == '_') && all restChar cs
             [] -> False
   where
+    -- | 标识符里其余字符的合法集
     restChar c = isAsciiLower c || isAsciiUpper c || isDigit c || c == '_'
 
 -- | 检查一个标识符，不合法就报错（带上"是表名还是列名"）
@@ -138,6 +147,7 @@ createTableSql spec = do
     defs <- mapM columnDef cols
     pure ("CREATE TABLE " ++ T.unpack tbl ++ " (" ++ intercalate ", " defs ++ ")")
   where
+    -- | 列类型不认时报错
     columnDef (ColumnSpec name ty) = do
         col <- checkIdent "column" name
         ctype <- maybe (Left ("unknown column type: " ++ T.unpack ty)) Right (columnTypeOf ty)
@@ -238,6 +248,7 @@ whereClause filters = case filters of
         terms <- mapM term filters
         pure (" WHERE " ++ intercalate " AND " terms)
   where
+    -- | 一个等值条件
     term (column, value) = do
         col <- checkIdent "column" column
         pure (T.unpack col ++ " = " ++ sqlLiteral value)
@@ -249,20 +260,21 @@ orderClause (Just (column, ascending)) = do
     col <- checkIdent "column" column
     pure (" ORDER BY " ++ T.unpack col ++ (if ascending then " ASC" else " DESC"))
 
--- | 账号名：与普通标识符同一套规则，另允许点与短横线（写成字符串形式）
+-- | 账号名：标识符规则另允许点与短横线
 accountName :: Text -> Either String Text
 accountName name
     | T.null name || T.length name > 64 = Left "account name is empty or too long"
     | not (T.all allowed name) = Left ("account name may only contain ASCII letters, digits, dot, dash or underscore: " ++ T.unpack name)
     | otherwise = Right name
   where
+    -- | 账号名允许的字符集
     allowed c = isAsciiLower c || isAsciiUpper c || isDigit c || c `elem` ("_.-" :: String)
 
 -- | 单引号字符串字面量
 quoted :: Text -> String
 quoted value = "'" ++ escapeStringLiteral (T.unpack value) ++ "'"
 
--- | 构造 CREATE USER（口令是明文，账号服务负责加盐派生）
+-- | 构造 CREATE USER
 createUserSql :: Text -> Text -> Either String String
 createUserSql name password = do
     user <- accountName name
@@ -283,3 +295,77 @@ dropUserSql :: Text -> Either String String
 dropUserSql name = do
     user <- accountName name
     pure ("DROP USER " ++ T.unpack user)
+
+-- | 角色名：与账号名同一套字符规则
+roleName :: Text -> Either String Text
+roleName name
+    | T.null name || T.length name > 64 = Left "role name is empty or too long"
+    | not (T.all allowed name) = Left ("role name may only contain ASCII letters, digits, dot, dash or underscore: " ++ T.unpack name)
+    | otherwise = Right name
+  where
+    -- | 角色名允许的字符集
+    allowed c = isAsciiLower c || isAsciiUpper c || isDigit c || c `elem` ("_.-" :: String)
+
+-- | 授权对象：`*`，或长度不超过 128 的裸表名/`库.表`
+grantObject :: Text -> Either String Text
+grantObject object
+    | T.strip object == "*" = Right "*"
+    | T.null object || T.length object > 128 = Left "object name is empty or too long"
+    | not (T.all allowed object) = Left ("object name may only contain ASCII letters, digits, dot, dash or underscore: " ++ T.unpack object)
+    | otherwise = Right object
+  where
+    -- | 授权对象允许的字符集
+    allowed c = isAsciiLower c || isAsciiUpper c || isDigit c || c `elem` ("_.-" :: String)
+
+-- | 权限清单：词要纯字母，认不认由 server 定
+privilegeWords :: [Text] -> Either String [Text]
+privilegeWords privileges
+    | null privileges = Left "at least one privilege is required"
+    | otherwise = mapM word privileges
+  where
+    -- | 单个权限词
+    word one
+        | T.null one || not (T.all (\c -> isAsciiLower c || isAsciiUpper c) one) = Left ("not a privilege keyword: " ++ T.unpack one)
+        | otherwise = Right one
+
+-- | 构造 CREATE ROLE
+createRoleSql :: Text -> Either String String
+createRoleSql name = do
+    role <- roleName name
+    pure ("CREATE ROLE " ++ T.unpack role)
+
+-- | 构造 DROP ROLE
+dropRoleSql :: Text -> Either String String
+dropRoleSql name = do
+    role <- roleName name
+    pure ("DROP ROLE " ++ T.unpack role)
+
+-- | 构造 GRANT 权限 ON 对象 TO 角色
+grantPrivilegesSql :: [Text] -> Text -> Text -> Either String String
+grantPrivilegesSql privileges object role = do
+    words' <- privilegeWords privileges
+    target <- grantObject object
+    who <- roleName role
+    pure ("GRANT " ++ T.unpack (T.intercalate ", " words') ++ " ON " ++ T.unpack target ++ " TO " ++ T.unpack who)
+
+-- | 构造 REVOKE 权限 ON 对象 FROM 角色
+revokePrivilegesSql :: [Text] -> Text -> Text -> Either String String
+revokePrivilegesSql privileges object role = do
+    words' <- privilegeWords privileges
+    target <- grantObject object
+    who <- roleName role
+    pure ("REVOKE " ++ T.unpack (T.intercalate ", " words') ++ " ON " ++ T.unpack target ++ " FROM " ++ T.unpack who)
+
+-- | 构造 GRANT <角色> TO <用户>[, ...]
+grantRoleSql :: Text -> [Text] -> Either String String
+grantRoleSql role users = do
+    who <- roleName role
+    members <- requireNonEmpty "users" users >>= mapM accountName
+    pure ("GRANT " ++ T.unpack who ++ " TO " ++ T.unpack (T.intercalate ", " members))
+
+-- | 构造 REVOKE 角色 FROM 用户
+revokeRoleSql :: Text -> [Text] -> Either String String
+revokeRoleSql role users = do
+    who <- roleName role
+    members <- requireNonEmpty "users" users >>= mapM accountName
+    pure ("REVOKE " ++ T.unpack who ++ " FROM " ++ T.unpack (T.intercalate ", " members))
diff --git a/chusql-web/src/ChuSQL/Web/Auth.hs b/chusql-interface/src/ChuSQL/Interface/Auth.hs
similarity index 61%
rename from chusql-web/src/ChuSQL/Web/Auth.hs
rename to chusql-interface/src/ChuSQL/Interface/Auth.hs
index 2d2fa11..c0241f5 100644
--- a/chusql-web/src/ChuSQL/Web/Auth.hs
+++ b/chusql-interface/src/ChuSQL/Interface/Auth.hs
@@ -1,6 +1,6 @@
 {-# LANGUAGE OverloadedStrings #-}
 
-module ChuSQL.Web.Auth (
+module ChuSQL.Interface.Auth (
     Credential (..),
     defaultIterations,
     hashPassword,
@@ -19,6 +19,15 @@ module ChuSQL.Web.Auth (
     lookupSession,
     deleteSession,
     sessionToken,
+    PayloadStore,
+    newPayloadStore,
+    payloadPolicy,
+    setPayloadPolicy,
+    createPayloadSession,
+    lookupPayload,
+    putPayload,
+    dropPayload,
+    sweepPayloads,
 ) where
 
 import Control.Concurrent.MVar (MVar, modifyMVar, modifyMVar_, newMVar)
@@ -37,8 +46,9 @@ import qualified Data.Text.Encoding as TE
 import Data.Time.Clock (NominalDiffTime, UTCTime, diffUTCTime)
 import Text.Read (readMaybe)
 
--- 口令与 Session：口令只存 PBKDF2 编码串，会话是服务端内存状态。
+-- 口令哈希与会话仓库，服务端与 Web 管理端共用。
 
+-- | 一条账号凭据：账号名 + 编码串
 data Credential = Credential
     { credUser :: Text
     , credEncoded :: Text
@@ -115,6 +125,7 @@ verifyPassword encoded candidate = case parseHash encoded of
 hashLooksValid :: Text -> Bool
 hashLooksValid = isJust . parseHash
 
+-- | 一条会话：账号、创建/最后活动时间与账号版本号
 data Session = Session
     { sessUser :: Text
     , sessCreated :: UTCTime
@@ -122,6 +133,7 @@ data Session = Session
     , sessRevision :: Maybe Integer
     }
 
+-- | 会话过期策略：空闲上限与绝对上限
 data SessionPolicy = SessionPolicy
     { spIdleSeconds :: NominalDiffTime
     , spAbsoluteSeconds :: NominalDiffTime
@@ -131,6 +143,7 @@ data SessionPolicy = SessionPolicy
 defaultSessionPolicy :: SessionPolicy
 defaultSessionPolicy = SessionPolicy (8 * 3600) (24 * 3600)
 
+-- | 会话仓库：令牌表、时钟与策略
 data SessionStore = SessionStore
     { storeMap :: MVar (Map.Map Text Session)
     , storeClock :: IO UTCTime
@@ -170,6 +183,7 @@ sessionToken = hexEncode <$> getRandomBytes 32
 createSession :: SessionStore -> Text -> IO Text
 createSession store user = createVersionedSession store user Nothing
 
+-- | 开一条会话并记下账号版本号，返回令牌
 createVersionedSession :: SessionStore -> Text -> Maybe Integer -> IO Text
 createVersionedSession store user revision = do
     token <- sessionToken
@@ -183,6 +197,7 @@ createVersionedSession store user revision = do
 lookupSession :: SessionStore -> Text -> IO (Maybe Text)
 lookupSession store token = fmap (fmap fst) (lookupVersionedSession store token)
 
+-- | 查令牌拿回账号名与账号版本号，并刷新最后活动时间
 lookupVersionedSession :: SessionStore -> Text -> IO (Maybe (Text, Maybe Integer))
 lookupVersionedSession store token = do
     now <- storeClock store
@@ -196,3 +211,95 @@ lookupVersionedSession store token = do
 -- | 删掉一条会话（退出登录）
 deleteSession :: SessionStore -> Text -> IO ()
 deleteSession store token = modifyMVar_ (storeMap store) (pure . Map.delete token)
+
+-- | 一条带载荷的会话：账号、时间与载荷
+data StoredSession a = StoredSession
+    { psUser :: Text
+    , psCreated :: UTCTime
+    , psSeen :: UTCTime
+    , psPayload :: a
+    }
+
+-- | 带载荷的会话仓库：令牌表、时钟与策略
+data PayloadStore a = PayloadStore
+    { psStoreMap :: MVar (Map.Map Text (StoredSession a))
+    , psClock :: IO UTCTime
+    , psPolicy :: IORef SessionPolicy
+    }
+
+-- | 造一个空的带载荷仓库
+newPayloadStore :: IO UTCTime -> SessionPolicy -> IO (PayloadStore a)
+newPayloadStore clock policy = do
+    ref <- newMVar Map.empty
+    policyRef <- newIORef policy
+    pure (PayloadStore ref clock policyRef)
+
+-- | 现在用的是哪套过期策略
+payloadPolicy :: PayloadStore a -> IO SessionPolicy
+payloadPolicy = readIORef . psPolicy
+
+-- | 换一套过期策略
+setPayloadPolicy :: PayloadStore a -> SessionPolicy -> IO ()
+setPayloadPolicy store = writeIORef (psPolicy store)
+
+-- | 这条带载荷的会话过期了吗
+payloadExpired :: UTCTime -> SessionPolicy -> StoredSession a -> Bool
+payloadExpired now pol s =
+    diffUTCTime now (psSeen s) > spIdleSeconds pol
+        || diffUTCTime now (psCreated s) > spAbsoluteSeconds pol
+
+-- | 清掉过期的带载荷会话
+prunePayloads :: UTCTime -> SessionPolicy -> Map.Map Text (StoredSession a) -> Map.Map Text (StoredSession a)
+prunePayloads now pol = Map.filter (not . payloadExpired now pol)
+
+-- | 上线一条带载荷的会话，返回令牌
+createPayloadSession :: PayloadStore a -> Text -> a -> IO Text
+createPayloadSession store user payload = do
+    token <- sessionToken
+    now <- psClock store
+    pol <- payloadPolicy store
+    modifyMVar_ (psStoreMap store) $ \m ->
+        pure (Map.insert token (StoredSession user now now payload) (prunePayloads now pol m))
+    pure token
+
+-- | 查令牌并刷新最后活动时间，拿回账号名与载荷
+lookupPayload :: PayloadStore a -> Text -> IO (Maybe (Text, a))
+lookupPayload store token = do
+    now <- psClock store
+    pol <- payloadPolicy store
+    modifyMVar (psStoreMap store) $ \m -> do
+        let kept = prunePayloads now pol m
+        pure $ case Map.lookup token kept of
+            Nothing -> (kept, Nothing)
+            Just s -> (Map.insert token s{psSeen = now} kept, Just (psUser s, psPayload s))
+
+-- | 换掉载荷；会话已没了就返回 False
+putPayload :: PayloadStore a -> Text -> a -> IO Bool
+putPayload store token payload = do
+    now <- psClock store
+    pol <- payloadPolicy store
+    modifyMVar (psStoreMap store) $ \m -> do
+        let kept = prunePayloads now pol m
+        pure $ case Map.lookup token kept of
+            Nothing -> (kept, False)
+            Just s -> (Map.insert token s{psSeen = now, psPayload = payload} kept, True)
+
+-- | 摘掉会话并把载荷交还
+dropPayload :: PayloadStore a -> Text -> IO (Maybe a)
+dropPayload store token = do
+    now <- psClock store
+    pol <- payloadPolicy store
+    modifyMVar (psStoreMap store) $ \m -> do
+        let kept = prunePayloads now pol m
+        pure $ case Map.lookup token kept of
+            Nothing -> (kept, Nothing)
+            Just s -> (Map.delete token kept, Just (psPayload s))
+
+-- | 清掉过期会话并把它们的载荷交还；调用者负责关掉这些载荷
+sweepPayloads :: PayloadStore a -> IO [a]
+sweepPayloads store = do
+    now <- psClock store
+    pol <- payloadPolicy store
+    modifyMVar (psStoreMap store) $ \m -> do
+        let (gone, kept) = Map.partition (payloadExpired now pol) m
+        pure (kept, map psPayload (Map.elems gone))
diff --git a/chusql-web/src/ChuSQL/Web/Config.hs b/chusql-interface/src/ChuSQL/Interface/Config.hs
similarity index 70%
rename from chusql-web/src/ChuSQL/Web/Config.hs
rename to chusql-interface/src/ChuSQL/Interface/Config.hs
index f699003..8d1bf76 100644
--- a/chusql-web/src/ChuSQL/Web/Config.hs
+++ b/chusql-interface/src/ChuSQL/Interface/Config.hs
@@ -1,6 +1,6 @@
 {-# LANGUAGE OverloadedStrings #-}
 
-module ChuSQL.Web.Config (
+module ChuSQL.Interface.Config (
     WebConfig (..),
     defaultWebConfig,
     defaultUser,
@@ -12,12 +12,14 @@ module ChuSQL.Web.Config (
     staticDirCandidates,
     rootUserName,
     canonicalSettingKeys,
-    resolvePipeName,
+    resolvePlainPassword,
+    ServerConfig (..),
+    defaultServerConfig,
+    loadServerConfigAt,
 ) where
 
-import ChuSQL.Storage.IPC (defaultPipeName)
-import ChuSQL.Web.Auth (Credential (..), hashPassword)
-import ChuSQL.Web.TOML (readSection)
+import ChuSQL.Interface.Auth (Credential (..), hashPassword)
+import ChuSQL.Interface.TOML (readSection)
 import Data.Char (toLower)
 import qualified Data.Map.Strict as Map
 import Data.Maybe (fromMaybe)
@@ -26,11 +28,7 @@ import qualified Data.Text as T
 import System.Directory (doesDirectoryExist)
 import Text.Read (readMaybe)
 
--- 运行参数：命令行 > 全局 chusql.toml 的分区 > 内置默认，不看环境变量。
--- 配置文件位置是固定的（安装时定下，见 ChuSQL.Web.TOML.defaultConfigFile），
--- 想读别处的文件只能在命令行用 --config 指。
--- 自己那段是 [web]；管名与数据目录取自 [server] pipe_name / [storage] data_dir，
--- 因为它们是存储进程的事实，前端只当端点读。root 凭据只认 [web] 里的明文。
+-- Web 与 server 的运行参数：命令行 > chusql.toml 分区 > 内置默认。
 
 -- | 默认账号名
 defaultUser :: Text
@@ -40,13 +38,12 @@ defaultUser = "root"
 defaultPassword :: Text
 defaultPassword = "chusql"
 
+-- | Web 管理端配置
 data WebConfig = WebConfig
     { wcHost :: String
     , wcPort :: Int
     , wcStaticDir :: FilePath
     , wcUser :: Text
-    , wcStorageServer :: Maybe FilePath
-    , wcPipeName :: Maybe String
     , wcDataDir :: Maybe FilePath
     , wcCookieSecure :: Bool
     , wcBodyLimit :: Int
@@ -62,16 +59,14 @@ data WebConfig = WebConfig
     }
     deriving (Show, Eq)
 
--- | 内置默认
+-- | Web 管理端参数的内置默认值
 defaultWebConfig :: WebConfig
 defaultWebConfig =
     WebConfig
         { wcHost = "127.0.0.1"
-        , wcPort = 7777
+        , wcPort = 7778
         , wcStaticDir = "static"
         , wcUser = ""
-        , wcStorageServer = Nothing
-        , wcPipeName = Nothing
         , wcDataDir = Nothing
         , wcCookieSecure = False
         , wcBodyLimit = 65536
@@ -86,12 +81,12 @@ defaultWebConfig =
         , wcSeedDemo = False
         }
 
--- | [web] 分区里的键统一成连字符写法（scripts/chusql.toml 用的是下划线）
---   两种写法同时出现时，连字符（设置页写的规范形式）优先。
+-- | 把设置键统一成连字符写法，重名时连字符优先
 canonicalSettingKeys :: Map.Map Text Text -> Map.Map Text Text
 canonicalSettingKeys saved =
     foldr (\(key, value) acc -> Map.insert (canonicalKey key) value acc) Map.empty (Map.toList saved)
   where
+    -- | 取一个键的规范名
     canonicalKey key = fromMaybe key (lookup key keyAliases)
 
 -- | 下划线写法到连字符写法的别名
@@ -109,22 +104,20 @@ keyAliases =
     , ("max_sql_length", "max-sql-length")
     , ("password_min_length", "password-min-length")
     , ("password_classes", "password-classes")
-    , ("storage_server", "storage-server")
     ]
 
--- | 这份配置用的还是内置默认口令吗。
---   显式留空（password = ""）是"只允许管理员免密登录"，算已经配置过。
+-- | 这份配置用的还是内置默认口令吗
 usingDefaultCredentials :: Map.Map Text Text -> Bool
 usingDefaultCredentials saved = Map.notMember "password" saved
 
 -- | 设置文件里某个键的非空值
 nonEmptyValue :: Text -> Map.Map Text Text -> Maybe Text
+-- | 查一个键
 nonEmptyValue key saved = case T.strip <$> Map.lookup key saved of
     Just value | not (T.null value) -> Just value
     _ -> Nothing
 
--- | root 凭据只认设置文件里的明文：给了明文就哈希它；显式留空就是免密（空编码串）；
---   没配这一项才回落到内置演示口令。
+-- | root 凭据：明文就哈希，留空免密，缺省用演示口令
 resolveCredential :: WebConfig -> Map.Map Text Text -> IO Credential
 resolveCredential cfg saved = do
     encoded <- case Map.lookup "password" saved of
@@ -133,32 +126,29 @@ resolveCredential cfg saved = do
         Nothing -> hashPassword defaultPassword
     pure (Credential (rootUserName cfg saved) encoded)
 
--- | 管理员名字：命令行 --user > 设置文件 user > 内置默认
+-- | 管理员名字：命令行 > 设置文件 > 内置默认
 rootUserName :: WebConfig -> Map.Map Text Text -> Text
 rootUserName cfg saved
     | not (T.null (T.strip (wcUser cfg))) = T.strip (wcUser cfg)
     | otherwise = fromMaybe defaultUser (nonEmptyValue "user" saved)
 
--- | 读配置：内置默认 < [web] 分区（端点取自 [server] / [storage]）。
---   user / password 不在这里读：它们由 rootUserName / resolveCredential 直接看设置文件。
+-- | 读配置：默认叠上 [web] 与 [storage]
 loadWebConfigAt :: FilePath -> IO WebConfig
 loadWebConfigAt path = do
     raw <- readSection path "web"
-    server <- readSection path "server"
     storage <- readSection path "storage"
-    pure (withEndpoint server storage (webConfigFromSection (canonicalSettingKeys raw)))
+    pure (withStorage storage (webConfigFromSection (canonicalSettingKeys raw)))
 
--- | 端点：存储进程 bind 的管名与它用的数据目录，前端只读不改
-withEndpoint :: Map.Map Text Text -> Map.Map Text Text -> WebConfig -> WebConfig
-withEndpoint server storage cfg =
-    cfg
-        { wcPipeName = T.unpack <$> nonEmptyValue "pipe_name" server
-        , wcDataDir = T.unpack <$> nonEmptyValue "data_dir" storage
-        }
+-- | 数据目录取自 [storage] 段
+withStorage :: Map.Map Text Text -> WebConfig -> WebConfig
+withStorage storage cfg =
+    cfg{wcDataDir = T.unpack <$> nonEmptyValue "data_dir" storage}
 
--- | 实际要连的管名：配置里没有就用与存储层一致的默认值
-resolvePipeName :: WebConfig -> String
-resolvePipeName cfg = fromMaybe defaultPipeName (wcPipeName cfg)
+-- | 管理员明文口令，没配回落到演示口令，显式留空回空串
+resolvePlainPassword :: Map.Map Text Text -> Text
+resolvePlainPassword saved = case Map.lookup "password" saved of
+    Just plain -> T.strip plain
+    Nothing -> defaultPassword
 
 -- | [web] 分区里的启动参数，缺失或坏值一律回到内置默认
 webConfigFromSection :: Map.Map Text Text -> WebConfig
@@ -178,7 +168,6 @@ webConfigFromSection saved =
         , wcMaxRows = sectionInt "max-rows" saved (wcMaxRows defaultWebConfig)
         , wcMaxSqlLength = sectionInt "max-sql-length" saved (wcMaxSqlLength defaultWebConfig)
         , wcSeedDemo = sectionBool "seed" saved (wcSeedDemo defaultWebConfig)
-        , wcStorageServer = T.unpack <$> nonEmptyValue "storage-server" saved
         }
 
 -- | 分区里一个键的非空字符串值
@@ -204,7 +193,41 @@ staticDirCandidates given =
 resolveStaticDir :: FilePath -> IO (Maybe FilePath)
 resolveStaticDir given = go (staticDirCandidates given)
   where
+    -- | 逐个试
     go [] = pure Nothing
     go (d : ds) = do
         ok <- doesDirectoryExist d
         if ok then pure (Just d) else go ds
+
+-- | 服务器监听参数
+data ServerConfig = ServerConfig
+    { scHost :: String
+    , scPort :: Int
+    , scMaxMessage :: Int
+    , scMaxRows :: Int
+    }
+    deriving (Eq, Show)
+
+-- | 默认本机 7777，行 1 MiB，最多 1000 行
+defaultServerConfig :: ServerConfig
+defaultServerConfig = ServerConfig "127.0.0.1" 7777 (1024 * 1024) 1000
+
+-- | 读 [server] 段键，缺的用默认
+loadServerConfigAt :: FilePath -> IO ServerConfig
+loadServerConfigAt path = do
+    values <- readSection path "server"
+    let -- | 取一个键的非空字符串值
+        textOf key fallback = case Map.lookup key values of
+            Just value | not (T.null (T.strip value)) -> T.unpack (T.strip value)
+            _ -> fallback
+        -- | 取一个键的整数值
+        intOf key fallback = case Map.lookup key values >>= readMaybe . T.unpack . T.strip of
+            Just number -> number
+            Nothing -> fallback
+    pure
+        defaultServerConfig
+            { scHost = textOf "host" (scHost defaultServerConfig)
+            , scPort = intOf "port" (scPort defaultServerConfig)
+            , scMaxMessage = intOf "max_message" (scMaxMessage defaultServerConfig)
+            , scMaxRows = intOf "max_rows" (scMaxRows defaultServerConfig)
+            }
diff --git a/chusql-interface/src/ChuSQL/Interface/Link.hs b/chusql-interface/src/ChuSQL/Interface/Link.hs
new file mode 100644
index 0000000..2fa3548
--- /dev/null
+++ b/chusql-interface/src/ChuSQL/Interface/Link.hs
@@ -0,0 +1,221 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module ChuSQL.Interface.Link (
+    Client,
+    connectClient,
+    closeClient,
+    clientLogin,
+    clientQuery,
+    clientPing,
+    clientCatalog,
+    clientDatabases,
+    clientRoles,
+    clientAccounts,
+    clientPolicy,
+    clientReloadPolicy,
+) where
+
+import ChuSQL.Core.Protocol (Account, QueryResult (..), TableInfo (..))
+import ChuSQL.Interface.Protocol (
+    ClientRequest (..),
+    RoleView,
+    ServerResponse (..),
+    decodeResponse,
+    encodeRequest,
+    protocolVersion,
+ )
+import Control.Concurrent.MVar (MVar, newMVar, withMVar)
+import Control.Exception (IOException, try)
+import qualified Data.ByteString.Lazy as BL
+import qualified Data.ByteString.Lazy.Char8 as BLC
+import qualified Data.ByteString.Char8 as BSC
+import Data.Text (Text)
+import qualified Data.Text as T
+import Network.Socket (
+    AddrInfo (..),
+    SocketType (Stream),
+    addrAddress,
+    addrFamily,
+    connect,
+    defaultHints,
+    defaultProtocol,
+    getAddrInfo,
+    socket,
+    socketToHandle,
+ )
+import System.IO (BufferMode (LineBuffering), Handle, IOMode (ReadWriteMode), hClose, hFlush, hSetBuffering, hSetNewlineMode, noNewlineTranslation)
+import System.IO.Error (isEOFError)
+
+-- 前端到 server 的 TCP 链路：一行一条 JSON，命令行与 Web 端共用。
+
+-- | 一条已连上、已对过协议版本的连接
+data Client = Client
+    { clHandle :: Handle
+    , clLock :: MVar ()
+    }
+
+-- | 连上 server 并对协议版本，失败给人话错误
+connectClient :: Text -> Int -> IO (Either Text Client)
+connectClient host port = do
+    opened <- try (openConnection host port) :: IO (Either IOException Handle)
+    case opened of
+        Left err -> pure (Left ("cannot reach the server at " <> T.pack (address host port) <> ": " <> T.pack (describe err)))
+        Right handle -> do
+            lock <- newMVar ()
+            let client = Client handle lock
+            greeted <- request client (ReqHello protocolVersion)
+            case greeted of
+                Right (RespHello version)
+                    | version == protocolVersion -> pure (Right client)
+                    | otherwise ->
+                        giveUp handle
+                            ( "server "
+                                <> T.pack (address host port)
+                                <> " speaks protocol "
+                                <> T.pack (show version)
+                                <> ", this client needs "
+                                <> T.pack (show protocolVersion)
+                            )
+                Right (RespError code message) -> giveUp handle (code <> ": " <> message)
+                Right _ -> giveUp handle "unexpected response to hello"
+                Left message -> giveUp handle message
+  where
+    -- | 对不上就关连接并回错误
+    giveUp handle message = do
+        _ <- try (hClose handle) :: IO (Either IOException ())
+        pure (Left message)
+
+-- | 断开连接；重复调用不报错
+closeClient :: Client -> IO ()
+closeClient client = do
+    _ <- try (hClose (clHandle client)) :: IO (Either IOException ())
+    pure ()
+
+-- | 一行请求一行响应；同一条连接上的请求串起来发
+request :: Client -> ClientRequest -> IO (Either Text ServerResponse)
+request client message = withMVar (clLock client) $ \_ -> do
+    outcome <- try (exchange (clHandle client) message) :: IO (Either IOException (Either Text ServerResponse))
+    pure $ case outcome of
+        Left err -> Left (T.pack (describe err))
+        Right answer -> answer
+
+-- | 在句柄上发一行请求、读回一行响应
+exchange :: Handle -> ClientRequest -> IO (Either Text ServerResponse)
+exchange handle message = do
+    BLC.hPutStr handle (encodeRequest message)
+    BLC.hPutStr handle "\n"
+    hFlush handle
+    line <- BSC.hGetLine handle
+    pure (decodeResponse (BL.fromStrict line))
+
+-- | 登录；成功返回是不是管理员
+clientLogin :: Client -> Text -> Text -> IO (Either Text Bool)
+clientLogin client user password = do
+    answer <- request client (ReqLogin user password)
+    case answer of
+        Left message -> pure (Left message)
+        Right (RespLogin _ admin) -> pure (Right admin)
+        Right other -> pure (failed "login" other)
+
+-- | 跑一条语句，拿回结果集
+clientQuery :: Client -> Text -> IO (Either Text QueryResult)
+clientQuery client sql = do
+    answer <- request client (ReqQuery sql)
+    case answer of
+        Left message -> pure (Left message)
+        Right (RespResult result) -> pure (Right result)
+        Right other -> pure (failed "a query" other)
+
+-- | 探活
+clientPing :: Client -> IO (Either Text ())
+clientPing client = do
+    answer <- request client ReqPing
+    case answer of
+        Left message -> pure (Left message)
+        Right RespPong -> pure (Right ())
+        Right other -> pure (failed "a ping" other)
+
+-- | 数据字典（\\dt 与 \\d 用）
+clientCatalog :: Client -> IO (Either Text [TableInfo])
+clientCatalog client = do
+    answer <- request client ReqCatalog
+    case answer of
+        Left message -> pure (Left message)
+        Right (RespCatalog infos) -> pure (Right infos)
+        Right other -> pure (failed "a catalog" other)
+
+-- | 库清单（\\l 用）
+clientDatabases :: Client -> IO (Either Text [Text])
+clientDatabases client = do
+    answer <- request client ReqDatabases
+    case answer of
+        Left message -> pure (Left message)
+        Right (RespDatabases names) -> pure (Right names)
+        Right other -> pure (failed "a database list" other)
+
+-- | 角色总览（\\dr 用）
+clientRoles :: Client -> IO (Either Text [RoleView])
+clientRoles client = do
+    answer <- request client ReqRoles
+    case answer of
+        Left message -> pure (Left message)
+        Right (RespRoles roles) -> pure (Right roles)
+        Right other -> pure (failed "a role list" other)
+
+-- | 账号清单（\\du 与管理页用）
+clientAccounts :: Client -> IO (Either Text [Account])
+clientAccounts client = do
+    answer <- request client ReqAccounts
+    case answer of
+        Left message -> pure (Left message)
+        Right (RespAccounts accounts) -> pure (Right accounts)
+        Right other -> pure (failed "an account list" other)
+
+-- | 当前生效的口令策略（最短长度、至少几类字符）
+clientPolicy :: Client -> IO (Either Text (Int, Int))
+clientPolicy client = do
+    answer <- request client ReqPolicy
+    case answer of
+        Left message -> pure (Left message)
+        Right (RespPolicy minLength classes) -> pure (Right (minLength, classes))
+        Right other -> pure (failed "a password policy" other)
+
+-- | 让 server 重读它自己的设置文件并换上新的口令策略
+clientReloadPolicy :: Client -> IO (Either Text (Int, Int))
+clientReloadPolicy client = do
+    answer <- request client ReqReloadPolicy
+    case answer of
+        Left message -> pure (Left message)
+        Right (RespPolicy minLength classes) -> pure (Right (minLength, classes))
+        Right other -> pure (failed "a password policy reload" other)
+
+-- | 应答形状对不上时的错误，error 应答取码与说明
+failed :: Text -> ServerResponse -> Either Text a
+failed what response = case response of
+    RespError code message -> Left (code <> ": " <> message)
+    _ -> Left ("unexpected response to " <> what)
+
+-- | 建连接（套接字转成文本模式的行缓冲句柄）
+openConnection :: Text -> Int -> IO Handle
+openConnection host port = do
+    let hints = defaultHints{addrSocketType = Stream}
+    infos <- getAddrInfo (Just hints) (Just (T.unpack host)) (Just (show port))
+    case infos of
+        [] -> ioError (userError ("cannot resolve server address: " ++ address host port))
+        (info : _) -> do
+            sock <- socket (addrFamily info) Stream defaultProtocol
+            connect sock (addrAddress info)
+            handle <- socketToHandle sock ReadWriteMode
+            hSetBuffering handle LineBuffering
+            hSetNewlineMode handle noNewlineTranslation
+            pure handle
+
+-- | 把主机端口拼成地址字样
+address :: Text -> Int -> String
+address host port = T.unpack host ++ ":" ++ show port
+
+-- | 断线给人的说法：EOF 就是 server 把连接关了
+describe :: IOException -> String
+describe err
+    | isEOFError err = "the server closed the connection"
+    | otherwise = show err
diff --git a/chusql-interface/src/ChuSQL/Interface/Policy.hs b/chusql-interface/src/ChuSQL/Interface/Policy.hs
new file mode 100644
index 0000000..4a06065
--- /dev/null
+++ b/chusql-interface/src/ChuSQL/Interface/Policy.hs
@@ -0,0 +1,42 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module ChuSQL.Interface.Policy (
+    PasswordPolicy (..),
+    defaultPasswordPolicy,
+    passwordKeys,
+    policyFromValues,
+) where
+
+import ChuSQL.Interface.Settings (defaultOf)
+import qualified Data.Map.Strict as Map
+import Data.Maybe (fromMaybe)
+import Data.Text (Text)
+import qualified Data.Text as T
+import Text.Read (readMaybe)
+
+-- 口令策略值与策略计算，服务端与 Web 管理端共用。
+
+-- | 口令策略：最短长度与至少几类字符
+data PasswordPolicy = PasswordPolicy
+    { ppMinLength :: Int
+    , ppClasses :: Int
+    }
+    deriving (Show, Eq)
+
+-- | 默认：至少 12 个字符、至少两类字符
+defaultPasswordPolicy :: PasswordPolicy
+defaultPasswordPolicy = PasswordPolicy 12 2
+
+-- | 设置文件里决定口令策略的键
+passwordKeys :: [Text]
+passwordKeys = ["password-min-length", "password-classes"]
+
+-- | 策略值：缺项或空值回落到内置默认
+policyFromValues :: PasswordPolicy -> Map.Map Text Text -> PasswordPolicy
+policyFromValues before values = PasswordPolicy
+    (number "password-min-length" (ppMinLength before)) (number "password-classes" (ppClasses before))
+  where
+    -- | 取一个键的数值，缺项或空值回落到给定默认
+    number key fallback = case Map.lookup key values of
+        Nothing -> fallback
+        Just value -> fromMaybe fallback (readMaybe (T.unpack (if T.null value then defaultOf key else value)))
diff --git a/chusql-interface/src/ChuSQL/Interface/Protocol.hs b/chusql-interface/src/ChuSQL/Interface/Protocol.hs
new file mode 100644
index 0000000..83230d6
--- /dev/null
+++ b/chusql-interface/src/ChuSQL/Interface/Protocol.hs
@@ -0,0 +1,248 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module ChuSQL.Interface.Protocol (
+    protocolVersion,
+    serverName,
+    ClientRequest (..),
+    ServerResponse (..),
+    decodeRequest,
+    encodeRequest,
+    encodeResponse,
+    decodeResponse,
+    Grant (..),
+    RoleView (..),
+) where
+
+import ChuSQL.Core.Protocol (Account (..), QueryResult (..), TableInfo (..), queryResultJson)
+import Data.Aeson (FromJSON (..), ToJSON (..), Value, object, withObject, (.:), (.:?), (.!=), (.=))
+import qualified Data.Aeson as A
+import qualified Data.Aeson.Key as AK
+import qualified Data.Aeson.KeyMap as KM
+import qualified Data.ByteString.Char8 as BSC
+import qualified Data.ByteString.Lazy as BL
+import Data.Maybe (fromMaybe)
+import Data.Text (Text)
+import qualified Data.Text as T
+
+-- server 线上协议的编解码：一行一条 JSON（UTF-8）。
+
+-- | 一条角色授权：角色 + 具体权限 + 对象
+data Grant = Grant
+    { grantRole :: Text
+    , grantPrivilege :: Text
+    , grantObject :: Text
+    }
+    deriving (Show, Eq, Ord)
+
+-- | 一个角色的全貌
+data RoleView = RoleView
+    { roleName :: Text
+    , roleGrants :: [Grant]
+    , roleMembers :: [Text]
+    }
+    deriving (Show, Eq)
+
+-- | 一条授权转成 JSON
+instance ToJSON Grant where
+    toJSON grant =
+        object
+            [ "role" .= grantRole grant
+            , "privilege" .= grantPrivilege grant
+            , "object" .= grantObject grant
+            ]
+
+-- | 从 JSON 读一条授权
+instance FromJSON Grant where
+    parseJSON = withObject "Grant" $ \o ->
+        Grant <$> o .: "role" <*> o .: "privilege" <*> o .: "object"
+
+-- | 一个角色转成 JSON
+instance ToJSON RoleView where
+    toJSON view =
+        object
+            [ "role" .= roleName view
+            , "grants" .= roleGrants view
+            , "members" .= roleMembers view
+            ]
+
+-- | 从 JSON 读一个角色
+instance FromJSON RoleView where
+    parseJSON = withObject "RoleView" $ \o ->
+        RoleView
+            <$> o .: "role"
+            <*> o .:? "grants" .!= []
+            <*> o .:? "members" .!= []
+
+-- | 协议版本；对不上就报协议错误
+protocolVersion :: Int
+protocolVersion = 1
+
+-- | server 名字，握手时回给客户端
+serverName :: Text
+serverName = "chusql-server"
+
+-- | 客户端请求
+data ClientRequest
+    = ReqHello Int
+    | ReqLogin Text Text
+    | ReqQuery Text
+    | ReqPing
+    | ReqQuit
+    | ReqStorage Value
+    | ReqCatalog
+    | ReqDatabases
+    | ReqRoles
+    | ReqAccounts
+    | ReqPolicy
+    | ReqReloadPolicy
+    deriving (Eq, Show)
+
+-- | 线上请求的原始字段
+data WireRequest = WireRequest
+    { wrMethod :: Text
+    , wrProtocol :: Maybe Int
+    , wrUser :: Maybe Text
+    , wrPassword :: Maybe Text
+    , wrSql :: Maybe Text
+    , wrRequest :: Maybe Value
+    }
+
+-- | 从 JSON 读原始请求字段
+instance A.FromJSON WireRequest where
+    parseJSON = A.withObject "request" $ \o ->
+        WireRequest
+            <$> o A..: "method"
+            <*> o A..:? "protocol"
+            <*> o A..:? "user"
+            <*> o A..:? "password"
+            <*> o A..:? "sql"
+            <*> o A..:? "request"
+
+-- | 请求解码：方法名走 method 标签
+decodeRequest :: BSC.ByteString -> Either Text ClientRequest
+decodeRequest raw = case A.eitherDecodeStrict raw of
+    Left _ -> Left "request is not valid JSON"
+    Right wire -> case T.toLower (T.strip (wrMethod wire)) of
+        "hello" -> Right (ReqHello (fromMaybe protocolVersion (wrProtocol wire)))
+        "login" -> case (wrUser wire, wrPassword wire) of
+            (Just user, Just password) -> Right (ReqLogin user password)
+            _ -> Left "login needs both user and password"
+        "query" -> maybe (Left "query needs sql") (Right . ReqQuery) (wrSql wire)
+        "storage" -> maybe (Left "storage needs request") (Right . ReqStorage) (wrRequest wire)
+        "catalog" -> Right ReqCatalog
+        "databases" -> Right ReqDatabases
+        "roles" -> Right ReqRoles
+        "accounts" -> Right ReqAccounts
+        "policy" -> Right ReqPolicy
+        "reload-policy" -> Right ReqReloadPolicy
+        "ping" -> Right ReqPing
+        "quit" -> Right ReqQuit
+        other -> Left ("unknown method: " <> other)
+
+-- | 客户端侧的请求编码（一行一条 JSON，不带换行）
+encodeRequest :: ClientRequest -> BL.ByteString
+encodeRequest = A.encode . requestJson
+
+-- | 客户端请求转 JSON；方法名走 method 标签
+requestJson :: ClientRequest -> Value
+requestJson request = case request of
+    ReqHello version -> object ["method" .= ("hello" :: Text), "protocol" .= version]
+    ReqLogin user password -> object ["method" .= ("login" :: Text), "user" .= user, "password" .= password]
+    ReqQuery sql -> object ["method" .= ("query" :: Text), "sql" .= sql]
+    ReqPing -> object ["method" .= ("ping" :: Text)]
+    ReqQuit -> object ["method" .= ("quit" :: Text)]
+    ReqStorage payload -> object ["method" .= ("storage" :: Text), "request" .= payload]
+    ReqCatalog -> object ["method" .= ("catalog" :: Text)]
+    ReqDatabases -> object ["method" .= ("databases" :: Text)]
+    ReqRoles -> object ["method" .= ("roles" :: Text)]
+    ReqAccounts -> object ["method" .= ("accounts" :: Text)]
+    ReqPolicy -> object ["method" .= ("policy" :: Text)]
+    ReqReloadPolicy -> object ["method" .= ("reload-policy" :: Text)]
+
+-- | 服务端响应
+data ServerResponse
+    = RespHello Int
+    | RespLogin Text Bool
+    | RespResult QueryResult
+    | RespPong
+    | RespBye
+    | RespError Text Text
+    | RespStorage Value
+    | RespCatalog [TableInfo]
+    | RespDatabases [Text]
+    | RespRoles [RoleView]
+    | RespAccounts [Account]
+    | RespPolicy Int Int
+    deriving (Eq, Show)
+
+-- | 响应转 JSON；结果集只多一个 status 字段
+encodeResponse :: ServerResponse -> BL.ByteString
+encodeResponse = A.encode . responseJson
+
+-- | 服务端响应转 JSON；结果集只是多一个 status 字段
+responseJson :: ServerResponse -> Value
+responseJson response = case response of
+    RespHello version -> object ["status" .= ("hello" :: Text), "protocol" .= version, "server" .= serverName]
+    RespLogin user admin -> object ["status" .= ("ok" :: Text), "user" .= user, "admin" .= admin]
+    RespPong -> object ["status" .= ("pong" :: Text)]
+    RespBye -> object ["status" .= ("bye" :: Text)]
+    RespError code message -> object ["status" .= ("error" :: Text), "code" .= code, "message" .= message]
+    RespStorage value -> object ["status" .= ("storage" :: Text), "response" .= value]
+    RespCatalog infos -> object ["status" .= ("catalog" :: Text), "schemas" .= infos]
+    RespDatabases names -> object ["status" .= ("databases" :: Text), "databases" .= names]
+    RespRoles roleList -> object ["status" .= ("roles" :: Text), "roles" .= roleList]
+    RespAccounts accountList -> object ["status" .= ("accounts" :: Text), "accounts" .= accountList]
+    RespPolicy minLength classes -> object ["status" .= ("policy" :: Text), "minLength" .= minLength, "classes" .= classes]
+    RespResult result -> case queryResultJson result of
+        A.Object fields -> A.Object (KM.insert "status" (A.String "result") fields)
+        other -> other
+
+-- | 响应解码（客户端用）
+decodeResponse :: BL.ByteString -> Either Text ServerResponse
+decodeResponse raw = case A.eitherDecode raw of
+    Left _ -> Left "response is not valid JSON"
+    Right (A.Object fields) -> case KM.lookup "status" fields of
+        Just (A.String status) -> decodeStatus status fields
+        _ -> Left "response is missing status"
+    Right _ -> Left "response is not a JSON object"
+  where
+    -- | 按 status 字段分派
+    decodeStatus status fields = case status of
+        "hello" -> Right (RespHello (intOf "protocol" fields))
+        "ok" -> Right (RespLogin (textOf "user" fields) (boolOf "admin" fields))
+        "pong" -> Right RespPong
+        "bye" -> Right RespBye
+        "error" -> Right (RespError (textOf "code" fields) (textOf "message" fields))
+        "storage" -> case KM.lookup "response" fields of
+            Just value -> Right (RespStorage value)
+            Nothing -> Left "storage response is missing response"
+        "result" -> case A.fromJSON (A.Object fields) of
+            A.Success result -> Right (RespResult result)
+            A.Error message -> Left (T.pack message)
+        "catalog" -> fromField "schemas" RespCatalog fields
+        "databases" -> fromField "databases" RespDatabases fields
+        "roles" -> fromField "roles" RespRoles fields
+        "accounts" -> fromField "accounts" RespAccounts fields
+        "policy" -> Right (RespPolicy (intOf "minLength" fields) (intOf "classes" fields))
+        other -> Left ("unexpected status: " <> other)
+
+    -- | 取一个字段解成目标类型
+    fromField :: A.FromJSON a => Text -> (a -> ServerResponse) -> A.Object -> Either Text ServerResponse
+    fromField key wrap fields = case A.fromJSON (fromMaybe A.Null (KM.lookup (AK.fromText key) fields)) of
+        A.Success value -> Right (wrap value)
+        A.Error message -> Left (T.pack message)
+
+    -- | 取一个整数字段
+    intOf key fields = case KM.lookup key fields of
+        Just (A.Number number) -> truncate number
+        _ -> 0
+
+    -- | 取一个文本字段
+    textOf key fields = case KM.lookup key fields of
+        Just (A.String text) -> text
+        _ -> ""
+
+    -- | 取一个布尔字段
+    boolOf key fields = case KM.lookup key fields of
+        Just (A.Bool flag) -> flag
+        _ -> False
diff --git a/chusql-web/src/ChuSQL/Web/RateLimit.hs b/chusql-interface/src/ChuSQL/Interface/RateLimit.hs
similarity index 93%
rename from chusql-web/src/ChuSQL/Web/RateLimit.hs
rename to chusql-interface/src/ChuSQL/Interface/RateLimit.hs
index a77b4eb..6f091ee 100644
--- a/chusql-web/src/ChuSQL/Web/RateLimit.hs
+++ b/chusql-interface/src/ChuSQL/Interface/RateLimit.hs
@@ -1,4 +1,4 @@
-module ChuSQL.Web.RateLimit (
+module ChuSQL.Interface.RateLimit (
     RateLimiter,
     newRateLimiter,
     setRateLimit,
@@ -15,16 +15,19 @@ import Data.Time.Clock (NominalDiffTime, UTCTime, diffUTCTime)
 
 -- 登录失败限流：按用户名数一个滑动窗口里的失败次数。
 
+-- | 一个键的失败计数与窗口起点
 data Attempt = Attempt
     { attCount :: Int
     , attStart :: UTCTime
     }
 
+-- | 限流阈值：次数上限与窗口长度
 data RateLimitPolicy = RateLimitPolicy
     { rlpMax :: Int
     , rlpWindow :: NominalDiffTime
     }
 
+-- | 限流器：计数表、阈值与时钟
 data RateLimiter = RateLimiter
     { rlMap :: MVar (Map.Map Text Attempt)
     , rlPolicy :: IORef RateLimitPolicy
diff --git a/chusql-interface/src/ChuSQL/Interface/Session.hs b/chusql-interface/src/ChuSQL/Interface/Session.hs
new file mode 100644
index 0000000..a1de66a
--- /dev/null
+++ b/chusql-interface/src/ChuSQL/Interface/Session.hs
@@ -0,0 +1,110 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module ChuSQL.Interface.Session (
+    Session,
+    newSession,
+    sessionIsAdmin,
+    sessionDatabase,
+    isPlainIdentifier,
+    authenticateSession,
+    switchDatabase,
+    runStatement,
+    catalog,
+    databases,
+    roleViews,
+    accounts,
+) where
+
+import ChuSQL.Core.Protocol (Account, QueryResult (..), TableInfo)
+import ChuSQL.Interface.Link (
+    Client,
+    clientAccounts,
+    clientCatalog,
+    clientDatabases,
+    clientLogin,
+    clientQuery,
+    clientRoles,
+ )
+import ChuSQL.Interface.Protocol (RoleView)
+import Data.Char (isAlpha, isAlphaNum)
+import Data.IORef (IORef, newIORef, readIORef, writeIORef)
+import Data.Text (Text)
+import qualified Data.Text as T
+
+-- 前端会话：本地记登录态与当前库，语句答案全部来自 server。
+
+-- | 一个前端会话：连接、当前库与管理员标记
+data Session = Session
+    { ssClient :: Client
+    , ssCurrent :: IORef Text
+    , ssAdmin :: IORef Bool
+    }
+
+-- | 开一个前端会话：登录之前没有管理员身份，也没有选中的库
+newSession :: Client -> IO Session
+newSession client = Session client <$> newIORef "" <*> newIORef False
+
+-- | 是不是管理员（由登录结果决定）
+sessionIsAdmin :: Session -> IO Bool
+sessionIsAdmin = readIORef . ssAdmin
+
+-- | 当前库
+sessionDatabase :: Session -> IO Text
+sessionDatabase = readIORef . ssCurrent
+
+-- | 与解析器一致的裸标识符判断
+isPlainIdentifier :: Text -> Bool
+isPlainIdentifier name =
+    not (T.null name)
+        && T.length name <= 64
+        && (isAlpha (T.head name) || T.head name == '_')
+        && T.all (\ch -> isAlphaNum ch || ch == '_') name
+
+-- | 登录：身份由 server 判定，这里只把管理员标记记下来
+authenticateSession :: Session -> Text -> Text -> IO (Either Text ())
+authenticateSession session user password = do
+    answer <- clientLogin (ssClient session) user password
+    case answer of
+        Left message -> pure (Left message)
+        Right admin -> writeIORef (ssAdmin session) admin >> pure (Right ())
+
+-- | 换库：名字先按解析器规矩校验，由 server 执行 USE
+switchDatabase :: Session -> Text -> IO (Either Text ())
+switchDatabase session rawName
+    | not (isPlainIdentifier name) = pure (Left ("not a plain database name: " <> name))
+    | otherwise = do
+        answer <- runStatement session ("USE " <> name)
+        case answer of
+            Left message -> pure (Left message)
+            Right _ -> pure (Right ())
+  where
+    -- | 规范化后的库名
+    name = T.toLower (T.strip rawName)
+
+-- | 跑一条语句；结果集里带回的当前库口径跟着一起更新
+runStatement :: Session -> Text -> IO (Either Text QueryResult)
+runStatement session sql = do
+    answer <- clientQuery (ssClient session) sql
+    case answer of
+        Left message -> pure (Left message)
+        Right result -> do
+            case qrDatabase result of
+                Just name -> writeIORef (ssCurrent session) name
+                Nothing -> pure ()
+            pure (Right result)
+
+-- | 数据字典（\\dt 与 \\d 用）
+catalog :: Session -> IO (Either Text [TableInfo])
+catalog session = clientCatalog (ssClient session)
+
+-- | 库清单（\\l 用）
+databases :: Session -> IO (Either Text [Text])
+databases session = clientDatabases (ssClient session)
+
+-- | 角色总览（\\dr 用）
+roleViews :: Session -> IO (Either Text [RoleView])
+roleViews session = clientRoles (ssClient session)
+
+-- | 账号清单（\\du 与管理页用）
+accounts :: Session -> IO (Either Text [Account])
+accounts session = clientAccounts (ssClient session)
diff --git a/chusql-web/src/ChuSQL/Web/Settings.hs b/chusql-interface/src/ChuSQL/Interface/Settings.hs
similarity index 85%
rename from chusql-web/src/ChuSQL/Web/Settings.hs
rename to chusql-interface/src/ChuSQL/Interface/Settings.hs
index 71f2f0d..21b3b93 100644
--- a/chusql-web/src/ChuSQL/Web/Settings.hs
+++ b/chusql-interface/src/ChuSQL/Interface/Settings.hs
@@ -1,6 +1,6 @@
 {-# LANGUAGE OverloadedStrings #-}
 
-module ChuSQL.Web.Settings (
+module ChuSQL.Interface.Settings (
     SettingItem (..),
     settingCatalogue,
     findItem,
@@ -15,16 +15,16 @@ module ChuSQL.Web.Settings (
     effectiveSettings,
 ) where
 
-import ChuSQL.Web.Config (WebConfig (..), canonicalSettingKeys, defaultUser)
-import ChuSQL.Web.TOML (readSection, writeSection)
+import ChuSQL.Interface.Config (WebConfig (..), canonicalSettingKeys, defaultUser)
+import ChuSQL.Interface.TOML (readSection, writeSection)
 import Data.List (nub)
 import qualified Data.Map.Strict as Map
 import Data.Text (Text)
 import qualified Data.Text as T
 
--- Web 配置项目录，与启动脚本共用一份全局 chusql.toml；
--- 每个键只写在它所属的那一段里，web 不再复制存储层的键。
+-- 设置目录，以及全局 chusql.toml 的读、写与校验。
 
+-- | 一个可配置项
 data SettingItem = SettingItem
     { siKey :: Text
     , siLabel :: Text
@@ -38,10 +38,10 @@ data SettingItem = SettingItem
     }
     deriving (Show, Eq)
 
--- | 全部可配置项（顺序即界面里的顺序）
+-- | 全部可配置项与界面顺序
 settingCatalogue :: [SettingItem]
 settingCatalogue =
-    [ item "port" "HTTP port" "server" "int" "7777" True True
+    [ item "port" "HTTP port" "server" "int" "7778" True True
     , item "host" "Listen address" "server" "text" "127.0.0.1" True True
     , item "static-dir" "Static directory" "server" "text" "static" True True
     , item "cookie-secure" "Secure cookie (behind TLS)" "server" "bool" "0" True False
@@ -59,16 +59,18 @@ settingCatalogue =
     , item "password-min-length" "口令最短长度" "auth" "int" "12" True False
     , item "password-classes" "口令字符类别数" "auth" "int" "2" True False
     , owned "data-dir" "Data directory" "storage" "text" "" "storage" "data_dir"
-    , owned "pipe-name" "Endpoint name" "storage" "text" "" "server" "pipe_name"
     , owned "storage-page-size" "Storage page size" "storage" "int" "4096" "page" "size"
     , owned "storage-btree-order" "Storage B+tree order" "storage" "int" "4" "btree" "order"
     , owned "storage-buffer-pool" "Storage buffer pool pages" "storage" "int" "1024" "buffer" "pool_size"
     , owned "storage-log" "Storage log level" "storage" "text" "info" "log" "level"
-    , item "storage-server" "Storage server executable" "storage" "text" "" True True
     , item "seed" "Seed demo data on start" "storage" "bool" "1" True True
+    , owned "tcp-host" "TCP listen address" "network" "text" "127.0.0.1" "server" "host"
+    , owned "tcp-port" "TCP port" "network" "int" "7777" "server" "port"
+    , owned "tcp-max-message" "TCP max request line (bytes)" "network" "int" "1048576" "server" "max_message"
+    , owned "tcp-max-rows" "TCP rows per result" "network" "int" "1000" "server" "max_rows"
     ]
   where
-    -- web 自己的键：分区写死 [web]，TOML 键名就是界面键名
+    -- | web 自己的键：分区写死 [web]
     item k l g kind def rootOnly restart =
         SettingItem
             { siKey = k
@@ -95,11 +97,11 @@ settingCatalogue =
             , siTomlKey = tomlKey
             }
 
--- | web 自己那段
+-- | web 自己的分区名
 webSection :: Text
 webSection = "web"
 
--- | 目录里涉及的分区（按出现顺序，去重）
+-- | 目录里涉及的分区，去重
 catalogueSections :: [Text]
 catalogueSections = nub [siSection i | i <- settingCatalogue]
 
@@ -113,7 +115,7 @@ findItem key = case [i | i <- settingCatalogue, siKey i == key] of
 isRootOnly :: Text -> Bool
 isRootOnly key = maybe False siRootOnly (findItem key)
 
--- | 只读项：root 凭据只认设置文件里的明文，网页端不能改（改文件后重启生效）
+-- | 网页端不能改的键
 lockedKeys :: [Text]
 lockedKeys = ["user", "password"]
 
@@ -140,10 +142,11 @@ liveKeys =
     , "max-sql-length"
     ]
 
--- | 读目录里用到的每个分区，摊成界面键；只有 [web] 统一成连字符写法
+-- | 读目录里用到的每个分区，摊成界面键
 readSettingsFile :: FilePath -> IO (Map.Map Text Text)
 readSettingsFile path = fmap Map.unions (mapM readSectionOf catalogueSections)
   where
+    -- | 读一个分区，摊成界面键
     readSectionOf section = do
         raw <- readSection path section
         let values = if section == webSection then canonicalSettingKeys raw else raw
@@ -156,10 +159,11 @@ readSettingsFile path = fmap Map.unions (mapM readSectionOf catalogueSections)
                 ]
             )
 
--- | 按分区写回：每个键落进自己的段，别的分区与注释原样保留
+-- | 按分区写回，别的分区与注释原样保留
 writeSettingsFile :: FilePath -> Map.Map Text Text -> IO (Either String ())
 writeSettingsFile path values = writeSections catalogueSections
   where
+    -- | 各分区依次写回
     writeSections [] = pure (Right ())
     writeSections (section : rest) = do
         let entries =
@@ -177,10 +181,11 @@ writeSettingsFile path values = writeSections catalogueSections
                     Left err -> pure (Left err)
                     Right () -> writeSections rest
 
--- | 把界面上传来的值合并进现有文件内容（只接受目录里有的键）
+-- | 把界面传来的值合并进现有内容，只认目录里的键
 applySettings :: Map.Map Text Text -> Map.Map Text Text -> Either String (Map.Map Text Text)
 applySettings current = go (Right current) . Map.toList
   where
+    -- | 逐项校验并合并
     go (Left e) _ = Left e
     go (Right acc) [] = Right acc
     go (Right acc) ((key, value) : rest) = case findItem key of
@@ -189,7 +194,7 @@ applySettings current = go (Right current) . Map.toList
             Left e -> Left e
             Right () -> go (Right (Map.insert key value acc)) rest
 
--- | 按类型校验一个值（空串表示"清掉"，一律放行）
+-- | 按类型校验一个值，空串一律放行
 checkKind :: SettingItem -> Text -> Either String ()
 checkKind spec value
     | T.null (T.strip value) = Right ()
@@ -205,7 +210,7 @@ checkKind spec value
         _ -> Left (T.unpack (siKey spec) ++ " needs a boolean, got: " ++ T.unpack value)
     | otherwise = Right ()
 
--- | 一项的内置默认值（设置被清掉、也没有别处给值时用它）
+-- | 一项的内置默认值
 defaultOf :: Text -> Text
 defaultOf key = maybe "" siDefault (findItem key)
 
@@ -229,9 +234,10 @@ effectiveSettings cfg =
         , ("user", if T.null (T.strip (wcUser cfg)) then defaultUser else T.strip (wcUser cfg))
         , ("seed", boolText (wcSeedDemo cfg))
         , ("data-dir", maybe "" T.pack (wcDataDir cfg))
-        , ("pipe-name", maybe "" T.pack (wcPipeName cfg))
         ]
   where
+    -- | 数值转文本
     tshow = T.pack . show
+    -- | 布尔转 "1"/"0"
     boolText True = "1"
     boolText False = "0"
diff --git a/chusql-web/src/ChuSQL/Web/TOML.hs b/chusql-interface/src/ChuSQL/Interface/TOML.hs
similarity index 89%
rename from chusql-web/src/ChuSQL/Web/TOML.hs
rename to chusql-interface/src/ChuSQL/Interface/TOML.hs
index 49ddb6a..88d4361 100644
--- a/chusql-web/src/ChuSQL/Web/TOML.hs
+++ b/chusql-interface/src/ChuSQL/Interface/TOML.hs
@@ -1,6 +1,6 @@
 {-# LANGUAGE OverloadedStrings #-}
 
-module ChuSQL.Web.TOML
+module ChuSQL.Interface.TOML
     ( readSection
     , writeSection
     , defaultConfigFile
@@ -19,7 +19,6 @@ import System.Directory (XdgDirectory (XdgConfig), createDirectoryIfMissing, doe
 import System.FilePath (takeDirectory, (</>))
 
 -- 全局 chusql.toml 的最小读写：只认 [section] 与 key = value。
--- 读写都是一次性打开就关，不长期占着文件句柄，别的层随时能读同一份文件。
 
 -- | 读一个分区；文件不存在或没有这个分区都当空表
 readSection :: FilePath -> Text -> IO (Map Text Text)
@@ -44,6 +43,7 @@ writeSection path section values = do
             written <- tryWrite (TE.encodeUtf8 updated)
             pure written
   where
+    -- | 目录不存在就先建
     prepareDirectory = do
         let dir = takeDirectory path
         if null dir
@@ -51,6 +51,7 @@ writeSection path section values = do
             else do
                 done <- try (createDirectoryIfMissing True dir) :: IO (Either IOException ())
                 pure (either (Left . show) (const (Right ())) done)
+    -- | 写文件，异常转成错误串
     tryWrite bytes = do
         done <- try (BS.writeFile path bytes) :: IO (Either IOException ())
         pure (either (Left . show) (const (Right ())) done)
@@ -59,6 +60,7 @@ writeSection path section values = do
 sectionEntries :: Text -> [Text] -> [(Text, Text)]
 sectionEntries wanted = go ""
   where
+    -- | 走到目标分区后收键值对
     go _ [] = []
     go current (line : rest)
         | Just name <- sectionName line = go name rest
@@ -89,6 +91,7 @@ assignment line = case T.breakOn "=" (stripComment line) of
 stripComment :: Text -> Text
 stripComment = T.pack . go False . T.unpack
   where
+    -- | 引号外遇到 # 就到此为止
     go _ [] = []
     go inString ('#' : rest)
         | not inString = []
@@ -103,12 +106,15 @@ unquote value
     | T.length value >= 2 && T.head value == '\'' && T.last value == '\'' = T.drop 1 (T.dropEnd 1 value)
     | otherwise = value
 
--- | 行级重写：本分区里已有的键就地更新，空值删行，缺的键补在分区末尾
+-- | 行级重写：已有键就地更新，空值删行，缺的补末尾
 rewrite :: Text -> Map Text Text -> [Text] -> [Text]
 rewrite section values = addMissing . replaceInSection . dropEmpties
   where
+    -- | 删掉空值的键
     dropEmpties = filter (\line -> maybe True (not . T.null . snd) (assignment line))
+    -- | 在目标分区里就地换行
     replaceInSection = go ""
+    -- | 走到目标分区后逐行替换
     go _ [] = []
     go current (line : rest)
         | Just name <- sectionName line = line : go name rest
@@ -116,25 +122,30 @@ rewrite section values = addMissing . replaceInSection . dropEmpties
         | otherwise = case assignment line of
             Just (key, _) | Just value <- Map.lookup key values -> assignmentLine key value : go current rest
             _ -> line : go current rest
+    -- | 分区里缺的键补在末尾
     addMissing lines' =
         let present = Set.fromList (keysOf section lines')
             missing = [(key, value) | (key, value) <- Map.toList values, not (Set.member key present), not (T.null value)]
          in if null missing then lines' else appendSection section missing lines'
 
+-- | 拼一行 key = value
 assignmentLine :: Text -> Text -> Text
 assignmentLine key value = key <> " = " <> quote value
 
+-- | 需要时才加引号
 quote :: Text -> Text
 quote value
     | T.all allowed value && not (T.null value) = value
     | otherwise = "\"" <> T.replace "\"" "\\\"" value <> "\""
   where
+    -- | 可以裸写的字符集
     allowed ch = ch `elem` ("0123456789.-" :: String)
 
 -- | 取某个分区里出现过的键
 keysOf :: Text -> [Text] -> [Text]
 keysOf wanted = go ""
   where
+    -- | 走到目标分区后收键名
     go _ [] = []
     go current (line : rest)
         | Just name <- sectionName line = go name rest
@@ -150,14 +161,13 @@ appendSection section entries lines' =
         ++ (if null lines' || not (T.null (last lines')) then [""] else [])
         ++ ("[" <> section <> "]") : [assignmentLine key value | (key, value) <- entries]
 
--- | 全局配置文件的位置：安装时定下的固定路径，跟随系统惯例
--- （Windows: %APPDATA%\ChuSQL\chusql.toml；其它平台: $XDG_CONFIG_HOME 或 ~/.config 下的 ChuSQL/chusql.toml）
+-- | 全局配置文件的固定路径，跟随系统惯例
 defaultConfigFile :: IO FilePath
 defaultConfigFile = do
     dir <- getXdgDirectory XdgConfig "ChuSQL"
     pure (dir </> "chusql.toml")
 
--- | 定位配置文件：命令行 --config 指的是哪份就读哪份，否则用固定路径
+-- | 定位配置文件：命令行 --config 优先，否则用固定路径
 resolveConfigPath :: Maybe FilePath -> IO FilePath
 resolveConfigPath (Just path) = pure path
 resolveConfigPath Nothing = defaultConfigFile
diff --git a/chusql-interface/stack.yaml b/chusql-interface/stack.yaml
new file mode 100644
index 0000000..04c6063
--- /dev/null
+++ b/chusql-interface/stack.yaml
@@ -0,0 +1,5 @@
+resolver: lts-24.59
+
+packages:
+- .
+- ../chusql-core/model
diff --git a/chusql-interface/stack.yaml.lock b/chusql-interface/stack.yaml.lock
new file mode 100644
index 0000000..e3f9041
--- /dev/null
+++ b/chusql-interface/stack.yaml.lock
@@ -0,0 +1,12 @@
+# This file was autogenerated by Stack.
+# You should not edit this file by hand.
+# For more information, please see the documentation at:
+#   https://docs.haskellstack.org/en/stable/topics/lock_files
+
+packages: []
+snapshots:
+- completed:
+    sha256: 0f728e30e843d7f00460ad56858b995a3b227fca683659c7df9f2fc3988a3ce1
+    size: 732465
+    url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/24/59.yaml
+  original: lts-24.59
diff --git a/chusql-server/app/Main.hs b/chusql-server/app/Main.hs
new file mode 100644
index 0000000..6417984
--- /dev/null
+++ b/chusql-server/app/Main.hs
@@ -0,0 +1,223 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module Main (main) where
+
+import ChuSQL.Core.Engine.Storage.FFI (storageVersion)
+import ChuSQL.Core.Engine.Storage.IPC (closeConnection, localStorageLink, setStorageLink)
+import ChuSQL.Interface.Auth (Credential (..))
+import ChuSQL.Interface.Config (
+    WebConfig (..),
+    defaultPassword,
+    defaultUser,
+    loadWebConfigAt,
+    resolveCredential,
+    usingDefaultCredentials,
+ )
+import ChuSQL.Interface.RateLimit (newRateLimiter)
+import ChuSQL.Interface.Settings (readSettingsFile)
+import ChuSQL.Interface.TOML (resolveConfigPath)
+import ChuSQL.Server.Backend (Backend (..), ipcBackend)
+import ChuSQL.Server.TCP (
+    ServerConfig (..),
+    ServerEnv,
+    loadServerConfigAt,
+    newServerEnv,
+    runServer,
+ )
+import Control.Exception (IOException, bracket, try)
+import qualified Data.Map.Strict as Map
+import Data.Text (Text)
+import qualified Data.Text as T
+import Data.Time.Clock (getCurrentTime)
+import System.Environment (getArgs)
+import System.Exit (exitFailure)
+import System.IO (BufferMode (LineBuffering), hSetBuffering, stdout)
+import Text.Read (readMaybe)
+
+-- TCP 服务器入口：解析命令行与配置，装入存储库并以一行一 JSON 的协议对外服务。
+
+data Options = Options
+    { optConfig :: Maybe FilePath
+    , optHost :: Maybe String
+    , optPort :: Maybe Int
+    , optUser :: Maybe Text
+    , optMaxMessage :: Maybe Int
+    , optMaxRows :: Maybe Int
+    , optHelp :: Bool
+    }
+
+-- | 全部选项都取默认值
+emptyOptions :: Options
+emptyOptions =
+    Options
+        { optConfig = Nothing
+        , optHost = Nothing
+        , optPort = Nothing
+        , optUser = Nothing
+        , optMaxMessage = Nothing
+        , optMaxRows = Nothing
+        , optHelp = False
+        }
+
+-- | 解析参数
+parseArgs :: [String] -> Either String Options
+parseArgs = go emptyOptions
+  where
+    -- | 逐条消费参数列表
+    go opts [] = Right opts
+    go opts ("--help" : rest) = go opts{optHelp = True} rest
+    go opts ("-h" : rest) = go opts{optHelp = True} rest
+    go opts ("--config" : v : rest) = go opts{optConfig = Just v} rest
+    go opts ("--host" : v : rest) = go opts{optHost = Just v} rest
+    go opts ("--user" : v : rest) = go opts{optUser = Just (T.pack v)} rest
+    go opts ("--port" : v : rest) = withInt "--port" v (\n -> go opts{optPort = Just n} rest)
+    go opts ("--max-message" : v : rest) = withInt "--max-message" v (\n -> go opts{optMaxMessage = Just n} rest)
+    go opts ("--max-rows" : v : rest) = withInt "--max-rows" v (\n -> go opts{optMaxRows = Just n} rest)
+    go _ (a : _) = Left ("unrecognized argument or missing value: " ++ a)
+
+    -- | 把参数值读成整数，读不出就报错
+    withInt :: String -> String -> (Int -> Either String Options) -> Either String Options
+    withInt name v k = maybe (Left (name ++ " needs an integer, got: " ++ v)) k (readMaybe v)
+
+-- | 打印用法说明
+usage :: IO ()
+usage = do
+    putStrLn "usage: chusql-server [options]"
+    putStrLn ""
+    putStrLn "config: chusql.toml sits at a fixed place and holds every knob;"
+    putStrLn "        Windows: %APPDATA%\\ChuSQL\\chusql.toml"
+    putStrLn "        other:   $XDG_CONFIG_HOME/ChuSQL/chusql.toml (or ~/.config/ChuSQL/chusql.toml)"
+    putStrLn "        [storage] data_dir; [server] host/port/max_message/max_rows;"
+    putStrLn "        [web] user/password (administrator credentials)"
+    putStrLn ""
+    putStrLn "  --config FILE          read that config file instead"
+    putStrLn "  --host H               listen address              ([server] host, default 127.0.0.1)"
+    putStrLn "  --port N               listen port                 ([server] port, default 7777)"
+    putStrLn "  --user NAME            administrator name          ([web] user, default root)"
+    putStrLn "  --max-message N        max bytes per request line  ([server] max_message, default 1048576)"
+    putStrLn "  --max-rows N           rows returned per query     ([server] max_rows, default 1000)"
+    putStrLn ""
+    putStrLn "protocol: one JSON object per line; hello / login / query / storage / ping / quit"
+    putStrLn "  {\"method\":\"login\",\"user\":\"root\",\"password\":\"...\"} then {\"method\":\"query\",\"sql\":\"SELECT 1\"}"
+    putStrLn "  {\"method\":\"storage\",\"request\":{...}} forwards one storage request (Web and the CLI use this)"
+    putStrLn ""
+    putStrLn "storage: this process loads the chusql_core_storage library in-process and owns the data directory"
+    putStrLn ""
+    putStrLn "administrator password: user / password in the [web] section of chusql.toml, else the built-in demo"
+    putStrLn "  an empty password means the administrator signs in with no password; ordinary accounts are then refused"
+    putStrLn ("without either the demo administrator is " ++ T.unpack defaultUser ++ " / " ++ T.unpack defaultPassword)
+
+-- | 命令行覆盖管理员
+applyWebOptions :: WebConfig -> Options -> WebConfig
+applyWebOptions cfg opts =
+    cfg
+        { wcUser = orElse (optUser opts) (wcUser cfg)
+        }
+
+-- | 命令行覆盖监听配置
+applyServerOptions :: ServerConfig -> Options -> ServerConfig
+applyServerOptions config opts =
+    config
+        { scHost = orElse (optHost opts) (scHost config)
+        , scPort = orElse (optPort opts) (scPort config)
+        , scMaxMessage = orElse (optMaxMessage opts) (scMaxMessage config)
+        , scMaxRows = orElse (optMaxRows opts) (scMaxRows config)
+        }
+
+-- | 有 Just 就用它，否则用兜底值
+orElse :: Maybe a -> a -> a
+orElse (Just x) _ = x
+orElse Nothing y = y
+
+-- | 入口
+main :: IO ()
+main = do
+    hSetBuffering stdout LineBuffering
+    args <- getArgs
+    case parseArgs args of
+        Left err -> do
+            putStrLn ("bad arguments: " ++ err)
+            usage
+            exitFailure
+        Right opts
+            | optHelp opts -> usage
+            | otherwise -> run opts
+
+-- | 起服务：装入存储库并装配各服务组件
+run :: Options -> IO ()
+run opts = do
+    configPath <- resolveConfigPath (optConfig opts)
+    base <- loadWebConfigAt configPath
+    let cfg = applyWebOptions base opts
+    saved <- readSettingsFile configPath
+    cred <- resolveCredential cfg saved
+    config <- applyServerOptions <$> loadServerConfigAt configPath <*> pure opts
+    opened <- localStorageLink (Just configPath)
+    case opened of
+        Left err -> do
+            putStrLn ("cannot open the storage library: " ++ err)
+            exitFailure
+        Right link -> do
+            setStorageLink link
+            backend <- ipcBackend
+            printBanner cfg config configPath
+            checkStorage backend
+            reportCredential cred saved
+            limiter <-
+                newRateLimiter
+                    getCurrentTime
+                    (wcLoginMaxAttempts cfg)
+                    (fromIntegral (wcLoginWindow cfg))
+            env <- newServerEnv backend cred configPath config limiter
+            let announce port = putStrLn ("listening:    tcp://" ++ scHost config ++ ":" ++ show port)
+            bracket (pure link) (const closeConnection) (const (serve env announce))
+
+-- | 起 TCP 服务并处理绑定失败
+serve :: ServerEnv -> (Int -> IO ()) -> IO ()
+serve env announce = do
+    result <- try (runServer env announce) :: IO (Either IOException ())
+    case result of
+        Right () -> pure ()
+        Left e -> do
+            putStrLn ("failed to serve TCP: " ++ show e)
+            putStrLn "  the port is probably taken or reserved by the system; try another one: --port 7777"
+            exitFailure
+
+-- | 报告口令来源，用内置默认口令时告警
+reportCredential :: Credential -> Map.Map Text Text -> IO ()
+reportCredential cred saved
+    | usingDefaultCredentials saved = do
+        putStrLn ""
+        putStrLn "  !! Administrator credentials are not configured; the built-in demo password is in use:"
+        putStrLn ("  !!   user " ++ T.unpack (credUser cred) ++ " / password " ++ T.unpack defaultPassword)
+        putStrLn "  !!   set user / password in the [web] section of chusql.toml and restart"
+        putStrLn ""
+    | T.null (credEncoded cred) =
+        putStrLn ("administrator: " ++ T.unpack (credUser cred) ++ " (passwordless: only the administrator may sign in)")
+    | otherwise = putStrLn ("administrator: " ++ T.unpack (credUser cred) ++ " (credentials come from the settings file only)")
+
+-- | 探测存储是否可用，答不上 ping 就退出
+checkStorage :: Backend -> IO ()
+checkStorage backend = do
+    up <- bePing backend
+    if up
+        then putStrLn "storage:      up (the library answered ping)"
+        else do
+            putStrLn "storage:      DOWN (the storage library did not answer ping)"
+            exitFailure
+
+-- | 启动横幅
+printBanner :: WebConfig -> ServerConfig -> FilePath -> IO ()
+printBanner cfg config configPath = do
+    version <- storageVersion
+    putStrLn "================== ChuSQL Server ==================="
+    putStrLn ("config file:  " ++ configPath)
+    putStrLn ("protocol:     chusql 1 (one JSON object per line)")
+    putStrLn
+        ( "limits:       message "
+            ++ show (scMaxMessage config)
+            ++ "B, query rows "
+            ++ show (scMaxRows config)
+        )
+    putStrLn ("storage:      chusql_core_storage library " ++ version)
+    putStrLn ("data dir:     " ++ orElse (wcDataDir cfg) "(from the config file, else the default)")
diff --git a/chusql-server/chusql-server.cabal b/chusql-server/chusql-server.cabal
new file mode 100644
index 0000000..36c9a3a
--- /dev/null
+++ b/chusql-server/chusql-server.cabal
@@ -0,0 +1,79 @@
+cabal-version: 2.4
+
+name:           chusql-server
+version:        1.0.0
+synopsis:       ChuSQL 数据库服务器：TCP 端点 + 自家协议 + SQL 会话
+description:    ChuSQL 的数据库服务器。负责监听 TCP、一行一条 JSON 的自家协议、
+                登录与限流，并把用户 SQL 转交给 chusql-core-engine（存储则由进程内
+                的 chusql_core_storage 动态库承担）。Web 管理端与命令行客户端都只
+                通过这条 TCP 连接访问数据库。
+build-type:     Simple
+
+library
+    hs-source-dirs:   src
+    exposed-modules:  ChuSQL.Server.Accounts
+                      ChuSQL.Server.Backend
+                      ChuSQL.Server.Policy
+                      ChuSQL.Server.Privileges
+                      ChuSQL.Server.Session
+                      ChuSQL.Server.TCP
+    build-depends:    base >= 4.14 && < 5
+                    , aeson
+                    , bytestring
+                    , chusql-core-engine
+                    , chusql-core-model
+                    , chusql-interface
+                    , containers
+                    , crypton
+                    , directory
+                    , filepath
+                    , memory
+                    , network
+                    , scientific
+                    , text
+                    , time
+                    , vector
+    default-language: Haskell2010
+    ghc-options:      -Wall
+
+executable chusql-server
+    main-is:          Main.hs
+    hs-source-dirs:   app
+    build-depends:    base
+                    , chusql-core-engine
+                    , chusql-core-model
+                    , chusql-interface
+                    , chusql-server
+                    , containers
+                    , filepath
+                    , text
+                    , time
+    default-language: Haskell2010
+    ghc-options:      -Wall -threaded
+    -- 运行期找 libchusql_core_storage.so：$ORIGIN 让二进制与动态库同目录即可
+    if os(linux)
+        ld-options: -Wl,-rpath,$ORIGIN
+    if os(osx)
+        ld-options: -Wl,-rpath,@loader_path
+
+test-suite chusql-server-test
+    type:             exitcode-stdio-1.0
+    main-is:          Spec.hs
+    hs-source-dirs:   test
+    build-depends:    base
+                    , aeson
+                    , bytestring
+                    , chusql-core-engine
+                    , chusql-core-model
+                    , chusql-interface
+                    , chusql-server
+                    , containers
+                    , directory
+                    , filepath
+                    , hspec
+                    , network
+                    , text
+                    , time
+                    , vector
+    default-language: Haskell2010
+    ghc-options:      -Wall -threaded
diff --git a/chusql-web/src/ChuSQL/Web/Accounts.hs b/chusql-server/src/ChuSQL/Server/Accounts.hs
similarity index 89%
rename from chusql-web/src/ChuSQL/Web/Accounts.hs
rename to chusql-server/src/ChuSQL/Server/Accounts.hs
index dc3ec51..3b14bd7 100644
--- a/chusql-web/src/ChuSQL/Web/Accounts.hs
+++ b/chusql-server/src/ChuSQL/Server/Accounts.hs
@@ -1,6 +1,6 @@
 {-# LANGUAGE OverloadedStrings #-}
 
-module ChuSQL.Web.Accounts (
+module ChuSQL.Server.Accounts (
     Accounts, AccountError (..), Principal (..), PasswordPolicy (..), defaultPasswordPolicy,
     newAccounts, accountsPolicy, setAccountsPolicy, passwordAllowed,
     rootUserName, principalName, principalIsRoot,
@@ -8,27 +8,18 @@ module ChuSQL.Web.Accounts (
     listAccounts, findAccount, AccountCommand (..), accountCommand, runAccountCommand,
 ) where
 
-import ChuSQL.Storage.IPC (Account (..), Request (..))
-import ChuSQL.Syntax.AST (Statement (..))
-import ChuSQL.Web.Auth
-import ChuSQL.Web.Backend (Backend (..), currentStamp)
+import ChuSQL.Core.Engine.Storage.IPC (Account (..), Request (..))
+import ChuSQL.Core.Engine.Syntax.AST (Statement (..))
+import ChuSQL.Interface.Auth
+import ChuSQL.Interface.Policy (PasswordPolicy (..), defaultPasswordPolicy)
+import ChuSQL.Server.Backend (Backend (..), currentStamp)
 import Control.Concurrent.MVar (MVar, newMVar, withMVar)
 import Data.Char (isAlphaNum, isAscii, isAsciiLower, isAsciiUpper, isDigit)
 import Data.IORef (IORef, newIORef, readIORef, writeIORef)
 import Data.Text (Text)
 import qualified Data.Text as T
 
--- 账号服务：root 来自配置，普通账号由 root 用 CREATE/ALTER/DROP USER 管，口令在这里做策略检查与 PBKDF2 派生。
-
-data PasswordPolicy = PasswordPolicy
-    { ppMinLength :: Int
-    , ppClasses :: Int
-    }
-    deriving (Show, Eq)
-
--- | 默认：至少 12 个字符、至少两类字符
-defaultPasswordPolicy :: PasswordPolicy
-defaultPasswordPolicy = PasswordPolicy 12 2
+-- 账号服务：root 来自配置，普通账号由 root 用 CREATE/ALTER/DROP USER 管理，口令在此校验并派生哈希。
 
 data AccountError = AccountError Text Text deriving (Show, Eq)
 
@@ -39,6 +30,7 @@ data Principal
     deriving (Eq)
 
 instance Show Principal where
+    -- | 身份的可读形式
     show (Root name) = "root " ++ show name
     show (Ordinary a) = "account " ++ show (accountUser a)
 
@@ -60,7 +52,7 @@ data Accounts = Accounts
     , acRoot :: Credential
     }
 
--- | 只记下配置根账号；root 不写系统表，所以启动时不需要任何持久化动作
+-- | 建账号服务，记录配置根账号
 newAccounts :: Backend -> SessionStore -> Credential -> IO Accounts
 newAccounts backend sessions credential = do
     lock <- newMVar ()
@@ -79,20 +71,24 @@ rootName = normalize . credUser . acRoot
 rootUserName :: Accounts -> Text
 rootUserName = rootName
 
+-- | 读当前生效的口令策略
 accountsPolicy :: Accounts -> IO PasswordPolicy
 accountsPolicy = readIORef . acPolicy
 
+-- | 换上一份新口令策略
 setAccountsPolicy :: Accounts -> PasswordPolicy -> IO ()
 setAccountsPolicy service = writeIORef (acPolicy service)
 
--- | 口令策略：长度 + 字符类别（历史与有效期随自助改密一起取消）
+-- | 按策略检查口令长度与字符类别
 passwordAllowed :: PasswordPolicy -> Text -> Either AccountError ()
 passwordAllowed policy password
     | T.length password < ppMinLength policy || T.length password > 256 = bad "password length does not meet policy"
     | classes < ppClasses policy = bad "password needs more character classes"
     | otherwise = Right ()
   where
+    -- | 构造一条请求错误
     bad = Left . AccountError "bad_request"
+    -- | 命中的字符类别数
     classes =
         length
             ( filter id
@@ -110,9 +106,10 @@ validateUserName name
         Left (AccountError "bad_request" "invalid account name")
     | otherwise = Right ()
   where
+    -- | 该字符是否允许使用
     allowed c = isAscii c && (isAlphaNum c || c `elem` ("_.-" :: String))
 
--- | 新建/改口令时的额外限制：管理员的名字保留给配置里的 root
+-- | 校验新账号名，并挡掉管理员保留名
 validateNewName :: Accounts -> Text -> Either AccountError ()
 validateNewName service name = do
     validateUserName name
@@ -137,7 +134,7 @@ storageResult (Left _) = Left storageFailure
 readAccounts :: Accounts -> IO (Either AccountError [Account])
 readAccounts service = fmap (either (const (Left storageFailure)) Right) (beAccounts (acBackend service) ReqAccountsList)
 
--- | 当前令牌对应的身份；会话版本与账号 revision 对不上就失效
+-- | 按令牌解析当前身份，版本对不上即失效
 currentUnlocked :: Accounts -> Text -> IO (Either AccountError Principal)
 currentUnlocked service token = do
     session <- lookupVersionedSession (acSessions service) token
@@ -156,11 +153,11 @@ currentUnlocked service token = do
                         then Right (Ordinary account)
                         else Left unauthorized
 
+-- | 加锁解析当前身份
 currentPrincipal :: Accounts -> Text -> IO (Either AccountError Principal)
 currentPrincipal service token = withMVar (acLock service) $ \_ -> currentUnlocked service token
 
--- | 登录：先比配置里的 root，再查系统表里的普通账号（没有切换身份的入口）。
---   配置里的口令留空即"免密"：只有管理员能用空口令进来，普通账号一律拒绝。
+-- | 登录：先比 root，再查普通账号；空口令即免密
 authenticate :: Accounts -> Text -> Text -> IO (Either AccountError Text)
 authenticate service user password = withMVar (acLock service) $ \_ ->
     if normalize user == rootName service
@@ -170,7 +167,9 @@ authenticate service user password = withMVar (acLock service) $ \_ ->
                 then pure (Left (AccountError "forbidden" "this server only accepts the administrator"))
                 else signInOrdinary
   where
+    -- | 配置里没有口令
     passwordless = T.null (credEncoded (acRoot service))
+    -- | 管理员登录
     signInRoot
         | passwordless =
             if T.null password
@@ -179,6 +178,7 @@ authenticate service user password = withMVar (acLock service) $ \_ ->
         | verifyPassword (credEncoded (acRoot service)) password =
             Right <$> createVersionedSession (acSessions service) (rootName service) Nothing
         | otherwise = pure (Left unauthorized)
+    -- | 普通账号登录
     signInOrdinary = do
         stored <- readAccounts service
         case stored of
@@ -217,7 +217,7 @@ createUser service name password = withMVar (acLock service) $ \_ -> do
             encoded <- hashPassword password
             storageResult <$> beAccounts (acBackend service) (ReqAccountCreate (normalize name) encoded)
 
--- | 改一个普通账号的口令（管理员重置，不受历史/有效期限制）
+-- | 管理员重置普通账号口令
 resetPassword :: Accounts -> Text -> Text -> IO (Either AccountError ())
 resetPassword service name password = withMVar (acLock service) $ \_ -> do
     policy <- accountsPolicy service
diff --git a/chusql-web/src/ChuSQL/Web/Backend.hs b/chusql-server/src/ChuSQL/Server/Backend.hs
similarity index 86%
rename from chusql-web/src/ChuSQL/Web/Backend.hs
rename to chusql-server/src/ChuSQL/Server/Backend.hs
index 1b7d11f..a985bd1 100644
--- a/chusql-web/src/ChuSQL/Web/Backend.hs
+++ b/chusql-server/src/ChuSQL/Server/Backend.hs
@@ -1,6 +1,6 @@
 {-# LANGUAGE OverloadedStrings #-}
 
-module ChuSQL.Web.Backend (
+module ChuSQL.Server.Backend (
     StatementResult (..),
     Backend (..),
     columnsFromStatement,
@@ -20,21 +20,22 @@ module ChuSQL.Web.Backend (
     tableRefsOf,
 ) where
 
-import ChuSQL.Engine (runStatement, runStatementM)
-import ChuSQL.Model
-import ChuSQL.Semantic (prepare)
-import ChuSQL.Storage (MonadStorage (schema))
-import ChuSQL.Storage.IPC (
+import ChuSQL.Core.Engine (runStatement, runStatementM)
+import ChuSQL.Core.Model
+import ChuSQL.Core.Engine.Semantic (prepare)
+import ChuSQL.Core.Engine.Storage (MonadStorage (schema))
+import ChuSQL.Core.Engine.Storage.IPC (
     Account (..),
     IPCStorage (..),
     Request (..),
     Response (..),
     SchemaColumn (..),
     TableInfo (..),
+    sendRawRequest,
     sendRequest,
  )
-import ChuSQL.Syntax.AST
-import ChuSQL.Syntax.Parser (parseStatement)
+import ChuSQL.Core.Engine.Syntax.AST
+import ChuSQL.Core.Engine.Syntax.Parser (parseStatement)
 import Control.Concurrent.MVar (MVar, modifyMVar, newMVar, readMVar, withMVar)
 import Data.List (nub)
 import Data.Text (Text)
@@ -44,7 +45,7 @@ import qualified Data.Aeson as A
 import qualified Data.ByteString.Lazy.Char8 as BL
 import qualified Data.Text as T
 
--- 后端：跑一条语句与取数据字典，分 IPC（真存储）和内存（测试）两套。
+-- 后端抽象：跑语句、取数据字典与账号，分 IPC（真存储）和内存（测试）两套实现。
 
 data StatementResult = StatementResult
     { srColumns :: [String]
@@ -58,6 +59,8 @@ data Backend = Backend
     , beAccounts :: Request -> IO (Either String [Account])
     , beWithDatabase :: String -> Backend
     , beDatabases :: IO (Either String [String])
+    -- | 原样转发一条存储请求
+    , beStorage :: A.Value -> IO (Either String A.Value)
     }
 
 -- | 按给定列名取列，固定列顺序
@@ -67,7 +70,7 @@ columnsFromStatement db stmt = case prepare db stmt of
     Right (SelectExpr items _ _ _ _ _) -> map fst items
     _ -> []
 
--- | 走本地端点的后端（真存储：Windows 具名管道 / Unix 套接字）
+-- | 走本地存储链路的后端
 ipcBackend :: IO Backend
 ipcBackend = do
     lock <- newMVar ()
@@ -95,10 +98,22 @@ ipcBackend = do
                     RespTables names -> Right names
                     RespError err -> Left err
                     _ -> Left "unexpected database response"
+            , beStorage = \payload -> withMVar lock $ \_ -> runRaw payload
             }
     -- 没有默认库：没选库时 current 是空串，任何请求都得先选库
     pure (backend "")
   where
+    -- | 转发一条存储请求并解析响应
+    runRaw :: A.Value -> IO (Either String A.Value)
+    runRaw payload = do
+        response <- sendRawRequest (BL.toStrict (A.encode payload))
+        pure $ case response of
+            Left err -> Left err
+            Right raw -> case A.eitherDecodeStrict raw of
+                Left err -> Left ("storage response is not valid JSON: " ++ err)
+                Right value -> Right value
+
+    -- | 走存储链路跑一条语句
     runIpc :: String -> String -> IO (Either String StatementResult)
     runIpc current sql = case fmap (inDatabase current) (parseStatement sql) of
         Left e -> pure (Left e)
@@ -114,12 +129,11 @@ ipcBackend = do
                         (r : _) -> pure (map fst r)
                     pure (Right (StatementResult cols rows))
 
--- | 内存后端（测试）：状态就是一个 `Database`，名字是它代表的库
+-- | 测试用内存后端，状态是一个 Database
 memoryBackend :: String -> MVar Database -> Backend
 memoryBackend = memoryBackendWith False
 
--- | 同一份内存状态可以按普通库（trusted=False）或系统库（trusted=True）视角跑：
---   系统库要能读写角色/授权表，普通库连看都不许看。
+-- | 构造内存后端，Bool 决定普通库还是系统库视角
 memoryBackendWith :: Bool -> String -> MVar Database -> Backend
 memoryBackendWith trusted name ref =
     Backend
@@ -147,30 +161,33 @@ memoryBackendWith trusted name ref =
                     [[("account", VStr (BL.unpack (A.encode a))) ] | a <- accounts]) : filter ((/= usersTable) . fst) db, Right accounts)
         , beWithDatabase = withDatabase
         , beDatabases = pure (Right (nub [name, systemDatabaseName]))
+        , beStorage = \_ -> pure (Left "storage is not available in this backend")
         }
   where
+    -- | 按视角过滤库里的表
     scoped = if trusted then filter (not . reserved . fst) else visible
+    -- | 该视角下要隐藏的表
     hidden = if trusted then reserved else internalTable
+    -- | 取结果列名，空结果回落到解析
     colsOf db stmt rows = case rows of
         [] -> columnsFromStatement db stmt
         (r : _) -> map fst r
 
-    -- 系统库视角给权限服务用；夹具自己的库走普通视角；没选库时只放行不碰表的语句
+    -- | 按目标库名挑视角
     withDatabase target
         | target == systemDatabaseName = memoryBackendWith True name ref
         | target == name = memoryBackendWith False name ref
         | null target = noDatabaseBackend (memoryBackendWith False name ref)
         | otherwise = unavailableDatabase ("unknown database: " ++ target) (memoryBackendWith False name ref)
 
+-- | 把后端的语句与字典都改成同一条错误
 unavailableDatabase :: String -> Backend -> Backend
 unavailableDatabase message backend = backend
     { beStatement = \_ -> pure (Left message)
     , beCatalog = pure (Left message)
     }
 
--- | 没选库时的视角：不碰表的语句（USE、建库、账号与角色）照跑，
---   一旦语句里出现裸表名就报 no database selected。
---   与存储层口径一致：`db.table` 这种限定名不需要先选库。
+-- | 未选库时的视角：只放行不碰表的语句
 noDatabaseBackend :: Backend -> Backend
 noDatabaseBackend backend = backend
     { beStatement = \sql -> case parseStatement sql of
@@ -181,11 +198,11 @@ noDatabaseBackend backend = backend
     , beCatalog = pure (Left "no database selected")
     }
 
--- | Database context is an immutable request value, never shared connection state.
---   子查询里出现的表名同样要带上数据库前缀，否则会落到错误的库里。
+-- | 给语句里的裸表名补上当前库前缀，子查询里的表名也一起改
 inDatabase :: String -> Statement -> Statement
 inDatabase current = walk
   where
+    -- | 递归改写语句里的表名
     walk :: Statement -> Statement
     walk stmt = case stmt of
         q@Select{} ->
@@ -214,14 +231,16 @@ inDatabase current = walk
         AlterColumnNull t c b -> AlterColumnNull (table t) c b
         other -> other
 
+    -- | 给单个表名补库前缀，已限定或没选库就原样
     table t | '.' `elem` t || null current = t
             | otherwise = current ++ "." ++ t
 
+    -- | 改写 FROM 子句
     source FromUnit = FromUnit
     source (FromTable a t) = FromTable a (table t)
     source (FromJoin k l a t e) = FromJoin k (source l) a (table t) (expr e)
 
-    -- 表达式里的子查询也要一起改写
+    -- | 改写表达式里的子查询
     expr (ScalarSub sq) = ScalarSub (sub sq)
     expr (ExistsSub sq neg) = ExistsSub (sub sq) neg
     expr (InSub a sq neg) = InSub (expr a) (sub sq) neg
@@ -245,9 +264,10 @@ inDatabase current = walk
     expr (MaxOf a) = MaxOf (expr a)
     expr other = other
 
+    -- | 改写一个子查询
     sub sq = sq {subqueryStatement = walk (subqueryStatement sq)}
 
--- | 语句里出现的表（含 JOIN、子查询、INSERT/UPDATE/DELETE 的目标）
+-- | 语句里出现的表
 statementTables :: Statement -> [Text]
 statementTables stmt = nub (case stmt of
     Select{} ->
@@ -307,6 +327,7 @@ exprTables expr = case expr of
     MaxOf a -> exprTables a
     _ -> []
   where
+    -- | 两侧都取表名
     both a b = exprTables a ++ exprTables b
 
 -- | 一张表的线上信息（内存实现：没有索引，统计现算）
@@ -320,6 +341,7 @@ tableInfoOf (name, tbl) =
         , tiStats = [(c, distinctOf c, False) | (c, _) <- tableCols tbl]
         }
   where
+    -- | 一列的不同值个数
     distinctOf c = length (nub [v | r <- tableRows tbl, Just v <- [lookup c r]])
 
 -- | 本地列类型转线上字符串（和 IPC 那边同一套写法）
@@ -340,14 +362,14 @@ wireColumn name col =
         , scCheck = columnCheck col
         }
 
--- | 系统库：账号、角色与授权表住在这里，其中的表都是系统表，只给管理员
+-- | 系统库名，账号、角色与授权表住在这里
 systemDatabaseName :: String
 systemDatabaseName = "system"
 
 usersTable :: String
 usersTable = "__chusql_users"
 
--- | 角色与授权表：住在 system 库，名字不带 `__chusql_` 前缀（Rust 存储层拒收那个前缀）
+-- | 角色与授权表的名字，不带内部前缀
 rolesTable :: String
 rolesTable = "sys_roles"
 
@@ -360,13 +382,15 @@ membersTable = "sys_members"
 internalNames :: [String]
 internalNames = [rolesTable, grantsTable, membersTable]
 
+-- | 名字是否带内部表前缀
 reserved :: String -> Bool
 reserved = T.isPrefixOf "__chusql_" . T.toLower . T.pack
 
--- | 服务自己的内部表：目录里不出现，普通作用域读写都拒（系统作用域才放行角色/授权表）
+-- | 是不是服务自己的内部表
 internalTable :: String -> Bool
 internalTable name = reserved name || T.unpack (T.toLower (T.pack name)) `elem` internalNames
 
+-- | 去掉内部表
 visible :: Database -> Database
 visible = filter (not . internalTable . fst)
 
@@ -374,6 +398,7 @@ visible = filter (not . internalTable . fst)
 currentStamp :: IO T.Text
 currentStamp = T.pack . formatTime defaultTimeLocale "%Y-%m-%d %H:%M:%S" <$> getCurrentTime
 
+-- | 在内存账号表上执行一条账号请求
 memoryAccounts :: Database -> T.Text -> Request -> Either String [Account]
 memoryAccounts db stamp req = do
     accounts <- case lookup usersTable db of
@@ -395,6 +420,7 @@ memoryAccounts db stamp req = do
             _ -> Right [x | x <- accounts, accountUser x /= T.toLower u]
         _ -> Left "invalid account request"
   where
+    -- | 把一行解回账号
     decodeAccount row = case lookup "account" row of
         Just (VStr encoded) -> A.eitherDecode (BL.pack encoded)
         _ -> Left "invalid account record"
diff --git a/chusql-server/src/ChuSQL/Server/Policy.hs b/chusql-server/src/ChuSQL/Server/Policy.hs
new file mode 100644
index 0000000..a00bd1f
--- /dev/null
+++ b/chusql-server/src/ChuSQL/Server/Policy.hs
@@ -0,0 +1,23 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module ChuSQL.Server.Policy (
+    configurePasswordPolicy,
+    policyFromValues,
+    passwordKeys,
+) where
+
+import ChuSQL.Interface.Policy (defaultPasswordPolicy, passwordKeys, policyFromValues)
+import ChuSQL.Interface.Settings (applySettings, defaultOf, readSettingsFile)
+import ChuSQL.Server.Accounts (Accounts, setAccountsPolicy)
+import qualified Data.Map.Strict as Map
+
+-- 口令策略装配：从设置文件读 password-* 键算出生效策略，并装到账号服务上。
+
+-- | 从设置文件装口令策略，坏值报错
+configurePasswordPolicy :: Accounts -> FilePath -> IO ()
+configurePasswordPolicy accounts path = do
+    saved <- readSettingsFile path
+    let values = Map.fromList [(key, Map.findWithDefault (defaultOf key) key saved) | key <- passwordKeys]
+    case applySettings Map.empty values of
+        Left err -> ioError (userError err)
+        Right valid -> setAccountsPolicy accounts (policyFromValues defaultPasswordPolicy valid)
diff --git a/chusql-web/src/ChuSQL/Web/Privileges.hs b/chusql-server/src/ChuSQL/Server/Privileges.hs
similarity index 88%
rename from chusql-web/src/ChuSQL/Web/Privileges.hs
rename to chusql-server/src/ChuSQL/Server/Privileges.hs
index 7fb81c4..90bc4e0 100644
--- a/chusql-web/src/ChuSQL/Web/Privileges.hs
+++ b/chusql-server/src/ChuSQL/Server/Privileges.hs
@@ -1,15 +1,6 @@
 {-# LANGUAGE OverloadedStrings #-}
 
--- | 角色与权限服务。
---
---   模型：权限挂在角色上，用户通过角色成员资格继承角色权限；管理员（root）隐式全权，
---   新账号默认零权限。语句（CREATE ROLE / DROP ROLE / GRANT / REVOKE）由引擎解析并做
---   基本校验，真正落库在这里。
---
---   存储：system 库里的三张普通表（`sys_roles` / `sys_grants` / `sys_members`）。
---   起普通名字是因为 Rust 存储层拒收 `__chusql_` 前缀的表名，那条路走不通；
---   读写都借 system 作用域后端的普通 SQL，内存后端与 IPC 后端共用一套逻辑。
-module ChuSQL.Web.Privileges (
+module ChuSQL.Server.Privileges (
     Grant (..),
     Membership (..),
     PrivilegeCommand (..),
@@ -26,11 +17,12 @@ module ChuSQL.Web.Privileges (
     runPrivilegeCommand,
 ) where
 
-import ChuSQL.Model (Row, Value (..))
-import ChuSQL.Syntax.AST
-import ChuSQL.Web.Accounts (Principal, principalIsRoot, principalName)
-import ChuSQL.Web.Actions (sqlLiteral)
-import ChuSQL.Web.Backend (
+import ChuSQL.Core.Model (Row, Value (..))
+import ChuSQL.Core.Engine.Syntax.AST
+import ChuSQL.Server.Accounts (Principal, principalIsRoot, principalName)
+import ChuSQL.Interface.Actions (sqlLiteral)
+import ChuSQL.Interface.Protocol (Grant (..), RoleView (..))
+import ChuSQL.Server.Backend (
     Backend (..),
     StatementResult (..),
     exprTables,
@@ -45,18 +37,13 @@ import Data.List (intercalate, isInfixOf, nub, sort)
 import Data.Text (Text)
 import qualified Data.Text as T
 
--- | 出错口径与账号服务一致，映射由 API 层统一做
+-- 角色与权限服务：角色、授权与成员关系落在 system 库的表里，并据此判权限。
+
+-- | 出错口径与账号服务一致
 data PrivilegeError = PrivilegeError Text Text
     deriving (Show, Eq)
 
--- | 一条角色授权：角色 + 具体权限 + 对象（`*` 或 `库.表`）
-data Grant = Grant
-    { grantRole :: Text
-    , grantPrivilege :: Text
-    , grantObject :: Text
-    }
-    deriving (Show, Eq, Ord)
-
+-- 一条角色授权（定义在共享协议层）
 -- | 角色成员资格
 data Membership = Membership
     { memberRole :: Text
@@ -64,13 +51,7 @@ data Membership = Membership
     }
     deriving (Show, Eq, Ord)
 
--- | 一个角色的全貌
-data RoleView = RoleView
-    { roleName :: Text
-    , roleGrants :: [Grant]
-    , roleMembers :: [Text]
-    }
-    deriving (Show, Eq)
+-- | 一个角色的全貌：授权与成员
 
 data PrivilegeCommand
     = CreateRoleCommand Text
@@ -86,13 +67,13 @@ data Privileges = Privileges
     , pvLock :: MVar ()
     }
 
--- | 服务固定看 system 库；构造时不碰存储，第一次用才建表
+-- | 建权限服务，固定在 system 库上
 newPrivileges :: Backend -> IO Privileges
 newPrivileges base = do
     lock <- newMVar ()
     pure (Privileges (beWithDatabase base systemDatabaseName) lock)
 
--- | 语句 → 管理命令（引擎只解析与基本校验，不认的语句给 Nothing）
+-- | 语句转管理命令，不认的给 Nothing
 privilegeCommand :: Statement -> Maybe PrivilegeCommand
 privilegeCommand stmt = case stmt of
     CreateRole name -> Just (CreateRoleCommand (T.pack name))
@@ -112,13 +93,13 @@ runPrivilegeCommand service principal database command
     | needsDatabase = pure (Left (PrivilegeError "no_database" "no database selected"))
     | otherwise = withTables service (applyCommand service database command)
   where
-    -- 授权到具体对象（不是 `*`）时要把裸表名补成 `库.表`，没选库就无从补全
+    -- | 授权到具体对象时需要先选库
     needsDatabase = T.null database && case command of
         GrantPrivilegesCommand _ object _ -> T.strip object /= "*"
         RevokePrivilegesCommand _ object _ -> T.strip object /= "*"
         _ -> False
 
--- | 语句鉴权：管理员全通；普通身份按语句需要的每一项 (表, 权限) 查
+-- | 语句鉴权：管理员全通，普通身份按需查
 authorize :: Privileges -> Principal -> Text -> Statement -> IO (Either PrivilegeError ())
 authorize service principal database stmt
     | principalIsRoot principal = pure (Right ())
@@ -134,7 +115,7 @@ authorizeTables service principal database needed
         grants <- grantsOfUser service (principalName principal)
         pure (grants >>= \found -> checkAll database found needed)
 
--- | 只留下用户有 SELECT 权限的表（管理员看全部）；表清单接口用
+-- | 只留下用户有 SELECT 权的表
 filterTables :: Privileges -> Principal -> Text -> [Text] -> IO (Either PrivilegeError [Text])
 filterTables service principal database tables
     | principalIsRoot principal = pure (Right tables)
@@ -150,6 +131,7 @@ listRoleViews service = withTables service $ do
         Left err -> pure (Left err)
         Right known -> sequence <$> mapM view (sort known)
   where
+    -- | 组装一个角色的总览
     view role = do
         grants <- roleGrantsOf service role
         members <- membersOfRole service role
@@ -162,7 +144,7 @@ normalizeObject database object
     | T.any (== '.') object = T.toLower (T.strip object)
     | otherwise = normalizeUser database <> "." <> normalizeUser object
 
--- | 一条语句需要哪些 (表, 权限)；Nothing 表示管理员专属
+-- | 一条语句需要哪些 (表, 权限)
 requiredActions :: Statement -> Maybe [(Text, Text)]
 requiredActions stmt = case stmt of
     Select{} -> Just (selectNeeds (selectFrom stmt) (maybe [] (: []) (selectWhere stmt)))
@@ -173,7 +155,9 @@ requiredActions stmt = case stmt of
     Delete table cond -> Just ((T.pack table, "delete") : selectsOf (maybe [] (: []) cond))
     _ -> Nothing
   where
+    -- | FROM 子句要的 SELECT 权限
     selectNeeds source exprs = [(ref, "select") | ref <- nub (tableRefsOf source)] ++ selectsOf exprs
+    -- | 表达式里子查询要的 SELECT 权限
     selectsOf exprs = [(ref, "select") | ref <- nub (concatMap exprTables exprs)]
 
 -- | 每项 (表, 权限) 都要被某条授权覆盖
@@ -183,6 +167,7 @@ checkAll database grants needed = case [pair | pair@(table, privilege) <- needed
     ((table, privilege) : _) ->
         Left (PrivilegeError "forbidden" ("permission denied: " <> T.toUpper privilege <> " ON " <> table))
   where
+    -- | 某一项是否被授权覆盖
     covered table privilege =
         let target = normalizeObject database table
          in any
@@ -301,15 +286,18 @@ withTables service action = withMVar (pvLock service) $ \_ -> do
         Left err -> pure (Left err)
         Right () -> action
 
+-- | 确保三张内部表存在
 ensureTables :: Privileges -> IO (Either PrivilegeError ())
 ensureTables service = each tableDefs (createTable service)
   where
+    -- | 三张内部表的定义
     tableDefs =
         [ (rolesTable, "(name VARCHAR(64))")
         , (grantsTable, "(role VARCHAR(64), privilege VARCHAR(16), object VARCHAR(128))")
         , (membersTable, "(role VARCHAR(64), member VARCHAR(64))")
         ]
 
+-- | 建一张内部表，已存在算成功
 createTable :: Privileges -> (String, String) -> IO (Either PrivilegeError ())
 createTable service (table, columns) = do
     result <- beStatement (pvBackend service) ("CREATE TABLE " ++ table ++ " " ++ columns)
@@ -341,6 +329,7 @@ cell column row = case lookup column row of
     Just (VStr value) -> T.pack value
     _ -> ""
 
+-- | 一行记录转成授权
 grantOf :: Row -> Grant
 grantOf row =
     Grant
@@ -349,19 +338,22 @@ grantOf row =
         , grantObject = T.toLower (T.strip (cell "object" row))
         }
 
+-- | 拼一条删授权的 SQL
 deleteGrantSql :: Text -> Text -> Text -> String
 deleteGrantSql role privilege object =
     "DELETE FROM " ++ grantsTable ++ " WHERE role = " ++ roleLiteral role
         ++ " AND privilege = " ++ literal privilege ++ " AND object = " ++ literal object
 
+-- | 拼一条插入的 SQL
 insertSql :: String -> [String] -> [Text] -> String
 insertSql table columns values =
     "INSERT INTO " ++ table ++ " (" ++ intercalate ", " columns ++ ") VALUES (" ++ intercalate ", " (map literal values) ++ ")"
 
--- | 授权里的 ALL 展开成四种具体权限（存具体权限，鉴权不做兜底）
+-- | 把 ALL 展开成四种具体权限
 expandPrivileges :: [Text] -> [Text]
 expandPrivileges privileges = nub (concatMap expand (map (T.toLower . T.strip) privileges))
   where
+    -- | 展开一条权限名
     expand "all" = ["select", "insert", "update", "delete"]
     expand other = [other]
 
@@ -374,23 +366,29 @@ each (item : rest) action = do
         Left err -> pure (Left err)
         Right () -> each rest action
 
+-- | 角色名的 SQL 字面量
 roleLiteral :: Text -> String
 roleLiteral = literal . normalizeRole
 
+-- | 文本值的 SQL 字面量
 literal :: Text -> String
 literal = sqlLiteral . VStr . T.unpack
 
+-- | 角色名统一小写去空白
 normalizeRole :: Text -> Text
 normalizeRole = T.toLower . T.strip
 
+-- | 用户名统一小写去空白
 normalizeUser :: Text -> Text
 normalizeUser = T.toLower . T.strip
 
 forbidden :: PrivilegeError
 forbidden = PrivilegeError "forbidden" "administrator required"
 
+-- | 未知角色的错误
 unknownRole :: Text -> PrivilegeError
 unknownRole role = PrivilegeError "not_found" ("unknown role: " <> role)
 
+-- | 存储错误转成权限错误
 storageError :: String -> PrivilegeError
 storageError message = PrivilegeError "storage_error" ("privilege storage: " <> T.pack message)
diff --git a/chusql-server/src/ChuSQL/Server/Session.hs b/chusql-server/src/ChuSQL/Server/Session.hs
new file mode 100644
index 0000000..a8dda41
--- /dev/null
+++ b/chusql-server/src/ChuSQL/Server/Session.hs
@@ -0,0 +1,327 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module ChuSQL.Server.Session
+    ( QueryResult (..)
+    , Session
+    , SessionError (..)
+    , engineErrorCode
+    , newSession
+    , sessionUser
+    , sessionIsAdmin
+    , sessionDatabase
+    , isPlainIdentifier
+    , authenticateSession
+    , authenticateSessionCoded
+    , switchDatabase
+    , runStatement
+    , runStatementCoded
+    , catalog
+    , accounts
+    , roleViews
+    , databases
+    , policyOf
+    , reloadPolicy
+    , queryResultJson
+    ) where
+
+import ChuSQL.Core.Model (Value (..))
+import ChuSQL.Core.Protocol (Account, QueryResult (..), queryResultJson)
+import ChuSQL.Core.Engine.Storage.IPC (TableInfo (..))
+import ChuSQL.Core.Engine.Syntax.AST (Statement (..))
+import ChuSQL.Core.Engine.Syntax.Parser (parseStatement)
+import ChuSQL.Interface.AccountTable (systemTableInfo)
+import ChuSQL.Interface.Auth (Credential, defaultSessionPolicy, newSessionStore)
+import ChuSQL.Server.Accounts
+import ChuSQL.Server.Backend (Backend (..), StatementResult (..))
+import ChuSQL.Server.Policy (configurePasswordPolicy)
+import ChuSQL.Server.Privileges (PrivilegeCommand, PrivilegeError (..), Privileges, RoleView, authorize, filterTables, listRoleViews, newPrivileges, privilegeCommand, runPrivilegeCommand)
+import Control.Exception (IOException, try)
+import Data.Bifunctor (first)
+import Data.Char (isAlpha, isAlphaNum)
+import Data.IORef (IORef, newIORef, readIORef, writeIORef)
+import Data.Text (Text)
+import qualified Data.Text as T
+import Data.Time.Clock (getCurrentTime)
+
+-- SQL 会话：Web、命令行与 TCP 服务器共用的账号、权限与语句执行入口。
+
+-- | 带错误码的失败：码与 Web REST 的错误码同一个词汇表
+data SessionError = SessionError
+    { sessCode :: Text
+    , sessMessage :: Text
+    }
+    deriving (Eq, Show)
+
+-- | 引擎报错翻成错误码
+engineErrorCode :: String -> SessionError
+engineErrorCode err
+    | "no database selected" `T.isInfixOf` message = SessionError "no_database" message
+    | "unknown table" `T.isInfixOf` message = SessionError "not_found" message
+    | otherwise = SessionError "query_error" message
+  where
+    message = T.pack err
+
+data Session = Session
+    { ssBackend :: Backend
+    , ssAccounts :: Accounts
+    , ssPrivileges :: Privileges
+    , ssCurrent :: IORef Text
+    , ssPrincipal :: IORef (Maybe Principal)
+    , ssSettingsFile :: FilePath
+    }
+
+-- | 开一个会话：账号与角色服务、配置策略都和 Web 端一致
+newSession :: Backend -> Credential -> FilePath -> IO Session
+newSession backend credential settingsFile = do
+    sessions <- newSessionStore getCurrentTime defaultSessionPolicy
+    accountsService <- newAccounts backend sessions credential
+    privileges <- newPrivileges backend
+    configurePasswordPolicy accountsService settingsFile
+    -- 服务启动后只有系统库：没 USE 之前不预设任何工作库
+    current <- newIORef ""
+    principal <- newIORef Nothing
+    pure (Session backend accountsService privileges current principal settingsFile)
+
+-- | 当前生效的口令策略（只有管理员能看）
+policyOf :: Session -> IO (Either Text PasswordPolicy)
+policyOf session = do
+    admin <- sessionIsAdmin session
+    if not admin
+        then pure (Left "administrator required")
+        else Right <$> accountsPolicy (ssAccounts session)
+
+-- | 重读设置文件里的口令策略
+reloadPolicy :: Session -> IO (Either Text PasswordPolicy)
+reloadPolicy session = do
+    admin <- sessionIsAdmin session
+    if not admin
+        then pure (Left "administrator required")
+        else do
+            outcome <- try (configurePasswordPolicy (ssAccounts session) (ssSettingsFile session)) :: IO (Either IOException ())
+            case outcome of
+                Left err -> pure (Left (T.pack (show err)))
+                Right () -> policyOf session
+
+-- | 当前登录的账号名
+sessionUser :: Session -> IO (Maybe Text)
+sessionUser session = fmap principalName <$> readIORef (ssPrincipal session)
+
+-- | 是不是配置里的 root
+sessionIsAdmin :: Session -> IO Bool
+sessionIsAdmin session = maybe False principalIsRoot <$> readIORef (ssPrincipal session)
+
+-- | 当前库
+sessionDatabase :: Session -> IO Text
+sessionDatabase = readIORef . ssCurrent
+
+-- | 与解析器一致的裸标识符判断
+isPlainIdentifier :: Text -> Bool
+isPlainIdentifier name =
+    not (T.null name)
+        && T.length name <= 64
+        && (isAlpha (T.head name) || T.head name == '_')
+        && T.all (\ch -> isAlphaNum ch || ch == '_') name
+
+-- | 登录：root 比配置凭据，普通账号查系统表
+authenticateSession :: Session -> Text -> Text -> IO (Either Text ())
+authenticateSession session user password =
+    fmap (first sessMessage) (authenticateSessionCoded session user password)
+
+-- | 登录（带错误码）
+authenticateSessionCoded :: Session -> Text -> Text -> IO (Either SessionError ())
+authenticateSessionCoded session user password = do
+    result <- authenticate (ssAccounts session) user password
+    case result of
+        Left err -> pure (Left (accountErrorOf err))
+        Right token -> do
+            who <- currentPrincipal (ssAccounts session) token
+            case who of
+                Left err -> pure (Left (accountErrorOf err))
+                Right principal -> do
+                    writeIORef (ssPrincipal session) (Just principal)
+                    pure (Right ())
+
+-- | 换库；系统库只有 root 能进
+switchDatabase :: Session -> Text -> IO (Either Text ())
+switchDatabase session name =
+    fmap (first sessMessage) (switchDatabaseCoded session name)
+
+-- | 换库（带错误码）
+switchDatabaseCoded :: Session -> Text -> IO (Either SessionError ())
+switchDatabaseCoded session rawName
+    | not (isPlainIdentifier name) = pure (Left (SessionError "bad_request" ("not a plain database name: " <> name)))
+    | name == "system" = do
+        admin <- sessionIsAdmin session
+        if admin then go else pure (Left (SessionError "forbidden" "the system database is only available to the administrator"))
+    | otherwise = go
+  where
+    name = T.toLower (T.strip rawName)
+    -- | 真的切库并记下当前库
+    go = do
+        backend <- currentBackend session
+        result <- beStatement backend ("USE " ++ T.unpack name)
+        case result of
+            Left err -> pure (Left (engineErrorCode err))
+            Right _ -> writeIORef (ssCurrent session) name >> pure (Right ())
+
+-- | 跑一条语句：USE、账号与角色语句分流，其余交引擎
+runStatement :: Session -> Text -> IO (Either Text QueryResult)
+runStatement session sql = fmap (first sessMessage) (runStatementCoded session sql)
+
+-- | 跑一条语句（带错误码）
+runStatementCoded :: Session -> Text -> IO (Either SessionError QueryResult)
+runStatementCoded session sql = case parseStatement (T.unpack sql) of
+    Right (UseDatabase name) -> do
+        switched <- switchDatabaseCoded session (T.pack name)
+        case switched of
+            Left err -> pure (Left err)
+            Right () -> do
+                current <- readIORef (ssCurrent session)
+                pure (Right (emptyResult (Just current)))
+    Right statement
+        | Just command <- accountCommand statement -> runAccount session command
+        | Just command <- privilegeCommand statement -> runPrivilege session command
+        | otherwise -> do
+            allowed <- authorized session statement
+            case allowed of
+                Left err -> pure (Left err)
+                Right () -> runPlain session sql
+    Left _ -> runPlain session sql
+
+-- | 普通身份跑语句前的权限判定；管理员与未登录放行
+authorized :: Session -> Statement -> IO (Either SessionError ())
+authorized session statement = do
+    who <- readIORef (ssPrincipal session)
+    case who of
+        Just principal | not (principalIsRoot principal) -> do
+            database <- readIORef (ssCurrent session)
+            result <- authorize (ssPrivileges session) principal database statement
+            pure (either (Left . privilegeErrorOf) (const (Right ())) result)
+        _ -> pure (Right ())
+
+-- | 落到引擎/存储层的一条语句
+runPlain :: Session -> Text -> IO (Either SessionError QueryResult)
+runPlain session sql = do
+    backend <- currentBackend session
+    result <- beStatement backend (T.unpack sql)
+    pure (either (Left . engineErrorCode) (Right . resultOf) result)
+
+-- | 数据字典；普通身份只看到有 SELECT 权的表
+catalog :: Session -> IO (Either Text [TableInfo])
+catalog session = do
+    current <- readIORef (ssCurrent session)
+    if T.null current
+        then pure (Left "no database selected")
+        else do
+            backend <- currentBackend session
+            result <- beCatalog backend
+            case result of
+                Left e -> pure (Left (T.pack e))
+                Right infos -> do
+                    who <- readIORef (ssPrincipal session)
+                    visible <- case who of
+                        Just principal | not (principalIsRoot principal) -> do
+                            allowed <- filterTables (ssPrivileges session) principal current (map (T.pack . tiTable) infos)
+                            pure (either (Left . privilegeMessage) (\names -> Right (filter (\info -> T.pack (tiTable info) `elem` names) infos)) allowed)
+                        _ -> pure (Right infos)
+                    case visible of
+                        Left message -> pure (Left message)
+                        Right tables
+                            | current == "system" -> Right <$> withAccountInfo session tables
+                            | otherwise -> pure (Right tables)
+
+-- | 系统库里补上账号表
+withAccountInfo :: Session -> [TableInfo] -> IO [TableInfo]
+withAccountInfo session tables = do
+    admin <- sessionIsAdmin session
+    if not admin
+        then pure tables
+        else do
+            result <- listAccounts (ssAccounts session)
+            pure $ case result of
+                Left _ -> tables
+                Right rows -> systemTableInfo{tiRows = length rows} : tables
+
+-- | 库清单（\l 用）
+databases :: Session -> IO (Either Text [Text])
+databases session = do
+    result <- beDatabases (ssBackend session)
+    pure (either (Left . T.pack) (Right . map T.pack) result)
+
+-- | 角色总览，只给管理员
+roleViews :: Session -> IO (Either Text [RoleView])
+roleViews session = do
+    admin <- sessionIsAdmin session
+    if not admin
+        then pure (Left "administrator required")
+        else do
+            result <- listRoleViews (ssPrivileges session)
+            pure (either (Left . privilegeMessage) Right result)
+
+-- | 账号清单（\du 与账号管理页用）；只给管理员
+accounts :: Session -> IO (Either Text [Account])
+accounts session = do
+    admin <- sessionIsAdmin session
+    if not admin
+        then pure (Left "administrator required")
+        else do
+            result <- listAccounts (ssAccounts session)
+            pure (either (Left . T.pack . show) Right result)
+
+-- | 当前库对应的后端
+currentBackend :: Session -> IO Backend
+currentBackend session = do
+    name <- readIORef (ssCurrent session)
+    pure (beWithDatabase (ssBackend session) (T.unpack name))
+
+-- | 账号语句走账号服务，普通账号一律拒绝
+runAccount :: Session -> AccountCommand -> IO (Either SessionError QueryResult)
+runAccount session command = do
+    who <- readIORef (ssPrincipal session)
+    case who of
+        Nothing -> pure (Left (SessionError "unauthorized" "sign in first"))
+        Just principal -> do
+            result <- runAccountCommand (ssAccounts session) principal command
+            pure (either (Left . accountErrorOf) (const (Right (emptyResult Nothing))) result)
+
+-- | 角色语句走权限服务，普通账号拒绝
+runPrivilege :: Session -> PrivilegeCommand -> IO (Either SessionError QueryResult)
+runPrivilege session command = do
+    who <- readIORef (ssPrincipal session)
+    case who of
+        Nothing -> pure (Left (SessionError "unauthorized" "sign in first"))
+        Just principal -> do
+            database <- readIORef (ssCurrent session)
+            result <- runPrivilegeCommand (ssPrivileges session) principal database command
+            pure (either (Left . privilegeErrorOf) (const (Right (emptyResult Nothing))) result)
+
+-- | 账号错误转成会话错误
+accountErrorOf :: AccountError -> SessionError
+accountErrorOf (AccountError code message) = SessionError code message
+
+-- | 权限错误转成会话错误
+privilegeErrorOf :: PrivilegeError -> SessionError
+privilegeErrorOf (PrivilegeError code message) = SessionError code message
+
+-- | 取权限错误的文案
+privilegeMessage :: PrivilegeError -> Text
+privilegeMessage (PrivilegeError _ message) = message
+
+-- | 只带库名的空结果
+emptyResult :: Maybe Text -> QueryResult
+emptyResult database = QueryResult [] [] 0 False database
+
+-- | 存储结果转成查询结果
+resultOf :: StatementResult -> QueryResult
+resultOf result =
+    QueryResult
+        { qrColumns = map T.pack (srColumns result)
+        , qrRows = [map (cellOf row) (srColumns result) | row <- srRows result]
+        , qrRowCount = length (srRows result)
+        , qrTruncated = False
+        , qrDatabase = Nothing
+        }
+  where
+    -- | 按列名取单元格
+    cellOf row name = maybe VNull id (lookup name row)
+
diff --git a/chusql-server/src/ChuSQL/Server/TCP.hs b/chusql-server/src/ChuSQL/Server/TCP.hs
new file mode 100644
index 0000000..6c369b4
--- /dev/null
+++ b/chusql-server/src/ChuSQL/Server/TCP.hs
@@ -0,0 +1,288 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module ChuSQL.Server.TCP (
+    ServerConfig (..),
+    defaultServerConfig,
+    loadServerConfigAt,
+    ServerEnv (..),
+    newServerEnv,
+    ServerHandle (..),
+    startServer,
+    runServer,
+) where
+
+import ChuSQL.Interface.Auth (Credential)
+import ChuSQL.Interface.Config (ServerConfig (..), defaultServerConfig, loadServerConfigAt)
+import ChuSQL.Interface.Policy (PasswordPolicy (..))
+import ChuSQL.Interface.Protocol (ClientRequest (..), ServerResponse (..), decodeRequest, encodeResponse, protocolVersion)
+import ChuSQL.Interface.RateLimit (RateLimiter, rateLimitBlock, rateLimitClear, rateLimitRecord)
+import ChuSQL.Server.Backend (Backend (..))
+import ChuSQL.Server.Session (QueryResult (..), Session, SessionError (..), accounts, authenticateSessionCoded, catalog, databases, newSession, policyOf, reloadPolicy, roleViews, runStatementCoded, sessionIsAdmin, sessionUser)
+import Control.Concurrent (forkIO)
+import Control.Concurrent.MVar (MVar, modifyMVar_, newMVar, readMVar)
+import Control.Exception (IOException, try)
+import Control.Monad (void)
+import qualified Data.ByteString.Char8 as BSC
+import qualified Data.ByteString.Lazy.Char8 as BLC
+import Data.Maybe (fromMaybe)
+import Data.Text (Text)
+import qualified Data.Text as T
+import Network.Socket (
+    AddrInfo (..),
+    AddrInfoFlag (AI_PASSIVE),
+    SockAddr (SockAddrInet, SockAddrInet6),
+    Socket,
+    SocketOption (ReuseAddr),
+    SocketType (Stream),
+    accept,
+    addrAddress,
+    addrFamily,
+    bind,
+    close,
+    defaultHints,
+    defaultProtocol,
+    getAddrInfo,
+    getSocketName,
+    listen,
+    setSocketOption,
+    socket,
+    socketToHandle,
+  )
+import System.IO (BufferMode (LineBuffering), IOMode (ReadWriteMode), hClose, hFlush, hPutStrLn, hSetBuffering, hSetNewlineMode, noNewlineTranslation, stderr)
+import System.IO.Error (isEOFError)
+
+-- TCP 服务器：监听端口，一连接一会话，按一行一 JSON 收发协议消息。
+
+-- 服务器
+
+data ServerEnv = ServerEnv
+    { srvBackend :: Backend
+    , srvCredential :: Credential
+    , srvSettingsFile :: FilePath
+    , srvConfig :: ServerConfig
+    , srvLimiter :: RateLimiter
+    }
+
+-- | 组装服务器环境：每个连接再各开一个会话
+newServerEnv :: Backend -> Credential -> FilePath -> ServerConfig -> RateLimiter -> IO ServerEnv
+newServerEnv backend credential settingsFile config limiter =
+    pure (ServerEnv backend credential settingsFile config limiter)
+
+data ServerHandle = ServerHandle
+    { shPort :: Int
+    , shStop :: IO ()
+    }
+
+-- | 起监听并在线程里收连接（测试与嵌入用）
+startServer :: ServerEnv -> IO ServerHandle
+startServer env = do
+    sock <- listenSocket (scHost (srvConfig env)) (scPort (srvConfig env))
+    port <- actualPort sock
+    stopped <- newMVar False
+    _ <- forkIO (acceptLoop env sock stopped)
+    pure (ServerHandle port (stopListening sock stopped))
+
+-- | 在调用线程里收连接（可执行文件用）；绑好端口先回调一次
+runServer :: ServerEnv -> (Int -> IO ()) -> IO ()
+runServer env announce = do
+    sock <- listenSocket (scHost (srvConfig env)) (scPort (srvConfig env))
+    port <- actualPort sock
+    announce port
+    stopped <- newMVar False
+    acceptLoop env sock stopped
+
+-- | 置停止标记并关掉监听套接字
+stopListening :: Socket -> MVar Bool -> IO ()
+stopListening sock stopped = do
+    modifyMVar_ stopped (const (pure True))
+    void (try (close sock) :: IO (Either IOException ()))
+
+-- | 建监听套接字；端口 0 表示由系统分配
+listenSocket :: String -> Int -> IO Socket
+listenSocket host port = do
+    let hints = defaultHints{addrSocketType = Stream, addrFlags = [AI_PASSIVE]}
+        node = if null host then Nothing else Just host
+    infos <- getAddrInfo (Just hints) node (Just (show port))
+    case infos of
+        [] -> ioError (userError ("cannot resolve listen address: " ++ host))
+        (info : _) -> do
+            sock <- socket (addrFamily info) Stream defaultProtocol
+            setSocketOption sock ReuseAddr 1
+            bind sock (addrAddress info)
+            listen sock 128
+            pure sock
+
+-- | 系统分配端口后读回真正的端口
+actualPort :: Socket -> IO Int
+actualPort sock = do
+    address <- getSocketName sock
+    pure $ case address of
+        SockAddrInet port _ -> fromIntegral port
+        SockAddrInet6 port _ _ _ -> fromIntegral port
+        _ -> 0
+
+-- | 循环 accept，把每个连接交给独立线程
+acceptLoop :: ServerEnv -> Socket -> MVar Bool -> IO ()
+acceptLoop env sock stopped = loop
+  where
+    -- | 等下一个连接
+    loop = do
+        stop <- readMVar stopped
+        if stop
+            then pure ()
+            else do
+                accepted <- try (accept sock) :: IO (Either IOException (Socket, SockAddr))
+                case accepted of
+                    Left err -> do
+                        stopping <- readMVar stopped
+                        if stopping then pure () else hPutStrLn stderr ("accept failed: " ++ show err)
+                    Right (conn, _) -> do
+                        void (forkIO (reportConnection env conn))
+                        loop
+
+-- | 连接线程：异常写到 stderr
+reportConnection :: ServerEnv -> Socket -> IO ()
+reportConnection env conn = do
+    outcome <- try (serveConnection env conn) :: IO (Either IOException ())
+    case outcome of
+        Left err -> hPutStrLn stderr ("connection failed: " ++ show err)
+        Right () -> pure ()
+
+-- | 一个连接一个会话：一行一条 JSON，读到 EOF 就收工
+serveConnection :: ServerEnv -> Socket -> IO ()
+serveConnection env conn = do
+    h <- socketToHandle conn ReadWriteMode
+    hSetBuffering h LineBuffering
+    hSetNewlineMode h noNewlineTranslation
+    session <- newSession (srvBackend env) (srvCredential env) (srvSettingsFile env)
+    outcome <- try (loop h session) :: IO (Either IOException ())
+    case outcome of
+        Left err | not (isEOFError err) -> hPutStrLn stderr ("connection error: " ++ show err)
+        _ -> pure ()
+    void (try (hClose h) :: IO (Either IOException ()))
+  where
+    -- | 逐行读请求并应答
+    loop h session = do
+        line <- BSC.hGetLine h
+        let cleaned = BSC.dropWhileEnd (== '\r') line
+        if BSC.length cleaned > scMaxMessage (srvConfig env)
+            then send h (RespError "too_large" "request line too large") >> loop h session
+            else case decodeRequest cleaned of
+                Left message -> send h (RespError "bad_request" message) >> loop h session
+                Right request -> do
+                    (response, keepGoing) <- dispatch env session request
+                    send h response
+                    if keepGoing then loop h session else pure ()
+    -- | 发一条响应并冲缓冲
+    send h response = do
+        BLC.hPutStr h (encodeResponse response)
+        BLC.hPutStr h "\n"
+        hFlush h
+
+-- | 一条请求一条响应，quit 后停连接
+dispatch :: ServerEnv -> Session -> ClientRequest -> IO (ServerResponse, Bool)
+dispatch env session request = case request of
+    ReqHello version
+        | version == protocolVersion -> pure (RespHello protocolVersion, True)
+        | otherwise -> pure (RespError "bad_request" ("unsupported protocol version: " <> tshow version), True)
+    ReqLogin user password -> do
+        response <- login env session user password
+        pure (response, True)
+    ReqQuery sql -> do
+        who <- sessionUser session
+        response <- case who of
+            Nothing -> pure (RespError "unauthorized" "sign in first")
+            Just _
+                | T.null (T.strip sql) -> pure (RespError "bad_request" "sql must not be empty")
+                | otherwise -> do
+                    result <- runStatementCoded session sql
+                    pure $ case result of
+                        Left err -> RespError (sessCode err) (sessMessage err)
+                        Right queryResult -> RespResult (trimResult (scMaxRows (srvConfig env)) queryResult)
+        pure (response, True)
+    ReqStorage payload -> do
+        who <- sessionUser session
+        response <- case who of
+            Nothing -> pure (RespError "unauthorized" "sign in first")
+            Just _ -> do
+                admin <- sessionIsAdmin session
+                if not admin
+                    then pure (RespError "forbidden" "administrator required")
+                    else do
+                        result <- beStorage (srvBackend env) payload
+                        pure $ case result of
+                            Left err -> RespError "storage_error" (T.pack err)
+                            Right value -> RespStorage value
+        pure (response, True)
+    ReqCatalog -> do
+        response <- overSession session (catalog session) RespCatalog
+        pure (response, True)
+    ReqDatabases -> do
+        response <- overSession session (databases session) RespDatabases
+        pure (response, True)
+    ReqRoles -> do
+        response <- overSession session (roleViews session) RespRoles
+        pure (response, True)
+    ReqAccounts -> do
+        response <- overSession session (accounts session) RespAccounts
+        pure (response, True)
+    ReqPolicy -> do
+        response <- overSession session (policyOf session) policyResponse
+        pure (response, True)
+    ReqReloadPolicy -> do
+        response <- overSession session (reloadPolicy session) policyResponse
+        pure (response, True)
+    ReqPing -> pure (RespPong, True)
+    ReqQuit -> pure (RespBye, False)
+
+-- | 口令策略在线上只有两个数字：最短长度与至少几类字符
+policyResponse :: PasswordPolicy -> ServerResponse
+policyResponse (PasswordPolicy minLength classes) = RespPolicy minLength classes
+
+-- | 会话方法统一口径：没登录先挡，其余失败按码表落到响应
+overSession :: Session -> IO (Either Text a) -> (a -> ServerResponse) -> IO ServerResponse
+overSession session action wrap = do
+    who <- sessionUser session
+    case who of
+        Nothing -> pure (RespError "unauthorized" "sign in first")
+        Just _ -> do
+            result <- action
+            pure $ case result of
+                Left message -> RespError (sessionCode message) message
+                Right value -> wrap value
+
+-- | 会话层的失败文案归一到协议错误码
+sessionCode :: Text -> Text
+sessionCode message
+    | message == "no database selected" = "no_database"
+    | message == "administrator required" = "forbidden"
+    | otherwise = "query_error"
+
+-- | 登录：按账号名限流，成功清账
+login :: ServerEnv -> Session -> Text -> Text -> IO ServerResponse
+login env session user password = do
+    let key = T.toLower (T.strip user)
+    blocked <- rateLimitBlock (srvLimiter env) key
+    case blocked of
+        Just seconds -> pure (RespError "too_many_attempts" ("too many failed logins, retry in " <> tshow (ceiling seconds :: Integer) <> "s"))
+        Nothing -> do
+            result <- authenticateSessionCoded session key password
+            case result of
+                Left err -> do
+                    rateLimitRecord (srvLimiter env) key
+                    pure (RespError (sessCode err) (sessMessage err))
+                Right () -> do
+                    rateLimitClear (srvLimiter env) key
+                    who <- sessionUser session
+                    admin <- sessionIsAdmin session
+                    pure (RespLogin (fromMaybe key who) admin)
+
+-- | 按上限截行，总行数保持不变
+trimResult :: Int -> QueryResult -> QueryResult
+trimResult limit result
+    | length (qrRows result) > limit = result{qrRows = take limit (qrRows result), qrTruncated = True}
+    | otherwise = result
+
+-- | show 成 Text
+tshow :: Show a => a -> Text
+tshow = T.pack . show
diff --git a/chusql-server/stack.yaml b/chusql-server/stack.yaml
new file mode 100644
index 0000000..83e06af
--- /dev/null
+++ b/chusql-server/stack.yaml
@@ -0,0 +1,10 @@
+resolver: lts-24.59
+
+extra-lib-dirs:
+    - ../chusql-core/storage/target/release
+
+packages:
+    - .
+    - ../chusql-core/engine
+    - ../chusql-core/model
+    - ../chusql-interface
diff --git a/chusql-server/stack.yaml.lock b/chusql-server/stack.yaml.lock
new file mode 100644
index 0000000..e3f9041
--- /dev/null
+++ b/chusql-server/stack.yaml.lock
@@ -0,0 +1,12 @@
+# This file was autogenerated by Stack.
+# You should not edit this file by hand.
+# For more information, please see the documentation at:
+#   https://docs.haskellstack.org/en/stable/topics/lock_files
+
+packages: []
+snapshots:
+- completed:
+    sha256: 0f728e30e843d7f00460ad56858b995a3b227fca683659c7df9f2fc3988a3ce1
+    size: 732465
+    url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/24/59.yaml
+  original: lts-24.59
diff --git a/chusql-server/test/Spec.hs b/chusql-server/test/Spec.hs
new file mode 100644
index 0000000..0cfaeb1
--- /dev/null
+++ b/chusql-server/test/Spec.hs
@@ -0,0 +1,416 @@
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE PatternSynonyms #-}
+
+module Main (main) where
+
+import ChuSQL.Core.Model (Database, Table (..), Value (..), pattern TInt, pattern TStr)
+import ChuSQL.Interface.Auth (Credential (..), hashPasswordWith)
+import ChuSQL.Interface.Protocol (ClientRequest (..), ServerResponse (..), decodeRequest, encodeResponse)
+import ChuSQL.Interface.RateLimit (newRateLimiter)
+import ChuSQL.Server.Backend (memoryBackend)
+import ChuSQL.Server.Session (QueryResult (..))
+import ChuSQL.Server.TCP (
+    ServerConfig (..),
+    ServerEnv,
+    ServerHandle (..),
+    defaultServerConfig,
+    loadServerConfigAt,
+    newServerEnv,
+    startServer,
+ )
+import Control.Concurrent (threadDelay)
+import Control.Concurrent.MVar (newMVar)
+import Control.Exception (IOException, bracket, finally, try)
+import Control.Monad (void)
+import Data.Aeson (decode)
+import qualified Data.Aeson as A
+import qualified Data.Aeson.Key as K
+import qualified Data.Aeson.KeyMap as KM
+import qualified Data.ByteString as BS
+import qualified Data.ByteString.Char8 as BSC
+import qualified Data.ByteString.Lazy as BL
+import Data.Maybe (fromMaybe)
+import Data.Text (Text)
+import qualified Data.Text as T
+import qualified Data.Vector as V
+import Data.Time.Clock (getCurrentTime)
+import Network.Socket (
+    AddrInfo (..),
+    SocketType (Stream),
+    addrAddress,
+    addrFamily,
+    connect,
+    defaultHints,
+    defaultProtocol,
+    getAddrInfo,
+    socket,
+    socketToHandle,
+    withSocketsDo,
+ )
+import System.Directory (doesFileExist, getTemporaryDirectory, removeFile)
+import System.FilePath ((</>))
+import System.IO (
+    BufferMode (LineBuffering),
+    Handle,
+    IOMode (ReadWriteMode),
+    hClose,
+    hFlush,
+    hIsEOF,
+    hSetBuffering,
+    hSetNewlineMode,
+    noNewlineTranslation,
+ )
+import System.Timeout (timeout)
+import Test.Hspec
+
+-- TCP 服务器测试：协议编解码、配置读取与真连服务器的端到端用例。
+
+-- | 测试入口
+main :: IO ()
+main = hspec spec
+
+-- | 全部用例
+spec :: Spec
+spec = do
+    tcpSpec
+    tcpServerSpec
+
+-- 夹具：内存后端装在 MVar 里，跟 Web 测试同一套表
+
+-- | 夹具库名
+testDatabaseName :: String
+testDatabaseName = "test"
+
+-- | users 5 行 + orders 1 行
+testDb :: Database
+testDb =
+    [ ( "users"
+      , Table
+            "users"
+            [("id", TInt), ("name", TStr), ("age", TInt)]
+            [ [("id", VInt i), ("name", VStr ("user" ++ show i)), ("age", VInt (20 + i))]
+            | i <- [1 .. 5]
+            ]
+      )
+    , ( "orders"
+      , Table
+            "orders"
+            [("id", TInt), ("user_id", TInt)]
+            [[("id", VInt 1), ("user_id", VInt 1)]]
+      )
+    ]
+
+-- | 测试账号：迭代次数压低（跑得快），口令 `s3cret`
+testCredential :: Credential
+testCredential = Credential "admin" (hashPasswordWith 1000 (BS.replicate 16 7) "s3cret")
+
+-- 小工具
+
+-- | 取字段
+field :: Text -> A.Value -> Maybe A.Value
+field name (A.Object o) = KM.lookup (K.fromText name) o
+field _ _ = Nothing
+
+-- | 取字段（没有给 Null）
+at :: Text -> A.Value -> A.Value
+at name value = fromMaybe A.Null (field name value)
+
+-- | 当数组看
+items :: A.Value -> [A.Value]
+items (A.Array xs) = V.toList xs
+items _ = []
+
+-- | 当文本看
+asText :: A.Value -> Text
+asText (A.String t) = t
+asText _ = ""
+
+-- | 当整数看
+asInt :: A.Value -> Int
+asInt (A.Number n) = round n
+asInt _ = -1
+
+-- | JSON 当布尔看
+asBool :: A.Value -> Bool
+asBool (A.Bool b) = b
+asBool _ = False
+
+-- | 第 i 个元素（越界给 Nothing，不用 `!!`）
+nth :: Int -> [a] -> Maybe a
+nth i xs = case drop i xs of
+    (x : _) -> Just x
+    [] -> Nothing
+
+-- | 临时 TOML
+tcpConfigPath :: String -> IO FilePath
+tcpConfigPath name = do
+    tmp <- getTemporaryDirectory
+    pure (tmp </> ("chusql-server-test-" ++ name ++ ".toml"))
+
+-- | 临时设置文件（新会话读口令策略用）
+tempSettingsPath :: String -> IO FilePath
+tempSettingsPath name = do
+    tmp <- getTemporaryDirectory
+    pure (tmp </> ("chusql-server-test-" ++ name ++ "-settings.json"))
+
+-- | 文件不存在也算成功
+removeIfExists :: FilePath -> IO ()
+removeIfExists path = do
+    there <- doesFileExist path
+    if there then void (try (removeFile path) :: IO (Either IOException ())) else pure ()
+
+-- | 起一台内存后端的测试服务器
+withTcpServer :: ServerConfig -> (ServerEnv -> ServerHandle -> IO a) -> IO a
+withTcpServer config body = do
+    db <- newMVar testDb
+    limiter <- newRateLimiter getCurrentTime 50 300
+    path <- tempSettingsPath "tcp-server"
+    removeIfExists path
+    env <- newServerEnv (memoryBackend testDatabaseName db) testCredential path config{scPort = 0} limiter
+    handle <- startServer env
+    body env handle `finally` shStop handle
+
+-- | 连上服务器并配成行缓冲句柄
+withConnection :: ServerHandle -> (Handle -> IO a) -> IO a
+withConnection handle body = bracket open closeQuietly body
+  where
+    -- | 关连接，忽略异常
+    closeQuietly h = do
+        _ <- try (hClose h) :: IO (Either IOException ())
+        pure ()
+    -- | 建连接并配成行缓冲句柄
+    open = withSocketsDo $ do
+        infos <- getAddrInfo (Just defaultHints{addrSocketType = Stream}) (Just "127.0.0.1") (Just (show (shPort handle)))
+        info <- case infos of
+            (i : _) -> pure i
+            [] -> ioError (userError "cannot resolve the test server address")
+        sock <- socket (addrFamily info) Stream defaultProtocol
+        connect sock (addrAddress info)
+        h <- socketToHandle sock ReadWriteMode
+        hSetBuffering h LineBuffering
+        hSetNewlineMode h noNewlineTranslation
+        pure h
+
+-- | 发一行收一行；服务器不回话就判失败，别把用例挂死
+tcpTalk :: Handle -> BS.ByteString -> IO A.Value
+tcpTalk h raw = do
+    BSC.hPutStr h raw
+    BSC.hPutStr h "\n"
+    hFlush h
+    line <- timeout (5 * 1000000) (BSC.hGetLine h)
+    case line of
+        Just got -> pure (fromMaybe A.Null (decode (BL.fromStrict got)))
+        Nothing -> do
+            expectationFailure "the TCP server did not answer in time"
+            pure A.Null
+
+-- | 登录一行
+tcpLogin :: Handle -> Text -> Text -> IO A.Value
+tcpLogin h user password =
+    tcpTalk h (BSC.pack ("{\"method\":\"login\",\"user\":\"" ++ T.unpack user ++ "\",\"password\":\"" ++ T.unpack password ++ "\"}"))
+
+-- | 查询一行
+tcpQuery :: Handle -> Text -> IO A.Value
+tcpQuery h sql = tcpTalk h (BSC.pack ("{\"method\":\"query\",\"sql\":\"" ++ T.unpack sql ++ "\"}"))
+
+-- | 断言对端已经收工（读到 EOF）
+tcpClosed :: Handle -> IO ()
+tcpClosed h = do
+    done <- timeout (5 * 1000000) (hIsEOF h)
+    done `shouldBe` Just True
+
+-- 用例
+
+-- | 协议与配置的用例
+tcpSpec :: Spec
+tcpSpec = do
+    describe "TCP protocol: decoding a request line" $ do
+        it "hello without a protocol number takes the current version" $
+            decodeRequest "{\"method\":\"hello\"}" `shouldBe` Right (ReqHello 1)
+        it "hello keeps the protocol number the client asked for" $
+            decodeRequest "{\"method\":\"hello\",\"protocol\":2}" `shouldBe` Right (ReqHello 2)
+        it "method names are case-insensitive" $
+            decodeRequest "{\"method\":\"PING\"}" `shouldBe` Right ReqPing
+        it "unknown extra fields are ignored" $
+            decodeRequest "{\"method\":\"quit\",\"line\":7}" `shouldBe` Right ReqQuit
+        it "login without a password is refused" $
+            decodeRequest "{\"method\":\"login\",\"user\":\"admin\"}" `shouldBe` Left "login needs both user and password"
+        it "query without sql is refused" $
+            decodeRequest "{\"method\":\"query\"}" `shouldBe` Left "query needs sql"
+        it "an unknown method is named in the error" $
+            decodeRequest "{\"method\":\"frobnicate\"}" `shouldBe` Left "unknown method: frobnicate"
+        it "a line that is not JSON is a bad request, not a crash" $
+            decodeRequest "not json" `shouldBe` Left "request is not valid JSON"
+
+    describe "TCP protocol: encoding a response" $ do
+        it "hello carries the protocol version and the server name" $ do
+            let value = fromMaybe A.Null (decode (encodeResponse (RespHello 1)))
+            asText (at "status" value) `shouldBe` "hello"
+            asText (at "server" value) `shouldBe` "chusql-server"
+            asInt (at "protocol" value) `shouldBe` 1
+        it "login reports the account and whether it is the administrator" $ do
+            let value = fromMaybe A.Null (decode (encodeResponse (RespLogin "admin" True)))
+            asText (at "user" value) `shouldBe` "admin"
+            asBool (at "admin" value) `shouldBe` True
+        it "an error carries a code and a message" $ do
+            let value = fromMaybe A.Null (decode (encodeResponse (RespError "no_database" "no database selected")))
+            asText (at "status" value) `shouldBe` "error"
+            asText (at "code" value) `shouldBe` "no_database"
+            asText (at "message" value) `shouldBe` "no database selected"
+        it "a result set is the command line JSON with a status field added" $ do
+            let sample = QueryResult ["id"] [[VInt 1]] 1 False (Just "test")
+                value = fromMaybe A.Null (decode (encodeResponse (RespResult sample)))
+            asText (at "status" value) `shouldBe` "result"
+            map asText (items (at "columns" value)) `shouldBe` ["id"]
+            asInt (at "rowCount" value) `shouldBe` 1
+            asBool (at "truncated" value) `shouldBe` False
+            asText (at "database" value) `shouldBe` "test"
+
+    describe "server config ([server] in chusql.toml)" $ do
+        it "falls back to the defaults when the file has no server section" $ do
+            path <- tcpConfigPath "server-default"
+            removeIfExists path
+            loadServerConfigAt path `shouldReturn` defaultServerConfig
+        it "reads host, port, max_message and max_rows" $ do
+            path <- tcpConfigPath "server-keys"
+            BS.writeFile path "[server]\nhost = \"0.0.0.0\"\nport = 7777\nmax_message = 4096\nmax_rows = 7\n"
+            config <- loadServerConfigAt path
+            scHost config `shouldBe` "0.0.0.0"
+            scPort config `shouldBe` 7777
+            scMaxMessage config `shouldBe` 4096
+            scMaxRows config `shouldBe` 7
+        it "keeps the HTTP, storage and page keys out of the server config" $ do
+            path <- tcpConfigPath "server-other-keys"
+            BS.writeFile path "[web]\nport = 8888\n\n[storage]\ndata_dir = \"/tmp/chusql\"\n\n[page]\nsize = 8192\n"
+            config <- loadServerConfigAt path
+            scPort config `shouldBe` scPort defaultServerConfig
+            scMaxRows config `shouldBe` scMaxRows defaultServerConfig
+
+-- | 真连 TCP 服务器的用例
+tcpServerSpec :: Spec
+tcpServerSpec = do
+    describe "TCP server: handshake and login" $ do
+        it "binds a real port when asked for port 0" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                shPort handle `shouldSatisfy` (> 0)
+        it "answers hello with the same protocol version" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                withConnection handle $ \h -> do
+                    reply <- tcpTalk h "{\"method\":\"hello\",\"protocol\":1}"
+                    asText (at "status" reply) `shouldBe` "hello"
+                    asInt (at "protocol" reply) `shouldBe` 1
+        it "still answers a client that connects long after startup" $
+            -- 回归点：早先 accept 外面套 timeout 轮询，超时异常会在 accept
+            -- 返回后把刚拿到的连接丢掉，只有延迟连接的客户端能撞上
+            withTcpServer defaultServerConfig $ \_ handle -> do
+                threadDelay 400000
+                withConnection handle $ \h -> do
+                    reply <- tcpTalk h "{\"method\":\"hello\",\"protocol\":1}"
+                    asText (at "status" reply) `shouldBe` "hello"
+                    asText (at "server" reply) `shouldBe` "chusql-server"
+        it "refuses a protocol version it does not speak" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                withConnection handle $ \h -> do
+                    reply <- tcpTalk h "{\"method\":\"hello\",\"protocol\":9}"
+                    asText (at "code" reply) `shouldBe` "bad_request"
+                    asText (at "message" reply) `shouldBe` "unsupported protocol version: 9"
+        it "refuses a query before login" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                withConnection handle $ \h -> do
+                    reply <- tcpQuery h "select * from users"
+                    asText (at "status" reply) `shouldBe` "error"
+                    asText (at "code" reply) `shouldBe` "unauthorized"
+                    asText (at "message" reply) `shouldBe` "sign in first"
+        it "refuses a wrong password and then accepts the right one" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                withConnection handle $ \h -> do
+                    bad <- tcpLogin h "admin" "wrong"
+                    asText (at "status" bad) `shouldBe` "error"
+                    asText (at "code" bad) `shouldBe` "unauthorized"
+                    good <- tcpLogin h "admin" "s3cret"
+                    asText (at "status" good) `shouldBe` "ok"
+                    asText (at "user" good) `shouldBe` "admin"
+                    asBool (at "admin" good) `shouldBe` True
+
+    describe "TCP server: SQL over the wire" $ do
+        it "USE picks a database and the result reports it" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                withConnection handle $ \h -> do
+                    _ <- tcpLogin h "admin" "s3cret"
+                    reply <- tcpQuery h "use test"
+                    asText (at "status" reply) `shouldBe` "result"
+                    asText (at "database" reply) `shouldBe` "test"
+        it "SELECT returns the fixture rows" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                withConnection handle $ \h -> do
+                    _ <- tcpLogin h "admin" "s3cret"
+                    _ <- tcpQuery h "use test"
+                    reply <- tcpQuery h "select * from users"
+                    asText (at "status" reply) `shouldBe` "result"
+                    map asText (items (at "columns" reply)) `shouldBe` ["id", "name", "age"]
+                    asInt (at "rowCount" reply) `shouldBe` 5
+                    let first = case map items (items (at "rows" reply)) of
+                            (r : _) -> r
+                            [] -> []
+                    length first `shouldBe` 3
+                    asInt (fromMaybe A.Null (nth 0 first)) `shouldBe` 1
+                    asText (fromMaybe A.Null (nth 1 first)) `shouldBe` "user1"
+        it "an unknown table maps to not_found" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                withConnection handle $ \h -> do
+                    _ <- tcpLogin h "admin" "s3cret"
+                    _ <- tcpQuery h "use test"
+                    reply <- tcpQuery h "select * from nope"
+                    asText (at "code" reply) `shouldBe` "not_found"
+        it "a query without a selected database maps to no_database" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                withConnection handle $ \h -> do
+                    _ <- tcpLogin h "admin" "s3cret"
+                    reply <- tcpQuery h "select * from users"
+                    asText (at "code" reply) `shouldBe` "no_database"
+        it "an empty sql is a bad request" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                withConnection handle $ \h -> do
+                    _ <- tcpLogin h "admin" "s3cret"
+                    reply <- tcpTalk h "{\"method\":\"query\",\"sql\":\"  \"}"
+                    asText (at "code" reply) `shouldBe` "bad_request"
+                    asText (at "message" reply) `shouldBe` "sql must not be empty"
+        it "the row limit truncates the rows but keeps the total count" $
+            withTcpServer defaultServerConfig{scMaxRows = 2} $ \_ handle ->
+                withConnection handle $ \h -> do
+                    _ <- tcpLogin h "admin" "s3cret"
+                    _ <- tcpQuery h "use test"
+                    reply <- tcpQuery h "select * from users"
+                    length (items (at "rows" reply)) `shouldBe` 2
+                    asInt (at "rowCount" reply) `shouldBe` 5
+                    asBool (at "truncated" reply) `shouldBe` True
+
+    describe "TCP server: framing and lifecycle" $ do
+        it "a bad JSON line does not kill the connection" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                withConnection handle $ \h -> do
+                    bad <- tcpTalk h "not json"
+                    asText (at "code" bad) `shouldBe` "bad_request"
+                    pong <- tcpTalk h "{\"method\":\"ping\"}"
+                    asText (at "status" pong) `shouldBe` "pong"
+        it "a line over the message limit is refused as too_large" $
+            withTcpServer defaultServerConfig{scMaxMessage = 32} $ \_ handle ->
+                withConnection handle $ \h -> do
+                    reply <- tcpTalk h (BSC.pack ("{\"method\":\"query\",\"sql\":\"" ++ replicate 40 'a' ++ "\"}"))
+                    asText (at "code" reply) `shouldBe` "too_large"
+        it "ping answers pong and quit closes the connection" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                withConnection handle $ \h -> do
+                    pong <- tcpTalk h "{\"method\":\"ping\"}"
+                    asText (at "status" pong) `shouldBe` "pong"
+                    bye <- tcpTalk h "{\"method\":\"quit\"}"
+                    asText (at "status" bye) `shouldBe` "bye"
+                    tcpClosed h
+        it "one connection is one session" $
+            withTcpServer defaultServerConfig $ \_ handle ->
+                withConnection handle $ \h -> do
+                    reply <- tcpLogin h "admin" "s3cret"
+                    asText (at "status" reply) `shouldBe` "ok"
+                    withConnection handle $ \other -> do
+                        blocked <- tcpQuery other "select * from users"
+                        asText (at "code" blocked) `shouldBe` "unauthorized"
diff --git a/chusql-storage/src/endpoint.rs b/chusql-storage/src/endpoint.rs
deleted file mode 100644
index 7c9927b..0000000
--- a/chusql-storage/src/endpoint.rs
+++ /dev/null
@@ -1,99 +0,0 @@
-// 本地端点：Windows 上是具名管道 `\\.\pipe\<name>`，Unix/macOS 上是文件系统套接字
-// `<socket_dir>/<name>.sock`。存储进程、Haskell 前端（见 chusql-engine 的 Storage.IPC）
-// 和集成测试都用同一条规则，保证对同一个 `[server] pipe_name` 算出同一个端点。
-//
-// 用文件系统套接字而不是 Linux 抽象命名空间：抽象命名空间没有文件、跨平台不存在，
-// 而带路径的套接字两个方向都能连，Haskell 那边也能用常规 socket 连上。
-
-use interprocess::local_socket::{prelude::*, ListenerOptions};
-#[cfg(unix)]
-use interprocess::local_socket::GenericFilePath;
-#[cfg(windows)]
-use interprocess::local_socket::GenericNamespaced;
-#[cfg(unix)]
-use std::path::{Path, PathBuf};
-
-/// 端点的可读形式：Windows 是 `\\.\pipe\<name>`，Unix 是套接字文件路径。
-pub fn display(pipe_name: &str) -> String {
-    #[cfg(windows)]
-    {
-        format!("\\\\.\\pipe\\{}", pipe_name)
-    }
-    #[cfg(unix)]
-    {
-        socket_path(pipe_name).display().to_string()
-    }
-}
-
-/// Unix 端点路径：`$XDG_RUNTIME_DIR` → `$TMPDIR` → `/tmp`，文件名固定 `<pipe_name>.sock`。
-#[cfg(unix)]
-pub fn socket_path(pipe_name: &str) -> PathBuf {
-    let dir = std::env::var_os("XDG_RUNTIME_DIR")
-        .filter(|v| !v.is_empty())
-        .or_else(|| std::env::var_os("TMPDIR").filter(|v| !v.is_empty()))
-        .map(PathBuf::from)
-        .unwrap_or_else(|| PathBuf::from("/tmp"));
-    dir.join(format!("{}.sock", pipe_name))
-}
-
-/// 连到正在监听的存储进程。
-pub fn connect(pipe_name: &str) -> std::io::Result<LocalSocketStream> {
-    #[cfg(windows)]
-    {
-        let name = pipe_name
-            .to_ns_name::<GenericNamespaced>()
-            .map_err(|e| std::io::Error::other(e.to_string()))?;
-        LocalSocketStream::connect(name)
-    }
-    #[cfg(unix)]
-    {
-        let path = socket_path(pipe_name);
-        let name = path
-            .to_fs_name::<GenericFilePath>()
-            .map_err(|e| std::io::Error::other(e.to_string()))?;
-        LocalSocketStream::connect(name)
-    }
-}
-
-/// 监听端点：Windows 直接建具名管道；Unix 先探活，再清掉上次崩溃留下的残留套接字文件。
-pub fn listen(pipe_name: &str) -> std::io::Result<LocalSocketListener> {
-    #[cfg(windows)]
-    {
-        let name = pipe_name
-            .to_ns_name::<GenericNamespaced>()
-            .map_err(|e| std::io::Error::other(e.to_string()))?;
-        ListenerOptions::new().name(name).create_sync()
-    }
-    #[cfg(unix)]
-    {
-        let path = socket_path(pipe_name);
-        prepare_socket_path(&path)?;
-        let name = path
-            .to_fs_name::<GenericFilePath>()
-            .map_err(|e| std::io::Error::other(e.to_string()))?;
-        ListenerOptions::new().name(name).create_sync()
-    }
-}
-
-/// Unix：先探活的监听者，再清掉残留的套接字文件。
-#[cfg(unix)]
-fn prepare_socket_path(path: &Path) -> std::io::Result<()> {
-    match std::os::unix::net::UnixStream::connect(path) {
-        Ok(_) => Err(std::io::Error::new(
-            std::io::ErrorKind::AddrInUse,
-            format!(
-                "another storage server already listens on {}",
-                path.display()
-            ),
-        )),
-        Err(_) => {
-            if path.exists() {
-                std::fs::remove_file(path)?;
-            }
-            if let Some(parent) = path.parent() {
-                std::fs::create_dir_all(parent)?;
-            }
-            Ok(())
-        }
-    }
-}
diff --git a/chusql-web/app/Main.hs b/chusql-web/app/Main.hs
index 271abd0..8a09389 100644
--- a/chusql-web/app/Main.hs
+++ b/chusql-web/app/Main.hs
@@ -3,32 +3,28 @@
 module Main (main) where
 
 import ChuSQL.Web.API (AppEnv (..), Live (..), newAppEnvAt, setLive, webApp)
-import ChuSQL.Web.Auth (Credential (..), SessionPolicy (..), newSessionStore)
-import ChuSQL.Web.Backend (Backend, ipcBackend)
-import ChuSQL.Web.Demo (SeedReport (..), seedDemo)
-import ChuSQL.Web.Config (
+import ChuSQL.Interface.Auth (Credential (..), SessionPolicy (..), setPayloadPolicy)
+import ChuSQL.Interface.Config (
+    ServerConfig (..),
     WebConfig (..),
     defaultPassword,
     defaultUser,
+    loadServerConfigAt,
     loadWebConfigAt,
     resolveCredential,
-    resolvePipeName,
+    resolvePlainPassword,
     resolveStaticDir,
+    rootUserName,
     staticDirCandidates,
     usingDefaultCredentials,
  )
-import ChuSQL.Web.RateLimit (newRateLimiter)
-import ChuSQL.Storage.IPC (setPipeName)
-import ChuSQL.Web.Settings (effectiveSettings, readSettingsFile)
-import ChuSQL.Web.TOML (resolveConfigPath)
-import ChuSQL.Web.StorageProcess (
-    StorageProcess (..),
-    findStorageServer,
-    startStorageProcess,
-    stopStorageProcess,
-    waitForStorage,
- )
-import Control.Exception (IOException, bracket, onException, try)
+import ChuSQL.Interface.Link (clientPing, closeClient, connectClient)
+import ChuSQL.Interface.RateLimit (newRateLimiter)
+import ChuSQL.Interface.Session (authenticateSession, newSession)
+import ChuSQL.Interface.Settings (effectiveSettings, readSettingsFile)
+import ChuSQL.Interface.TOML (resolveConfigPath)
+import ChuSQL.Web.Demo (SeedReport (..), seedDemo)
+import Control.Exception (IOException, try)
 import Data.Char (toLower)
 import qualified Data.Map.Strict as Map
 import Data.String (fromString)
@@ -43,14 +39,13 @@ import System.Exit (exitFailure)
 import System.IO (BufferMode (LineBuffering), hSetBuffering, stdout)
 import Text.Read (readMaybe)
 
--- Web 管理端入口：读配置、备凭据、拉起存储进程，最后起 Warp。
+-- Web 管理端入口：读配置，把请求转给拥有存储的 server，最后起 Warp。
 
 data Options = Options
     { optConfig :: Maybe FilePath
     , optHost :: Maybe String
     , optPort :: Maybe Int
     , optStatic :: Maybe FilePath
-    , optStorage :: Maybe FilePath
     , optUser :: Maybe Text
     , optCookieSecure :: Maybe Bool
     , optBodyLimit :: Maybe Int
@@ -74,7 +69,6 @@ emptyOptions =
         , optHost = Nothing
         , optPort = Nothing
         , optStatic = Nothing
-        , optStorage = Nothing
         , optUser = Nothing
         , optCookieSecure = Nothing
         , optBodyLimit = Nothing
@@ -94,13 +88,13 @@ emptyOptions =
 parseArgs :: [String] -> Either String Options
 parseArgs = go emptyOptions
   where
+    -- | 逐个参数累加进 Options
     go opts [] = Right opts
     go opts ("--help" : rest) = go opts{optHelp = True} rest
     go opts ("-h" : rest) = go opts{optHelp = True} rest
     go opts ("--config" : v : rest) = go opts{optConfig = Just v} rest
     go opts ("--host" : v : rest) = go opts{optHost = Just v} rest
     go opts ("--static" : v : rest) = go opts{optStatic = Just v} rest
-    go opts ("--storage" : v : rest) = go opts{optStorage = Just v} rest
     go opts ("--user" : v : rest) = go opts{optUser = Just (T.pack v)} rest
     go opts ("--port" : v : rest) = withInt "--port" v (\n -> go opts{optPort = Just n} rest)
     go opts ("--body-limit" : v : rest) = withInt "--body-limit" v (\n -> go opts{optBodyLimit = Just n} rest)
@@ -116,13 +110,15 @@ parseArgs = go emptyOptions
     go opts ("--cookie-secure" : v : rest) = go opts{optCookieSecure = Just (isTrue v)} rest
     go _ (a : _) = Left ("unrecognized argument or missing value: " ++ a)
 
+    -- | 解析一个整数参数
     withInt :: String -> String -> (Int -> Either String Options) -> Either String Options
     withInt name v k = maybe (Left (name ++ " needs an integer, got: " ++ v)) k (readMaybe v)
 
+    -- | 把 1/true/yes/on 认成真
     isTrue :: String -> Bool
     isTrue s = map toLower s `elem` ["1", "true", "yes", "on"]
 
--- | 帮助
+-- | 打印命令行用法
 usage :: IO ()
 usage = do
     putStrLn "usage: chusql-web [options]"
@@ -130,15 +126,14 @@ usage = do
     putStrLn "config: chusql.toml sits at a fixed place and its sections hold every knob below;"
     putStrLn "        Windows: %APPDATA%\\ChuSQL\\chusql.toml"
     putStrLn "        other:   $XDG_CONFIG_HOME/ChuSQL/chusql.toml (or ~/.config/ChuSQL/chusql.toml)"
-    putStrLn "        [web] host/port/static_dir/user/password and the limits; [server] pipe_name;"
+    putStrLn "        [web] host/port/static_dir/user/password and the limits;"
     putStrLn "        [storage] data_dir; [page] size; [btree] order; [buffer] pool_size; [log] level"
     putStrLn ""
     putStrLn "  --config FILE          read that config file instead ([web] host ...)"
     putStrLn "  --host H               listen address              ([web] host, default 127.0.0.1)"
-    putStrLn "  --port N               listen port                 ([web] port, default 7777)"
+    putStrLn "  --port N               listen port                 ([web] port, default 7778)"
     putStrLn "  --static DIR           static asset directory      ([web] static_dir, default static)"
     putStrLn "  --user NAME            administrator name          ([web] user, default root)"
-    putStrLn "  --storage SERVER       Rust storage exe to spawn   ([web] storage_server)"
     putStrLn "  --cookie-secure BOOL   add Secure to the cookie    ([web] cookie_secure, default false)"
     putStrLn "  --body-limit N         max request body bytes      ([web] body_limit, default 65536)"
     putStrLn "  --session-idle N       session idle timeout, sec   ([web] session_idle, default 28800)"
@@ -155,8 +150,10 @@ usage = do
     putStrLn "  an empty password means the administrator signs in with no password; ordinary accounts are then refused"
     putStrLn ("without either the demo administrator is " ++ T.unpack defaultUser ++ " / " ++ T.unpack defaultPassword)
     putStrLn "ordinary accounts: CREATE USER / ALTER USER / DROP USER from the SQL console (administrator only)"
-    putStrLn "storage process: [server] pipe_name says where to talk and where a spawned one listens;"
-    putStrLn "  [storage] data_dir, [page] size, [btree] order, [buffer] pool_size and [log] level are its own"
+    putStrLn "storage: the server owns the data directory and loads the chusql_core_storage library;"
+    putStrLn "  this process is a plain TCP client: every statement, lookup and account request goes to it"
+    putStrLn "  [server] host / port says where it listens; [storage] data_dir, [page] size, [btree] order,"
+    putStrLn "  [buffer] pool_size and [log] level are the server's own"
 
 -- | 命令行覆盖配置
 applyOptions :: WebConfig -> Options -> WebConfig
@@ -165,9 +162,6 @@ applyOptions cfg opts =
         { wcHost = orElse (optHost opts) (wcHost cfg)
         , wcPort = orElse (optPort opts) (wcPort cfg)
         , wcStaticDir = orElse (optStatic opts) (wcStaticDir cfg)
-        , wcStorageServer = case optStorage opts of
-            Just p -> Just p
-            Nothing -> wcStorageServer cfg
         , wcUser = orElse (optUser opts) (wcUser cfg)
         , wcCookieSecure = orElse (optCookieSecure opts) (wcCookieSecure cfg)
         , wcBodyLimit = orElse (optBodyLimit opts) (wcBodyLimit cfg)
@@ -182,21 +176,12 @@ applyOptions cfg opts =
         , wcSeedDemo = orElse (optSeedDemo opts) (wcSeedDemo cfg)
         }
   where
+    -- | 有就用新的，没有留旧值
     orElse :: Maybe a -> a -> a
     orElse (Just x) _ = x
     orElse Nothing y = y
 
--- | 配了存储进程路径就拉起来，没配就假设外面已经跑着
-startStorageIfWanted :: WebConfig -> FilePath -> IO (Either String (Maybe StorageProcess))
-startStorageIfWanted cfg configPath = case wcStorageServer cfg of
-    Nothing -> pure (Right Nothing)
-    Just given -> do
-        found <- findStorageServer (Just given)
-        case found of
-            Left e -> pure (Left e)
-            Right bin -> fmap (fmap Just) (startStorageProcess bin configPath)
-
--- | 入口
+-- | 程序入口
 main :: IO ()
 main = do
     hSetBuffering stdout LineBuffering
@@ -210,13 +195,12 @@ main = do
             | optHelp opts -> usage
             | otherwise -> run opts
 
--- | 起服务
+-- | 读配置装配环境，检查 server，起 Warp
 run :: Options -> IO ()
 run opts = do
     configPath <- resolveConfigPath (optConfig opts)
     base <- loadWebConfigAt configPath
     let cfg = applyOptions base opts
-    setPipeName (resolvePipeName cfg)
     foundStatic <- resolveStaticDir (wcStaticDir cfg)
     case foundStatic of
         Nothing -> do
@@ -224,44 +208,31 @@ run opts = do
             exitFailure
         Just staticDir -> do
             let settingsFile = configPath
+                policy = SessionPolicy (fromIntegral (wcSessionIdle cfg)) (fromIntegral (wcSessionMax cfg))
             saved <- readSettingsFile settingsFile
-            cred <- resolveCredential cfg saved
-            storage <- startStorageIfWanted cfg configPath
-            case storage of
-                Left err -> do
-                    putStrLn err
-                    exitFailure
-                Right maybeStorage -> do
-                    backend <- ipcBackend
-                    let policy =
-                            SessionPolicy
-                                (fromIntegral (wcSessionIdle cfg))
-                                (fromIntegral (wcSessionMax cfg))
-                    sessions <- newSessionStore getCurrentTime policy
-                    limiter <-
-                        newRateLimiter
-                            getCurrentTime
-                            (wcLoginMaxAttempts cfg)
-                            (fromIntegral (wcLoginWindow cfg))
-                    env0 <- newAppEnvAt settingsFile backend sessions cred limiter staticDir
-                        `onException` maybe (pure ()) stopStorageProcess maybeStorage
-                    let env =
-                            env0
-                                { aeCookieSecure = wcCookieSecure cfg
-                                , aeEffective = effectiveSettings cfg
-                                , aeLog = TIO.putStrLn
-                                }
-                    setLive env (liveFromConfig cfg)
-                    app <- webApp env
-                    printBanner cfg configPath staticDir maybeStorage
-                    reportCredential cred saved
-                    waitForStorageReport
-                    seedIfWanted cfg backend
-                    let settings =
-                            Warp.setPort (wcPort cfg) (Warp.setHost (fromString (wcHost cfg)) Warp.defaultSettings)
-                    case maybeStorage of
-                        Nothing -> serve settings app
-                        Just sp -> bracket (pure sp) stopStorageProcess (const (serve settings app))
+            config <- loadServerConfigAt settingsFile
+            limiter <-
+                newRateLimiter
+                    getCurrentTime
+                    (wcLoginMaxAttempts cfg)
+                    (fromIntegral (wcLoginWindow cfg))
+            env0 <- newAppEnvAt settingsFile (T.pack (scHost config)) (scPort config) limiter staticDir
+            let env =
+                    env0
+                        { aeCookieSecure = wcCookieSecure cfg
+                        , aeEffective = effectiveSettings cfg
+                        , aeLog = TIO.putStrLn
+                        }
+            setPayloadPolicy (aeSessions env) policy
+            setLive env (liveFromConfig cfg)
+            app <- webApp env
+            printBanner cfg configPath staticDir
+            reportCredential cfg saved
+            checkServer (aeServerHost env) (aeServerPort env)
+            seedIfWanted cfg saved (aeServerHost env) (aeServerPort env)
+            let settings =
+                    Warp.setPort (wcPort cfg) (Warp.setHost (fromString (wcHost cfg)) Warp.defaultSettings)
+            serve settings app
 
 -- | 本次启动的配置摊成热改参数
 liveFromConfig :: WebConfig -> Live
@@ -291,47 +262,63 @@ serve settings app = do
             exitFailure
 
 -- | 口令是从哪来的（用了内置默认口令就明确警告）
-reportCredential :: Credential -> Map.Map Text Text -> IO ()
-reportCredential cred saved
-    | usingDefaultCredentials saved = do
-        putStrLn ""
-        putStrLn "  !! Administrator credentials are not configured; the built-in demo password is in use:"
-        putStrLn ("  !!   user " ++ T.unpack (credUser cred) ++ " / password " ++ T.unpack defaultPassword)
-        putStrLn "  !!   set user / password in the [web] section of chusql.toml and restart"
-        putStrLn ""
-    | T.null (credEncoded cred) =
-        putStrLn ("administrator: " ++ T.unpack (credUser cred) ++ " (passwordless: only the administrator may sign in)")
-    | otherwise = putStrLn ("administrator: " ++ T.unpack (credUser cred) ++ " (credentials come from the settings file only)")
+reportCredential :: WebConfig -> Map.Map Text Text -> IO ()
+reportCredential cfg saved = do
+    credential <- resolveCredential cfg saved
+    if usingDefaultCredentials saved
+        then do
+            putStrLn ""
+            putStrLn "  !! Administrator credentials are not configured; the built-in demo password is in use:"
+            putStrLn ("  !!   user " ++ T.unpack (credUser credential) ++ " / password " ++ T.unpack defaultPassword)
+            putStrLn "  !!   set user / password in the [web] section of chusql.toml and restart"
+            putStrLn ""
+        else
+            if T.null (credEncoded credential)
+                then putStrLn ("administrator: " ++ T.unpack (rootUserName cfg saved) ++ " (passwordless: only the administrator may sign in)")
+                else putStrLn ("administrator: " ++ T.unpack (rootUserName cfg saved) ++ " (credentials come from the settings file only)")
 
--- | 配了 seed 就补一份演示数据
-seedIfWanted :: WebConfig -> Backend -> IO ()
-seedIfWanted cfg backend
+-- | 配了 seed 就以管理员身份补演示数据
+seedIfWanted :: WebConfig -> Map.Map Text Text -> Text -> Int -> IO ()
+seedIfWanted cfg saved host port
     | not (wcSeedDemo cfg) = pure ()
     | otherwise = do
-        result <- seedDemo backend
-        case result of
-            Left e -> TIO.putStrLn ("demo data skipped: " <> T.pack e)
-            Right report ->
-                TIO.putStrLn
-                    ( "demo data: "
-                        <> (if null (srCreated report) then "already present" else "created " <> T.pack (unwords (srCreated report)))
-                        <> (if null (srSkipped report) then "" else ", kept " <> T.pack (unwords (srSkipped report)))
-                        <> (if null (srIndexes report) then "" else ", index on " <> T.pack (unwords (srIndexes report)))
-                    )
+        opened <- connectClient host port
+        case opened of
+            Left message -> TIO.putStrLn ("demo data skipped: " <> message)
+            Right client -> do
+                session <- newSession client
+                signed <- authenticateSession session (rootUserName cfg saved) (resolvePlainPassword saved)
+                case signed of
+                    Left message -> TIO.putStrLn ("demo data skipped: " <> message)
+                    Right () -> do
+                        result <- seedDemo session
+                        case result of
+                            Left message -> TIO.putStrLn ("demo data skipped: " <> message)
+                            Right report ->
+                                TIO.putStrLn
+                                    ( "demo data: "
+                                        <> (if null (srCreated report) then "already present" else "created " <> T.pack (unwords (srCreated report)))
+                                        <> (if null (srSkipped report) then "" else ", kept " <> T.pack (unwords (srSkipped report)))
+                                        <> (if null (srIndexes report) then "" else ", index on " <> T.pack (unwords (srIndexes report)))
+                                    )
+                closeClient client
 
--- | 报一下存储进程通不通
-waitForStorageReport :: IO ()
-waitForStorageReport = do
-    up <- waitForStorage 20
-    putStrLn
-        ( if up
-            then "storage:      up (endpoint answered ping)"
-            else "storage:      DOWN (no ping reply; start the Rust storage process or pass --storage)"
-        )
+-- | ping 一次 server，报告它通不通
+checkServer :: Text -> Int -> IO ()
+checkServer host port = do
+    opened <- connectClient host port
+    case opened of
+        Left message -> putStrLn ("storage:      DOWN (" ++ T.unpack message ++ ")")
+        Right client -> do
+            probe <- clientPing client
+            closeClient client
+            case probe of
+                Right () -> putStrLn "storage:      up (the server answered ping)"
+                Left message -> putStrLn ("storage:      DOWN (" ++ T.unpack message ++ ")")
 
 -- | 启动横幅
-printBanner :: WebConfig -> FilePath -> FilePath -> Maybe StorageProcess -> IO ()
-printBanner cfg configPath staticDir maybeStorage = do
+printBanner :: WebConfig -> FilePath -> FilePath -> IO ()
+printBanner cfg configPath staticDir = do
     putStrLn "==================== ChuSQL Web ===================="
     putStrLn ("url:          http://" ++ wcHost cfg ++ ":" ++ show (wcPort cfg) ++ "/")
     putStrLn ("config file:  " ++ configPath)
@@ -360,6 +347,4 @@ printBanner cfg configPath staticDir maybeStorage = do
             ++ show (wcLoginWindow cfg)
             ++ "s"
         )
-    case maybeStorage of
-        Just sp -> putStrLn ("storage proc: spawned, talking on pipe " ++ spPipe sp)
-        Nothing -> putStrLn "storage proc: assumed to run elsewhere (pipe name from [server] pipe_name)"
+    putStrLn "storage:      through the server that owns the data directory"
diff --git a/chusql-web/chusql-web.cabal b/chusql-web/chusql-web.cabal
index 4f71481..e8e2d61 100644
--- a/chusql-web/chusql-web.cabal
+++ b/chusql-web/chusql-web.cabal
@@ -4,37 +4,27 @@ name:           chusql-web
 version:        1.0.0
 synopsis:       ChuSQL Web 管理端：Scotty + REST API + 静态页面
 description:    ChuSQL 的浏览器管理端。负责 HTTP 交付、鉴权、静态文件，
-                以及把用户 SQL 转交给 chusql-engine（再由 IPC 打到 Rust 存储进程）。
+                并把用户的 SQL 经 TCP 转交给 chusql-server（存储由服务器进程里的
+                chusql_core_storage 动态库承担）。本进程不链引擎，也不碰存储。
+                数据库服务器与 TCP 协议在 chusql-server 包里，这里只做 HTTP 这一面。
 build-type:     Simple
 
 library
     hs-source-dirs:   src
-    exposed-modules:  ChuSQL.Web.Actions
-                      ChuSQL.Web.Accounts
-                      ChuSQL.Web.API
-                      ChuSQL.Web.Auth
-                      ChuSQL.Web.Backend
-                      ChuSQL.Web.Config
+    exposed-modules:  ChuSQL.Web.API
                       ChuSQL.Web.Demo
-                      ChuSQL.Web.Privileges
-                      ChuSQL.Web.RateLimit
                       ChuSQL.Web.Secure
-                      ChuSQL.Web.Settings
                       ChuSQL.Web.Static
-                      ChuSQL.Web.StorageProcess
-                      ChuSQL.Web.TOML
                       ChuSQL.Web.UISettings
     build-depends:    base >= 4.14 && < 5
                     , aeson
                     , bytestring
-                    , chusql-engine
+                    , chusql-core-model
+                    , chusql-interface
                     , containers
-                    , crypton
                     , directory
                     , filepath
                     , http-types
-                    , memory
-                    , process
                     , scientific
                     , scotty
                     , text
@@ -48,30 +38,32 @@ executable chusql-web
     main-is:          Main.hs
     hs-source-dirs:   app
     build-depends:    base
-                    , bytestring
-                    , chusql-engine
+                    , chusql-interface
                     , chusql-web
                     , containers
-                    , crypton
-                    , directory
-                    , filepath
-                    , http-types
-                    , memory
                     , text
                     , time
                     , wai
                     , warp
     default-language: Haskell2010
     ghc-options:      -Wall
+    -- 运行期找 libchusql_core_storage.so：$ORIGIN 让二进制与动态库同目录即可
+    if os(linux)
+        ld-options: -Wl,-rpath,$ORIGIN
+    if os(osx)
+        ld-options: -Wl,-rpath,@loader_path
 
 test-suite chusql-web-test
     type:             exitcode-stdio-1.0
     main-is:          Spec.hs
     hs-source-dirs:   test
+    other-modules:    Gates
+    build-tool-depends: chusql-server:chusql-server
     build-depends:    base
                     , aeson
                     , bytestring
-                    , chusql-engine
+                    , chusql-core-model
+                    , chusql-interface
                     , chusql-web
                     , containers
                     , directory
@@ -88,4 +80,4 @@ test-suite chusql-web-test
                     , wai-extra
                     , warp
     default-language: Haskell2010
-    ghc-options:      -Wall
+    ghc-options:      -Wall -threaded
diff --git a/chusql-web/src/ChuSQL/Web/Api.hs b/chusql-web/src/ChuSQL/Web/API.hs
similarity index 63%
rename from chusql-web/src/ChuSQL/Web/Api.hs
rename to chusql-web/src/ChuSQL/Web/API.hs
index 9ee7e9c..9530b75 100644
--- a/chusql-web/src/ChuSQL/Web/Api.hs
+++ b/chusql-web/src/ChuSQL/Web/API.hs
@@ -2,12 +2,12 @@
 
 module ChuSQL.Web.API (
     AppEnv (..),
+    WebSession (..),
     Live (..),
     defaultLive,
     setLive,
     readLive,
     applyLiveKeys,
-    configurePasswordPolicy,
     webApp,
     sessionCookieName,
     parseCookieHeader,
@@ -20,57 +20,73 @@ module ChuSQL.Web.API (
     newAppEnvAt,
 ) where
 
-import ChuSQL.Model (Row, Value (..))
-import ChuSQL.Semantic (check)
-import ChuSQL.Storage.IPC (Account (..), SchemaColumn (..), TableInfo (..))
-import ChuSQL.Syntax.AST (Statement (..))
-import ChuSQL.Syntax.Parser (parseStatement)
-import ChuSQL.Web.Accounts
-import ChuSQL.Web.Actions (
+import ChuSQL.Core.Model (Row, Value (..))
+import ChuSQL.Core.Protocol (Account (..), QueryResult (..), SchemaColumn (..), TableInfo (..))
+import ChuSQL.Interface.AccountTable (accountColumns, accountTableName, isAccountTable, passwordColumn, systemTableInfo)
+import ChuSQL.Interface.Actions (
     ColumnSpec (..),
     CreateTableSpec (..),
+    alterUserSql,
     coerceValue,
     columnTypeOf,
     createDatabaseSql,
     createIndexSql,
+    createRoleSql,
     createTableSql,
+    createUserSql,
     deleteRowSql,
     dropColumnSql,
     dropDatabaseSql,
     dropIndexSql,
+    dropRoleSql,
     dropTableSql,
+    dropUserSql,
+    grantPrivilegesSql,
+    grantRoleSql,
     insertRowSql,
     isIdentifier,
+    revokePrivilegesSql,
+    revokeRoleSql,
     selectRowsSql,
     updateRowSql,
  )
-import ChuSQL.Web.Auth (
-    Credential (..),
+import ChuSQL.Interface.Auth (
+    PayloadStore,
     SessionPolicy (..),
-    SessionStore,
-    deleteSession,
-    setSessionPolicy,
+    createPayloadSession,
+    defaultSessionPolicy,
+    dropPayload,
+    lookupPayload,
+    newPayloadStore,
     sessionToken,
+    setPayloadPolicy,
+    sweepPayloads,
  )
-import ChuSQL.Web.Backend (Backend, StatementResult (..), beCatalog, bePing, beStatement, beWithDatabase, beDatabases, statementNeedsDatabase)
-import ChuSQL.Web.Demo (SeedReport (..), seedDemo)
-import ChuSQL.Web.Privileges (
-    Grant (..),
-    PrivilegeCommand (..),
-    PrivilegeError (..),
-    Privileges,
-    RoleView (..),
-    authorize,
-    authorizeTables,
-    filterTables,
-    listRoleViews,
-    newPrivileges,
-    privilegeCommand,
-    runPrivilegeCommand,
+import ChuSQL.Interface.Link (
+    Client,
+    clientPing,
+    clientPolicy,
+    clientReloadPolicy,
+    closeClient,
+    connectClient,
  )
-import ChuSQL.Web.RateLimit (RateLimiter, rateLimitBlock, rateLimitClear, rateLimitRecord, setRateLimit)
-import ChuSQL.Web.Secure (bodyLimitDynamic, sameOriginOnly, securityHeaders, contentSecurityPolicy)
-import ChuSQL.Web.Settings (
+import ChuSQL.Interface.Protocol (Grant (..), RoleView (..))
+import ChuSQL.Interface.RateLimit (RateLimiter, rateLimitBlock, rateLimitClear, rateLimitRecord, setRateLimit)
+import ChuSQL.Interface.Session (
+    Session,
+    authenticateSession,
+    catalog,
+    databases,
+    isPlainIdentifier,
+    newSession,
+    roleViews,
+    runStatement,
+    sessionDatabase,
+    sessionIsAdmin,
+    switchDatabase,
+ )
+import qualified ChuSQL.Interface.Session as FrontSession
+import ChuSQL.Interface.Settings (
     SettingItem (..),
     applySettings,
     defaultOf,
@@ -80,8 +96,10 @@ import ChuSQL.Web.Settings (
     settingCatalogue,
     writeSettingsFile,
  )
+import ChuSQL.Interface.TOML (defaultConfigFile)
+import ChuSQL.Web.Demo (SeedReport (..), seedDemo)
+import ChuSQL.Web.Secure (bodyLimitDynamic, sameOriginOnly, securityHeaders, contentSecurityPolicy)
 import ChuSQL.Web.Static (contentTypeOf, readStatic, safeRelative)
-import ChuSQL.Web.TOML (defaultConfigFile)
 import ChuSQL.Web.UISettings (
     readUISettings,
     resolveUISettingsFile,
@@ -89,30 +107,34 @@ import ChuSQL.Web.UISettings (
     validateUISettings,
     writeUISettings,
  )
+import Control.Concurrent.MVar (MVar, modifyMVar, newMVar, withMVar)
 import Control.Exception (IOException, try)
 import Data.Aeson (FromJSON (..), eitherDecode, object, withObject, (.:), (.=))
 import qualified Data.Aeson as A
 import qualified Data.Aeson.Key as K
 import qualified Data.Aeson.KeyMap as KM
-import qualified Data.ByteString.Lazy as BL
 import qualified Data.ByteString as BS
+import qualified Data.ByteString.Lazy as BL
 import Data.IORef (IORef, newIORef, readIORef, writeIORef)
-import Data.List (sortBy)
+import Data.List (nub, sortBy)
 import qualified Data.Map.Strict as Map
 import Data.Maybe (catMaybes, fromMaybe)
 import Data.Scientific (fromFloatDigits)
 import Data.Text (Text)
 import qualified Data.Text as T
 import qualified Data.Text.Encoding as TE
+import qualified Data.Text.Encoding.Error as TEE
 import qualified Data.Text.Lazy as TL
+import Data.Time.Clock (getCurrentTime)
 import qualified Data.Vector as V
-import Network.HTTP.Types (status204, status400, status401, status403, status404, status409, status413, status429, status500)
-import Network.Wai (Application)
+import Network.HTTP.Types (Status, status204, status400, status401, status403, status404, status409, status413, status429, status500)
+import Network.Wai (Application, Request (..))
 import Text.Read (readMaybe)
 import Web.Scotty
 
 -- REST API 与页面交付：鉴权、JSON 与引擎结果的互转、错误到状态码的映射。
 
+-- | 一组可热改的运行参数
 data Live = Live
     { lvBodyLimit :: Int
     , lvSessionIdle :: Int
@@ -141,11 +163,11 @@ defaultLive =
         , lvMaxSqlLength = 20000
         }
 
+-- | Web 进程共享的运行环境
 data AppEnv = AppEnv
-    { aeBackend :: Backend
-    , aeSessions :: SessionStore
-    , aeAccounts :: Accounts
-    , aePrivileges :: Privileges
+    { aeServerHost :: Text
+    , aeServerPort :: Int
+    , aeSessions :: PayloadStore WebSession
     , aeLimiter :: RateLimiter
     , aeStaticDir :: FilePath
     , aeCookieSecure :: Bool
@@ -153,34 +175,38 @@ data AppEnv = AppEnv
     , aeSettingsFile :: FilePath
     , aeUISettingsFile :: FilePath
     , aeEffective :: Map.Map Text Text
-    , aeDatabase :: Text
     , aeLog :: Text -> IO ()
     }
 
+-- | 一条网页会话：TCP 连接、登录状态与账号名
+data WebSession = WebSession
+    { wsClient :: Client
+    , wsSession :: Session
+    , wsUser :: Text
+    , wsAdmin :: Bool
+    }
+
 -- | 会话 Cookie 名
 sessionCookieName :: Text
 sessionCookieName = "chusql_session"
 
--- | 参数齐全地造一份环境（各项上限用内置默认，调用方按配置改）；配置文件用固定路径
-newAppEnv :: Backend -> SessionStore -> Credential -> RateLimiter -> FilePath -> IO AppEnv
-newAppEnv backend sessions cred limiter staticDir = do
+-- | 造一份运行环境，各项上限用内置默认
+newAppEnv :: Text -> Int -> RateLimiter -> FilePath -> IO AppEnv
+newAppEnv host port limiter staticDir = do
     settingsFile <- resolveSettingsFileSafe
-    newAppEnvAt settingsFile backend sessions cred limiter staticDir
+    newAppEnvAt settingsFile host port limiter staticDir
 
--- | 同上，但明说读写哪份配置文件（--config 走这里，保证读写的和启动读的是同一份）
-newAppEnvAt :: FilePath -> Backend -> SessionStore -> Credential -> RateLimiter -> FilePath -> IO AppEnv
-newAppEnvAt settingsFile backend sessions cred limiter staticDir = do
-    accounts <- newAccounts backend sessions cred
-    privileges <- newPrivileges backend
+-- | 同上，但显式指定配置文件路径
+newAppEnvAt :: FilePath -> Text -> Int -> RateLimiter -> FilePath -> IO AppEnv
+newAppEnvAt settingsFile host port limiter staticDir = do
+    sessions <- newPayloadStore getCurrentTime defaultSessionPolicy
     liveRef <- newIORef defaultLive
-    configurePasswordPolicy accounts settingsFile
     uiSettingsFile <- resolveUISettingsFileSafe
     pure
         AppEnv
-            { aeBackend = backend
+            { aeServerHost = host
+            , aeServerPort = port
             , aeSessions = sessions
-            , aeAccounts = accounts
-            , aePrivileges = privileges
             , aeLimiter = limiter
             , aeStaticDir = staticDir
             , aeCookieSecure = False
@@ -188,11 +214,10 @@ newAppEnvAt settingsFile backend sessions cred limiter staticDir = do
             , aeSettingsFile = settingsFile
             , aeUISettingsFile = uiSettingsFile
             , aeEffective = Map.empty
-            , aeDatabase = ""
             , aeLog = const (pure ())
             }
 
--- | 系统库：账号表住在这里，其中的表都是系统表，只有管理员能进。
+-- | 系统库：账号表住在这里，只有管理员能进
 systemDatabase :: Text
 systemDatabase = "system"
 
@@ -200,26 +225,7 @@ systemDatabase = "system"
 reservedDatabase :: Text -> Bool
 reservedDatabase name = name == systemDatabase
 
-configurePasswordPolicy :: Accounts -> FilePath -> IO ()
-configurePasswordPolicy accounts path = do
-    saved <- readSettingsFile path
-    let values = Map.fromList [(key, Map.findWithDefault (defaultOf key) key saved) | key <- passwordKeys]
-    case applySettings Map.empty values of
-        Left err -> ioError (userError err)
-        Right valid -> setAccountsPolicy accounts (policyFromValues defaultPasswordPolicy valid)
-
-passwordKeys :: [Text]
-passwordKeys = ["password-min-length", "password-classes"]
-
-policyFromValues :: PasswordPolicy -> Map.Map Text Text -> PasswordPolicy
-policyFromValues before values = PasswordPolicy
-    (number "password-min-length" (ppMinLength before)) (number "password-classes" (ppClasses before))
-  where
-    number key fallback = case Map.lookup key values of
-        Nothing -> fallback
-        Just value -> fromMaybe fallback (readMaybe (T.unpack (if T.null value then defaultOf key else value)))
-
--- | 配置文件位置是固定的，这里只兜住「拿不到用户目录」的极端情况
+-- | 定位配置文件路径，失败时回落到固定名
 resolveSettingsFileSafe :: IO FilePath
 resolveSettingsFileSafe = do
     found <- try defaultConfigFile :: IO (Either IOException FilePath)
@@ -247,11 +253,33 @@ readLive = readIORef . aeLive
 liveBodyLimit :: AppEnv -> IO Int
 liveBodyLimit env = lvBodyLimit <$> readLive env
 
--- | 组装 WAI 应用：Scotty 路由外面套三层中间件
+-- | 组装 WAI 应用：路由外套四层中间件
 webApp :: AppEnv -> IO Application
 webApp env = do
     inner <- scottyApp (routes env)
-    pure (securityHeaders (sameOriginOnly (bodyLimitDynamic (liveBodyLimit env) inner)))
+    locks <- newMVar Map.empty
+    pure (securityHeaders (sameOriginOnly (bodyLimitDynamic (liveBodyLimit env) (serializeSessions locks inner))))
+
+-- | 同一条会话的请求串行执行
+serializeSessions :: MVar (Map.Map Text (MVar ())) -> Application -> Application
+serializeSessions locks app req respond = case sessionKey req of
+    Nothing -> app req respond
+    Just key -> do
+        lock <- lockFor locks key
+        withMVar lock (const (app req respond))
+  where
+    -- | 取请求所属的会话令牌
+    sessionKey _ = do
+        rawCookie <- lookup "Cookie" (requestHeaders req)
+        parseCookieHeader sessionCookieName (TE.decodeUtf8With TEE.lenientDecode rawCookie)
+
+-- | 一条会话一把锁（按 Cookie 令牌去重）
+lockFor :: MVar (Map.Map Text (MVar ())) -> Text -> IO (MVar ())
+lockFor locks key = modifyMVar locks $ \known -> case Map.lookup key known of
+    Just lock -> pure (known, lock)
+    Nothing -> do
+        lock <- newMVar ()
+        pure (Map.insert key lock known, lock)
 
 -- | 路由表：界面一键操作全走结构化接口
 routes :: AppEnv -> ScottyM ()
@@ -292,59 +320,81 @@ routes env = do
     post "/api/query" (withDatabase env queryH)
     notFound (notFoundH env)
 
--- | A request carries its own immutable database context; shared IPC never stores USE state.
---   没带 `X-ChuSQL-Database` 就是"没选库"：绑定空库，需要库的接口自己报 no database selected。
+-- | 先认会话，再按请求头切本会话的库
 withDatabase :: AppEnv -> (AppEnv -> ActionM ()) -> ActionM ()
 withDatabase env action = do
-    principal <- requirePrincipal env
+    ws <- requireSession env
     chosen <- maybe "" (T.toLower . TL.toStrict) <$> header "X-ChuSQL-Database"
-    if T.null chosen
-        then action env{aeBackend = beWithDatabase (aeBackend env) "", aeDatabase = ""}
+    if not (T.null chosen) && (not (isPlainIdentifier chosen) || T.length chosen > 64)
+        then reply400 "bad_request" "invalid database name"
         else
-            if not (isIdentifier chosen) || T.length chosen > 64
-                then reply400 "bad_request" "invalid database name"
-                else
-                    if chosen == systemDatabase && not (principalIsRoot principal)
-                        then reply403 "the system database is only available to the administrator"
-                        else action env {aeBackend = beWithDatabase (aeBackend env) (T.unpack chosen), aeDatabase = chosen}
+            if chosen == systemDatabase && not (wsAdmin ws)
+                then reply403 "the system database is only available to the administrator"
+                else do
+                    ready <- liftIO (if T.null chosen then pure (Right ()) else switchDatabase (wsSession ws) chosen)
+                    case ready of
+                        Left message -> serverError message
+                        Right () -> action env
 
--- | 需要当前库的接口先过这一关（裸表名/建表都要先选库）。
---   走 accountError 而不是 reply400：它会 finish，否则 handler 还会往下跑并覆盖这个错误。
-requireDatabase :: AppEnv -> ActionM ()
-requireDatabase env =
-    if T.null (aeDatabase env)
-        then accountError (AccountError "no_database" "no database selected")
-        else pure ()
+-- | 取当前库名，未选库时报错
+requireDatabaseName :: WebSession -> ActionM Text
+requireDatabaseName ws = do
+    current <- liftIO (sessionDatabase (wsSession ws))
+    if T.null current
+        then apiError "no_database" "no database selected"
+        else pure current
+
+-- | 取本请求的会话，没有令牌就 401
+requireSession :: AppEnv -> ActionM WebSession
+requireSession env = do
+    token <- requestSessionToken >>= maybe (apiError "unauthorized" "sign in first") pure
+    found <- liftIO (lookupPayload (aeSessions env) token)
+    case found of
+        Nothing -> apiError "unauthorized" "sign in first"
+        Just (_, ws) -> pure ws
+
+-- | 管理员专属操作
+requireAdminSession :: AppEnv -> ActionM WebSession
+requireAdminSession env = do
+    ws <- requireSession env
+    adminOnly ws
+    pure ws
+
+-- | 只有管理员能碰的东西
+adminOnly :: WebSession -> ActionM ()
+adminOnly ws
+    | wsAdmin ws = pure ()
+    | otherwise = apiError "forbidden" "administrator required"
 
 -- | 数据库清单；系统库 system 只给管理员看。
 databasesH :: AppEnv -> ActionM ()
 databasesH env = do
-    principal <- requirePrincipal env
-    result <- liftIO (beDatabases (aeBackend env))
+    ws <- requireSession env
+    result <- liftIO (databases (wsSession ws))
     case result of
-        Left e -> engineError e
-        Right names -> json (if principalIsRoot principal then names else filter (/= T.unpack systemDatabase) names)
+        Left message -> serverError message
+        Right names -> json (if wsAdmin ws then names else filter (/= systemDatabase) names)
 
--- | 新建数据库：名字过标识符白名单，真正建库交给存储层。
+-- | 新建数据库：校验名字后交给 server
 createDatabaseH :: AppEnv -> ActionM ()
 createDatabaseH env = do
-    requireAdmin env
+    ws <- requireAdminSession env
     withJsonObject env $ \o -> case textField "name" o of
         Left err -> reply400 "bad_request" err
         Right name -> case createDatabaseSql name of
             Left err -> reply400 "bad_request" (T.pack err)
-            Right sql -> runWrite env sql
+            Right sql -> runWrite ws sql
 
 -- | 删除数据库；系统库 system 一律拒绝。
 dropDatabaseH :: AppEnv -> ActionM ()
 dropDatabaseH env = do
-    requireAdmin env
+    ws <- requireAdminSession env
     name <- pathParam "name"
     if reservedDatabase name
         then reply400 "bad_request" "the system database cannot be dropped"
         else case dropDatabaseSql name of
             Left err -> reply400 "bad_request" (T.pack err)
-            Right sql -> runWrite env sql
+            Right sql -> runWrite ws sql
 
 -- | 首页：登录与管理界面同一个 HTML
 indexH :: AppEnv -> ActionM ()
@@ -390,11 +440,20 @@ notFoundH _ = reply404
 healthH :: ActionM ()
 healthH = json (object ["status" .= ("ok" :: Text)])
 
--- | 进程 + 存储：启动脚本靠这个判断存储接上了没
+-- | 探活：回进程与存储状态，顺带清理过期会话
 statusH :: AppEnv -> ActionM ()
 statusH env = do
-    up <- liftIO (bePing (aeBackend env))
-    json (object ["status" .= ("ok" :: Text), "storage" .= (if up then "up" else "down" :: Text)])
+    expired <- liftIO (sweepPayloads (aeSessions env))
+    liftIO (mapM_ (closeClient . wsClient) expired)
+    opened <- liftIO (connectClient (aeServerHost env) (aeServerPort env))
+    case opened of
+        Left message -> json (object ["status" .= ("ok" :: Text), "storage" .= ("down" :: Text), "detail" .= message])
+        Right client -> do
+            probe <- liftIO (clientPing client)
+            liftIO (closeClient client)
+            case probe of
+                Right () -> json (object ["status" .= ("ok" :: Text), "storage" .= ("up" :: Text)])
+                Left message -> json (object ["status" .= ("ok" :: Text), "storage" .= ("down" :: Text), "detail" .= message])
 
 -- | 登录：对了发 Cookie，错了 401/429
 loginH :: AppEnv -> ActionM ()
@@ -418,50 +477,79 @@ loginH env = do
                                 setHeader "Retry-After" (TL.fromStrict (T.pack (show (ceiling left :: Int))))
                                 status status429
                                 json (apiErrorJson "too_many_attempts" "too many failed sign-in attempts, try again later")
-                            Nothing -> do
-                                live <- liftIO (readLive env)
-                                result <- liftIO (authenticate (aeAccounts env) user password)
-                                case result of
-                                    Right token -> do
-                                        liftIO (rateLimitClear (aeLimiter env) user)
-                                        setHeader "Set-Cookie" (TL.fromStrict (sessionCookie env token (Just (lvSessionMax live))))
-                                        liftIO (aeLog env ("sign-in ok user=" <> user))
-                                        status status204
-                                    Left err@(AccountError code _) | code /= "unauthorized" -> accountError err
-                                    Left _ -> do
-                                        liftIO (rateLimitRecord (aeLimiter env) user)
-                                        liftIO (aeLog env ("sign-in failed user=" <> user))
-                                        status status401
-                                        json (apiErrorJson "unauthorized" "invalid user name or password")
+                            Nothing -> openSession env user password
 
--- | 退出：删服务端会话 + 让浏览器丢 Cookie
+-- | 用用户口令连 server，成功后建会话
+openSession :: AppEnv -> Text -> Text -> ActionM ()
+openSession env user password = do
+    live <- liftIO (readLive env)
+    opened <- liftIO (connectClient (aeServerHost env) (aeServerPort env))
+    case opened of
+        Left message -> do
+            liftIO (aeLog env ("sign-in failed user=" <> user <> " " <> message))
+            status status500
+            json (apiErrorJson "internal" message)
+        Right client -> do
+            session <- liftIO (newSession client)
+            signed <- liftIO (authenticateSession session user password)
+            case signed of
+                Left message -> do
+                    liftIO (closeClient client)
+                    liftIO (rateLimitRecord (aeLimiter env) user)
+                    liftIO (aeLog env ("sign-in failed user=" <> user <> " " <> message))
+                    if errorCodeOf message == "unauthorized"
+                        then do
+                            status status401
+                            json (apiErrorJson "unauthorized" "invalid user name or password")
+                        else serverError message
+                Right () -> do
+                    admin <- liftIO (sessionIsAdmin session)
+                    token <- liftIO (createPayloadSession (aeSessions env) user (WebSession client session user admin))
+                    liftIO (rateLimitClear (aeLimiter env) user)
+                    setHeader "Set-Cookie" (TL.fromStrict (sessionCookie env token (Just (lvSessionMax live))))
+                    liftIO (aeLog env ("sign-in ok user=" <> user))
+                    status status204
+
+-- | 退出：收掉会话与连接，清除 Cookie
 logoutH :: AppEnv -> ActionM ()
 logoutH env = do
     token <- requestSessionToken
     case token of
         Nothing -> pure ()
-        Just t -> liftIO (deleteSession (aeSessions env) t)
+        Just t -> do
+            gone <- liftIO (dropPayload (aeSessions env) t)
+            case gone of
+                Nothing -> pure ()
+                Just ws -> liftIO (closeClient (wsClient ws))
     setHeader "Set-Cookie" (TL.fromStrict (sessionCookie env "" (Just 0)))
     status status204
 
--- | 当前登录的是谁
+-- | 当前登录者与生效的口令策略
 sessionH :: AppEnv -> ActionM ()
 sessionH env = do
-    principal <- requirePrincipal env
-    policy <- liftIO (accountsPolicy (aeAccounts env))
-    json (object ["user" .= principalName principal, "administrator" .= principalIsRoot principal,
-        "policy" .= object ["minLength" .= ppMinLength policy, "classes" .= ppClasses policy]])
+    ws <- requireSession env
+    policy <- liftIO (clientPolicy (wsClient ws))
+    case policy of
+        Left message -> serverError message
+        Right (minLength, classes) ->
+            json
+                ( object
+                    [ "user" .= wsUser ws
+                    , "administrator" .= wsAdmin ws
+                    , "policy" .= object ["minLength" .= minLength, "classes" .= classes]
+                    ]
+                )
 
 -- | 读设置：文件值、启动生效值与内置默认一起给出
 settingsH :: AppEnv -> ActionM ()
 settingsH env = do
-    principal <- requirePrincipal env
+    ws <- requireSession env
     fileValues <- liftIO (readSettingsFile (aeSettingsFile env))
-    let owner = principalIsRoot principal
+    let owner = wsAdmin ws
     json
         ( object
             [ "file" .= aeSettingsFile env
-            , "account" .= principalName principal
+            , "account" .= wsUser ws
             , "owner" .= owner
             , "items" .= map (itemJson (aeEffective env) fileValues owner) settingCatalogue
             ]
@@ -501,17 +589,17 @@ itemJson effectiveValues fileValues owner spec =
 -- | 改设置：写配置文件并让可热改项立即生效
 putSettingsH :: AppEnv -> ActionM ()
 putSettingsH env = do
-    user <- requireUser env
+    ws <- requireSession env
+    let user = wsUser ws
     withJsonObject env $ \o -> case settingsUpdates o of
         Left err -> reply400 "bad_request" err
         Right updates -> do
-            principal <- requirePrincipal env
             let locked = [k | k <- Map.keys updates, isLockedSetting k]
                 forbidden =
                     [ k
                     | k <- Map.keys updates
                     , maybe False siRootOnly (findSetting k)
-                    , not (principalIsRoot principal)
+                    , not (wsAdmin ws)
                     ]
             if not (null locked)
                 then reply403 ("administrator credentials live in the settings file and cannot be changed here: " <> T.intercalate ", " locked)
@@ -528,18 +616,24 @@ putSettingsH env = do
                                         Left err -> reply500 (T.pack err)
                                         Right () -> do
                                             applied <- liftIO (applyLiveKeys env updates)
-                                            let needsRestart = [k | k <- Map.keys updates, not (k `elem` applied), not (T.null (Map.findWithDefault "" k updates))]
+                                            -- 口令策略住在 server：让它重读自己的设置文件
+                                            reloaded <- liftIO (clientReloadPolicy (wsClient ws))
+                                            let policyKeys = ["password-min-length", "password-classes"]
+                                                appliedNow = case reloaded of
+                                                    Right _ -> nub (applied ++ [k | k <- policyKeys, Map.member k updates])
+                                                    Left _ -> applied
+                                                needsRestart = [k | k <- Map.keys updates, not (k `elem` appliedNow), not (T.null (Map.findWithDefault "" k updates))]
                                             liftIO (aeLog env ("settings updated by " <> user <> ": " <> T.intercalate ", " (Map.keys updates)))
                                             json
                                                 ( object
                                                     [ "ok" .= True
                                                     , "file" .= aeSettingsFile env
-                                                    , "applied" .= applied
+                                                    , "applied" .= appliedNow
                                                     , "restartRequired" .= needsRestart
                                                     ]
                                                 )
 
--- | 读前端 IDE 设置（放在自己的文件里，与服务配置无关）
+-- | 读前端 IDE 的设置文件
 uiSettingsH :: AppEnv -> ActionM ()
 uiSettingsH env = do
     _ <- requireUser env
@@ -564,46 +658,23 @@ putUISettingsH env = do
                         Left err -> reply500 (T.pack err)
                         Right () -> status status204
 
--- | 账号表的名字：网页里像普通表一样浏览与编辑，但写入走账号命令
-accountTableName :: String
-accountTableName = "__chusql_users"
-
--- | 这张表是不是账号表
-isAccountTable :: Text -> Bool
-isAccountTable name = T.toLower name == T.pack accountTableName
-
--- | 账号表只住在系统库 system 里：在别的库上点名它一律 400。
-accountRoute :: AppEnv -> Text -> ActionM Bool
-accountRoute env name
+-- | 点账号表时只认系统库，否则 400
+accountRoute :: WebSession -> Text -> ActionM Bool
+accountRoute ws name
     | not (isAccountTable name) = pure False
-    | aeDatabase env /= systemDatabase = do
-        reply400 "bad_request" "the account table lives in the system database"
-        finish
-    | otherwise = pure True
-
--- | 口令列：密文只在服务端产生，界面不支持排序与筛选
-passwordColumn :: String
-passwordColumn = "password"
-
--- | 账号表的列：id 主键、用户名唯一索引、口令密文、注册时间与最近登录时间
-accountColumns :: [SchemaColumn]
-accountColumns =
-    [ accountColumnSpec "id" "int" False True True False
-    , accountColumnSpec "user" "varchar(64)" False False False True
-    , accountColumnSpec passwordColumn "varchar(256)" False False False False
-    , accountColumnSpec "registered_at" "timestamp" False False False False
-    , accountColumnSpec "last_login_at" "timestamp" True False False False
-    ]
-
--- | 账号表的列（约束由账号服务管）
-accountColumnSpec :: String -> String -> Bool -> Bool -> Bool -> Bool -> SchemaColumn
-accountColumnSpec name ty nullable autoIncrement primary unique =
-    SchemaColumn name ty nullable Nothing autoIncrement primary unique Nothing
+    | otherwise = do
+        current <- liftIO (sessionDatabase (wsSession ws))
+        if current /= systemDatabase
+            then do
+                reply400 "bad_request" "the account table lives in the system database"
+                finish
+            else pure True
 
 -- | 账号行：平铺的各列
 accountRowsOf :: [Account] -> [Row]
 accountRowsOf = map accountRow
   where
+    -- | 一个账号转成一行
     accountRow a =
         [ ("id", VInt (fromIntegral (accountId a)))
         , ("user", VStr (T.unpack (accountUser a)))
@@ -623,6 +694,7 @@ systemTableJson count =
         , "columns" .= map accountColumnJson accountColumns
         ]
   where
+    -- | 一列转成线上 JSON
     accountColumnJson sc =
         object
             [ "name" .= scName sc
@@ -637,11 +709,11 @@ systemTableJson count =
             , "secret" .= (scName sc == passwordColumn)
             ]
 
--- | 读一遍账号表，读不到就 500
-requireAccounts :: AppEnv -> ActionM [Account]
-requireAccounts env = do
-    result <- liftIO (listAccounts (aeAccounts env))
-    either accountError pure result
+-- | 读一遍账号表，读不到就按 server 给的码回
+requireAccounts :: WebSession -> ActionM [Account]
+requireAccounts ws = do
+    result <- liftIO (FrontSession.accounts (wsSession ws))
+    either serverError pure result
 
 -- | 口令列不接受排序与筛选
 rejectSecretColumn :: Maybe (Text, Bool) -> [(Text, Value)] -> Either Text ()
@@ -650,18 +722,10 @@ rejectSecretColumn order filters
     | any ((== T.pack passwordColumn) . fst) filters = Left "the password column cannot be filtered"
     | otherwise = Right ()
 
--- | 只有管理员能用账号表
-rootOnly :: Principal -> ActionM ()
-rootOnly principal =
-    if principalIsRoot principal
-        then pure ()
-        else accountError (AccountError "forbidden" "administrator required")
-
 -- | 账号表的一页数据（排序与筛选都在内存里做）
-baseRowsH :: AppEnv -> ActionM ()
-baseRowsH env = do
-    principal <- requirePrincipal env
-    rootOnly principal
+baseRowsH :: WebSession -> AppEnv -> ActionM ()
+baseRowsH ws env = do
+    adminOnly ws
     live <- liftIO (readLive env)
     limit <- intParam "limit" (lvPageSize live) 1 (lvMaxPageSize live)
     offset <- intParam "offset" 0 0 1000000
@@ -673,7 +737,7 @@ baseRowsH env = do
         (Right sortOrder, Right filters) -> case rejectSecretColumn sortOrder filters of
             Left err -> reply400 "bad_request" err
             Right () -> do
-                accounts <- requireAccounts env
+                accounts <- requireAccounts ws
                 let rows = filterAccountRows filters (sortAccountRows sortOrder (accountRowsOf accounts))
                     page = take limit (drop offset rows)
                     cols = map scName accountColumns
@@ -692,19 +756,17 @@ baseRowsH env = do
                         ]
                     )
 
--- | 账号表的结构（排序校验用）
-systemTableInfo :: TableInfo
-systemTableInfo = TableInfo accountTableName accountColumns 0 [] []
-
 -- | 按用户名排序（其余列不支持排序）
 sortAccountRows :: Maybe (Text, Bool) -> [Row] -> [Row]
 sortAccountRows Nothing rows = rows
 sortAccountRows (Just (column, ascending)) rows =
     sortBy compareUser rows
   where
+    -- | 比两个账号单元
     compareUser a b = case (accountCell a column, accountCell b column) of
         (Just x, Just y) -> if ascending then compare x y else compare y x
         _ -> EQ
+    -- | 取账号行里某列的文本值
     accountCell row name = case lookup (T.unpack name) row of
         Just VNull -> Just ""
         Just (VStr s) -> Just s
@@ -717,76 +779,94 @@ filterAccountRows :: [(Text, Value)] -> [Row] -> [Row]
 filterAccountRows [] rows = rows
 filterAccountRows filters rows = [r | r <- rows, all (matches r) filters]
   where
+    -- | 行是否满足一条等值条件
     matches row (column, wanted) = case lookup (T.unpack column) row of
         Just value -> value == wanted
         Nothing -> False
 
 -- | 账号表写入：插一行 = CREATE USER
-baseInsertH :: AppEnv -> ActionM ()
-baseInsertH env = do
-    principal <- requirePrincipal env
-    rootOnly principal
+baseInsertH :: AppEnv -> WebSession -> ActionM ()
+baseInsertH env ws = do
+    adminOnly ws
     withJsonObject env $ \o -> case valuesField o >>= readRowValues False accountColumns of
         Left err -> reply400 "bad_request" err
         Right values -> case (lookupValue "user" values, lookupValue (T.pack passwordColumn) values) of
-            (Just (VStr user), Just (VStr password)) -> runAccountWrite env principal (CreateAccount (T.pack user) (T.pack password))
+            (Just (VStr user), Just (VStr password)) -> case createUserSql (T.pack user) (T.pack password) of
+                Left err -> reply400 "bad_request" (T.pack err)
+                Right sql -> runWrite ws sql
             _ -> reply400 "bad_request" "user and password are required"
 
--- | 账号表写入：改一行 = ALTER USER（只改口令，不许改名）
-baseUpdateH :: AppEnv -> Text -> ActionM ()
-baseUpdateH env target = do
-    principal <- requirePrincipal env
-    rootOnly principal
+-- | 账号表写入：改一行 = ALTER USER
+baseUpdateH :: AppEnv -> WebSession -> Text -> ActionM ()
+baseUpdateH env ws target = do
+    adminOnly ws
     withJsonObject env $ \o -> case valuesField o >>= readRowValues False accountColumns of
         Left err -> reply400 "bad_request" err
         Right values -> case (values, lookupValue (T.pack passwordColumn) values) of
-            ([(_, VStr password)], Just _) -> runAccountWrite env principal (ResetAccountPassword target (T.pack password))
+            ([(_, VStr password)], Just _) -> case alterUserSql target (T.pack password) of
+                Left err -> reply400 "bad_request" (T.pack err)
+                Right sql -> runWrite ws sql
             _ -> reply400 "bad_request" "only the password of an existing account can be changed"
 
 -- | 账号表写入：删一行 = DROP USER
-baseDeleteH :: AppEnv -> Text -> ActionM ()
-baseDeleteH env target = do
-    principal <- requirePrincipal env
-    rootOnly principal
-    runAccountWrite env principal (DropAccount target)
-
--- | 账号写入：SQL 控制台与基表行接口共用的执行路径
-runAccountWrite :: AppEnv -> Principal -> AccountCommand -> ActionM ()
-runAccountWrite env principal command = do
-    result <- liftIO (runAccountCommand (aeAccounts env) principal command)
-    case result of
-        Left err -> accountError err
-        Right () -> json (object ["ok" .= True])
+baseDeleteH :: AppEnv -> WebSession -> Text -> ActionM ()
+baseDeleteH _env ws target = do
+    adminOnly ws
+    case dropUserSql target of
+        Left err -> reply400 "bad_request" (T.pack err)
+        Right sql -> runWrite ws sql
 
 -- | 取一个列值
 lookupValue :: Text -> [(String, Value)] -> Maybe Value
 lookupValue name values = lookup (T.unpack name) values
 
-accountError :: AccountError -> ActionM a
-accountError (AccountError code message) = do
-    status $ case code of
-        "unauthorized" -> status401
-        "forbidden" -> status403
-        "not_found" -> status404
-        "conflict" -> status409
-        "storage_error" -> status500
-        _ -> status400
+-- | 错误码 + 消息 → 状态码 + 统一错误体
+apiError :: Text -> Text -> ActionM a
+apiError code message = do
+    status (statusOf code)
     json (apiErrorJson code message)
     finish
 
+-- | 拆开 server 的 code: message 并映射
+serverError :: Text -> ActionM a
+serverError message
+    | code `elem` knownCodes = apiError code detail
+    | otherwise = apiError "internal" message
+  where
+    (rawCode, rest) = T.breakOn ":" message
+    code = T.strip rawCode
+    detail = T.strip (T.drop 1 rest)
+    knownCodes = ["unauthorized", "forbidden", "not_found", "conflict", "bad_request", "no_database", "query_error", "storage_error", "too_large"]
+
+-- | 取错误消息里的错误码
+errorCodeOf :: Text -> Text
+errorCodeOf message = T.strip (fst (T.breakOn ":" message))
+
+-- | 错误码 → HTTP 状态码
+statusOf :: Text -> Status
+statusOf code = case code of
+    "unauthorized" -> status401
+    "forbidden" -> status403
+    "not_found" -> status404
+    "conflict" -> status409
+    "too_many_attempts" -> status429
+    "too_large" -> status413
+    "storage_error" -> status500
+    "internal" -> status500
+    _ -> status400
+
 -- | 按 key 找目录项
 findSetting :: Text -> Maybe SettingItem
 findSetting key = case [i | i <- settingCatalogue, siKey i == key] of
     (i : _) -> Just i
     [] -> Nothing
 
--- | 把能热改的设置应用到当前进程
+-- | 把热改设置应用到当前进程
 applyLiveKeys :: AppEnv -> Map.Map Text Text -> IO [Text]
 applyLiveKeys env updates = do
-    beforePolicy <- accountsPolicy (aeAccounts env)
-    setAccountsPolicy (aeAccounts env) (policyFromValues beforePolicy updates)
     before <- readLive env
     let wanted = [k | k <- liveKeys, Map.member k updates]
+        -- | 取热改项的整数值
         intOf key = case T.strip (Map.findWithDefault "" key updates) of
             "" -> intFromText (effectiveValueOf (aeEffective env) key)
             given -> intFromText given
@@ -803,7 +883,7 @@ applyLiveKeys env updates = do
                 , lvMaxSqlLength = intOf "max-sql-length"
                 }
     writeIORef (aeLive env) after
-    setSessionPolicy
+    setPayloadPolicy
         (aeSessions env)
         (SessionPolicy (fromIntegral (lvSessionIdle after)) (fromIntegral (lvSessionMax after)))
     setRateLimit (aeLimiter env) (lvLoginMaxAttempts after) (fromIntegral (lvLoginWindow after))
@@ -813,55 +893,44 @@ applyLiveKeys env updates = do
 effectiveValueOf :: Map.Map Text Text -> Text -> Text
 effectiveValueOf effectiveValues key = fromMaybe (defaultOf key) (Map.lookup key effectiveValues)
 
--- | 字符串当整数看（坏值回落到 0，不让它把进程带崩）
+-- | 把字符串解析成整数，坏值给 0
 intFromText :: Text -> Int
 intFromText given = fromMaybe 0 (readMaybe (T.unpack (T.strip given)))
 
--- | 表清单（列 / 行数 / 索引 / 列统计）；普通身份只看得到自己有 SELECT 的表，管理员额外看到账号表
+-- | 表清单；管理员额外看到账号表
 tablesH :: AppEnv -> ActionM ()
 tablesH env = do
-    requireDatabase env
-    principal <- requirePrincipal env
-    result <- liftIO (beCatalog (aeBackend env))
+    ws <- requireSession env
+    current <- requireDatabaseName ws
+    result <- liftIO (catalog (wsSession ws))
     case result of
-        Left e -> engineError e
+        Left message -> serverError message
         Right infos -> do
-            readable <- readableTables env principal infos
-            extra <- if aeDatabase env == systemDatabase && principalIsRoot principal
-                then (: []) . systemTableJson . length <$> requireAccounts env
+            let tables = [info | info <- infos, not (isAccountTable (T.pack (tiTable info)))]
+            extra <- if current == systemDatabase && wsAdmin ws
+                then (: []) . systemTableJson . length <$> requireAccounts ws
                 else pure []
-            json (map tableInfoJson readable ++ extra)
-
--- | 普通身份的表清单按 SELECT 权限过滤
-readableTables :: AppEnv -> Principal -> [TableInfo] -> ActionM [TableInfo]
-readableTables env principal infos
-    | principalIsRoot principal = pure infos
-    | otherwise = do
-        result <- liftIO (filterTables (aePrivileges env) principal (aeDatabase env) (map (T.pack . tiTable) infos))
-        case result of
-            Left err -> privilegeError err
-            Right allowed -> pure (filter (\info -> T.pack (tiTable info) `elem` allowed) infos)
+            json (map tableInfoJson tables ++ extra)
 
 -- | 单表结构
 tableH :: AppEnv -> ActionM ()
 tableH env = do
-    requireDatabase env
-    principal <- requirePrincipal env
+    ws <- requireSession env
+    _ <- requireDatabaseName ws
     name <- pathParam "t"
-    account <- accountRoute env name
+    account <- accountRoute ws name
     if account
         then do
-            rootOnly principal
-            accounts <- requireAccounts env
+            adminOnly ws
+            accounts <- requireAccounts ws
             json (systemTableJson (length accounts))
         else
             if not (isIdentifier name)
                 then reply400 "bad_request" "invalid table name"
                 else do
-                    requirePrivilege env [(name, "select")]
-                    result <- liftIO (beCatalog (aeBackend env))
+                    result <- liftIO (catalog (wsSession ws))
                     case result of
-                        Left e -> engineError e
+                        Left message -> serverError message
                         Right infos -> case findTable name infos of
                             Nothing -> reply404
                             Just info -> json (tableInfoJson info)
@@ -869,54 +938,50 @@ tableH env = do
 -- | 分页浏览一张表，支持排序与等值过滤；账号表走内存里的账号行
 rowsH :: AppEnv -> ActionM ()
 rowsH env = do
-    requireDatabase env
+    ws <- requireSession env
+    _ <- requireDatabaseName ws
     name <- pathParam "t"
-    account <- accountRoute env name
+    account <- accountRoute ws name
     if account
-        then baseRowsH env
-        else do
-            requirePrivilege env [(name, "select")]
+        then baseRowsH ws env
+        else
             if not (isIdentifier name)
                 then reply400 "bad_request" "invalid table name"
                 else do
-                    catalogResult <- liftIO (beCatalog (aeBackend env))
-                    case catalogResult of
-                        Left e -> engineError e
-                        Right infos -> case findTable name infos of
-                            Nothing -> reply404
-                            Just info -> do
-                                live <- liftIO (readLive env)
-                                limit <- intParam "limit" (lvPageSize live) 1 (lvMaxPageSize live)
-                                offset <- intParam "offset" 0 0 1000000
-                                rawFilter <- (queryParamMaybe "filter" :: ActionM (Maybe Text))
-                                order <- sortParam info
-                                case (order, parseFilters info rawFilter) of
-                                    (Left err, _) -> reply400 "bad_request" err
-                                    (_, Left err) -> reply400 "bad_request" err
-                                    (Right sortOrder, Right filters) -> case selectRowsSql name sortOrder filters of
-                                        Left err -> reply400 "bad_request" (T.pack err)
-                                        Right sql -> do
-                                            result <- liftIO (beStatement (aeBackend env) sql)
-                                            case result of
-                                                Left e -> engineError e
-                                                Right res -> do
-                                                    let cols = map scName (tiColumns info)
-                                                        page = take limit (drop offset (srRows res))
-                                                        (sortColumn, ascending) = splitSort sortOrder
-                                                    json
-                                                        ( object
-                                                            [ "table" .= tiTable info
-                                                            , "columns" .= cols
-                                                            , "rows" .= map (renderRow cols) page
-                                                            , "total" .= length (srRows res)
-                                                            , "limit" .= limit
-                                                            , "offset" .= offset
-                                                            , "sort" .= maybe A.Null A.String sortColumn
-                                                            , "dir" .= (if ascending then "asc" else "desc" :: Text)
-                                                            , "filters" .= map fst filters
-                                                            ]
-                                                        )
+                    info <- requireTable ws name
+                    live <- liftIO (readLive env)
+                    limit <- intParam "limit" (lvPageSize live) 1 (lvMaxPageSize live)
+                    offset <- intParam "offset" 0 0 1000000
+                    rawFilter <- (queryParamMaybe "filter" :: ActionM (Maybe Text))
+                    order <- sortParam info
+                    case (order, parseFilters info rawFilter) of
+                        (Left err, _) -> reply400 "bad_request" err
+                        (_, Left err) -> reply400 "bad_request" err
+                        (Right sortOrder, Right filters) -> case selectRowsSql name sortOrder filters of
+                            Left err -> reply400 "bad_request" (T.pack err)
+                            Right sql -> do
+                                result <- liftIO (runStatement (wsSession ws) (T.pack sql))
+                                case result of
+                                    Left message -> serverError message
+                                    Right res -> do
+                                        let cols = map T.unpack (qrColumns res)
+                                            page = take limit (drop offset (qrRows res))
+                                            (sortColumn, ascending) = splitSort sortOrder
+                                        json
+                                            ( object
+                                                [ "table" .= tiTable info
+                                                , "columns" .= cols
+                                                , "rows" .= map (map valueJson) page
+                                                , "total" .= qrRowCount res
+                                                , "limit" .= limit
+                                                , "offset" .= offset
+                                                , "sort" .= maybe A.Null A.String sortColumn
+                                                , "dir" .= (if ascending then "asc" else "desc" :: Text)
+                                                , "filters" .= map fst filters
+                                                ]
+                                            )
 
+-- | 等值过滤条件：列名与原值
 data RowFilter = RowFilter Text Text
 
 instance FromJSON RowFilter where
@@ -931,6 +996,7 @@ parseFilters info (Just rawFilter)
         Left _ -> Left "filter must be a JSON array of {column, value}"
         Right specs -> catMaybes <$> mapM toPair specs
   where
+    -- | 一条过滤条件转成列与引擎值
     toPair (RowFilter column rawValue)
         | T.null rawValue = Right Nothing
         | otherwise = do
@@ -938,6 +1004,7 @@ parseFilters info (Just rawFilter)
             ty <- maybe (Left ("unsupported column type for: " <> column)) Right (columnTypeOf (T.pack (scType schema)))
             value <- either (Left . T.pack) Right (coerceValue ty (A.String rawValue))
             pure (Just (column, value))
+    -- | 按列名找表结构里的列
     lookupColumn column = case [c | c <- tiColumns info, T.pack (scName c) == column] of
         (c : _) -> Just c
         [] -> Nothing
@@ -959,6 +1026,7 @@ sortParam info = do
             | column `notElem` map (T.pack . scName) (tiColumns info) -> Left ("unknown column: " <> column)
             | otherwise -> Right (Just (column, dirOf rawDir))
   where
+    -- | dir 参数转排序方向
     dirOf given = case fmap (T.toLower . T.strip) given of
         Just "desc" -> False
         _ -> True
@@ -966,145 +1034,150 @@ sortParam info = do
 -- | 建表：按列结构拼 CREATE TABLE
 createTableH :: AppEnv -> ActionM ()
 createTableH env = do
-    requireDatabase env
-    requireAdmin env
+    ws <- requireSession env
+    _ <- requireDatabaseName ws
+    adminOnly ws
     withJsonObject env $ \o -> case decodeCreateTable o of
         Left err -> reply400 "bad_request" err
         Right spec -> case createTableSql spec of
             Left err -> reply400 "bad_request" (T.pack err)
-            Right sql -> runWrite env sql
+            Right sql -> runWrite ws sql
 
 -- | 删表；账号表不许删
 dropTableH :: AppEnv -> ActionM ()
 dropTableH env = do
-    requireDatabase env
-    requireAdmin env
+    ws <- requireSession env
+    _ <- requireDatabaseName ws
+    adminOnly ws
     name <- pathParam "t"
-    account <- accountRoute env name
+    account <- accountRoute ws name
     if account
         then reply400 "bad_request" "the account table cannot be dropped"
         else case dropTableSql name of
             Left err -> reply400 "bad_request" (T.pack err)
-            Right sql -> runWrite env sql
+            Right sql -> runWrite ws sql
 
--- | 插一行，所有列必须给全；账号表上等于 CREATE USER
+-- | 插一行；账号表上等于 CREATE USER
 insertRowH :: AppEnv -> ActionM ()
 insertRowH env = do
-    requireDatabase env
+    ws <- requireSession env
+    _ <- requireDatabaseName ws
     name <- pathParam "t"
-    account <- accountRoute env name
+    account <- accountRoute ws name
     if account
-        then baseInsertH env
+        then baseInsertH env ws
         else do
-            requirePrivilege env [(name, "insert")]
-            info <- requireTable env name
+            info <- requireTable ws name
             withJsonObject env $ \o -> case valuesField o >>= readRowValues False (tiColumns info) of
                 Left err -> reply400 "bad_request" err
                 Right row -> case insertRowSql name row of
                     Left err -> reply400 "bad_request" (T.pack err)
-                    Right sql -> runWrite env sql
+                    Right sql -> runWrite ws sql
 
--- | 改一行，只改给出来的列；账号表上等于 ALTER USER（只改口令）
+-- | 改一行，只改给出的列
 updateRowH :: AppEnv -> ActionM ()
 updateRowH env = do
-    requireDatabase env
+    ws <- requireSession env
+    _ <- requireDatabaseName ws
     name <- pathParam "t"
-    account <- accountRoute env name
+    account <- accountRoute ws name
     if account
         then do
             target <- pathParam "id"
-            baseUpdateH env target
+            baseUpdateH env ws target
         else do
-            requirePrivilege env [(name, "update")]
             key <- rowIdParam
-            info <- requireTable env name
+            info <- requireTable ws name
             withJsonObject env $ \o -> case valuesField o >>= readRowValues False (tiColumns info) of
                 Left err -> reply400 "bad_request" err
                 Right assigns -> case updateRowSql name key assigns of
                     Left err -> reply400 "bad_request" (T.pack err)
-                    Right sql -> runWrite env sql
+                    Right sql -> runWrite ws sql
 
 -- | 删一行；账号表上等于 DROP USER
 deleteRowH :: AppEnv -> ActionM ()
 deleteRowH env = do
-    requireDatabase env
+    ws <- requireSession env
+    _ <- requireDatabaseName ws
     name <- pathParam "t"
-    account <- accountRoute env name
+    account <- accountRoute ws name
     if account
         then do
             target <- pathParam "id"
-            baseDeleteH env target
+            baseDeleteH env ws target
         else do
-            requirePrivilege env [(name, "delete")]
             key <- rowIdParam
-            _ <- requireTable env name
+            _ <- requireTable ws name
             case deleteRowSql name key of
                 Left err -> reply400 "bad_request" (T.pack err)
-                Right sql -> runWrite env sql
+                Right sql -> runWrite ws sql
 
 -- | 建索引，索引列必须整数且唯一；账号表没有索引可建
 createIndexH :: AppEnv -> ActionM ()
 createIndexH env = do
-    requireDatabase env
-    requireAdmin env
+    ws <- requireSession env
+    _ <- requireDatabaseName ws
+    adminOnly ws
     name <- pathParam "t"
-    account <- accountRoute env name
+    account <- accountRoute ws name
     if account
         then reply400 "bad_request" "the account table has no indexes"
         else do
-            info <- requireTable env name
+            info <- requireTable ws name
             withJsonObject env $ \o -> case textField "column" o of
                 Left err -> reply400 "bad_request" err
                 Right column -> case columnTypeOf (columnTypeText (tiColumns info) column) of
                     Nothing -> reply400 "bad_request" ("unknown column: " <> column)
                     Just _ -> case createIndexSql name column of
                         Left err -> reply400 "bad_request" (T.pack err)
-                        Right sql -> runWrite env sql
+                        Right sql -> runWrite ws sql
 
--- | 删索引（内建索引不放行：存储层也会拒，这里先给一句清楚的话）
+-- | 删索引，内建 id 索引不放行
 dropIndexH :: AppEnv -> ActionM ()
 dropIndexH env = do
-    requireDatabase env
-    requireAdmin env
+    ws <- requireSession env
+    _ <- requireDatabaseName ws
+    adminOnly ws
     name <- pathParam "t"
     column <- pathParam "col"
-    account <- accountRoute env name
+    account <- accountRoute ws name
     if account
         then reply400 "bad_request" "the account table has no indexes"
         else do
-            _ <- requireTable env name
+            _ <- requireTable ws name
             if column == T.pack builtInIndexColumn
                 then reply400 "bad_request" "the built-in id index cannot be dropped"
                 else case dropIndexSql name column of
                     Left err -> reply400 "bad_request" (T.pack err)
-                    Right sql -> runWrite env sql
+                    Right sql -> runWrite ws sql
 
 -- | 删列，内建 id 列不放行；账号表的列是固定的
 dropColumnH :: AppEnv -> ActionM ()
 dropColumnH env = do
-    requireDatabase env
-    requireAdmin env
+    ws <- requireSession env
+    _ <- requireDatabaseName ws
+    adminOnly ws
     name <- pathParam "t"
     column <- pathParam "col"
-    account <- accountRoute env name
+    account <- accountRoute ws name
     if account
         then reply400 "bad_request" "the account table has no columns to drop"
         else do
-            _ <- requireTable env name
+            _ <- requireTable ws name
             if column == T.pack builtInIndexColumn
                 then reply400 "bad_request" "the built-in id column cannot be dropped"
                 else case dropColumnSql name column of
                     Left err -> reply400 "bad_request" (T.pack err)
-                    Right sql -> runWrite env sql
+                    Right sql -> runWrite ws sql
 
 -- | 一键灌演示数据（缺什么补什么，可以反复点）
 demoDataH :: AppEnv -> ActionM ()
 demoDataH env = do
-    requireDatabase env
-    requireAdmin env
-    result <- liftIO (seedDemo (aeBackend env))
+    ws <- requireAdminSession env
+    _ <- requireDatabaseName ws
+    result <- liftIO (seedDemo (wsSession ws))
     case result of
-        Left e -> reply500 (T.pack e)
+        Left message -> serverError message
         Right report ->
             json
                 ( object
@@ -1118,13 +1191,13 @@ demoDataH env = do
 -- | 角色总览：只有管理员能看
 rolesH :: AppEnv -> ActionM ()
 rolesH env = do
-    principal <- requirePrincipal env
-    rootOnly principal
-    result <- liftIO (listRoleViews (aePrivileges env))
+    ws <- requireAdminSession env
+    result <- liftIO (roleViews (wsSession ws))
     case result of
-        Left err -> privilegeError err
+        Left message -> serverError message
         Right views -> json (map roleViewJson views)
 
+-- | 一个角色的线上信息
 roleViewJson :: RoleView -> A.Value
 roleViewJson view =
     object
@@ -1133,6 +1206,7 @@ roleViewJson view =
         , "members" .= roleMembers view
         ]
 
+-- | 一条授权的线上信息
 grantJson :: Grant -> A.Value
 grantJson grant =
     object
@@ -1142,44 +1216,53 @@ grantJson grant =
 
 -- | 建角色
 createRoleH :: AppEnv -> ActionM ()
-createRoleH env = withJsonObject env $ \o -> case textField "name" o of
-    Left err -> reply400 "bad_request" err
-    Right name -> runPrivilegeWrite env (CreateRoleCommand name)
+createRoleH env = do
+    ws <- requireAdminSession env
+    withJsonObject env $ \o -> case textField "name" o of
+        Left err -> reply400 "bad_request" err
+        Right name -> runPrivilegeSql ws (createRoleSql name)
 
 -- | 删角色（连带清掉它的授权与成员）
 dropRoleH :: AppEnv -> ActionM ()
-dropRoleH env = pathParam "name" >>= \name -> runPrivilegeWrite env (DropRoleCommand name)
+dropRoleH env = do
+    ws <- requireAdminSession env
+    name <- pathParam "name"
+    runPrivilegeSql ws (dropRoleSql name)
 
 -- | 给角色加权限
 grantRoleH :: AppEnv -> ActionM ()
 grantRoleH env = do
+    ws <- requireAdminSession env
     role <- pathParam "name"
     withJsonObject env $ \o -> case grantFields o of
         Left err -> reply400 "bad_request" err
-        Right (privileges, objectName) -> runPrivilegeWrite env (GrantPrivilegesCommand privileges objectName role)
+        Right (privileges, objectName) -> runPrivilegeSql ws (grantPrivilegesSql privileges objectName role)
 
 -- | 收角色的权限
 revokeRoleH :: AppEnv -> ActionM ()
 revokeRoleH env = do
+    ws <- requireAdminSession env
     role <- pathParam "name"
     withJsonObject env $ \o -> case grantFields o of
         Left err -> reply400 "bad_request" err
-        Right (privileges, objectName) -> runPrivilegeWrite env (RevokePrivilegesCommand privileges objectName role)
+        Right (privileges, objectName) -> runPrivilegeSql ws (revokePrivilegesSql privileges objectName role)
 
 -- | 把用户加进角色
 addRoleMemberH :: AppEnv -> ActionM ()
 addRoleMemberH env = do
+    ws <- requireAdminSession env
     role <- pathParam "name"
     withJsonObject env $ \o -> case memberFields o of
         Left err -> reply400 "bad_request" err
-        Right users -> runPrivilegeWrite env (GrantRoleCommand role users)
+        Right users -> runPrivilegeSql ws (grantRoleSql role users)
 
 -- | 把用户移出角色
 removeRoleMemberH :: AppEnv -> ActionM ()
 removeRoleMemberH env = do
+    ws <- requireAdminSession env
     role <- pathParam "name"
     user <- pathParam "user"
-    runPrivilegeWrite env (RevokeRoleCommand role [user])
+    runPrivilegeSql ws (revokeRoleSql role [user])
 
 -- | 权限（一条或一串）与对象
 grantFields :: A.Object -> Either Text ([Text], Text)
@@ -1197,40 +1280,27 @@ memberFields o = case (KM.lookup "user" o, KM.lookup "users" o) of
     (_, Just (A.Array xs)) -> mapM stringValue (V.toList xs)
     _ -> Left "missing or non-string field: user"
 
+-- | 只接受字符串的取值
 stringValue :: A.Value -> Either Text Text
 stringValue (A.String value) = Right value
 stringValue _ = Left "values must be strings"
 
--- | 角色命令：只有管理员能跑
-runPrivilegeWrite :: AppEnv -> PrivilegeCommand -> ActionM ()
-runPrivilegeWrite env command = do
-    principal <- requirePrincipal env
-    result <- liftIO (runPrivilegeCommand (aePrivileges env) principal (aeDatabase env) command)
-    case result of
-        Left err -> privilegeError err
-        Right () -> json (object ["ok" .= True])
-
--- | 权限错误与账号错误共用一套状态码映射
-privilegeError :: PrivilegeError -> ActionM a
-privilegeError (PrivilegeError code message) = accountError (AccountError code message)
-
--- | 一键接口的权限门：普通身份必须持有对应的 (表, 权限)
-requirePrivilege :: AppEnv -> [(Text, Text)] -> ActionM ()
-requirePrivilege env needed = do
-    principal <- requirePrincipal env
-    allowed <- liftIO (authorizeTables (aePrivileges env) principal (aeDatabase env) needed)
-    either privilegeError pure allowed
-
--- | 管理员专属操作（建库 / 建表 / 索引 / 列 / 演示数据）
-requireAdmin :: AppEnv -> ActionM ()
-requireAdmin env = requirePrincipal env >>= rootOnly
+-- | 角色与授权命令：拼 SQL 交给 server
+runPrivilegeSql :: WebSession -> Either String String -> ActionM ()
+runPrivilegeSql ws statement = case statement of
+    Left err -> reply400 "bad_request" (T.pack err)
+    Right sql -> do
+        result <- liftIO (runStatement (wsSession ws) (T.pack sql))
+        case result of
+            Left message -> serverError message
+            Right _ -> json (object ["ok" .= True])
 
 -- | 写操作统一回执
-runWrite :: AppEnv -> String -> ActionM ()
-runWrite env sql = do
-    result <- liftIO (beStatement (aeBackend env) sql)
+runWrite :: WebSession -> String -> ActionM ()
+runWrite ws sql = do
+    result <- liftIO (runStatement (wsSession ws) (T.pack sql))
     case result of
-        Left e -> engineError e
+        Left message -> serverError message
         Right _ -> json (object ["ok" .= True])
 
 -- | 只收 JSON 对象，超限 413，非法 400
@@ -1246,15 +1316,15 @@ withJsonObject env k = do
             Right _ -> reply400 "bad_request" "request body must be a JSON object"
 
 -- | 表必须存在，否则 400/404 短路
-requireTable :: AppEnv -> Text -> ActionM TableInfo
-requireTable env name
+requireTable :: WebSession -> Text -> ActionM TableInfo
+requireTable ws name
     | not (isIdentifier name) = do
         reply400 "bad_request" "invalid table name"
         finish
     | otherwise = do
-        result <- liftIO (beCatalog (aeBackend env))
+        result <- liftIO (catalog (wsSession ws))
         case result of
-            Left e -> engineError e
+            Left message -> serverError message
             Right infos -> case findTable name infos of
                 Nothing -> do
                     reply404
@@ -1291,6 +1361,7 @@ settingsUpdates o = do
         then Left "no settings were given"
         else Map.fromList <$> mapM convert (KM.toList values)
   where
+    -- | 一个设置值转成文本
     convert (k, v) = case v of
         A.String s -> Right (K.toText k, s)
         A.Number n -> Right (K.toText k, T.pack (show n))
@@ -1307,6 +1378,7 @@ decodeCreateTable o = do
         _ -> Left "columns must be an array"
     pure (CreateTableSpec name cols)
   where
+    -- | 一列 {name, type} 转成列结构
     decodeColumn (A.Object c) = ColumnSpec <$> textField "name" c <*> textField "type" c
     decodeColumn _ = Left "each column must be {name, type}"
 
@@ -1322,12 +1394,14 @@ readRowValues requireAll cols o = do
                 else Left ("missing columns: " <> T.intercalate ", " (map T.pack missing))
         else pure provided
   where
+    -- | 一个列值按结构转成引擎值
     convert (k, v) = do
         let name = K.toString k
         schema <- maybe (Left ("unknown column: " <> T.pack name)) Right (lookupSchema name)
         ty <- maybe (Left ("unsupported column type for: " <> T.pack name)) Right (columnTypeOf (T.pack (scType schema)))
         value <- either (Left . T.pack) Right (coerceValue ty v)
         pure (name, value)
+    -- | 按列名找表结构里的列
     lookupSchema name = case [c | c <- cols, scName c == name] of
         (c : _) -> Just c
         [] -> Nothing
@@ -1338,11 +1412,11 @@ columnTypeText cols name = case [c | c <- cols, scName c == T.unpack name] of
     (c : _) -> T.pack (scType c)
     [] -> ""
 
--- | 执行任意一条语句：管理语句走各自的服务，其余先过权限门
+-- | 查询接口：校验请求体后执行 SQL
 queryH :: AppEnv -> ActionM ()
 queryH env = do
-    principal <- requirePrincipal env
-    let user = principalName principal
+    ws <- requireSession env
+    let user = wsUser ws
     rawBody <- body
     live <- liftIO (readLive env)
     if BL.length rawBody > fromIntegral (lvBodyLimit live)
@@ -1358,92 +1432,29 @@ queryH env = do
                             then reply413
                             else do
                                 liftIO (aeLog env ("query user=" <> user <> " sql=" <> sql))
-                                case parseStatement (T.unpack sql) of
-                                    Left _ -> executeSql env live sql
-                                    Right stmt -> case accountCommand stmt of
-                                        Just command -> runAccountSql env stmt command
-                                        Nothing -> case privilegeCommand stmt of
-                                            Just command -> runPrivilegeSql env stmt command
-                                            Nothing -> do
-                                                if T.null (aeDatabase env) && statementNeedsDatabase stmt
-                                                    then reply400 "no_database" "no database selected"
-                                                    else do
-                                                        allowed <- liftIO (authorize (aePrivileges env) principal (aeDatabase env) stmt)
-                                                        case allowed of
-                                                            Left err -> privilegeError err
-                                                            Right () -> executeSql env live sql
+                                executeSql ws live sql
 
--- | 把 SQL 交给引擎，结果按控制台口径回执
-executeSql :: AppEnv -> Live -> Text -> ActionM ()
-executeSql env live sql = do
-    result <- liftIO (beStatement (aeBackend env) (T.unpack sql))
+-- | 把 SQL 交给 server，结果按控制台口径回执
+executeSql :: WebSession -> Live -> Text -> ActionM ()
+executeSql ws live sql = do
+    result <- liftIO (runStatement (wsSession ws) sql)
     case result of
-        Left e -> engineError e
+        Left message -> serverError message
         Right res -> do
-            let shown = take (lvMaxRows live) (srRows res)
+            let shown = take (lvMaxRows live) (qrRows res)
             json
                 ( object
-                    [ "columns" .= srColumns res
-                    , "rows" .= map (renderRow (srColumns res)) shown
-                    , "rowCount" .= length (srRows res)
-                    , "truncated" .= (length (srRows res) > lvMaxRows live)
-                    , "database" .= (case parseStatement (T.unpack sql) of
-                        Right (UseDatabase name) -> Just (T.toLower (T.pack name))
-                        _ -> Nothing :: Maybe Text)
+                    [ "columns" .= qrColumns res
+                    , "rows" .= map (map valueJson) shown
+                    , "rowCount" .= qrRowCount res
+                    , "truncated" .= (qrTruncated res || qrRowCount res > lvMaxRows live)
+                    , "database" .= qrDatabase res
                     ]
                 )
 
--- | 执行账号管理语句：只有管理员能跑
-runAccountSql :: AppEnv -> Statement -> AccountCommand -> ActionM ()
-runAccountSql env stmt command = case check [] stmt of
-    Left e -> engineError e
-    Right () -> do
-        principal <- requirePrincipal env
-        result <- liftIO (runAccountCommand (aeAccounts env) principal command)
-        case result of
-            Left err -> accountError err
-            Right () ->
-                json
-                    ( object
-                        [ "columns" .= ([] :: [Text])
-                        , "rows" .= ([] :: [A.Value])
-                        , "rowCount" .= (0 :: Int)
-                        , "truncated" .= False
-                        ]
-                    )
-
--- | 执行角色与授权语句：只有管理员能跑
-runPrivilegeSql :: AppEnv -> Statement -> PrivilegeCommand -> ActionM ()
-runPrivilegeSql env stmt command = case check [] stmt of
-    Left e -> engineError e
-    Right () -> do
-        principal <- requirePrincipal env
-        result <- liftIO (runPrivilegeCommand (aePrivileges env) principal (aeDatabase env) command)
-        case result of
-            Left err -> privilegeError err
-            Right () ->
-                json
-                    ( object
-                        [ "columns" .= ([] :: [Text])
-                        , "rows" .= ([] :: [A.Value])
-                        , "rowCount" .= (0 :: Int)
-                        , "truncated" .= False
-                        ]
-                    )
-
 -- | 拿当前 Session 用户；没有就 401
 requireUser :: AppEnv -> ActionM Text
-requireUser env = principalName <$> requirePrincipal env
-
--- | 当前身份；没有会话就 401
-requirePrincipal :: AppEnv -> ActionM Principal
-requirePrincipal env = do
-    token <- requireToken
-    found <- liftIO (currentPrincipal (aeAccounts env) token)
-    either accountError pure found
-
-requireToken :: ActionM Text
-requireToken = requestSessionToken >>= maybe (accountError (AccountError "unauthorized" "sign in first")) pure
+requireUser env = wsUser <$> requireSession env
 
 -- | 请求里的会话令牌
 requestSessionToken :: ActionM (Maybe Text)
@@ -1457,6 +1468,7 @@ parseCookieHeader name headerValue = case [v | part <- T.splitOn ";" headerValue
     (v : _) -> Just v
     [] -> Nothing
   where
+    -- | 从一段 Cookie 里取指定键的值
     valueOf key part =
         let (k, rest) = T.breakOn "=" part
             value = T.strip (T.drop 1 rest)
@@ -1499,7 +1511,7 @@ valueJson (VFloat d) = A.Number (fromFloatDigits d)
 valueJson (VStr s) = A.String (T.pack s)
 valueJson (VBool b) = A.Bool b
 
--- | 一张表的线上信息：列、行数、索引与统计（普通表 kind = table）
+-- | 一张表的线上信息：列、行数、索引与统计
 tableInfoJson :: TableInfo -> A.Value
 tableInfoJson info =
     object
@@ -1510,6 +1522,7 @@ tableInfoJson info =
         , "columns" .= map columnJson (tiColumns info)
         ]
   where
+    -- | 一列转成线上 JSON
     columnJson sc =
         object
             [ "name" .= scName sc
@@ -1570,22 +1583,15 @@ reply500 message = do
     status status500
     json (apiErrorJson "internal" message)
 
--- | 引擎报的错映射成状态码：没有这张表是 404，其余是 400
-engineError :: String -> ActionM a
-engineError err = do
-    let message = T.pack err
-        missing = "unknown table" `T.isInfixOf` message
-    status (if missing then status404 else status400)
-    json (apiErrorJson (if missing then "not_found" else "query_error") message)
-    finish
-
 -- | 在字典里按名字找表
 findTable :: Text -> [TableInfo] -> Maybe TableInfo
 findTable name = go
   where
+    -- | 顺序找表
     go [] = Nothing
     go (i : is) = if tiTable i == T.unpack name then Just i else go is
 
+-- | 登录请求体
 data LoginRequest = LoginRequest
     { lrUser :: Text
     , lrPassword :: Text
@@ -1595,6 +1601,7 @@ instance FromJSON LoginRequest where
     parseJSON = withObject "LoginRequest" $ \o ->
         LoginRequest <$> o .: "user" <*> o .: "password"
 
+-- | 查询请求体
 data QueryRequest = QueryRequest
     { qrSql :: Text
     }
diff --git a/chusql-web/src/ChuSQL/Web/Demo.hs b/chusql-web/src/ChuSQL/Web/Demo.hs
index 2243cd3..1965c8f 100644
--- a/chusql-web/src/ChuSQL/Web/Demo.hs
+++ b/chusql-web/src/ChuSQL/Web/Demo.hs
@@ -10,16 +10,17 @@ module ChuSQL.Web.Demo (
     seedDemo,
 ) where
 
-import ChuSQL.Model (Value (..))
-import ChuSQL.Storage.IPC (TableInfo (..))
-import ChuSQL.Web.Actions (
+import ChuSQL.Core.Model (Value (..))
+import ChuSQL.Core.Protocol (TableInfo (..))
+import ChuSQL.Interface.Actions (
     ColumnSpec (..),
     CreateTableSpec (..),
     createIndexSql,
     createTableSql,
     insertRowsSql,
  )
-import ChuSQL.Web.Backend (Backend (..))
+import ChuSQL.Interface.Session (Session, catalog, runStatement)
+import Data.Text (Text)
 import qualified Data.Text as T
 
 -- 演示数据：三张表加一个二级索引，语句与界面走同一套拼 SQL 的代码。
@@ -75,12 +76,12 @@ data SeedReport = SeedReport
     }
     deriving (Show, Eq)
 
--- | 缺什么补什么，可反复点不重复灌
-seedDemo :: Backend -> IO (Either String SeedReport)
-seedDemo backend = do
-    catalog <- beCatalog backend
-    case catalog of
-        Left e -> pure (Left e)
+-- | 按需灌演示数据：缺表补表、缺索引补索引
+seedDemo :: Session -> IO (Either Text SeedReport)
+seedDemo session = do
+    catalogResult <- catalog session
+    case catalogResult of
+        Left message -> pure (Left message)
         Right infos -> do
             let existingTables = map tiTable infos
                 missing = [spec | spec <- demoTableSpecs, T.unpack (ctsTable spec) `notElem` existingTables]
@@ -93,34 +94,33 @@ seedDemo backend = do
                     ]
             created <- runAll (map createTableSql missing)
             case created of
-                Left e -> pure (Left e)
+                Left message -> pure (Left message)
                 Right () -> do
                     rowsDone <- runAll [insertRowsSql t rs | (t, rs) <- demoRows, t `elem` missingNames]
                     case rowsDone of
-                        Left e -> pure (Left e)
+                        Left message -> pure (Left message)
                         Right () -> do
-                            indexes <-
-                                runAll [createIndexSql t c | (t, c) <- wantedIndexes]
-                            pure $
-                                fmap
-                                    (const (SeedReport (map T.unpack missingNames) skipped (map (T.unpack . snd) wantedIndexes)))
-                                    indexes
+                            indexes <- runAll [createIndexSql t c | (t, c) <- wantedIndexes]
+                            pure $ fmap (const (SeedReport (map T.unpack missingNames) skipped (map (T.unpack . snd) wantedIndexes))) indexes
   where
-    runAll :: [Either String String] -> IO (Either String ())
+    -- | 顺序跑完一串语句，首错即停
+    runAll :: [Either String String] -> IO (Either Text ())
     runAll [] = pure (Right ())
     runAll (sql : rest) = case sql of
-        Left e -> pure (Left e)
+        Left e -> pure (Left (T.pack e))
         Right statement -> do
-            result <- beStatement backend statement
+            result <- runStatement session (T.pack statement)
             case result of
-                Left e -> pure (Left e)
+                Left message -> pure (Left message)
                 Right _ -> runAll rest
 
-    indexMissing :: [TableInfo] -> T.Text -> T.Text -> Bool
+    -- | 目录里这张表缺不缺这个索引
+    indexMissing :: [TableInfo] -> Text -> Text -> Bool
     indexMissing infos t c = case lookup (T.unpack t) [(tiTable i, tiIndexes i) | i <- infos] of
         Nothing -> True
         Just cols -> T.unpack c `notElem` cols
 
+-- | 演示用户数据
 userRecords :: [(String, Int)]
 userRecords =
     [ ("Alice", 24)
@@ -135,6 +135,7 @@ userRecords =
     , ("Judy", 29)
     ]
 
+-- | 演示订单数据
 orderRecords :: [(Int, String, Int)]
 orderRecords =
     [ (1, "Laptop", 1299)
@@ -151,6 +152,7 @@ orderRecords =
     , (9, "Lamp", 39)
     ]
 
+-- | 演示产品数据
 productRecords :: [(String, Int, Int)]
 productRecords =
     [ ("Laptop", 1001, 1299)
diff --git a/chusql-web/src/ChuSQL/Web/Static.hs b/chusql-web/src/ChuSQL/Web/Static.hs
index 3d672af..aa28ab5 100644
--- a/chusql-web/src/ChuSQL/Web/Static.hs
+++ b/chusql-web/src/ChuSQL/Web/Static.hs
@@ -23,7 +23,7 @@ maxNameLength = 128
 allowedExtensions :: [String]
 allowedExtensions = [".html", ".css", ".js", ".svg", ".png", ".ico", ".ttf", ".woff2"]
 
--- | 把请求里的文件名变成安全的相对路径；不合法给 Nothing
+-- | 把请求文件名校验成安全相对路径，不合法给 Nothing
 safeRelative :: Text -> Maybe FilePath
 safeRelative t
     | T.null t = Nothing
@@ -33,6 +33,7 @@ safeRelative t
     | map toLower (takeExtension (T.unpack t)) `notElem` allowedExtensions = Nothing
     | otherwise = Just (T.unpack t)
   where
+    -- | 文件名里是否出现不允许的字符
     badChar c = not (isAsciiLower c || isAsciiUpper c || isDigit c || c `elem` ("._-" :: String))
 
 -- | 读一个静态文件；不存在（或是目录）给 Nothing
diff --git a/chusql-web/src/ChuSQL/Web/StorageProcess.hs b/chusql-web/src/ChuSQL/Web/StorageProcess.hs
deleted file mode 100644
index 9f0ad4e..0000000
--- a/chusql-web/src/ChuSQL/Web/StorageProcess.hs
+++ /dev/null
@@ -1,113 +0,0 @@
-{-# LANGUAGE OverloadedStrings #-}
-
-module ChuSQL.Web.StorageProcess (
-    StorageProcess (..),
-    findStorageServer,
-    startStorageProcess,
-    startStorageProcessAt,
-    platformBinaryName,
-    storageChildArgs,
-    stopStorageProcess,
-    waitForStorage,
-) where
-
-import ChuSQL.Storage.IPC (Request (..), Response (..), closeConnection, sendRequest, setPipeName)
-import ChuSQL.Web.Config (loadWebConfigAt, resolvePipeName)
-import Control.Concurrent (threadDelay)
-import Control.Exception (SomeException, try)
-import Control.Monad (filterM)
-import System.Directory (doesFileExist)
-import System.Exit (ExitCode)
-import System.FilePath ((</>))
-import System.Info (os)
-import System.IO (Handle)
-import System.Process (
-    CreateProcess (..),
-    ProcessHandle,
-    StdStream (..),
-    createProcess,
-    proc,
-    terminateProcess,
-    waitForProcess,
- )
-
--- 拉起并管理 Rust 存储进程，起来后等管道应答 ping 再继续。
--- 调参、管名与数据目录都在全局 chusql.toml 里，孩子自己读；这里只负责起进程、
--- 用 --config 把「读哪份配置文件」告诉它，并等就绪。
-
-data StorageProcess = StorageProcess
-    { spProcess :: ProcessHandle
-    , spPipe :: String
-    }
-
--- | 可执行文件名跟平台走：Windows 带 .exe，其它平台不带。同一个 target 目录里可能
--- 同时躺着一份别处交叉编译出来的 .exe（Windows PE），在 Linux 上误选它只会拿到
--- config file not found（Windows 进程看不到 /tmp/... 这样的路径）。目标平台当参数传，
--- 两个分支都能被测试直接钉住。
-platformBinaryName :: String -> String -> FilePath
-platformBinaryName targetOs stem = if targetOs == "mingw32" then stem ++ ".exe" else stem
-
--- | 找存储进程，没有就给路径提示
-findStorageServer :: Maybe FilePath -> IO (Either String FilePath)
-findStorageServer (Just p) = do
-    ok <- doesFileExist p
-    pure (if ok then Right p else Left ("storage server not found: " ++ p))
-findStorageServer Nothing = do
-    let dirs =
-            [ "chusql-storage/target"
-            , "../chusql-storage/target"
-            , "../../chusql-storage/target"
-            , "target"
-            ]
-        modes = ["release", "debug"]
-        exes = [platformBinaryName os "chusql-storage"]
-        candidates = [d </> m </> e | d <- dirs, m <- modes, e <- exes]
-    found <- filterM doesFileExist candidates
-    pure $ case found of
-        (p : _) -> Right p
-        [] -> Left "no Rust storage server found; run `cargo build --release` in chusql-storage, or pass --storage <path>"
-
--- | 按配置文件里的管名起存储进程
-startStorageProcess :: FilePath -> FilePath -> IO (Either String StorageProcess)
-startStorageProcess bin configPath = do
-    cfg <- loadWebConfigAt configPath
-    startStorageProcessAt bin (resolvePipeName cfg) configPath
-
--- | 给存储子进程的参数：配置文件位置是固定的，唯一的显式覆盖就是写进 --config
-storageChildArgs :: FilePath -> [String]
-storageChildArgs configPath = ["--config", configPath]
-
--- | 用给定的管名起存储进程，并把本进程的端点也指到它；环境原样继承
-startStorageProcessAt :: FilePath -> String -> FilePath -> IO (Either String StorageProcess)
-startStorageProcessAt bin pipe configPath = do
-    let child = (proc bin (storageChildArgs configPath)){std_out = NoStream, std_err = Inherit}
-    started <-
-        try (createProcess child) ::
-            IO (Either SomeException (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle))
-    case started of
-        Left e -> pure (Left ("failed to start the storage process: " ++ show e))
-        Right (_, _, _, ph) -> do
-            setPipeName pipe
-            ready <- waitForStorage (200 :: Int)
-            if ready
-                then pure (Right (StorageProcess ph pipe))
-                else do
-                    _ <- try (terminateProcess ph) :: IO (Either SomeException ())
-                    pure (Left "storage process did not become ready within 5 seconds (no ping reply on the pipe)")
-
--- | 停掉存储进程，保留数据目录
-stopStorageProcess :: StorageProcess -> IO ()
-stopStorageProcess sp = do
-    closeConnection
-    _ <- try (terminateProcess (spProcess sp)) :: IO (Either SomeException ())
-    _ <- try (waitForProcess (spProcess sp)) :: IO (Either SomeException ExitCode)
-    pure ()
-
--- | 轮询 ping 直到对面应答
-waitForStorage :: Int -> IO Bool
-waitForStorage 0 = pure False
-waitForStorage n = do
-    r <- try (sendRequest ReqPing) :: IO (Either SomeException Response)
-    case r of
-        Right RespPong -> pure True
-        _ -> threadDelay 25000 >> waitForStorage (n - 1)
diff --git a/chusql-web/src/ChuSQL/Web/UiSettings.hs b/chusql-web/src/ChuSQL/Web/UISettings.hs
similarity index 96%
rename from chusql-web/src/ChuSQL/Web/UiSettings.hs
rename to chusql-web/src/ChuSQL/Web/UISettings.hs
index 3f92165..047f85c 100644
--- a/chusql-web/src/ChuSQL/Web/UiSettings.hs
+++ b/chusql-web/src/ChuSQL/Web/UISettings.hs
@@ -42,15 +42,18 @@ resolveUISettingsFile = do
             ready <- firstExistingDir uiSettingsFileCandidates
             pure (maybe firstCandidate id ready)
   where
+    -- | 首选候选路径
     firstCandidate = case uiSettingsFileCandidates of
         (p : _) -> p
         [] -> "chusql.ui.settings.json"
 
+    -- | 第一个存在的候选文件
     firstExistingFile [] = pure Nothing
     firstExistingFile (p : ps) = do
         ok <- doesFileExist p
         if ok then pure (Just p) else firstExistingFile ps
 
+    -- | 目录已存在的第一个候选
     firstExistingDir [] = pure Nothing
     firstExistingDir (p : ps) = do
         let dir = takeDirectory p
@@ -61,6 +64,7 @@ resolveUISettingsFile = do
 validateUISettings :: A.Value -> Either String (Map.Map Text A.Value)
 validateUISettings (A.Object o) = Map.fromList <$> mapM checkField (KM.toList o)
   where
+    -- | 校验一个字段
     checkField (rawKey, value) =
         let key = K.toText rawKey
          in case key of
@@ -80,16 +84,20 @@ validateUISettings (A.Object o) = Map.fromList <$> mapM checkField (KM.toList o)
                 "minimap" -> pair key <$> boolValue key value
                 _ -> Left ("unknown setting: " ++ T.unpack key)
 
+    -- | 把键和值配成一对
     pair key value = (key, value)
 
 validateUISettings _ = Left "settings must be a JSON object"
 
+-- | 字体链最多几项
 fontChainMax :: Int
 fontChainMax = 10
 
+-- | 单个字体名最长多少字
 fontNameMax :: Int
 fontNameMax = 64
 
+-- | 空值占位文本最长多少字
 nullTextMax :: Int
 nullTextMax = 64
 
diff --git a/chusql-web/stack.yaml b/chusql-web/stack.yaml
index 4048110..8e0303f 100644
--- a/chusql-web/stack.yaml
+++ b/chusql-web/stack.yaml
@@ -1,5 +1,11 @@
 resolver: lts-24.59
 
+extra-lib-dirs:
+    - ../chusql-core/storage/target/release
+
 packages:
     - .
-    - ../chusql-engine
+    - ../chusql-core/engine
+    - ../chusql-server
+    - ../chusql-core/model
+    - ../chusql-interface
diff --git a/chusql-web/static/api.js b/chusql-web/static/api.js
index 8766bbf..2a801c5 100644
--- a/chusql-web/static/api.js
+++ b/chusql-web/static/api.js
@@ -1,12 +1,14 @@
 // REST 数据源：与 chusql-web 的 /api/* 一一对应。
-// 所有请求带 X-ChuSQL-Database 头（服务端不保存 USE 状态）；401 时广播登录事件。
+// 请求都带 X-ChuSQL-Database 头；401 时广播登录事件。
 
 export const AUTH_EVENT = 'chusql-auth-required';
 
+// 是否是普通对象。
 function isObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+// 发一次请求并处理错误。
 async function request(url, init, database) {
   const headers = new Headers(init && init.headers ? init.headers : undefined);
   if (database) headers.set('X-ChuSQL-Database', database);
@@ -34,6 +36,7 @@ async function request(url, init, database) {
   return body;
 }
 
+// 组装 JSON 请求参数。
 function jsonInit(method, body) {
   return {
     method,
@@ -44,12 +47,14 @@ function jsonInit(method, body) {
 
 const identifier = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
 
+// 校验数据库名格式。
 function checkDatabaseName(name) {
   if (!identifier.test(String(name))) throw new Error('数据库名只能是字母、数字与下划线，且以字母或下划线开头。');
 }
 
 // ---------------------------------------------------------------- 会话
 
+// 读取当前会话。
 export async function currentSession() {
   const body = await request('/api/session');
   if (!isObject(body) || typeof body.user !== 'string') throw new Error('服务器返回的会话信息无法识别。');
@@ -60,16 +65,19 @@ export async function currentSession() {
   };
 }
 
+// 提交登录。
 export async function login(user, password) {
   await request('/api/login', jsonInit('POST', { user, password }));
 }
 
+// 退出登录。
 export async function logout() {
   await request('/api/logout', jsonInit('POST', {}));
 }
 
 // ---------------------------------------------------------------- 数据库
 
+// 列出数据库。
 export async function listDatabases() {
   const body = await request('/api/databases');
   if (!Array.isArray(body) || !body.every((name) => typeof name === 'string')) {
@@ -78,16 +86,18 @@ export async function listDatabases() {
   return body;
 }
 
+// 新建数据库。
 export async function createDatabase(name, database) {
   checkDatabaseName(name);
   await request('/api/databases', jsonInit('POST', { name }), database);
 }
 
+// 删除数据库。
 export async function dropDatabase(name, database) {
   await request(`/api/databases/${encodeURIComponent(name)}`, jsonInit('DELETE'), database);
 }
 
-// 切换当前库：走一条 USE 语句，服务端在响应里回带新的库名。
+// 切换当前库（发 USE 语句）。
 export async function useDatabase(name, database) {
   checkDatabaseName(name);
   return query(`USE ${name}`, database);
@@ -95,12 +105,14 @@ export async function useDatabase(name, database) {
 
 // ---------------------------------------------------------------- 表结构
 
+// 取类型基名（去掉参数）。
 function columnKind(type) {
   return String(type).split('(')[0].trim().toLowerCase();
 }
 
 const knownTypes = ['int', 'bigint', 'smallint', 'str', 'text', 'varchar', 'char', 'float', 'double', 'decimal', 'numeric', 'bool', 'date', 'timestamp', 'blob'];
 
+// 校验并规整列描述。
 function asColumns(value) {
   if (!Array.isArray(value)) throw new Error('服务器返回的列清单无法识别。');
   return value.map((entry) => {
@@ -112,6 +124,7 @@ function asColumns(value) {
   });
 }
 
+// 校验并规整表描述。
 function asTable(value) {
   if (!isObject(value) || typeof value.table !== 'string' || typeof value.rowCount !== 'number') {
     throw new Error('服务器返回的表描述无法识别。');
@@ -125,38 +138,46 @@ function asTable(value) {
   };
 }
 
+// 列出表。
 export async function listTables(database) {
   const body = await request('/api/tables', undefined, database);
   if (!Array.isArray(body)) throw new Error('服务器返回的表清单无法识别。');
   return body.map(asTable);
 }
 
+// 取单表结构。
 export async function getTable(database, table) {
   return asTable(await request(`/api/tables/${encodeURIComponent(table)}`, undefined, database));
 }
 
+// 新建表。
 export async function createTable(database, name, columns) {
   await request('/api/tables', jsonInit('POST', { name, columns }), database);
 }
 
+// 删除表。
 export async function dropTable(database, table) {
   await request(`/api/tables/${encodeURIComponent(table)}`, jsonInit('DELETE'), database);
 }
 
+// 建索引。
 export async function createIndex(database, table, column) {
   await request(`/api/tables/${encodeURIComponent(table)}/indexes`, jsonInit('POST', { column }), database);
 }
 
+// 删索引。
 export async function dropIndex(database, table, column) {
   await request(`/api/tables/${encodeURIComponent(table)}/indexes/${encodeURIComponent(column)}`, jsonInit('DELETE'), database);
 }
 
+// 删列。
 export async function dropColumn(database, table, column) {
   await request(`/api/tables/${encodeURIComponent(table)}/columns/${encodeURIComponent(column)}`, jsonInit('DELETE'), database);
 }
 
 // ---------------------------------------------------------------- 行
 
+// 分页取表数据。
 export async function fetchRows({ database, table, limit, offset, sort, dir, filters }) {
   const params = new URLSearchParams({ limit: String(limit), offset: String(offset) });
   if (sort) {
@@ -179,14 +200,17 @@ export async function fetchRows({ database, table, limit, offset, sort, dir, fil
   return { columns, rows, total: body.total };
 }
 
+// 插入一行。
 export async function insertRow(database, table, values) {
   await request(`/api/tables/${encodeURIComponent(table)}/rows`, jsonInit('POST', { values }), database);
 }
 
+// 更新一行。
 export async function updateRow(database, table, id, values) {
   await request(`/api/tables/${encodeURIComponent(table)}/rows/${encodeURIComponent(id)}`, jsonInit('PATCH', { values }), database);
 }
 
+// 删除一行。
 export async function deleteRow(database, table, id) {
   await request(`/api/tables/${encodeURIComponent(table)}/rows/${encodeURIComponent(id)}`, jsonInit('DELETE'), database);
 }
@@ -209,6 +233,7 @@ export async function commitChanges(database, changes) {
 
 // ---------------------------------------------------------------- 查询
 
+// 执行 SQL 并规整结果。
 export async function query(sql, database) {
   const started = performance.now();
   try {
@@ -231,27 +256,32 @@ export async function query(sql, database) {
   }
 }
 
+// 灌演示数据。
 export async function seedDemoData(database) {
   return request('/api/demo-data', jsonInit('POST', {}), database);
 }
 
 // ---------------------------------------------------------------- 设置
 
+// 读取服务器设置。
 export async function loadServerSettings() {
   const body = await request('/api/settings');
   if (!isObject(body) || !Array.isArray(body.items)) throw new Error('服务器返回的设置清单无法识别。');
   return body;
 }
 
+// 保存服务器设置。
 export async function saveServerSettings(values) {
   const body = await request('/api/settings', jsonInit('PUT', { values }));
   return isObject(body) ? body : { ok: true };
 }
 
+// 读取 IDE 设置。
 export async function loadUiSettings() {
   return request('/api/ui-settings');
 }
 
+// 保存 IDE 设置。
 export async function saveUiSettings(settings) {
   await request('/api/ui-settings', jsonInit('PUT', settings));
 }
diff --git a/chusql-web/static/app.js b/chusql-web/static/app.js
index 0d94d85..0b0e47e 100644
--- a/chusql-web/static/app.js
+++ b/chusql-web/static/app.js
@@ -1,6 +1,3 @@
-// ChuSQL Web IDE：纯 HTML + CSS + JS，无 React、无打包器、无 Node 依赖。
-// 结构：全局状态 → 页面骨架 → 各区域渲染 → 事件代理 → 会话/数据/变更动作。
-
 import * as api from './api.js';
 import { AUTH_EVENT } from './api.js';
 import {
@@ -35,6 +32,8 @@ import {
   typeLabel,
 } from './core.js';
 
+// ChuSQL Web IDE 主逻辑：状态、渲染、事件代理与会话/数据/变更动作。
+
 // ---------------------------------------------------------------- 状态
 
 const state = {
@@ -63,30 +62,36 @@ const root = document.getElementById('root');
 
 // ---------------------------------------------------------------- 小工具
 
+// 按 id 取 DOM 元素。
 function region(id) {
   return document.getElementById(id);
 }
 
+// 当前时间（时分秒）。
 function now() {
   return new Date().toLocaleTimeString('zh-CN', { hour12: false });
 }
 
+// 记一条消息并刷新下方面板。
 function log(level, text) {
   state.messages.push({ level, text, time: now() });
   if (state.messages.length > 200) state.messages.shift();
   renderBottom();
 }
 
+// 设置状态栏文案。
 function setStatus(text) {
   state.status = text;
   const el = region('status-message');
   if (el) el.textContent = text;
 }
 
+// 取错误的文字描述。
 function describe(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// 记录错误并写到状态栏。
 function fail(error) {
   const message = describe(error);
   log('error', message);
@@ -94,17 +99,20 @@ function fail(error) {
   return message;
 }
 
+// 生成下一个标签 id。
 function nextTabId(prefix) {
   state.tabSeq += 1;
   return `${prefix}-${state.tabSeq}`;
 }
 
+// 当前激活的标签。
 function activeTab() {
   return state.tabs.find((tab) => tab.id === state.activeId);
 }
 
 // ---------------------------------------------------------------- 登录页
 
+// 渲染登录页。
 function renderLogin(message, level) {
   state.view = 'login';
   root.innerHTML = `
@@ -122,6 +130,7 @@ function renderLogin(message, level) {
 
 // ---------------------------------------------------------------- 页面骨架
 
+// 渲染工作台骨架与对话框。
 function renderShell() {
   state.view = 'workbench';
   root.innerHTML = `
@@ -200,7 +209,7 @@ function renderShell() {
   applyLayout();
 }
 
-// 侧栏宽度与下方面板高度用 CSSOM 写，避免 CSP 拦掉内联 style 属性。
+// 应用侧栏宽度与下方面板高度。
 function applyLayout() {
   const workbench = region('workbench');
   if (!workbench) return;
@@ -210,6 +219,7 @@ function applyLayout() {
 
 // ---------------------------------------------------------------- 账号区
 
+// 渲染右上角账号区。
 function renderAccount() {
   const el = region('account');
   if (!el) return;
@@ -225,6 +235,7 @@ function renderAccount() {
 
 // ---------------------------------------------------------------- 侧栏
 
+// 渲染资源管理器侧栏。
 function renderSidebar() {
   const el = region('sidebar');
   if (!el) return;
@@ -298,6 +309,7 @@ function renderSidebar() {
 
 // ---------------------------------------------------------------- 标签栏
 
+// 渲染标签栏并刷新内容区。
 function renderTabs() {
   const el = region('editor');
   if (!el) return;
@@ -314,6 +326,7 @@ function renderTabs() {
 
 // ---------------------------------------------------------------- 编辑器区
 
+// 渲染当前标签的内容。
 function renderEditor() {
   const el = region('tab-content');
   if (!el) return;
@@ -332,11 +345,13 @@ function renderEditor() {
 
 // ---- 表格标签
 
+// 单元格显示内容的 HTML。
 function cellContent(value, nullText) {
   if (value === null || value === undefined) return `<span class="null-value">${escapeHtml(nullText)}</span>`;
   return escapeHtml(cellText(value, nullText));
 }
 
+// 渲染表格标签（工具栏、表头、数据行）。
 function renderTableTab(el, tab) {
   const data = tab.data;
   if (!data) {
@@ -429,13 +444,16 @@ function renderTableTab(el, tab) {
 
 // ---- SQL 标签
 
+// 生成行号文本。
 function lineNumbers(sql) {
   const count = String(sql ?? '').split('\n').length;
   return Array.from({ length: count }, (_, index) => index + 1).join('\n');
 }
 
+// 渲染 SQL 控制台标签。
 function renderSqlTab(el, tab) {
   const result = tab.result;
+  // 结果区 HTML。
   const resultHtml = (() => {
     if (!result) return '<p class="muted">按 Ctrl+Enter 运行，或点上面的"运行"。</p>';
     if (result.type === 'error') return `<p class="alert alert-error">${escapeHtml(result.message ?? '执行失败')}</p>`;
@@ -473,11 +491,13 @@ function renderSqlTab(el, tab) {
   const minimap = region('sql-minimap');
   if (!textarea) return;
 
+  // 刷新高亮层与行号。
   const refreshLayers = () => {
     if (highlight) highlight.innerHTML = highlightHtml(tab.sql);
     if (gutter) gutter.textContent = lineNumbers(tab.sql);
     sync();
   };
+  // 同步滚动位置与缩略图。
   const sync = () => {
     if (highlight) {
       highlight.scrollTop = textarea.scrollTop;
@@ -496,11 +516,14 @@ function renderSqlTab(el, tab) {
     }
   };
 
+  // 输入时更新 SQL 并刷新高亮。
   textarea.addEventListener('input', () => {
     tab.sql = textarea.value;
     refreshLayers();
   });
+  // 滚动时同步各层。
   textarea.addEventListener('scroll', sync);
+  // Tab 缩进，Ctrl+Enter 运行。
   textarea.addEventListener('keydown', (event) => {
     if (event.key === 'Tab') {
       event.preventDefault();
@@ -523,17 +546,22 @@ function renderSqlTab(el, tab) {
 
 // ---- 设置标签
 
+// 渲染设置标签页。
 function renderSettingsTab(el) {
   const settings = state.settings;
+  // 字体链输入框。
   const fontField = (key) => `
     <label class="field"><span>${escapeHtml(settingLabels[key])}</span>
       <input data-setting="fonts" data-key="${key}" value="${escapeHtml(fontsToText(settings[key]))}" placeholder="字体名用逗号分隔" /></label>`;
+  // 数值输入框。
   const numberField = (key) => `
     <label class="field"><span>${escapeHtml(settingLabels[key])}</span>
       <input type="number" data-setting="number" data-key="${key}" value="${settings[key]}" /></label>`;
+  // 布尔开关。
   const boolField = (key) => `
     <label class="toggle"><input type="checkbox" data-setting="boolean" data-key="${key}"${settings[key] ? ' checked' : ''} /><span>${escapeHtml(settingLabels[key])}</span></label>`;
 
+  // 服务器设置分组表单。
   const serverHtml = (() => {
     const server = state.serverSettings;
     if (!server) return '<p class="muted">正在读取服务器设置…</p>';
@@ -595,6 +623,7 @@ function renderSettingsTab(el) {
 
 // ---------------------------------------------------------------- 下方面板
 
+// 渲染下方面板（变更/消息）。
 function renderBottom() {
   const el = region('bottom');
   if (!el) return;
@@ -635,6 +664,7 @@ function renderBottom() {
 
 // ---------------------------------------------------------------- 数据加载
 
+// 读取并缓存当前会话。
 async function refreshSession() {
   try {
     state.session = await api.currentSession();
@@ -645,6 +675,7 @@ async function refreshSession() {
   }
 }
 
+// 加载数据库列表与当前库的表。
 async function loadWorkspace() {
   try {
     state.databases = await api.listDatabases();
@@ -661,6 +692,7 @@ async function loadWorkspace() {
   }
 }
 
+// 切换当前数据库。
 async function switchDatabase(name) {
   if (name === state.database) return;
   if (changeCount(state.changes) > 0) {
@@ -680,6 +712,7 @@ async function switchDatabase(name) {
   renderEditor();
 }
 
+// 打开表标签并加载数据。
 async function openTable(database, name) {
   const opened = openTableTab(state.tabs, database, name, nextTabId('table'));
   state.tabs = opened.tabs;
@@ -697,6 +730,7 @@ async function openTable(database, name) {
   await loadTableData(tab);
 }
 
+// 加载表标签的一页数据。
 async function loadTableData(tab) {
   const data = tab.data;
   data.loading = true;
@@ -736,6 +770,7 @@ async function loadTableData(tab) {
   }
 }
 
+// 重新加载所有表标签。
 async function reloadOpenTables() {
   for (const tab of state.tabs) {
     if (tab.kind === 'table') await loadTableData(tab);
@@ -744,6 +779,7 @@ async function reloadOpenTables() {
 
 // ---------------------------------------------------------------- 变更动作
 
+// 撤下某行的全部变更。
 function unstageRow(table, pk) {
   const prefix = `${table}:${JSON.stringify(pk)}:`;
   for (const key of [...state.changes.updates.keys()]) {
@@ -752,12 +788,14 @@ function unstageRow(table, pk) {
   state.changes.deletes.delete(deleteKey(table, pk));
 }
 
+// 暂存单元格修改。
 function stageUpdate(table, database, pk, column, oldValue, newValue) {
   if (oldValue === newValue) state.changes.updates.delete(changeKey(table, pk, column));
   else state.changes.updates.set(changeKey(table, pk, column), { table, database, pk, column, oldValue, newValue });
   afterChange();
 }
 
+// 暂存新增行。
 function stageInsert(table, database, values) {
   state.insertSeq += 1;
   const tempId = `new-${state.insertSeq}`;
@@ -765,18 +803,21 @@ function stageInsert(table, database, values) {
   afterChange();
 }
 
+// 暂存删除行。
 function stageDelete(table, database, pk, row) {
   unstageRow(table, pk);
   state.changes.deletes.set(deleteKey(table, pk), { table, database, pk, row });
   afterChange();
 }
 
+// 变更后重绘相关区域。
 function afterChange() {
   renderSidebar();
   renderEditor();
   renderBottom();
 }
 
+// 撤下一条暂存变更。
 function removeStaged(key) {
   if (state.changes.updates.has(key)) state.changes.updates.delete(key);
   else if (state.changes.inserts.has(key)) state.changes.inserts.delete(key);
@@ -784,6 +825,7 @@ function removeStaged(key) {
   afterChange();
 }
 
+// 撤销全部暂存变更。
 function rollbackAll() {
   state.changes = createEmptyChangeSet();
   for (const tab of state.tabs) if (tab.selected) tab.selected.clear();
@@ -791,6 +833,7 @@ function rollbackAll() {
   afterChange();
 }
 
+// 提交全部暂存变更。
 async function commitAll() {
   const payload = toCommitPayload(state.changes);
   if (!payload.length) {
@@ -832,6 +875,7 @@ async function commitAll() {
 
 // ---------------------------------------------------------------- SQL 运行
 
+// 运行 SQL 并展示结果。
 async function runSql(tab) {
   const sql = String(tab.sql ?? '').trim();
   if (!sql) return;
@@ -862,6 +906,7 @@ async function runSql(tab) {
 
 // ---------------------------------------------------------------- 标签动作
 
+// 激活指定标签。
 function activateTab(id) {
   state.activeId = id;
   const tab = activeTab();
@@ -870,6 +915,7 @@ function activateTab(id) {
   renderTabs();
 }
 
+// 关闭指定标签。
 function closeTabById(id) {
   const closed = closeTab(state.tabs, id, state.activeId);
   state.tabs = closed.tabs;
@@ -877,6 +923,7 @@ function closeTabById(id) {
   renderTabs();
 }
 
+// 新开一个查询标签。
 function openQuery(sql) {
   const title = `查询 ${state.tabs.filter((tab) => tab.kind === 'sql').length + 1}`;
   const opened = openQueryTab(state.tabs, title, nextTabId('sql'), state.database, sql ?? '');
@@ -885,6 +932,7 @@ function openQuery(sql) {
   renderTabs();
 }
 
+// 打开设置标签。
 function openSettings() {
   const opened = openSettingsTab(state.tabs, '设置', nextTabId('settings'));
   state.tabs = opened.tabs;
@@ -895,6 +943,7 @@ function openSettings() {
 
 // ---------------------------------------------------------------- 设置动作
 
+// 把 IDE 设置写到 CSS 变量。
 function applySettingsToDom() {
   const style = document.documentElement.style;
   style.setProperty('--ui-font', fontFamilyValue(state.settings.uiFonts));
@@ -909,6 +958,7 @@ function applySettingsToDom() {
 }
 
 let saveTimer;
+// 保存 IDE 设置（本地+服务器）。
 function persistSettings() {
   try {
     localStorage.setItem(IDE_SETTINGS_KEY, JSON.stringify(state.settings));
@@ -921,6 +971,7 @@ function persistSettings() {
   }, 400);
 }
 
+// 更新一项 IDE 设置。
 function updateSetting(key, value) {
   state.settings = { ...state.settings, [key]: value };
   applySettingsToDom();
@@ -928,6 +979,7 @@ function updateSetting(key, value) {
   renderEditor();
 }
 
+// 从本地存储读 IDE 设置。
 function loadLocalSettings() {
   try {
     const raw = localStorage.getItem(IDE_SETTINGS_KEY);
@@ -938,6 +990,7 @@ function loadLocalSettings() {
   }
 }
 
+// 从服务器读 IDE 设置。
 async function loadRemoteSettings() {
   try {
     state.settings = { ...state.settings, ...parseUiSettings(await api.loadUiSettings()) };
@@ -947,6 +1000,7 @@ async function loadRemoteSettings() {
   }
 }
 
+// 读取服务器设置。
 async function loadServerSettings() {
   try {
     state.serverSettings = await api.loadServerSettings();
@@ -956,6 +1010,7 @@ async function loadServerSettings() {
   renderEditor();
 }
 
+// 保存改过的服务器设置。
 async function saveServerSettings() {
   const inputs = [...document.querySelectorAll('[data-server-setting]')];
   const values = {};
@@ -986,6 +1041,7 @@ async function saveServerSettings() {
 
 // ---------------------------------------------------------------- 表格动作
 
+// 切换该列的排序。
 function sortColumn(tab, column) {
   const data = tab.data;
   if (data.sort === column) data.dir = data.dir === 'asc' ? 'desc' : 'asc';
@@ -997,6 +1053,7 @@ function sortColumn(tab, column) {
   void loadTableData(tab);
 }
 
+// 暂存删除选中的行。
 function deleteSelected(tab) {
   const keyColumn = tab.data.columns.find((column) => column.name === 'id');
   if (!keyColumn || !tab.selected) return;
@@ -1007,7 +1064,7 @@ function deleteSelected(tab) {
   afterChange();
 }
 
-// 点一下就地把单元格变成输入框；Enter/失焦提交，Esc 放弃。
+// 就地编辑单元格：提交或放弃。
 function beginCellEdit(cell, options) {
   if (cell.querySelector('input')) return;
   const input = document.createElement('input');
@@ -1018,6 +1075,7 @@ function beginCellEdit(cell, options) {
   input.focus();
   input.select();
   let done = false;
+  // 结束编辑并按需提交。
   const finish = (save) => {
     if (done) return;
     done = true;
@@ -1025,6 +1083,7 @@ function beginCellEdit(cell, options) {
     input.remove();
     options.commit(save ? parseEdited(raw, options.type) : undefined);
   };
+  // Enter 提交，Esc 放弃。
   input.addEventListener('keydown', (event) => {
     if (event.key === 'Enter') {
       event.preventDefault();
@@ -1034,9 +1093,11 @@ function beginCellEdit(cell, options) {
       finish(false);
     }
   });
+  // 失焦时提交。
   input.addEventListener('blur', () => finish(true));
 }
 
+// 在新建表对话框加一列。
 function addColumnRow(name, type) {
   const container = region('dlg-table-columns');
   if (!container) return;
@@ -1049,6 +1110,7 @@ function addColumnRow(name, type) {
   container.appendChild(row);
 }
 
+// 打开新建表对话框。
 function openCreateTableDialog() {
   region('dlg-table-name').value = '';
   region('dlg-table-error').textContent = '';
@@ -1058,6 +1120,7 @@ function openCreateTableDialog() {
   region('dlg-table').showModal();
 }
 
+// 打开建索引对话框。
 function openIndexDialog(table) {
   const meta = state.tables.find((entry) => entry.name === table);
   const select = region('dlg-index-column');
@@ -1070,6 +1133,7 @@ function openIndexDialog(table) {
   region('dlg-index').showModal();
 }
 
+// 提交新建数据库。
 async function createDatabase() {
   const name = region('dlg-db-name').value.trim();
   try {
@@ -1082,6 +1146,7 @@ async function createDatabase() {
   }
 }
 
+// 提交新建表。
 async function createTable() {
   const name = region('dlg-table-name').value.trim();
   const rows = [...region('dlg-table-columns').querySelectorAll('.column-row')];
@@ -1107,6 +1172,7 @@ async function createTable() {
   }
 }
 
+// 提交建索引。
 async function createIndexFor(table) {
   const dialog = region('dlg-index');
   const column = region('dlg-index-column').value;
@@ -1121,6 +1187,7 @@ async function createIndexFor(table) {
   }
 }
 
+// 删除当前数据库。
 async function dropCurrentDatabase() {
   const name = state.database;
   if (!window.confirm(`删除数据库 ${name}？此操作不可撤销。`)) return;
@@ -1136,6 +1203,7 @@ async function dropCurrentDatabase() {
   }
 }
 
+// 删除指定表。
 async function dropTableByName(table) {
   if (!window.confirm(`删除表 ${table}？`)) return;
   try {
@@ -1150,6 +1218,7 @@ async function dropTableByName(table) {
   }
 }
 
+// 删除指定列。
 async function dropColumnByName(table, column) {
   if (!window.confirm(`删除 ${table}.${column}？`)) return;
   try {
@@ -1162,6 +1231,7 @@ async function dropColumnByName(table, column) {
   }
 }
 
+// 删除指定索引。
 async function dropIndexByName(table, column) {
   if (!window.confirm(`删除 ${table}.${column} 上的索引？`)) return;
   try {
@@ -1175,9 +1245,11 @@ async function dropIndexByName(table, column) {
 
 // ---------------------------------------------------------------- 事件代理
 
+// 拖动分隔条调整尺寸。
 function startSplitterDrag(kind, event) {
   event.preventDefault();
   const workbench = region('workbench');
+  // 按鼠标位置调整宽度或高度。
   const move = (moveEvent) => {
     if (kind === 'v') {
       const width = Math.min(560, Math.max(180, moveEvent.clientX - 48));
@@ -1189,6 +1261,7 @@ function startSplitterDrag(kind, event) {
       workbench.style.setProperty('--dock-height', `${height}px`);
     }
   };
+  // 移除拖动监听。
   const stop = () => {
     window.removeEventListener('mousemove', move);
     window.removeEventListener('mouseup', stop);
@@ -1204,10 +1277,12 @@ const DATABASE_ACTIONS = new Set([
   'drop-database', 'commit', 'rollback', 'copy-sql',
 ]);
 
+// 该动作是否需要当前库。
 function needsDatabase(action) {
   return DATABASE_ACTIONS.has(action);
 }
 
+// 点击事件代理。
 function onClick(event) {
   const splitter = event.target.closest('[data-split]');
   if (splitter) {
@@ -1451,6 +1526,7 @@ function onClick(event) {
   }
 }
 
+// 输入与选择事件代理。
 function onChange(event) {
   const target = event.target;
   if (target.dataset.action === 'switch-database') {
@@ -1495,6 +1571,7 @@ function onChange(event) {
   else updateSetting(key, target.value);
 }
 
+// 提交事件代理（登录表单）。
 function onSubmit(event) {
   if (event.target.id !== 'login-form') return;
   event.preventDefault();
@@ -1524,6 +1601,7 @@ function onSubmit(event) {
   })();
 }
 
+// 键盘事件代理。
 function onKeydown(event) {
   if (event.key === 'Enter' && event.target.id === 'dlg-db-name') {
     event.preventDefault();
@@ -1533,6 +1611,7 @@ function onKeydown(event) {
 
 // ---------------------------------------------------------------- 启动
 
+// 会话过期时回到登录页。
 window.addEventListener(AUTH_EVENT, () => {
   if (state.view === 'login') return;
   state.session = null;
@@ -1546,6 +1625,7 @@ root.addEventListener('change', onChange);
 root.addEventListener('submit', onSubmit);
 root.addEventListener('keydown', onKeydown);
 
+// 启动：读设置、恢复会话、渲染。
 async function boot() {
   loadLocalSettings();
   applySettingsToDom();
diff --git a/chusql-web/static/core.js b/chusql-web/static/core.js
index 1505575..4754eae 100644
--- a/chusql-web/static/core.js
+++ b/chusql-web/static/core.js
@@ -1,9 +1,9 @@
-// 纯逻辑层：SQL 生成、变更集、筛选、类型、标签页与 IDE 设置默认值。
-// 不碰 DOM、不发请求，方便单独阅读与替换。
+// 纯逻辑层：SQL 生成、变更集、筛选、类型、标签页与 IDE 设置。
+// 不碰 DOM、不发请求。
 
 // ---------------------------------------------------------------- 转义
 
-// 所有拼进 innerHTML 的文本都要先过这里（表名、列名、单元格值都是用户数据）。
+// 转义 HTML 特殊字符。
 export function escapeHtml(value) {
   return String(value ?? '')
     .replaceAll('&', '&amp;')
@@ -20,7 +20,7 @@ const identifierPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
 // 账号表：在 system 库里像普通表一样浏览，写入会翻译成账号命令。
 export const accountsTable = '__chusql_users';
 
-// 字面量：NULL / 数字 / 布尔原样，其它按字符串加单引号并把单引号翻倍。
+// 值转 SQL 字面量（字符串加引号转义）。
 export function sqlLiteral(value) {
   if (value === null || value === undefined) return 'NULL';
   if (typeof value === 'number' || typeof value === 'boolean') return String(value);
@@ -70,11 +70,12 @@ export function changeSql(change) {
 
 // ---------------------------------------------------------------- 变更集
 
-// 空变更集：updates 按"表:主键:列"记，inserts/deletes 按各自的键记。
+// 建一个空变更集。
 export function createEmptyChangeSet() {
   return { updates: new Map(), inserts: new Map(), deletes: new Map() };
 }
 
+// 复制变更集。
 export function cloneChangeSet(changes) {
   return {
     updates: new Map(changes.updates),
@@ -83,6 +84,7 @@ export function cloneChangeSet(changes) {
   };
 }
 
+// 变更总条数。
 export function changeCount(changes) {
   return changes.updates.size + changes.inserts.size + changes.deletes.size;
 }
@@ -92,7 +94,7 @@ export function changeKey(table, pk, column) {
   return `${table}:${JSON.stringify(pk)}:${column}`;
 }
 
-// 插入行的键（临时 id，不落库）。
+// 插入行的键。
 export function insertKey(table, tempId) {
   return `${table}:${tempId}`;
 }
@@ -121,7 +123,7 @@ export function toCommitPayload(changes) {
   ];
 }
 
-// 面板里要显示的一条条变更：[{ key, kind, table, sql, … }]
+// 面板展示用的变更条目列表。
 export function changeEntries(changes) {
   const updates = [...changes.updates.entries()].map(([key, update]) => ({
     key,
@@ -155,16 +157,18 @@ export function changesSql(changes) {
 
 // ---------------------------------------------------------------- 筛选
 
+// 转义正则元字符。
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+// like 通配转正则。
 function likePattern(raw) {
   const escaped = escapeRegExp(raw).replaceAll('%', '.*').replaceAll('_', '.');
   return new RegExp(`^${escaped}$`, 'i');
 }
 
-// 表格筛选表达式：null / true / false / like 通配 / 数值比较 / 纯文本包含。
+// 判断单元格值是否命中筛选表达式。
 export function matchesFilter(value, rawExpression) {
   const expression = String(rawExpression ?? '').trim();
   if (!expression) return true;
@@ -209,23 +213,27 @@ export const creatableTypes = [
   'float', 'double', 'decimal(10,2)', 'date', 'timestamp', 'blob',
 ];
 
+// 取类型基名（去掉参数）。
 export function columnKind(type) {
   return String(type).split('(')[0].trim().toLowerCase();
 }
 
+// 是否整数类型。
 export function isIntegerType(type) {
   return ['int', 'bigint', 'smallint'].includes(columnKind(type));
 }
 
+// 是否数值类型。
 export function isNumericType(type) {
   return ['int', 'bigint', 'smallint', 'float', 'double', 'decimal', 'numeric'].includes(columnKind(type));
 }
 
+// 是否布尔类型。
 export function isBooleanType(type) {
   return ['bool', 'boolean'].includes(columnKind(type));
 }
 
-// 显示名：按基名查标签，参数原样跟在后面（varchar(20) → VARCHAR(20)）。
+// 类型的显示名。
 export function typeLabel(type) {
   const kind = columnKind(type);
   const label = typeLabels[kind];
@@ -236,7 +244,7 @@ export function typeLabel(type) {
 
 // ---------------------------------------------------------------- 值渲染
 
-// 单元格显示的文本；null/undefined 用设置里的占位文本。
+// 单元格显示文本（空值用占位文本）。
 export function cellText(value, nullText) {
   if (value === null || value === undefined) return nullText;
   if (typeof value === 'boolean') return value ? 'true' : 'false';
@@ -249,7 +257,7 @@ export function editText(value) {
   return String(value);
 }
 
-// 把编辑框里的文本变回提交给服务的值（空串按 null 处理，与界面上的"清空"一致）。
+// 编辑框文本转提交值（空串当 null）。
 export function parseEdited(raw, type) {
   const text = String(raw ?? '').trim();
   if (text === '') return null;
@@ -296,6 +304,7 @@ export function tokenizeSql(sql) {
   let plain = '';
   let index = 0;
   const text = String(sql ?? '');
+  // 收尾当前普通片段。
   const flush = () => {
     if (plain) {
       tokens.push({ text: plain, kind: 'plain' });
@@ -352,7 +361,7 @@ export function tokenizeSql(sql) {
   return tokens;
 }
 
-// 高亮片段转 HTML（词法切分的结果，文本仍然要转义）。
+// 高亮 SQL 片段转 HTML。
 export function highlightHtml(sql) {
   return tokenizeSql(sql)
     .map((token) => (token.kind === 'plain' ? escapeHtml(token.text) : `<span class="tok-${token.kind}">${escapeHtml(token.text)}</span>`))
@@ -492,6 +501,7 @@ export function fontsFromText(text) {
     .slice(0, 10);
 }
 
+// 字体链转逗号分隔文本。
 export function fontsToText(chain) {
   return chain.join(', ');
 }
diff --git a/chusql-web/static/index.html b/chusql-web/static/index.html
index fff4fda..0eac15c 100644
--- a/chusql-web/static/index.html
+++ b/chusql-web/static/index.html
@@ -1,8 +1,5 @@
 <!doctype html>
 
-<!-- ChuSQL Web IDE 页面壳：纯 HTML + CSS + JS，无打包器、无 Node 依赖。
-     这里不要写内联样式表或内联脚本：CSP 只给带 nonce 的样式放行。 -->
-
 <html lang="zh-CN">
   <head>
     <meta charset="UTF-8" />
@@ -11,6 +8,7 @@
     <title>ChuSQL 数据库终端</title>
     <link rel="stylesheet" href="/static/style.css" />
     <script type="module" src="/static/app.js"></script>
+    <!-- ChuSQL Web IDE 页面壳：挂载 #root，加载样式与 app.js。 -->
   </head>
   <body>
     <div id="root"></div>
diff --git a/chusql-web/static/style.css b/chusql-web/static/style.css
index 2ca69ab..8f6dd40 100644
--- a/chusql-web/static/style.css
+++ b/chusql-web/static/style.css
@@ -1,5 +1,4 @@
-/* ChuSQL Web IDE 样式：VS Code Dark+ 风格，纯手写，无框架。
-   字体与字号由 app.js 通过 CSS 变量（--ui-font 等）按 IDE 设置覆盖。 */
+/* ChuSQL Web IDE 样式：VS Code Dark+ 风格，变量由 app.js 覆盖。 */
 
 :root {
   --bg-base: #1e1e1e;
diff --git a/chusql-web/test/Gates.hs b/chusql-web/test/Gates.hs
new file mode 100644
index 0000000..5619adc
--- /dev/null
+++ b/chusql-web/test/Gates.hs
@@ -0,0 +1,269 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module Gates (gateSpec) where
+
+import qualified Data.ByteString as BS
+import Data.Text (Text)
+import qualified Data.Text as T
+import qualified Data.Text.Encoding as TE
+import System.Directory (doesFileExist)
+import System.FilePath ((</>))
+import Test.Hspec
+
+-- 门禁测试：安装打包脚本、发布流水线、文档结构里必须出现的内容。
+
+-- | 按 UTF-8 读取文件
+readUtf8 :: FilePath -> IO Text
+readUtf8 path = TE.decodeUtf8 <$> BS.readFile path
+
+-- | 门禁用例入口
+gateSpec :: Spec
+gateSpec = do
+    describe "Installer scripts (scripts/)" $ do
+        it "install.sh releases files, writes chusql.toml, sets PATH and removes the package" $ do
+            installer <- readUtf8 (".." </> "scripts" </> "install.sh")
+            installer `shouldSatisfy` T.isInfixOf "libchusql_core_storage"
+            installer `shouldSatisfy` T.isInfixOf "chusql.toml"
+            installer `shouldSatisfy` T.isInfixOf "PATH"
+            installer `shouldSatisfy` T.isInfixOf "rm -rf"
+        -- 一份脚本三种来源：包内（旁边有 bin/）、在线（管道进来时 $0 是 sh，按平台取 release 资源）、
+        -- 显式归档或源码。去掉任何一条，从 GitHub 装的用法就断了。
+        it "install.sh picks the package by platform and can fall back to source" $ do
+            installer <- readUtf8 (".." </> "scripts" </> "install.sh")
+            installer `shouldSatisfy` T.isInfixOf "bin/libchusql_core_storage"
+            installer `shouldSatisfy` T.isInfixOf "uname -s"
+            installer `shouldSatisfy` T.isInfixOf "uname -m"
+            installer `shouldSatisfy` T.isInfixOf "releases/latest/download"
+            -- 一个平台一个包（web 和 cli 都在里面那一个归档里），按平台标签找，没有组件名那一层
+            installer `shouldSatisfy` T.isInfixOf "chusql-$label.$ext"
+            installer `shouldSatisfy` T.isInfixOf "chusql.$ext"
+            -- 释放按这次的选择走：没选的组件一个文件都不落地
+            installer `shouldSatisfy` T.isInfixOf "cp \"$pack/bin/csql\""
+            installer `shouldSatisfy` T.isInfixOf ".sha256"
+            installer `shouldSatisfy` T.isInfixOf "--url"
+            installer `shouldSatisfy` T.isInfixOf "--from-source"
+            installer `shouldSatisfy` T.isInfixOf "stack build --fast"
+            -- 版本可以指定、也可以先列出来：latest 先去 GitHub API 里挑「最新正式版且带本平台包」，
+            -- 自建站点（GHE / 镜像 / 本地夹具）走 /api/v3，取包也换同一套基地址。
+            installer `shouldSatisfy` T.isInfixOf "--list-versions"
+            installer `shouldSatisfy` T.isInfixOf "api/v3"
+            installer `shouldSatisfy` T.isInfixOf "CHUSQL_GITHUB_BASE"
+            -- 版本接口未认证只有 60 次/小时，两个脚本都要能用 token 抬高限额
+            installer `shouldSatisfy` T.isInfixOf "CHUSQL_GITHUB_TOKEN"
+        -- Windows 侧要跟 install.sh 对齐：旁边没有包就去发行站下 zip，版本可指定、可列出来，
+        -- 自建站点同样靠 CHUSQL_GITHUB_BASE 换基地址（api/v3 + 下载路径一起换）。
+        it "install.ps1 downloads the package, picks a version and can list versions" $ do
+            installer <- readUtf8 (".." </> "scripts" </> "install.ps1")
+            installer `shouldSatisfy` T.isInfixOf "bin\\chusql_core_storage.dll"
+            -- 与 install.sh 同一套命名：一个平台一个包，没有组件名那一层
+            installer `shouldSatisfy` T.isInfixOf "chusql-$label.zip"
+            installer `shouldSatisfy` T.isInfixOf "'chusql.zip'"
+            installer `shouldSatisfy` T.isInfixOf "releases/latest/download"
+            installer `shouldSatisfy` T.isInfixOf "-Version"
+            installer `shouldSatisfy` T.isInfixOf "-ListVersions"
+            installer `shouldSatisfy` T.isInfixOf ".sha256"
+            installer `shouldSatisfy` T.isInfixOf "api/v3"
+            installer `shouldSatisfy` T.isInfixOf "CHUSQL_GITHUB_BASE"
+            -- 版本接口未认证只有 60 次/小时，两个脚本都要能用 token 抬高限额
+            installer `shouldSatisfy` T.isInfixOf "CHUSQL_GITHUB_TOKEN"
+            installer `shouldSatisfy` T.isInfixOf "Expand-Archive"
+            -- PowerShell 7 的两个坑：Content 可能是字节数组（.sha256 会变成一串数字），
+            -- 函数 return 数组会被折成「装数组的单个对象」（版本挑选会拿到整张 tag 表）。
+            -- 两处都要绕开，否则校验和版本选择会静默出错。
+            installer `shouldSatisfy` T.isInfixOf "Get-ResponseText"
+            installer `shouldSatisfy` T.isInfixOf "-is [byte[]]"
+            installer `shouldSatisfy` T.isInfixOf "ConvertFrom-Json"
+        -- 装什么由人当场选：逐个问、问答用英文、默认装 csql 不装 Web，选完才问管理员口令。
+        -- 提问顺序固定：先 cli 后 web。两个脚本文案必须一致，改一个就得改另一个。
+        it "both installers ask which components to install, in the same words" $ do
+            sh <- readUtf8 (".." </> "scripts" </> "install.sh")
+            ps <- readUtf8 (".." </> "scripts" </> "install.ps1")
+            let cliAsk = "Install the command line client (csql)? [Y/n]"
+                webAsk = "Install the web front end (browser UI)? [y/N]"
+            mapM_
+                ( \src -> do
+                    src `shouldSatisfy` T.isInfixOf cliAsk
+                    src `shouldSatisfy` T.isInfixOf webAsk
+                    src `shouldSatisfy` T.isInfixOf "Root password for"
+                    -- cli 的问题必须出现在 web 之前（文档里的用法示例也按这个顺序写）
+                    T.length (fst (T.breakOn cliAsk src)) `shouldSatisfy` (< T.length (fst (T.breakOn webAsk src)))
+                )
+                [sh, ps]
+            sh `shouldSatisfy` T.isInfixOf "--interactive"
+            sh `shouldSatisfy` T.isInfixOf "both"
+            ps `shouldSatisfy` T.isInfixOf "-Interactive"
+            ps `shouldSatisfy` T.isInfixOf "both"
+            -- 到底装的哪个版本要打出来：latest 解析来的和显式指定的，两处都得有。
+            sh `shouldSatisfy` T.isInfixOf "echo \"  version    $version\""
+            sh `shouldSatisfy` T.isInfixOf "note \"version    $version\""
+            ps `shouldSatisfy` T.isInfixOf "  version    {0}"
+        -- 本机打发行包：文件名叫法和 CI 出的资产一致（install.sh / install.ps1 按同一套平台标签取），
+        -- 落在 releases/ 下（不入库），并自带 sha256。缺任何一样，自己打的包安装脚本就认不出来。
+        it "the packaging scripts write the same asset names as the release pipeline" $ do
+            sh <- readUtf8 (".." </> "scripts" </> "package.sh")
+            ps <- readUtf8 (".." </> "scripts" </> "package.ps1")
+            mapM_
+                ( \src -> do
+                    src `shouldSatisfy` T.isInfixOf "releases"
+                    src `shouldSatisfy` T.isInfixOf "install.sh"
+                    src `shouldSatisfy` T.isInfixOf "install.ps1"
+                )
+                [sh, ps]
+            sh `shouldSatisfy` T.isInfixOf "tar -czf"
+            sh `shouldSatisfy` T.isInfixOf "sha256"
+            -- 一个平台一个包：名字里不再有组件那一层，web 与 cli 都在同一个归档里，
+            -- 装哪个由包内脚本问；脚本自己也要按两种选择各验一遍（没选的不许落地）
+            sh `shouldSatisfy` T.isInfixOf "chusql-$platform"
+            sh `shouldSatisfy` T.isInfixOf "chusql-web/static"
+            sh `shouldSatisfy` T.isInfixOf "bin/csql"
+            sh `shouldSatisfy` T.isInfixOf "for comp in cli web"
+            -- 打包脚本自己不再有组件开关：--component 只留在包内安装脚本里（给非交互用），
+            -- 这里的自检要靠「它自己的选项表里没有组件项」来证明，不能一口咬定全文不出现这三个字。
+            sh `shouldSatisfy` T.isInfixOf "try --no-build, --out-dir DIR, --platform LABEL"
+            sh `shouldSatisfy` (not . T.isInfixOf "--component)")
+            ps `shouldSatisfy` T.isInfixOf "Compress-Archive"
+            ps `shouldSatisfy` T.isInfixOf "Get-FileHash"
+            ps `shouldSatisfy` T.isInfixOf "chusql-$Platform"
+            ps `shouldSatisfy` T.isInfixOf "chusql-web\\static"
+            ps `shouldSatisfy` T.isInfixOf "bin\\csql.exe"
+            ps `shouldSatisfy` T.isInfixOf "Test-Installed $name 'cli'"
+            ps `shouldSatisfy` (not . T.isInfixOf "$Component")
+
+            ignore <- readUtf8 (".." </> ".gitignore")
+            ignore `shouldSatisfy` T.isInfixOf "releases/"
+        -- static_dir 是相对路径，启动器必须先切到安装目录；少了这一句，从别处执行
+        -- csql-web 就会因为找不到 static/ 直接退出（Windows 的 .ps1 靠 -WorkingDirectory）。
+        it "csql-web.sh switches to the install dir before starting" $ do
+            launcher <- readUtf8 (".." </> "scripts" </> "csql-web.sh")
+            launcher `shouldSatisfy` T.isInfixOf "cd \"$home_dir\""
+            launcher `shouldSatisfy` T.isInfixOf "chusql-server"
+        -- 默认数据目录按平台惯例算，四处必须说同一件事：Rust 代码、配置示例、模板、文档。
+        -- 跟安装脚本装的位置也是一处：Windows 装到 %LOCALAPPDATA%\ChuSQL、Unix 装到 ~/.local/share/chusql，
+        -- 数据都放在它下面的 data/ 里。
+        it "the default data dir follows the platform, and code, template and docs agree" $ do
+            rust <- readUtf8 (".." </> "chusql-core" </> "storage" </> "src" </> "config.rs")
+            rust `shouldSatisfy` T.isInfixOf "default_data_dir"
+            rust `shouldSatisfy` T.isInfixOf "LOCALAPPDATA"
+            rust `shouldSatisfy` T.isInfixOf "XDG_DATA_HOME"
+            rust `shouldSatisfy` (not . T.isInfixOf "DEFAULT_DATA_DIR")
+
+            exampleFile <- readUtf8 (".." </> "chusql-core" </> "storage" </> "chusql-core-storage.toml.example")
+            -- 示例文件说自己列的值就是默认值：data_dir 不能是能生效的一行
+            exampleFile `shouldSatisfy` (not . T.isInfixOf "\ndata_dir =")
+            exampleFile `shouldSatisfy` T.isInfixOf "%LOCALAPPDATA%"
+            exampleFile `shouldSatisfy` T.isInfixOf "XDG_DATA_HOME"
+
+            template <- readUtf8 (".." </> "scripts" </> "chusql.toml")
+            -- 模板那行是安装时被 sed / -replace 替换的占位，必须保持能生效
+            template `shouldSatisfy` T.isInfixOf "\ndata_dir = "
+            template `shouldSatisfy` T.isInfixOf "%LOCALAPPDATA%"
+
+            configDoc <- readUtf8 (".." </> "doc" </> "config.md")
+            configDoc `shouldSatisfy` T.isInfixOf "%LOCALAPPDATA%\\ChuSQL\\data"
+            configDoc `shouldSatisfy` T.isInfixOf "chusql/data"
+        -- 管道传输退休后，两侧都不该再算套接字路径、也不该再认管名。
+        it "neither side computes a socket path or a pipe name any more" $ do
+            haskellIpc <- readUtf8 (".." </> "chusql-core" </> "engine" </> "src" </> "ChuSQL" </> "Core" </> "Engine" </> "Storage" </> "IPC.hs")
+            haskellIpc `shouldSatisfy` (not . T.isInfixOf "XDG_RUNTIME_DIR")
+            haskellIpc `shouldSatisfy` (not . T.isInfixOf ".sock")
+            haskellIpc `shouldSatisfy` (not . T.isInfixOf "pipe")
+            rustModules <- readUtf8 (".." </> "chusql-core" </> "storage" </> "src" </> "lib.rs")
+            rustModules `shouldSatisfy` (not . T.isInfixOf "endpoint")
+            storageConfig <- readUtf8 (".." </> "chusql-core" </> "storage" </> "src" </> "config.rs")
+            storageConfig `shouldSatisfy` (not . T.isInfixOf "pipe_name")
+        it "the Linux pipeline builds both toolchains and runs every test suite" $ do
+            pipeline <- readUtf8 (".." </> ".github" </> "workflows" </> "linux.yml")
+            pipeline `shouldSatisfy` T.isInfixOf "ubuntu-latest"
+            pipeline `shouldSatisfy` T.isInfixOf "cargo test --release"
+            pipeline `shouldSatisfy` T.isInfixOf "cargo clippy"
+            pipeline `shouldSatisfy` T.isInfixOf "stack test --fast"
+            -- 打包与安装冒烟只在发版流水线里做（tag 触发 / 手动 dispatch），这条流水线不再出包
+            pipeline `shouldSatisfy` (not . T.isInfixOf "package.ps1")
+            pipeline `shouldSatisfy` (not . T.isInfixOf "smoke-linux.sh")
+            -- 仓库里没有 rustfmt.toml，历史代码不是按当前 rustfmt 排的：格式化不是门禁
+            pipeline `shouldSatisfy` (not . T.isInfixOf "cargo fmt")
+        -- 装的人不该被要求装两个工具链：发版流水线出预编译包，install.sh 按同一套平台标签去取。
+        -- 流水线里装配与打归档是直接写的（两个平台各一段）；本机要打同一个包用 scripts/ 下的
+        -- package.sh 与它的 PowerShell 版，两边的布局必须一致。
+        it "the release pipeline publishes one archive per platform, tagged the way install.sh looks it up" $ do
+            release <- readUtf8 (".." </> ".github" </> "workflows" </> "release.yml")
+            release `shouldSatisfy` T.isInfixOf "linux-x86_64"
+            release `shouldSatisfy` T.isInfixOf "macos-arm64"
+            release `shouldSatisfy` T.isInfixOf "macos-x86_64"
+            release `shouldSatisfy` T.isInfixOf "windows-x86_64"
+            release `shouldSatisfy` T.isInfixOf "cargo build --release"
+            release `shouldSatisfy` T.isInfixOf "stack build --fast chusql-web:exe:chusql-web"
+            release `shouldSatisfy` T.isInfixOf "stack build --fast chusql-cli:exe:csql"
+            release `shouldSatisfy` T.isInfixOf "tar -czf"
+            release `shouldSatisfy` T.isInfixOf "Compress-Archive"
+            release `shouldSatisfy` T.isInfixOf "scripts/install.sh"
+            release `shouldSatisfy` (not . T.isInfixOf "package.ps1")
+            release `shouldSatisfy` T.isInfixOf "sha256"
+            release `shouldSatisfy` T.isInfixOf "gh release upload"
+            -- 四个平台各一个包，名字里没有组件那一层：一个包里 web 与 cli 都有；
+            -- 矩阵里也不该再出现 web / cli 这一维（那样又会产出两个按组件命名的资产）
+            release `shouldSatisfy` T.isInfixOf "name: ${{ matrix.platform }}"
+            release `shouldSatisfy` T.isInfixOf "name=\"chusql-${{ matrix.platform }}\""
+            release `shouldSatisfy` T.isInfixOf "name = \"chusql-${{ matrix.platform }}\""
+            release `shouldSatisfy` (not . T.isInfixOf "matrix.component")
+            release `shouldSatisfy` (not . T.isInfixOf "component: [web, cli]")
+        it "no layer looks for a storage executable or a pipe name any more" $ do
+            engine <- readUtf8 (".." </> "chusql-core" </> "engine" </> "test" </> "Spec.hs")
+            bench <- readUtf8 (".." </> "benchmark" </> "src" </> "Main.hs")
+            template <- readUtf8 (".." </> "scripts" </> "chusql.toml")
+            mapM_
+                (\src -> src `shouldSatisfy` (not . T.isInfixOf "pipe_name"))
+                [engine, bench, template]
+            mapM_
+                (\src -> src `shouldSatisfy` (not . T.isInfixOf "chusql-storage.exe"))
+                [engine, bench]
+            -- 起存储进程那一整个模块已经删掉，别再长回来
+            moduleGone <-
+                doesFileExist
+                    (".." </> "chusql-server" </> "src" </> "ChuSQL" </> "Server" </> "StorageProcess.hs")
+            moduleGone `shouldBe` False
+
+    -- 细节分到 doc/ 下四份，README 只留面向用户的关键内容；链接断了或者文档没了，等于没写。
+    describe "Documentation (doc/)" $ do
+        it "the README keeps only the essentials and links the split documents" $ do
+            readme <- readUtf8 (".." </> "README.md")
+            mapM_
+                (\target -> readme `shouldSatisfy` T.isInfixOf ("doc/" <> target <> ".md"))
+                ["install", "config", "commands", "architecture"]
+            -- 安装选项与配置键的长表已经搬走，不该在 README 里再长回来
+            readme `shouldSatisfy` (not . T.isInfixOf "--from-source")
+            readme `shouldSatisfy` (not . T.isInfixOf "pool_size")
+            -- 仓库布局这类开发者信息属于 doc/architecture.md，不属于 README
+            readme `shouldSatisfy` (not . T.isInfixOf "chusql-engine/")
+        it "each split document covers what its name promises" $ do
+            let expectations =
+                    [ ("install", ["install.sh", "install.ps1", "--component", "--install-dir", "--from-source", "--version", "--list-versions", "-Component", "-Version", "-ListVersions", "-Interactive", "CHUSQL_GITHUB_TOKEN", "rm -rf"])
+                    , ("config", ["[web]", "[page]", "data_dir", "host", "port"])
+                    , ("commands", ["csql", "--format", "\\dt", "CREATE ROLE", "GRANT", "/api/roles"])
+                    , ("architecture", ["chusql-core", "chusql-server", "chusql-web", "csql", "data_dir", "CREATE DATABASE"])
+                    ]
+            mapM_
+                ( \(name, needles) -> do
+                    doc <- readUtf8 (".." </> "doc" </> name <> ".md")
+                    mapM_ (\needle -> doc `shouldSatisfy` T.isInfixOf needle) needles
+                )
+                expectations
+        -- doc/ 只写面向用户的内容：构建、测试、打包这些开发流程不进文档
+        it "the split documents stay user-facing (no build, test or packaging recipes)" $ do
+            let developerOnly =
+                    [ "package.ps1"
+                    , "stack build"
+                    , "stack test"
+                    , "cargo build"
+                    , "cargo test"
+                    , "cargo clippy"
+                    , ".stack-work"
+                    , ".github/workflows"
+                    , "smoke-linux.sh"
+                    ]
+            mapM_
+                ( \name -> do
+                    doc <- readUtf8 (".." </> "doc" </> name <> ".md")
+                    mapM_ (\needle -> doc `shouldSatisfy` (not . T.isInfixOf needle)) developerOnly
+                )
+                ["install", "config", "commands", "architecture"]
diff --git a/chusql-web/test/Spec.hs b/chusql-web/test/Spec.hs
index 34a8024..b24c937 100644
--- a/chusql-web/test/Spec.hs
+++ b/chusql-web/test/Spec.hs
@@ -1,116 +1,54 @@
 {-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE PatternSynonyms #-}
 
 module Main (main) where
 
-import ChuSQL.Model (ColumnType (..), Database, Table (..), Value (..), plainColumn, pattern TInt, pattern TStr, pattern TBool)
-import ChuSQL.Storage.IPC (Account (..), Request (..), SchemaColumn (..), TableInfo (..), setPipeName)
-import ChuSQL.Web.Accounts
-import Data.Either (isLeft, isRight)
-import ChuSQL.Syntax.AST (Expr (..), FromClause (..), JoinKind (..), Statement (..))
-import ChuSQL.Syntax.Parser (parseStatement)
-import ChuSQL.Web.Actions (
-    ColumnSpec (..),
-    CreateTableSpec (..),
-    coerceValue,
-    columnTypeOf,
-    createIndexSql,
-    createTableSql,
-    deleteRowSql,
-    dropIndexSql,
-    dropTableSql,
-    insertRowSql,
-    insertRowsSql,
-    isIdentifier,
-    selectRowsSql,
-    sqlLiteral,
-    updateRowSql,
- )
-import ChuSQL.Web.API (
-    AppEnv (..),
-    Live (..),
-    defaultLive,
-    newAppEnv,
-    parseCookieHeader,
-    readLive,
-    renderRow,
-    setLive,
-    webApp,
- )
-import ChuSQL.Web.Auth (
-    Credential (..),
-    SessionPolicy (..),
-    createSession,
-    defaultSessionPolicy,
-    deleteSession,
-    hashLooksValid,
-    hashPasswordWith,
-    lookupSession,
-    newSessionStore,
-    sessionPolicy,
-    sessionToken,
-    setSessionPolicy,
-    verifyPassword,
- )
-import ChuSQL.Web.Backend (beAccounts, columnsFromStatement, inDatabase, ipcBackend, memoryBackend, tableInfoOf)
-import ChuSQL.Web.Config (
-    WebConfig (..),
-    canonicalSettingKeys,
-    defaultPassword,
-    defaultUser,
-    defaultWebConfig,
-    loadWebConfigAt,
-    resolveCredential,
-    resolvePipeName,
-    usingDefaultCredentials,
- )
-import ChuSQL.Web.RateLimit (newRateLimiter, rateLimitBlock, rateLimitRecord, setRateLimit)
-import ChuSQL.Web.Settings (
-    SettingItem (..),
+import ChuSQL.Interface.RateLimit (newRateLimiter)
+import ChuSQL.Interface.Settings (
     applySettings,
-    effectiveSettings,
-    findItem,
-    isRestartRequired,
-    isRootOnly,
+    defaultOf,
+    isLockedSetting,
     liveKeys,
     readSettingsFile,
     settingCatalogue,
     writeSettingsFile,
  )
-import ChuSQL.Web.Static (contentTypeOf, readStatic, safeRelative)
-import ChuSQL.Web.StorageProcess (StorageProcess (..), platformBinaryName, startStorageProcess, storageChildArgs, stopStorageProcess, waitForStorage)
-import ChuSQL.Web.TOML (defaultConfigFile, resolveConfigPath)
-import ChuSQL.Web.UISettings (
-    readUISettings,
-    uiSettingsFileCandidates,
-    validateUISettings,
-    writeUISettings,
+import ChuSQL.Web.API (
+    AppEnv (..),
+    Live (..),
+    defaultLive,
+    isIdentifier,
+    newAppEnvAt,
+    parseCookieHeader,
+    sessionCookieName,
+    webApp,
  )
-import Control.Concurrent.MVar (newMVar)
-import Control.Exception (IOException, bracket, finally, try)
-import Control.Monad (forM_)
-import Data.Aeson (decode)
+import ChuSQL.Web.Static (contentTypeOf, safeRelative)
+import ChuSQL.Web.UISettings (validateUISettings)
+import Control.Concurrent (forkIO)
+import Control.Exception (IOException, bracket, try)
+import Control.Monad (when)
+import Data.Aeson (encode, object, (.=))
 import qualified Data.Aeson as A
 import qualified Data.Aeson.Key as K
 import qualified Data.Aeson.KeyMap as KM
 import qualified Data.ByteString as BS
 import qualified Data.ByteString.Char8 as BSC
 import qualified Data.ByteString.Lazy as BL
-import Data.IORef (newIORef, readIORef, writeIORef)
-import Data.List (isInfixOf, isPrefixOf, nub, partition, sort)
+import Data.Char (isDigit)
+import Data.List (isInfixOf)
 import qualified Data.Map.Strict as Map
 import Data.Maybe (fromMaybe)
 import Data.Text (Text)
 import qualified Data.Text as T
 import qualified Data.Text.Encoding as TE
-import Data.Time.Calendar (fromGregorian)
-import Data.Time.Clock (UTCTime (..), addUTCTime, getCurrentTime)
+import Data.Time.Clock (getCurrentTime)
 import Data.Unique (hashUnique, newUnique)
 import qualified Data.Vector as V
+import Gates (gateSpec)
 import Network.HTTP.Client (
     Manager,
     Request (method, requestBody, requestHeaders),
-    RequestBody (..),
+    RequestBody (RequestBodyLBS),
     Response (responseBody, responseHeaders, responseStatus),
     defaultManagerSettings,
     httpLbs,
@@ -118,171 +56,183 @@ import Network.HTTP.Client (
     parseRequest,
  )
 import Network.HTTP.Types (Header, Method, methodGet, methodPost, statusCode)
-import Network.Wai (Application)
+import qualified Network.Wai as Wai
 import qualified Network.Wai.Handler.Warp as Warp
 import qualified Network.Wai.Test as WT
-import System.Directory (XdgDirectory (XdgConfig), createDirectoryIfMissing, doesDirectoryExist, doesFileExist, getTemporaryDirectory, getXdgDirectory, removePathForcibly)
-import qualified System.Directory
-import System.Environment (getEnvironment, lookupEnv, setEnv, unsetEnv)
+import System.Directory (
+    createDirectoryIfMissing,
+    findExecutable,
+    getTemporaryDirectory,
+    removeFile,
+    removePathForcibly,
+ )
 import System.Exit (ExitCode (..))
 import System.FilePath ((</>))
-import System.IO (Handle)
 import System.Info (os)
+import System.IO (Handle, hGetLine)
 import System.Process (
-    CreateProcess (cwd, std_err, std_out),
+    CreateProcess (std_err, std_out),
     ProcessHandle,
-    StdStream (..),
+    StdStream (CreatePipe, NoStream),
     createProcess,
     proc,
-    readCreateProcessWithExitCode,
+    terminateProcess,
     waitForProcess,
  )
 import Test.Hspec
-import qualified System.Process as Process
 import Test.Hspec.Wai hiding (pendingWith)
 
--- ChuSQL Web 测试：纯函数、路由级（内存后端）、端到端（真 Rust 存储进程）。
+-- ChuSQL Web 测试：纯函数、静态交付、门禁，以及打到真 server 的 HTTP 与 socket 用例。
 
--- | 夹具库名：服务不再有默认库，测试世界里这一个库扮演"已选中的库"。
---   它只是个普通库名（不再是保留名）——保留的只有 system。
-testDatabaseName :: String
+-- | 夹具库名：测试默认选中的库
+testDatabaseName :: Text
 testDatabaseName = "test"
 
--- | 夹具库的请求头
-testDatabaseHeader :: Header
-testDatabaseHeader = ("X-ChuSQL-Database", TE.encodeUtf8 (T.pack testDatabaseName))
+-- | 夹具管理员
+adminUser :: Text
+adminUser = "admin"
 
--- | 没有显式指定库的请求都落到夹具库；要测"没选库"的用例请直接用 `request`
-fixtureHeaders :: [Header] -> [Header]
-fixtureHeaders hs
-    | any ((== "X-ChuSQL-Database") . fst) hs = hs
-    | otherwise = testDatabaseHeader : hs
+-- | 夹具管理员口令
+adminPassword :: Text
+adminPassword = "s3cret"
 
--- | users 5 行 + orders 1 行
-testDb :: Database
-testDb =
-    [ ( "users"
-      , Table
-            "users"
-            [("id", TInt), ("name", TStr), ("age", TInt)]
-            [ [("id", VInt i), ("name", VStr ("user" ++ show i)), ("age", VInt (20 + i))]
-            | i <- [1 .. 5]
-            ]
-      )
-    , ( "orders"
-      , Table
-            "orders"
-            [("id", TInt), ("user_id", TInt)]
-            [[("id", VInt 1), ("user_id", VInt 1)]]
-      )
-    ]
+-- | 换成别的库（同名的旧头去掉）
+withDb :: Text -> [Header] -> [Header]
+withDb name hs = ("X-ChuSQL-Database", TE.encodeUtf8 name) : filter ((/= "X-ChuSQL-Database") . fst) hs
 
--- | 测试账号：迭代次数压低（跑得快），口令 `s3cret`
-testCredential :: Credential
-testCredential = Credential "admin" (hashPasswordWith 1000 (BS.replicate 16 7) "s3cret")
+-- | with 块的会话别名，状态放 Application
+type TestSession a = WaiSession Wai.Application a
 
--- | 可控时钟的起点
-epoch :: UTCTime
-epoch = UTCTime (fromGregorian 2026 1 1) 0
+-- | with 的变体：把 Application 放进会话状态
+withApp :: IO Wai.Application -> SpecWith (Arg (WaiExpectation Wai.Application)) -> Spec
+withApp mkApp = withState ((\app -> (app, app)) <$> mkApp)
 
--- | 默认会话策略
-policy :: SessionPolicy
-policy = SessionPolicy (8 * 3600) (24 * 3600)
+-- | 纯断言抬进 WaiSession
+check :: IO () -> TestSession ()
+check = liftIO
 
--- | 造一条 `SELECT *`
-selectStar :: FromClause -> Statement
-selectStar from = Select ["*"] from Nothing [] [] Nothing
+-- | 加上 JSON 内容类型头
+jsonHeaders :: [Header] -> [Header]
+jsonHeaders hs = ("Content-Type", "application/json") : hs
 
--- | 造一条显式列名的 SELECT
-selectThese :: [String] -> FromClause -> Statement
-selectThese cols from = Select cols from Nothing [] [] Nothing
+-- | 拼出会话 Cookie 头
+cookieHeader :: Text -> Header
+cookieHeader token = ("Cookie", TE.encodeUtf8 (sessionCookieName <> "=" <> token))
 
--- | with 块里的会话类型别名
-type TestSession a = WaiSession () a
-
--- | 每个用例组一套：内存后端 + 可控时钟 + 临时静态目录
-freshWorld :: FilePath -> IO AppEnv
-freshWorld staticDir = freshWorldWith staticDir testCredential
-
--- | 同上，但换一个 root 凭据（免密用例用）
-freshWorldWith :: FilePath -> Credential -> IO AppEnv
-freshWorldWith staticDir credential = do
-    db <- newMVar testDb
-    clock <- newIORef epoch
-    sessions <- newSessionStore (readIORef clock) policy
-    limiter <- newRateLimiter (readIORef clock) 5 (5 * 60)
-    env <- newAppEnv (memoryBackend testDatabaseName db) sessions credential limiter staticDir
-    path <- tempSettingsPath "default"
-    removeIfExists path
-    uiPath <- tempUISettingsPath "default"
-    removeIfExists uiPath
-    pure env{aeSettingsFile = path, aeUISettingsFile = uiPath, aeEffective = Map.empty}
-
--- | 免密管理员的世界：空口令的凭据等价于"只允许管理员免密登录"
-withPasswordlessWorld :: FilePath -> (AppEnv -> SpecWith ((), Application)) -> Spec
-withPasswordlessWorld staticDir body = do
-    appEnv <- runIO (freshWorldWith staticDir (Credential "admin" ""))
-    with (webApp appEnv) (body appEnv)
-
--- | 临时设置文件（每个用例组一个名字，互不干扰）
-tempSettingsPath :: String -> IO FilePath
-tempSettingsPath name = do
-    tmp <- getTemporaryDirectory
-    pure (tmp </> ("chusql-web-test-" ++ name ++ "-settings.json"))
-
--- | 临时 IDE 设置文件（同样按用例组取名）
-tempUISettingsPath :: String -> IO FilePath
-tempUISettingsPath name = do
-    tmp <- getTemporaryDirectory
-    pure (tmp </> ("chusql-web-test-" ++ name ++ "-ui-settings.json"))
-
--- | 文件不存在也算成功
-removeIfExists :: FilePath -> IO ()
-removeIfExists path = do
-    there <- doesFileExist path
-    if there then removeFileSafe path else pure ()
+-- | 发独立会话的 WAI 请求，不共享 cookie jar
+requestAs :: Method -> BS.ByteString -> [Header] -> BL.ByteString -> TestSession WT.SResponse
+requestAs verb path hs payload = do
+    app <- getState
+    liftIO $ WT.runSession send app
   where
-    removeFileSafe p = do
-        _ <- try (System.Directory.removeFile p) :: IO (Either IOException ())
-        pure ()
+    -- | 清空 cookie jar 后发出请求
+    send = do
+        WT.modifyClientCookies (const Map.empty)
+        WT.srequest $
+            WT.SRequest
+                ( WT.setPath
+                    ( WT.defaultRequest
+                        { Wai.requestMethod = verb
+                        , Wai.requestHeaders = hs
+                        , Wai.requestBodyLength = Wai.KnownLength (fromIntegral (BL.length payload))
+                        }
+                    )
+                    path
+                )
+                payload
 
--- | 带自己的设置文件的用例组
-freshWorldAt :: FilePath -> String -> IO AppEnv
-freshWorldAt staticDir name = do
-    env <- freshWorld staticDir
-    path <- tempSettingsPath name
-    removeIfExists path
-    uiPath <- tempUISettingsPath name
-    removeIfExists uiPath
-    pure env{aeSettingsFile = path, aeUISettingsFile = uiPath}
+-- | 带头发 GET 请求
+getAs :: [Header] -> BS.ByteString -> TestSession WT.SResponse
+getAs hs path = requestAs methodGet path hs BL.empty
 
--- | 临时静态目录，内容固定便于断言
-makeStaticDir :: IO FilePath
-makeStaticDir = do
-    tmp <- getTemporaryDirectory
-    let dir = tmp </> "chusql-web-static-test"
-    createDirectoryIfMissing True dir
-    BS.writeFile (dir </> "index.html") "<!DOCTYPE html><html lang=\"zh-CN\"><head></head><body>ChuSQL Console</body></html>"
-    BS.writeFile (dir </> "app.js") "// test bundle\n"
-    BS.writeFile (dir </> "style.css") "body{}\n"
-    BS.writeFile (dir </> "secret.token") "do-not-serve\n"
-    pure dir
+-- | 带 JSON 头发 POST 请求
+postAs :: [Header] -> BS.ByteString -> BL.ByteString -> TestSession WT.SResponse
+postAs hs path payload = requestAs methodPost path (jsonHeaders hs) payload
 
--- | 一个用例组一套环境
-withWorld :: FilePath -> (AppEnv -> SpecWith ((), Application)) -> Spec
-withWorld staticDir body = do
-    appEnv <- runIO (freshWorld staticDir)
-    with (webApp appEnv) (body appEnv)
+-- | 带 JSON 头发 PUT 请求
+putAs :: [Header] -> BS.ByteString -> BL.ByteString -> TestSession WT.SResponse
+putAs hs path payload = requestAs "PUT" path (jsonHeaders hs) payload
 
--- | 同上，但带着自己的设置文件（改设置/改口令的用例不互相串）
-withWorldAt :: FilePath -> String -> (AppEnv -> SpecWith ((), Application)) -> Spec
-withWorldAt staticDir name body = do
-    appEnv <- runIO (freshWorldAt staticDir name)
-    with (webApp appEnv) (body appEnv)
+-- | 带 JSON 头发 PATCH 请求
+patchAs :: [Header] -> BS.ByteString -> BL.ByteString -> TestSession WT.SResponse
+patchAs hs path payload = requestAs "PATCH" path (jsonHeaders hs) payload
 
--- | 响应体解成 JSON
+-- | 带头发 DELETE 请求
+deleteAs :: [Header] -> BS.ByteString -> TestSession WT.SResponse
+deleteAs hs path = requestAs "DELETE" path hs BL.empty
+
+-- | 用账号口令登录
+loginAs :: Text -> Text -> TestSession WT.SResponse
+loginAs user password =
+    requestAs
+        methodPost
+        "/api/login"
+        (jsonHeaders [])
+        (encode (object ["user" .= user, "password" .= password]))
+
+-- | 登录并返回会话 Cookie 请求头
+signIn :: Text -> Text -> TestSession [Header]
+signIn user password = do
+    res <- loginAs user password
+    expectStatusWith "sign-in" res 204
+    case sessionCookieOf res of
+        Just token -> pure [cookieHeader token]
+        Nothing -> do
+            check (expectationFailure "sign-in succeeded without a session cookie")
+            pure []
+
+-- | 以管理员登录并取请求头
+adminHeaders :: TestSession [Header]
+adminHeaders = signIn adminUser adminPassword
+
+-- | 已登录的普通账号
+ordinaryHeaders :: Text -> Text -> TestSession [Header]
+ordinaryHeaders user password = do
+    res <- loginAs user password
+    expectStatusWith "ordinary sign-in" res 204
+    case sessionCookieOf res of
+        Just token -> pure [cookieHeader token]
+        Nothing -> do
+            check (expectationFailure "ordinary sign-in without a session cookie")
+            pure []
+
+-- | 建库，已存在就算就位
+ensureDatabase :: [Header] -> Text -> TestSession ()
+ensureDatabase hs name = do
+    listed <- getAs hs "/api/databases"
+    expectStatusWith "list databases" listed 200
+    let names = map asText (items (jsonBody listed))
+    when (name `notElem` names) $ do
+        created <- postAs hs "/api/databases" (encode (object ["name" .= name]))
+        expectStatusWith ("create database " <> T.unpack name) created 200
+
+-- | 建表：已存在就当就位
+ensureTable :: [Header] -> Text -> BL.ByteString -> TestSession ()
+ensureTable hs name body = do
+    listed <- getAs (withDb testDatabaseName hs) "/api/tables"
+    expectStatusWith "list tables" listed 200
+    let names = map (asText . at "table") (items (jsonBody listed))
+    when (name `notElem` names) $ do
+        created <- postAs (withDb testDatabaseName hs) "/api/tables" body
+        expectStatusWith ("create table " <> T.unpack name) created 200
+
+-- | 建账号：重名（409）也算就位
+ensureAccount :: [Header] -> Text -> Text -> TestSession ()
+ensureAccount hs user password = do
+    created <-
+        postAs
+            (withDb "system" hs)
+            "/api/tables/__chusql_users/rows"
+            (encode (object ["values" .= object ["user" .= user, "password" .= password]]))
+    check (statusCode (WT.simpleStatus created) `shouldSatisfy` (`elem` [200, 409]))
+
+-- | 列定义
+column :: Text -> Text -> A.Value
+column name ty = object ["name" .= name, "type" .= ty]
+
+-- | 响应体重解成 JSON
 jsonBody :: WT.SResponse -> A.Value
-jsonBody res = fromMaybe A.Null (decode (WT.simpleBody res))
+jsonBody res = fromMaybe A.Null (A.decode (WT.simpleBody res))
 
 -- | 取字段
 field :: Text -> A.Value -> Maybe A.Value
@@ -308,79 +258,37 @@ asInt :: A.Value -> Int
 asInt (A.Number n) = round n
 asInt _ = -1
 
--- | 第 i 个元素（越界给 Nothing，不用 `!!`）
+-- | 第 i 个元素，越界给 Nothing
 nth :: Int -> [a] -> Maybe a
 nth i xs = case drop i xs of
     (x : _) -> Just x
     [] -> Nothing
 
--- | 取 Set-Cookie 里的会话令牌
-sessionCookieOf :: WT.SResponse -> Maybe Text
-sessionCookieOf res = do
-    raw <- lookup "Set-Cookie" (WT.simpleHeaders res)
-    parseCookieHeader "chusql_session" (TE.decodeUtf8 raw)
+-- | 数组字段的长度
+arrayLen :: A.Value -> Int
+arrayLen = length . items
 
--- | 会话令牌变请求头；顺带带上夹具库——服务没有默认库，缺头就是"没选库"
-cookieHeaders :: WT.SResponse -> [Header]
-cookieHeaders res = case sessionCookieOf res of
-    Nothing -> []
-    Just token -> [("Cookie", TE.encodeUtf8 ("chusql_session=" <> token)), testDatabaseHeader]
+-- | 第一行（位置化数组）
+firstRow :: WT.SResponse -> [A.Value]
+firstRow res = case items (at "rows" (jsonBody res)) of
+    (A.Array xs : _) -> V.toList xs
+    _ -> []
 
--- | 把请求指到系统库 system（账号表与 system 库本身都在那里）
-systemHeaders :: [Header] -> [Header]
-systemHeaders hs = ("X-ChuSQL-Database", "system") : filter ((/= "X-ChuSQL-Database") . fst) hs
-
--- | 带 JSON 体的请求
-jsonRequest :: Method -> BS.ByteString -> BL.ByteString -> TestSession WT.SResponse
-jsonRequest httpMethod urlPath payload =
-    request httpMethod urlPath [("Content-Type", "application/json")] payload
-
--- | 登录请求体
-loginBody :: Text -> Text -> BL.ByteString
-loginBody user password =
-    BL.fromStrict . TE.encodeUtf8 $
-        T.concat ["{\"user\":\"", user, "\",\"password\":\"", password, "\"}"]
-
--- | 登录
-loginAs :: Text -> Text -> TestSession WT.SResponse
-loginAs user password = jsonRequest methodPost "/api/login" (loginBody user password)
-
--- | 带请求头的 GET
-getWith :: [Header] -> BS.ByteString -> TestSession WT.SResponse
-getWith headers path = request methodGet path (fixtureHeaders headers) ""
-
--- | 带请求头的 JSON POST
-postWith :: [Header] -> BS.ByteString -> BL.ByteString -> TestSession WT.SResponse
-postWith headers path payload =
-    request methodPost path (fixtureHeaders (("Content-Type", "application/json") : headers)) payload
-
--- | 带请求头的 JSON PUT（改设置用的是 PUT）
-putWith :: [Header] -> BS.ByteString -> BL.ByteString -> TestSession WT.SResponse
-putWith headers path payload =
-    request "PUT" path (fixtureHeaders (("Content-Type", "application/json") : headers)) payload
-
--- | 带请求头的 JSON PATCH（改行用的是 PATCH）
-patchWith :: [Header] -> BS.ByteString -> BL.ByteString -> TestSession WT.SResponse
-patchWith headers path payload =
-    request "PATCH" path (fixtureHeaders (("Content-Type", "application/json") : headers)) payload
-
--- | 带请求头的 DELETE
-deleteWith :: [Header] -> BS.ByteString -> TestSession WT.SResponse
-deleteWith headers path = request "DELETE" path (fixtureHeaders headers) ""
-
--- | 在 items 数组里按键找一项（找不到给 Null）
+-- | items 数组里按键找一项（找不到给 Null）
 headEntry :: Text -> [A.Value] -> A.Value
 headEntry key entries = case [e | e <- entries, asText (at "key" e) == key] of
     (e : _) -> e
     [] -> A.Null
 
--- | 纯断言抬进 WaiSession
-check :: IO () -> TestSession ()
-check = liftIO
+-- | 响应头
+responseHeader :: Header -> WT.SResponse -> Maybe BS.ByteString
+responseHeader (name, _) res = lookup name (WT.simpleHeaders res)
 
--- | 已经拿到响应对象时的状态码断言
-hasStatus :: WT.SResponse -> Int -> IO ()
-hasStatus res code = statusCode (WT.simpleStatus res) `shouldBe` code
+-- | 取 Set-Cookie 里的会话令牌
+sessionCookieOf :: WT.SResponse -> Maybe Text
+sessionCookieOf res = do
+    raw <- lookup "Set-Cookie" (WT.simpleHeaders res)
+    parseCookieHeader sessionCookieName (TE.decodeUtf8 raw)
 
 -- | 状态码断言，失败时把响应体和状态码一起报出来（定位用）
 expectStatusWith :: String -> WT.SResponse -> Int -> TestSession ()
@@ -399,2319 +307,635 @@ expectStatusWith label res code =
                         ++ show (WT.simpleBody res)
                     )
 
--- | 临时设几个环境变量跑一段，跑完恢复原样（原来没有就删掉）
-withEnv :: [(String, String)] -> IO a -> IO a
-withEnv kvs act = do
-    saved <- mapM (\(k, _) -> fmap ((,) k) (lookupEnv k)) kvs
-    mapM_ (uncurry setEnv) kvs
-    act `finally` mapM_ restore saved
-  where
-    restore (k, mv) = maybe (unsetEnv k) (setEnv k) mv
-
--- | 按 UTF-8 读文件（避免解码错）
-readUtf8 :: FilePath -> IO Text
-readUtf8 path = TE.decodeUtf8 <$> BS.readFile path
-
--- | Either 判空
-isLeftE :: Either a b -> Bool
-isLeftE (Left _) = True
-isLeftE (Right _) = False
-
 -- | Either 判成
 isRightE :: Either a b -> Bool
 isRightE = either (const False) (const True)
 
--- | 响应体里第一行（表格数据）
-firstRow :: WT.SResponse -> [A.Value]
-firstRow res = case items (at "rows" (jsonBody res)) of
-    (r : _) -> case r of
-        A.Array xs -> V.toList xs
-        _ -> []
-    [] -> []
-
--- | 数组字段的长度
-arrayLen :: A.Value -> Int
-arrayLen = length . items
-
-main :: IO ()
-main = hspec spec
-
-spec :: Spec
-spec = do
-    staticDir <- runIO makeStaticDir
-    unitSpec
-    actionsSpec
-    staticSpec staticDir
-    staticAssetSpec
-    staticServeSpec
-    authSpec staticDir
-    passwordlessSpec staticDir
-    catalogSpec staticDir
-    limitsSpec staticDir
-    oneClickSpec staticDir
-    sqlSpec staticDir
-    privilegesSpec staticDir
-    settingsSpec staticDir
-    uiSettingsSpec staticDir
-    sortSpec staticDir
-    securitySpec staticDir
-    e2eSpec staticDir
-
-unitSpec :: Spec
-unitSpec = do
-    describe "Password hashing" $ do
-        it "accepts the correct password" $
-            verifyPassword (hashPasswordWith 1000 (BS.replicate 16 1) "s3cret") "s3cret" `shouldBe` True
-        it "rejects a wrong password" $
-            verifyPassword (hashPasswordWith 1000 (BS.replicate 16 1) "s3cret") "wrong" `shouldBe` False
-        it "treats a broken encoded hash as mismatch instead of throwing" $
-            verifyPassword "garbage" "s3cret" `shouldBe` False
-
-    describe "Sessions" $ do
-        it "token is 64 hex chars and differs between calls" $ do
-            a <- sessionToken
-            b <- sessionToken
-            T.length a `shouldBe` 64
-            T.all (`elem` ("0123456789abcdef" :: String)) a `shouldBe` True
-            a `shouldNotBe` b
-        it "idle timeout drops the session" $ do
-            clock <- newIORef epoch
-            store <- newSessionStore (readIORef clock) policy
-            token <- createSession store "admin"
-            fresh <- lookupSession store token
-            fresh `shouldBe` Just "admin"
-            writeIORef clock (addUTCTime (9 * 3600) epoch)
-            stale <- lookupSession store token
-            stale `shouldBe` Nothing
-        it "activity refreshes the idle timer but the absolute limit still expires" $ do
-            clock <- newIORef epoch
-            store <- newSessionStore (readIORef clock) policy
-            token <- createSession store "admin"
-            writeIORef clock (addUTCTime (7 * 3600) epoch)
-            seen <- lookupSession store token
-            seen `shouldBe` Just "admin"
-            writeIORef clock (addUTCTime (13 * 3600) epoch)
-            seenAgain <- lookupSession store token
-            seenAgain `shouldBe` Just "admin"
-            writeIORef clock (addUTCTime (25 * 3600) epoch)
-            gone <- lookupSession store token
-            gone `shouldBe` Nothing
-        it "deleted session is no longer found" $ do
-            clock <- newIORef epoch
-            store <- newSessionStore (readIORef clock) policy
-            token <- createSession store "admin"
-            deleteSession store token
-            found <- lookupSession store token
-            found `shouldBe` Nothing
-        it "a new expiry policy takes effect immediately (settings hot reload path)" $ do
-            clock <- newIORef epoch
-            store <- newSessionStore (readIORef clock) (SessionPolicy (8 * 3600) (24 * 3600))
-            token <- createSession store "admin"
-            setSessionPolicy store (SessionPolicy 10 20)
-            now <- sessionPolicy store
-            spIdleSeconds now `shouldBe` 10
-            writeIORef clock (addUTCTime 11 epoch)
-            gone <- lookupSession store token
-            gone `shouldBe` Nothing
-
-    describe "Account policy and lifecycle" $ do
-        it "rejects invalid configurable policy limits" $ do
-            mapM_ (\(key, value) -> applySettings Map.empty (Map.singleton key value) `shouldSatisfy` isLeft)
-                [("password-min-length", "7"), ("password-classes", "5")]
-        it "the admin is configuration only: no storage needed to sign in" $ do
-            db <- newMVar testDb
-            sessions <- newSessionStore (pure epoch) policy
-            let backend = (memoryBackend testDatabaseName db){beAccounts = const (pure (Left "unavailable"))}
-            service <- newAccounts backend sessions testCredential
-            authenticate service "admin" "s3cret" >>= (`shouldSatisfy` isRight)
-            listAccounts service >>= (`shouldSatisfy` isLeft)
-        it "enforces password length and character classes" $ do
-            let pol = defaultPasswordPolicy
-            passwordAllowed pol "tiny" `shouldSatisfy` isLeft
-            passwordAllowed pol "alllowercaseletters" `shouldSatisfy` isLeft
-            passwordAllowed pol "long-password" `shouldBe` Right ()
-        it "the admin name is reserved and ordinary names are validated" $ do
-            db <- newMVar testDb
-            sessions <- newSessionStore (pure epoch) policy
-            service <- newAccounts (memoryBackend testDatabaseName db) sessions testCredential
-            runAccountCommand service (Root "admin") (CreateAccount "ADMIN" "another-password") >>= (`shouldSatisfy` isLeft)
-            runAccountCommand service (Root "admin") (CreateAccount "with space" "another-password") >>= (`shouldSatisfy` isLeft)
-            runAccountCommand service (Root "admin") (CreateAccount "alice" "tiny") >>= (`shouldSatisfy` isLeft)
-        it "creates, resets and drops ordinary accounts, and a reset revokes their sessions" $ do
-            db <- newMVar testDb
-            sessions <- newSessionStore (pure epoch) policy
-            service <- newAccounts (memoryBackend testDatabaseName db) sessions testCredential
-            let admin = Root "admin"
-            runAccountCommand service admin (CreateAccount "Alice" "alice-password") >>= (`shouldBe` Right ())
-            Right alice <- authenticate service "alice" "alice-password"
-            Right bob <- authenticate service "admin" "s3cret"
-            runAccountCommand service admin (ResetAccountPassword "alice" "alice-other-pass") >>= (`shouldBe` Right ())
-            currentPrincipal service alice >>= (`shouldSatisfy` isLeft)
-            currentPrincipal service bob >>= (`shouldSatisfy` isRight)
-            authenticate service "alice" "alice-password" >>= (`shouldSatisfy` isLeft)
-            authenticate service "alice" "alice-other-pass" >>= (`shouldSatisfy` isRight)
-            runAccountCommand service admin (DropAccount "alice") >>= (`shouldBe` Right ())
-            authenticate service "alice" "alice-other-pass" >>= (`shouldSatisfy` isLeft)
-            runAccountCommand service admin (DropAccount "alice") >>= (`shouldSatisfy` isLeft)
-        it "an ordinary account cannot administer accounts" $ do
-            db <- newMVar testDb
-            sessions <- newSessionStore (pure epoch) policy
-            service <- newAccounts (memoryBackend testDatabaseName db) sessions testCredential
-            let admin = Root "admin"
-            runAccountCommand service admin (CreateAccount "alice" "alice-password") >>= (`shouldBe` Right ())
-            Right token <- authenticate service "alice" "alice-password"
-            Right principal <- currentPrincipal service token
-            principalIsRoot principal `shouldBe` False
-            principalName principal `shouldBe` "alice"
-            runAccountCommand service principal (CreateAccount "bob" "bob-password") >>= (`shouldSatisfy` isLeft)
-            runAccountCommand service principal (DropAccount "alice") >>= (`shouldSatisfy` isLeft)
-            authenticate service "bob" "bob-password" >>= (`shouldSatisfy` isLeft)
-        it "a failed account write keeps the old password" $ do
-            db <- newMVar testDb
-            sessions <- newSessionStore (pure epoch) policy
-            let original = memoryBackend testDatabaseName db
-                backend = original{beAccounts = \req -> case req of
-                    ReqAccountReset {} -> pure (Left "write failed")
-                    _ -> beAccounts original req}
-            service <- newAccounts backend sessions testCredential
-            let admin = Root "admin"
-            runAccountCommand service admin (CreateAccount "alice" "alice-password") >>= (`shouldBe` Right ())
-            runAccountCommand service admin (ResetAccountPassword "alice" "alice-other-pass") >>= (`shouldSatisfy` isLeft)
-            authenticate service "alice" "alice-password" >>= (`shouldSatisfy` isRight)
-            authenticate service "alice" "alice-other-pass" >>= (`shouldSatisfy` isLeft)
-        it "a legacy row named like the administrator can be dropped, but not recreated" $ do
-            db <- newMVar testDb
-            sessions <- newSessionStore (pure epoch) policy
-            _ <- beAccounts (memoryBackend testDatabaseName db) (ReqAccountCreate "admin" "legacy-hash")
-            service <- newAccounts (memoryBackend testDatabaseName db) sessions testCredential
-            runAccountCommand service (Root "admin") (CreateAccount "admin" "another-password") >>= (`shouldSatisfy` isLeft)
-            runAccountCommand service (Root "admin") (ResetAccountPassword "admin" "another-password") >>= (`shouldSatisfy` isLeft)
-            runAccountCommand service (Root "admin") (DropAccount "admin") >>= (`shouldBe` Right ())
-
-    describe "Login rate limiting" $ do
-        it "below the limit is not blocked" $ do
-            clock <- newIORef epoch
-            rl <- newRateLimiter (readIORef clock) 3 60
-            rateLimitRecord rl "admin"
-            rateLimitRecord rl "admin"
-            open <- rateLimitBlock rl "admin"
-            open `shouldBe` Nothing
-        it "hitting the limit blocks and returns seconds to wait" $ do
-            clock <- newIORef epoch
-            rl <- newRateLimiter (readIORef clock) 3 60
-            mapM_ (const (rateLimitRecord rl "admin")) [1 :: Int, 2, 3]
-            blocked <- rateLimitBlock rl "admin"
-            blocked `shouldSatisfy` maybe False (> 0)
-        it "window expiry allows retries again" $ do
-            clock <- newIORef epoch
-            rl <- newRateLimiter (readIORef clock) 3 60
-            mapM_ (const (rateLimitRecord rl "admin")) [1 :: Int, 2, 3]
-            writeIORef clock (addUTCTime 61 epoch)
-            open <- rateLimitBlock rl "admin"
-            open `shouldBe` Nothing
-        it "raising the threshold unlocks immediately (settings hot reload)" $ do
-            clock <- newIORef epoch
-            rl <- newRateLimiter (readIORef clock) 3 60
-            mapM_ (const (rateLimitRecord rl "admin")) [1 :: Int, 2, 3]
-            blocked <- rateLimitBlock rl "admin"
-            blocked `shouldSatisfy` maybe False (> 0)
-            setRateLimit rl 10 60
-            unlocked <- rateLimitBlock rl "admin"
-            unlocked `shouldBe` Nothing
-
-    describe "Cookie parsing" $ do
-        it "picks the session token out of many cookies" $
-            parseCookieHeader "chusql_session" "a=1; chusql_session=abc123; b=2" `shouldBe` Just "abc123"
-        it "empty value does not count as a value" $
-            parseCookieHeader "chusql_session" "chusql_session=" `shouldBe` Nothing
-
-    describe "Password hash validation (checked before changing the password)" $ do
-        it "self-computed hash is valid" $
-            hashLooksValid (hashPasswordWith 1000 (BS.replicate 16 5) "s3cret") `shouldBe` True
-        it "broken hashes are invalid (bad length/algo/parts)" $ do
-            hashLooksValid "garbage" `shouldBe` False
-            hashLooksValid "pbkdf2-sha256$1000$00$00" `shouldBe` False
-            hashLooksValid "md5$1000$00$00" `shouldBe` False
-
-    describe "Settings catalogue (shared by the settings page and the server)" $ do
-        it "keys are unique and kind/default are filled" $ do
-            let keys = map siKey settingCatalogue
-            length keys `shouldBe` length (nub keys)
-            all (not . T.null . siKey) settingCatalogue `shouldBe` True
-            all (not . T.null . siLabel) settingCatalogue `shouldBe` True
-            all (\i -> siKind i `elem` ["text", "int", "bool", "secret"]) settingCatalogue `shouldBe` True
-            let machineReadable = [i | i <- settingCatalogue, siKind i `elem` ["int", "bool"]]
-            machineReadable `shouldSatisfy` (not . null)
-            all (not . T.null . siDefault) machineReadable `shouldBe` True
-            [siDefault i | i <- settingCatalogue, siKind i == "secret"] `shouldSatisfy` all T.null
-            let pairs = [(siSection i, siTomlKey i) | i <- settingCatalogue]
-            [s | (s, _) <- pairs] `shouldSatisfy` all (not . T.null)
-            [k | (_, k) <- pairs] `shouldSatisfy` all (not . T.null)
-            length pairs `shouldBe` length (nub pairs)
-            findItem "pipe-name" `shouldSatisfy` maybe False (\i -> (siSection i, siTomlKey i) == ("server", "pipe_name"))
-            findItem "storage-page-size" `shouldSatisfy` maybe False (\i -> (siSection i, siTomlKey i) == ("page", "size"))
-        it "critical settings are root-only, tuning ones are not" $ do
-            isRootOnly "port" `shouldBe` True
-            isRootOnly "host" `shouldBe` True
-            isRootOnly "user" `shouldBe` True
-            isRootOnly "password" `shouldBe` True
-            isRootOnly "rows-per-page" `shouldBe` False
-            isRootOnly "body-limit" `shouldBe` False
-        it "live keys exist in the catalogue and are all integers" $ do
-            liveKeys `shouldNotSatisfy` null
-            map findItem liveKeys `shouldSatisfy` all (/= Nothing)
-            [siKind i | Just i <- map findItem liveKeys] `shouldSatisfy` all (== "int")
-        it "restart and live flags do not conflict: port needs a restart, page size does not" $ do
-            isRestartRequired "port" `shouldBe` True
-            isRestartRequired "static-dir" `shouldBe` True
-            isRestartRequired "rows-per-page" `shouldBe` False
-            filter isRestartRequired liveKeys `shouldBe` []
-        it "the flattened startup config carries the real port/account" $ do
-            let flat = effectiveSettings defaultWebConfig
-            Map.lookup "port" flat `shouldBe` Just "7777"
-            Map.lookup "user" flat `shouldBe` Just defaultUser
-            Map.lookup "rows-per-page" flat `shouldBe` Just "25"
-            Map.member "password" flat `shouldBe` False
-            Map.member "password-hash" flat `shouldBe` False
-        it "merge settings: known keys applied, unknown rejected, empty clears" $ do
-            let merged = applySettings Map.empty (Map.fromList [("rows-per-page", "50"), ("port", "9000")])
-            fmap (Map.lookup "rows-per-page") merged `shouldBe` Right (Just "50")
-            applySettings Map.empty (Map.fromList [("nope", "1")]) `shouldSatisfy` isLeftE
-            fmap (Map.lookup "port") (applySettings (Map.fromList [("port", "9000")]) (Map.fromList [("port", "")]))
-                `shouldBe` Right (Just "")
-        it "type validation: ints reject letters, bools accept only known spellings" $ do
-            applySettings Map.empty (Map.fromList [("rows-per-page", "abc")]) `shouldSatisfy` isLeftE
-            applySettings Map.empty (Map.fromList [("rows-per-page", "10")]) `shouldSatisfy` isRightE
-            applySettings Map.empty (Map.fromList [("seed", "maybe")]) `shouldSatisfy` isLeftE
-            applySettings Map.empty (Map.fromList [("seed", "on")]) `shouldSatisfy` isRightE
-        it "write settings file: empty values are not stored and reads come back" $ do
-            tmp <- getTemporaryDirectory
-            let path = tmp </> "chusql-web-test-write-settings.json"
-            removeIfExists path
-            written <- writeSettingsFile path (Map.fromList [("port", "9000"), ("host", "")])
-            written `shouldBe` Right ()
-            stored <- readSettingsFile path
-            Map.lookup "port" stored `shouldBe` Just "9000"
-            Map.member "host" stored `shouldBe` False
-        it "write settings file: reports failure when the directory cannot be created" $ do
-            tmp <- getTemporaryDirectory
-            let blocker = tmp </> "chusql-web-test-blocker"
-            removeIfExists blocker
-            BS.writeFile blocker "not a directory"
-            failed <- writeSettingsFile (blocker </> "settings.json") (Map.fromList [("port", "1")])
-            failed `shouldSatisfy` isLeftE
-            removeIfExists blocker
-        it "an unreadable file counts as empty config (not a crash)" $ do
-            tmp <- getTemporaryDirectory
-            missing <- readSettingsFile (tmp </> "chusql-web-test-does-not-exist.json")
-            missing `shouldBe` Map.empty
-        it "the config file lives at the fixed place the installer writes" $ do
-            fixed <- defaultConfigFile
-            dir <- getXdgDirectory XdgConfig "ChuSQL"
-            fixed `shouldBe` (dir </> "chusql.toml")
-        it "an explicit --config path wins over the fixed place" $ do
-            tmp <- getTemporaryDirectory
-            let explicit = tmp </> "chusql-web-test-explicit.toml"
-            resolveConfigPath (Just explicit) `shouldReturn` explicit
-        it "without --config the fixed place is used" $ do
-            fixed <- defaultConfigFile
-            resolveConfigPath Nothing `shouldReturn` fixed
-
-    describe "Browsing SELECTs (column header click / WHERE filter cells)" $ do
-        it "column and direction produce ORDER BY" $ do
-            selectRowsSql "users" (Just ("age", True)) [] `shouldBe` Right "SELECT * FROM users ORDER BY age ASC"
-            selectRowsSql "users" (Just ("age", False)) [] `shouldBe` Right "SELECT * FROM users ORDER BY age DESC"
-        it "equality filters become WHERE with AND, placed before ORDER BY" $ do
-            selectRowsSql "users" Nothing [("name", VStr "Ann"), ("age", VInt 30)]
-                `shouldBe` Right "SELECT * FROM users WHERE name = 'Ann' AND age = 30"
-            selectRowsSql "users" (Just ("age", False)) [("name", VStr "O'Brien")]
-                `shouldBe` Right "SELECT * FROM users WHERE name = 'O''Brien' ORDER BY age DESC"
-            selectRowsSql "users" Nothing [("vip", VBool True)]
-                `shouldBe` Right "SELECT * FROM users WHERE vip = TRUE"
-        it "table and column names go through the whitelist (including filter columns)" $ do
-            selectRowsSql "users; DROP TABLE users" Nothing [] `shouldSatisfy` isLeftE
-            selectRowsSql "users" (Just ("age; DROP TABLE users", True)) [] `shouldSatisfy` isLeftE
-            selectRowsSql "users" Nothing [("age; DROP TABLE users", VInt 1)] `shouldSatisfy` isLeftE
-
-    describe "Identifier whitelist" $ do
-        it "normal table names pass" $ do
-            isIdentifier "users" `shouldBe` True
-            isIdentifier "user_1" `shouldBe` True
-            isIdentifier "_tmp" `shouldBe` True
-        it "leading digit / space / semicolon / empty string are rejected" $ do
-            isIdentifier "1users" `shouldBe` False
-            isIdentifier "user name" `shouldBe` False
-            isIdentifier "users;DROP TABLE users" `shouldBe` False
-            isIdentifier "" `shouldBe` False
-        it "over 64 characters is rejected" $
-            isIdentifier (T.replicate 65 "a") `shouldBe` False
-
-    describe "Static file name whitelist" $ do
-        it "normal file names pass" $ do
-            safeRelative "app.js" `shouldBe` Just "app.js"
-            safeRelative "style.css" `shouldBe` Just "style.css"
-            safeRelative "codicon.ttf" `shouldBe` Just "codicon.ttf"
-            safeRelative "editor.worker-a1.js" `shouldBe` Just "editor.worker-a1.js"
-        it "traversal / subdirectory / empty string are all rejected" $ do
-            safeRelative "../secret" `shouldBe` Nothing
-            safeRelative "sub/app.js" `shouldBe` Nothing
-            safeRelative "a\\b" `shouldBe` Nothing
-            safeRelative "" `shouldBe` Nothing
-            safeRelative "a b.js" `shouldBe` Nothing
-        it "disallowed extensions fail (.token / .db / no extension)" $ do
-            safeRelative "secret.token" `shouldBe` Nothing
-            safeRelative "catalog.json" `shouldBe` Nothing
-            safeRelative "data.db" `shouldBe` Nothing
-            safeRelative "README" `shouldBe` Nothing
-
-    describe "Content-Type" $ do
-        it "chosen by extension (case-insensitive)" $ do
-            contentTypeOf "index.html" `shouldBe` "text/html; charset=utf-8"
-            contentTypeOf "app.JS" `shouldBe` "text/javascript; charset=utf-8"
-            contentTypeOf "style.css" `shouldBe` "text/css; charset=utf-8"
-            contentTypeOf "codicon.ttf" `shouldBe` "font/ttf"
-            contentTypeOf "x.bin" `shouldBe` "application/octet-stream"
-
-    describe "Column inference (headers even for empty results)" $ do
-        it "normalizes default qualified headers" $ do
-            fmap (columnsFromStatement testDb) (parseStatement "SELECT users.name FROM users WHERE FALSE") `shouldBe` Right ["name"]
-        it "infers headers for a SELECT without FROM" $ do
-            fmap (columnsFromStatement testDb) (parseStatement "SELECT 1 + 2 LIMIT 0") `shouldBe` Right ["1 + 2"]
-        it "SELECT * expands to the table columns" $
-            columnsFromStatement testDb (selectStar (FromTable Nothing "users"))
-                `shouldBe` ["id", "name", "age"]
-        it "aliased SELECT * prefixes the alias" $
-            columnsFromStatement testDb (selectStar (FromTable (Just "u") "users"))
-                `shouldBe` ["u.id", "u.name", "u.age"]
-        it "JOIN SELECT * puts the left table first" $
-            columnsFromStatement
-                testDb
-                (selectStar (FromJoin InnerJoin (FromTable Nothing "users") (Just "o") "orders" (Eq (Col "users.id") (Col "o.user_id"))))
-                `shouldBe` ["users.id", "users.name", "users.age", "o.id", "o.user_id"]
-        it "explicit column names are kept as-is" $
-            columnsFromStatement testDb (selectThese ["name"] (FromTable Nothing "users")) `shouldBe` ["name"]
-        it "write statements have no result columns" $
-            columnsFromStatement testDb (DropTable "users") `shouldBe` []
-
-    describe "Row rendering" $ do
-        it "values follow the given column order, missing columns give null" $
-            renderRow ["name", "id", "age"] [("id", VInt 1), ("name", VStr "a")]
-                `shouldBe` [A.String "a", A.Number 1, A.Null]
-
-    describe "In-memory backend catalogue" $ do
-        it "row count, columns and stats all match" $ do
-            case lookup "users" testDb of
-                Nothing -> expectationFailure "testDb has no users"
-                Just tbl -> do
-                    let info = tableInfoOf ("users", tbl)
-                    tiTable info `shouldBe` "users"
-                    tiRows info `shouldBe` 5
-                    map scName (tiColumns info) `shouldBe` ["id", "name", "age"]
-                    tiStats info `shouldBe` [("id", 5, False), ("name", 5, False), ("age", 5, False)]
-
-    describe "Database qualification (inDatabase)" $ do
-        let rewrite db sql = parseStatement sql >>= Right . inDatabase db
-
-        it "prefixes the tables of a subquery as well" $ do
-            case rewrite "sales" "SELECT name FROM users WHERE id IN (SELECT user_id FROM orders)" of
-                Left err -> expectationFailure err
-                Right stmt -> do
-                    let text = show stmt
-                    ("sales.users" `isInfixOf` text) `shouldBe` True
-                    ("sales.orders" `isInfixOf` text) `shouldBe` True
-                    ("\"orders\"" `isInfixOf` text) `shouldBe` False
-
-        it "keeps the JOIN kind while prefixing both sides" $ do
-            case rewrite "sales" "SELECT u.name FROM users u LEFT JOIN orders o ON u.id = o.user_id" of
-                Left err -> expectationFailure err
-                Right stmt -> do
-                    let text = show stmt
-                    ("LeftJoin" `isInfixOf` text) `shouldBe` True
-                    ("sales.users" `isInfixOf` text) `shouldBe` True
-                    ("sales.orders" `isInfixOf` text) `shouldBe` True
-                    ("\"orders\"" `isInfixOf` text) `shouldBe` False
-
-        it "qualifies a subquery that sits inside a JOIN condition" $ do
-            case rewrite "sales" "SELECT u.name FROM users u JOIN orders o ON u.id = o.user_id AND EXISTS (SELECT 1 FROM orders x WHERE x.user_id = u.id)" of
-                Left err -> expectationFailure err
-                Right stmt -> do
-                    let text = show stmt
-                    ("sales.users" `isInfixOf` text) `shouldBe` True
-                    ("sales.orders" `isInfixOf` text) `shouldBe` True
-                    ("\"orders\"" `isInfixOf` text) `shouldBe` False
-
-        it "leaves table names alone when no database is selected" $ do
-            case rewrite "" "SELECT name FROM users WHERE id IN (SELECT user_id FROM orders)" of
-                Left err -> expectationFailure err
-                Right stmt -> do
-                    let text = show stmt
-                    ("\"users\"" `isInfixOf` text) `shouldBe` True
-                    ("\"orders\"" `isInfixOf` text) `shouldBe` True
-                    ("test." `isInfixOf` text) `shouldBe` False
-
-    describe "Administrator credential source (settings file only)" $ do
-        it "with nothing configured the built-in demo account is used" $ do
-            defaultUser `shouldBe` "root"
-            usingDefaultCredentials Map.empty `shouldBe` True
-            cred <- resolveCredential defaultWebConfig Map.empty
-            credUser cred `shouldBe` defaultUser
-            verifyPassword (credEncoded cred) defaultPassword `shouldBe` True
-        it "a plain password in the settings file wins" $ do
-            let saved = Map.singleton "password" "s3cret"
-            usingDefaultCredentials saved `shouldBe` False
-            cred <- resolveCredential defaultWebConfig saved
-            verifyPassword (credEncoded cred) "s3cret" `shouldBe` True
-            verifyPassword (credEncoded cred) defaultPassword `shouldBe` False
-        it "an explicitly empty password makes the administrator passwordless" $ do
-            let saved = Map.singleton "password" ""
-            usingDefaultCredentials saved `shouldBe` False
-            cred <- resolveCredential defaultWebConfig saved
-            credUser cred `shouldBe` defaultUser
-            credEncoded cred `shouldBe` ""
-            -- 空口令不是"能匹配任意口令"的哈希：它是一个明确的空编码串
-            verifyPassword (credEncoded cred) "" `shouldBe` False
-        it "the retired password-hash key is not a setting and never a credential" $ do
-            let encoded = hashPasswordWith 1000 (BS.replicate 16 9) "from-hash"
-            cred <- resolveCredential defaultWebConfig (Map.singleton "password-hash" encoded)
-            verifyPassword (credEncoded cred) defaultPassword `shouldBe` True
-            applySettings Map.empty (Map.singleton "password-hash" encoded) `shouldSatisfy` isLeftE
-        it "the administrator name comes from the file, and --user still wins" $ do
-            cred <- resolveCredential defaultWebConfig (Map.fromList [("user", "tester"), ("password", "s3cret")])
-            credUser cred `shouldBe` "tester"
-            fromCli <- resolveCredential defaultWebConfig{wcUser = "from-cli"} (Map.singleton "user" "tester")
-            credUser fromCli `shouldBe` "from-cli"
-        it "the password environment variables are no longer consulted" $ do
-            tmp <- getTemporaryDirectory
-            let missing = tmp </> "chusql-web-test-cred-env.toml"
-            removeIfExists missing
-            withEnv [("CHUSQL_WEB_PASSWORD", "from-env"), ("CHUSQL_WEB_USER", "env-user")] $ do
-                cfg <- loadWebConfigAt missing
-                wcUser cfg `shouldBe` ""
-                cred <- resolveCredential cfg Map.empty
-                credUser cred `shouldBe` defaultUser
-                verifyPassword (credEncoded cred) "from-env" `shouldBe` False
-
-    describe "Config: built-in defaults" $ do
-        it "port defaults to 7777 and the administrator name is not baked into the config" $ do
-            wcPort defaultWebConfig `shouldBe` 7777
-            wcHost defaultWebConfig `shouldBe` "127.0.0.1"
-            wcUser defaultWebConfig `shouldBe` ""
-            wcCookieSecure defaultWebConfig `shouldBe` False
-        it "session / rate limit / paging / row limits all have explicit defaults" $ do
-            wcSessionIdle defaultWebConfig `shouldBe` 8 * 3600
-            wcSessionMax defaultWebConfig `shouldBe` 24 * 3600
-            wcLoginMaxAttempts defaultWebConfig `shouldBe` 5
-            wcLoginWindow defaultWebConfig `shouldBe` 5 * 60
-            wcPageSize defaultWebConfig `shouldBe` 25
-            wcMaxPageSize defaultWebConfig `shouldBe` 500
-            wcMaxRows defaultWebConfig `shouldBe` 1000
-            wcMaxSqlLength defaultWebConfig `shouldBe` 20000
-            wcBodyLimit defaultWebConfig `shouldBe` 65536
-
-    describe "Config: environment variables are ignored (the file comes from --config)" $ do
-        it "port / host / static dir / limits in the environment change nothing" $ do
-            tmp <- getTemporaryDirectory
-            let missing = tmp </> "chusql-web-test-ignored-env.toml"
-            removeIfExists missing
-            withEnv
-                [ ("CHUSQL_WEB_PORT", "8123")
-                , ("CHUSQL_WEB_HOST", "0.0.0.0")
-                , ("CHUSQL_WEB_STATIC", "mysite")
-                , ("CHUSQL_WEB_SESSION_IDLE", "60")
-                , ("CHUSQL_WEB_SESSION_MAX", "120")
-                , ("CHUSQL_WEB_LOGIN_MAX_ATTEMPTS", "3")
-                , ("CHUSQL_WEB_LOGIN_WINDOW", "30")
-                , ("CHUSQL_WEB_PAGE_SIZE", "7")
-                , ("CHUSQL_WEB_MAX_PAGE_SIZE", "70")
-                , ("CHUSQL_WEB_MAX_ROWS", "9")
-                , ("CHUSQL_WEB_MAX_SQL_LENGTH", "1234")
-                , ("CHUSQL_WEB_BODY_LIMIT", "2048")
-                , ("CHUSQL_WEB_COOKIE_SECURE", "1")
-                ]
-                $ do
-                    cfg <- loadWebConfigAt missing
-                    cfg `shouldBe` defaultWebConfig
-        it "the retired endpoint variables change nothing either" $ do
-            tmp <- getTemporaryDirectory
-            let missing = tmp </> "chusql-web-test-ignored-endpoint.toml"
-            removeIfExists missing
-            withEnv
-                [ ("CHUSQL_PIPE", "from-env-pipe")
-                , ("CHUSQL_DATA_DIR", "from-env-data")
-                , ("CHUSQL_STORAGE_SERVER", "from-env-server")
-                ]
-                $ do
-                    cfg <- loadWebConfigAt missing
-                    wcPipeName cfg `shouldBe` Nothing
-                    wcDataDir cfg `shouldBe` Nothing
-                    wcStorageServer cfg `shouldBe` Nothing
-
-    describe "Config: the sections of the global chusql.toml" $ do
-        it "reads the section and accepts both underscore and hyphen spellings" $ do
-            tmp <- getTemporaryDirectory
-            let path = tmp </> "chusql-web-test-global.toml"
-            writeFile path "[page]\nsize = 8192\n\n[web]\nstatic_dir = \"webroot\"\nsession_idle = 4242\nrows_per_page = 33\n"
-            cfg <- loadWebConfigAt path
-            wcStaticDir cfg `shouldBe` "webroot"
-            wcSessionIdle cfg `shouldBe` 4242
-            wcPageSize cfg `shouldBe` 33
-            -- 别的层的分区不归 web 管，没给的键回到内置默认
-            wcPort cfg `shouldBe` 7777
-            wcMaxRows cfg `shouldBe` 1000
-            saved <- readSettingsFile path
-            Map.lookup "rows-per-page" saved `shouldBe` Just "33"
-        it "the endpoint comes from [server] pipe_name and [storage] data_dir, the executable from [web] storage_server" $ do
-            tmp <- getTemporaryDirectory
-            let path = tmp </> "chusql-web-test-endpoint.toml"
-            writeFile
-                path
-                "[server]\npipe_name = \"joint-pipe\"\n\n[storage]\ndata_dir = \"../localdata\"\n\n[web]\nstorage_server = \"chusql-storage.exe\"\n"
-            cfg <- loadWebConfigAt path
-            wcPipeName cfg `shouldBe` Just "joint-pipe"
-            resolvePipeName cfg `shouldBe` "joint-pipe"
-            wcDataDir cfg `shouldBe` Just "../localdata"
-            wcStorageServer cfg `shouldBe` Just "chusql-storage.exe"
-        it "without a file the pipe name falls back to the shared default" $ do
-            resolvePipeName defaultWebConfig `shouldBe` "chusql-joint"
-        it "a port in the environment no longer wins over the file" $ do
-            tmp <- getTemporaryDirectory
-            let path = tmp </> "chusql-web-test-global-env.toml"
-            writeFile path "[web]\nport = 1234\nhost = \"0.0.0.0\"\n"
-            withEnv [("CHUSQL_WEB_PORT", "4321")] $ do
-                cfg <- loadWebConfigAt path
-                wcPort cfg `shouldBe` 1234
-                wcHost cfg `shouldBe` "0.0.0.0"
-        it "the canonical hyphen key wins when both spellings are present" $ do
-            let both = Map.fromList [("session-idle", "1"), ("session_idle", "2")]
-            Map.lookup "session-idle" (canonicalSettingKeys both) `shouldBe` Just "1"
-        it "a missing config file falls back to the built-in defaults" $ do
-            tmp <- getTemporaryDirectory
-            let missing = tmp </> "chusql-web-test-missing-config.toml"
-            removeIfExists missing
-            cfg <- loadWebConfigAt missing
-            wcPort cfg `shouldBe` wcPort defaultWebConfig
-            wcPageSize cfg `shouldBe` wcPageSize defaultWebConfig
-
-    describe "Spawning the storage process" $ do
-        it "points the child at the same config file on its command line" $ do
-            storageChildArgs ("scripts" </> "chusql.toml")
-                `shouldBe` ["--config", "scripts" </> "chusql.toml"]
-        it "passes nothing else" $ do
-            storageChildArgs "chusql.toml" `shouldBe` ["--config", "chusql.toml"]
-
-    describe "Installer scripts (scripts/)" $ do
-        it "install.sh releases files, writes chusql.toml, sets PATH and removes the package" $ do
-            installer <- readUtf8 (".." </> "scripts" </> "install.sh")
-            installer `shouldSatisfy` T.isInfixOf "chusql-storage"
-            installer `shouldSatisfy` T.isInfixOf "chusql.toml"
-            installer `shouldSatisfy` T.isInfixOf "PATH"
-            installer `shouldSatisfy` T.isInfixOf "rm -rf"
-        -- 一份脚本三种来源：包内（旁边有 bin/）、在线（管道进来时 $0 是 sh，按平台取 release 资源）、
-        -- 显式归档或源码。去掉任何一条，从 GitHub 装的用法就断了。
-        it "install.sh picks the package by platform and can fall back to source" $ do
-            installer <- readUtf8 (".." </> "scripts" </> "install.sh")
-            installer `shouldSatisfy` T.isInfixOf "bin/chusql-storage"
-            installer `shouldSatisfy` T.isInfixOf "uname -s"
-            installer `shouldSatisfy` T.isInfixOf "uname -m"
-            installer `shouldSatisfy` T.isInfixOf "releases/latest/download"
-            installer `shouldSatisfy` T.isInfixOf "chusql-$component-$label.$ext"
-            installer `shouldSatisfy` T.isInfixOf ".sha256"
-            installer `shouldSatisfy` T.isInfixOf "--url"
-            installer `shouldSatisfy` T.isInfixOf "--from-source"
-            installer `shouldSatisfy` T.isInfixOf "stack build --fast"
-        -- static_dir 是相对路径，启动器必须先切到安装目录；少了这一句，从别处执行
-        -- csql-web 就会因为找不到 static/ 直接退出（Windows 的 .ps1 靠 -WorkingDirectory）。
-        it "csql-web.sh switches to the install dir before starting" $ do
-            launcher <- readUtf8 (".." </> "scripts" </> "csql-web.sh")
-            launcher `shouldSatisfy` T.isInfixOf "cd \"$home_dir\""
-            launcher `shouldSatisfy` T.isInfixOf "chusql-storage"
-        -- 默认数据目录按平台惯例算，四处必须说同一件事：Rust 代码、配置示例、模板、文档。
-        -- 跟安装脚本装的位置也是一处：Windows 装到 %LOCALAPPDATA%\ChuSQL、Unix 装到 ~/.local/share/chusql，
-        -- 数据都放在它下面的 data/ 里。
-        it "the default data dir follows the platform, and code, template and docs agree" $ do
-            rust <- readUtf8 (".." </> "chusql-storage" </> "src" </> "config.rs")
-            rust `shouldSatisfy` T.isInfixOf "default_data_dir"
-            rust `shouldSatisfy` T.isInfixOf "LOCALAPPDATA"
-            rust `shouldSatisfy` T.isInfixOf "XDG_DATA_HOME"
-            rust `shouldSatisfy` (not . T.isInfixOf "DEFAULT_DATA_DIR")
-
-            example <- readUtf8 (".." </> "chusql-storage" </> "chusql-storage.toml.example")
-            -- 示例文件说自己列的值就是默认值：data_dir 不能是能生效的一行
-            example `shouldSatisfy` (not . T.isInfixOf "\ndata_dir =")
-            example `shouldSatisfy` T.isInfixOf "%LOCALAPPDATA%"
-            example `shouldSatisfy` T.isInfixOf "XDG_DATA_HOME"
-
-            template <- readUtf8 (".." </> "scripts" </> "chusql.toml")
-            -- 模板那行是安装时被 sed / -replace 替换的占位，必须保持能生效
-            template `shouldSatisfy` T.isInfixOf "\ndata_dir = "
-            template `shouldSatisfy` T.isInfixOf "%LOCALAPPDATA%"
-
-            configDoc <- readUtf8 (".." </> "doc" </> "config.md")
-            configDoc `shouldSatisfy` T.isInfixOf "%LOCALAPPDATA%\\ChuSQL\\data"
-            configDoc `shouldSatisfy` T.isInfixOf "chusql/data"
-        -- 端点规则两侧必须一致：Rust 服务端和 Haskell 前端算出来的必须是同一个路径。
-        it "Rust and Haskell agree on where the Unix socket lives" $ do
-            rustEndpoint <- readUtf8 (".." </> "chusql-storage" </> "src" </> "endpoint.rs")
-            haskellIpc <- readUtf8 (".." </> "chusql-engine" </> "src" </> "ChuSQL" </> "Storage" </> "IPC.hs")
-            mapM_
-                ( \src -> do
-                    src `shouldSatisfy` T.isInfixOf "XDG_RUNTIME_DIR"
-                    src `shouldSatisfy` T.isInfixOf "TMPDIR"
-                    src `shouldSatisfy` T.isInfixOf "/tmp"
-                    src `shouldSatisfy` T.isInfixOf ".sock"
-                )
-                [rustEndpoint, haskellIpc]
-        it "the Linux pipeline builds both toolchains and runs every test suite" $ do
-            pipeline <- readUtf8 (".." </> ".github" </> "workflows" </> "linux.yml")
-            pipeline `shouldSatisfy` T.isInfixOf "ubuntu-latest"
-            pipeline `shouldSatisfy` T.isInfixOf "cargo test --release"
-            pipeline `shouldSatisfy` T.isInfixOf "cargo clippy"
-            pipeline `shouldSatisfy` T.isInfixOf "stack test --fast"
-            -- 打包与安装冒烟只在发版流水线里做（tag 触发 / 手动 dispatch），这条流水线不再出包
-            pipeline `shouldSatisfy` (not . T.isInfixOf "package.ps1")
-            pipeline `shouldSatisfy` (not . T.isInfixOf "smoke-linux.sh")
-            -- 仓库里没有 rustfmt.toml，历史代码不是按当前 rustfmt 排的：格式化不是门禁
-            pipeline `shouldSatisfy` (not . T.isInfixOf "cargo fmt")
-        -- 装的人不该被要求装两个工具链：发版流水线出预编译包，install.sh 按同一套平台标签去取。
-        -- 装配与打归档原来在 scripts/package.ps1 里，脚本删掉后直接写在流水线里（两个平台各一段）。
-        it "the release pipeline publishes one archive per platform, tagged the way install.sh looks it up" $ do
-            release <- readUtf8 (".." </> ".github" </> "workflows" </> "release.yml")
-            release `shouldSatisfy` T.isInfixOf "linux-x86_64"
-            release `shouldSatisfy` T.isInfixOf "macos-arm64"
-            release `shouldSatisfy` T.isInfixOf "macos-x86_64"
-            release `shouldSatisfy` T.isInfixOf "windows-x86_64"
-            release `shouldSatisfy` T.isInfixOf "cargo build --release"
-            release `shouldSatisfy` T.isInfixOf "stack build --fast chusql-web:exe:chusql-web"
-            release `shouldSatisfy` T.isInfixOf "stack build --fast chusql-cli:exe:csql"
-            release `shouldSatisfy` T.isInfixOf "tar -czf"
-            release `shouldSatisfy` T.isInfixOf "Compress-Archive"
-            release `shouldSatisfy` T.isInfixOf "scripts/install.sh"
-            release `shouldSatisfy` (not . T.isInfixOf "package.ps1")
-            release `shouldSatisfy` T.isInfixOf "sha256"
-            release `shouldSatisfy` T.isInfixOf "gh release upload"
-        it "the storage binary name follows the platform (a stray .exe must not win on Linux)" $ do
-            platformBinaryName "mingw32" "chusql-storage" `shouldBe` "chusql-storage.exe"
-            platformBinaryName "linux" "chusql-storage" `shouldBe` "chusql-storage"
-            -- 同一 target 目录里可能躺着一份别处交叉编译出来的 .exe：谁都不许再写
-            -- 「.exe 优先、无后缀兜底」这种候选表
-            engine <- readUtf8 (".." </> "chusql-engine" </> "test" </> "Spec.hs")
-            bench <- readUtf8 (".." </> "benchmark" </> "src" </> "Main.hs")
-            storage <- readUtf8 ("src" </> "ChuSQL" </> "Web" </> "StorageProcess.hs")
-            mapM_
-                (\src -> src `shouldSatisfy` (not . T.isInfixOf "\"chusql-storage.exe\", \"chusql-storage\""))
-                [engine, bench, storage]
-
-    -- 细节分到 doc/ 下四份，README 只留面向用户的关键内容；链接断了或者文档没了，等于没写。
-    describe "Documentation (doc/)" $ do
-        it "the README keeps only the essentials and links the split documents" $ do
-            readme <- readUtf8 (".." </> "README.md")
-            mapM_
-                (\target -> readme `shouldSatisfy` T.isInfixOf ("doc/" <> target <> ".md"))
-                ["install", "config", "commands", "architecture"]
-            -- 安装选项与配置键的长表已经搬走，不该在 README 里再长回来
-            readme `shouldSatisfy` (not . T.isInfixOf "--from-source")
-            readme `shouldSatisfy` (not . T.isInfixOf "pool_size")
-            -- 仓库布局这类开发者信息属于 doc/architecture.md，不属于 README
-            readme `shouldSatisfy` (not . T.isInfixOf "chusql-engine/")
-        it "each split document covers what its name promises" $ do
-            let expectations =
-                    [ ("install", ["install.sh", "install.ps1", "--component", "--install-dir", "--from-source", "rm -rf"])
-                    , ("config", ["[web]", "[page]", "pipe_name", "data_dir", "host", "port"])
-                    , ("commands", ["csql", "--format", "\\dt", "CREATE ROLE", "GRANT", "/api/roles"])
-                    , ("architecture", ["chusql-storage", "chusql-web", "csql", "pipe_name", "data_dir", "CREATE DATABASE"])
-                    ]
-            mapM_
-                ( \(name, needles) -> do
-                    doc <- readUtf8 (".." </> "doc" </> name <> ".md")
-                    mapM_ (\needle -> doc `shouldSatisfy` T.isInfixOf needle) needles
-                )
-                expectations
-        -- doc/ 只写面向用户的内容：构建、测试、打包这些开发流程不进文档
-        it "the split documents stay user-facing (no build, test or packaging recipes)" $ do
-            let developerOnly =
-                    [ "package.ps1"
-                    , "stack build"
-                    , "stack test"
-                    , "cargo build"
-                    , "cargo test"
-                    , "cargo clippy"
-                    , ".stack-work"
-                    , ".github/workflows"
-                    , "smoke-linux.sh"
-                    ]
-            mapM_
-                ( \name -> do
-                    doc <- readUtf8 (".." </> "doc" </> name <> ".md")
-                    mapM_ (\needle -> doc `shouldSatisfy` (not . T.isInfixOf needle)) developerOnly
-                )
-                ["install", "config", "commands", "architecture"]
-
-staticSpec :: FilePath -> Spec
-staticSpec staticDir = describe "Static files" $ do
-    it "an unreadable file gives Nothing" $
-        readStatic staticDir "nope.js" `shouldReturn` Nothing
-
--- | 手写静态前端：源文件入库，没有打包器，也不该再有 Node 工具链
-staticAssetSpec :: Spec
-staticAssetSpec = describe "Static front end (hand-written, no bundler)" $ do
-    let dir = "static"
-        asset name = dir </> name
-        readAsset name = readUtf8 (asset name)
-    it "the app shell is present and loads both assets from /static/" $ do
-        html <- readAsset "index.html"
-        html `shouldSatisfy` T.isInfixOf "id=\"root\""
-        html `shouldSatisfy` T.isInfixOf "src=\"/static/app.js\""
-        html `shouldSatisfy` T.isInfixOf "href=\"/static/style.css\""
-        -- 服务端把 nonce 元信息插在 </head> 前面，这个标记不能丢
-        html `shouldSatisfy` T.isInfixOf "</head>"
-    it "the shell has no inline script or style (the CSP allows neither)" $ do
-        html <- readAsset "index.html"
-        html `shouldSatisfy` (not . T.isInfixOf "<script>")
-        html `shouldSatisfy` (not . T.isInfixOf "<style")
-    it "no generated template keeps an inline style attribute (the CSP would block it)" $ do
-        js <- readAsset "app.js"
-        js `shouldSatisfy` (not . T.isInfixOf "style=\"")
-    it "the hand-written modules and the stylesheet are non-empty" $
-        mapM_ (\name -> BS.readFile (asset name) >>= (`shouldSatisfy` (not . BS.null)))
-            ["app.js", "core.js", "api.js", "style.css"]
-    it "the app carries the Chinese UI copy and the REST client keeps every endpoint" $ do
-        js <- readAsset "app.js"
-        js `shouldSatisfy` T.isInfixOf "待提交变更"
-        js `shouldSatisfy` T.isInfixOf "新建查询"
-        api <- readAsset "api.js"
-        api `shouldSatisfy` T.isInfixOf "X-ChuSQL-Database"
-        api `shouldSatisfy` T.isInfixOf "/api/tables/"
-        api `shouldSatisfy` T.isInfixOf "/api/ui-settings"
-        api `shouldSatisfy` T.isInfixOf "/api/query"
-    it "every shipped asset passes the static file name whitelist" $ do
-        names <- System.Directory.listDirectory dir
-        mapM_ (\name -> safeRelative (T.pack name) `shouldBe` Just name) names
-    it "content types are mapped for every shipped asset" $ do
-        contentTypeOf "index.html" `shouldBe` "text/html; charset=utf-8"
-        contentTypeOf "app.js" `shouldBe` "text/javascript; charset=utf-8"
-        contentTypeOf "core.js" `shouldBe` "text/javascript; charset=utf-8"
-        contentTypeOf "api.js" `shouldBe` "text/javascript; charset=utf-8"
-        contentTypeOf "style.css" `shouldBe` "text/css; charset=utf-8"
-    it "the Node toolchain is gone from the repository" $ do
-        frontendDir <- doesDirectoryExist (".." </> "chusql-web" </> "frontend")
-        nodeModules <- doesDirectoryExist (".." </> "chusql-web" </> "node_modules")
-        viteConfig <- doesFileExist (".." </> "chusql-web" </> "frontend" </> "vite.config.ts")
-        packageJson <- doesFileExist (".." </> "chusql-web" </> "frontend" </> "package.json")
-        frontendDir `shouldBe` False
-        nodeModules `shouldBe` False
-        viteConfig `shouldBe` False
-        packageJson `shouldBe` False
-
--- | 真静态目录里的资源由服务端交付（临时目录那套在 securitySpec 里另测）
-staticServeSpec :: Spec
-staticServeSpec = describe "Static front end served by the server" $
-    withWorld "static" $ \_ -> do
-        it "the home page carries the app root and the per-page nonce meta" $ do
-            res <- get "/"
-            check (hasStatus res 200)
-            let body = BL.toStrict (WT.simpleBody res)
-            check (body `shouldSatisfy` BS.isInfixOf "id=\"root\"")
-            check (body `shouldSatisfy` BS.isInfixOf "chusql-style-nonce")
-        it "the app script and stylesheet are served with their content types" $ do
-            js <- get "/static/app.js"
-            check (hasStatus js 200)
-            check (lookup "Content-Type" (WT.simpleHeaders js) `shouldBe` Just "text/javascript; charset=utf-8")
-            css <- get "/static/style.css"
-            check (hasStatus css 200)
-            check (lookup "Content-Type" (WT.simpleHeaders css) `shouldBe` Just "text/css; charset=utf-8")
-        it "traversal and unknown files are still rejected" $ do
-            get "/static/..%2fchusql.toml" `shouldRespondWith` 404
-            get "/static/nope.js" `shouldRespondWith` 404
-
-actionsSpec :: Spec
-actionsSpec = describe "One-click actions -> one SQL statement (ChuSQL.Web.Actions)" $ do
-    it "create table: column types and identifiers are validated" $ do
-        createTableSql (CreateTableSpec "customers" [ColumnSpec "id" "int", ColumnSpec "name" "str"])
-            `shouldBe` Right "CREATE TABLE customers (id int, name str)"
-        createTableSql (CreateTableSpec "bad name" [ColumnSpec "id" "int"]) `shouldSatisfy` isLeftE
-        createTableSql (CreateTableSpec "t" []) `shouldSatisfy` isLeftE
-        createTableSql (CreateTableSpec "t" [ColumnSpec "id" "blob"])
-            `shouldBe` Right "CREATE TABLE t (id blob)"
-        createTableSql (CreateTableSpec "t" [ColumnSpec "1bad" "int"]) `shouldSatisfy` isLeftE
-        createTableSql (CreateTableSpec "t" [ColumnSpec "id" "BOOL"]) `shouldSatisfy` isRightE
-    it "string literal escaping: single quotes doubled, the rest unchanged" $ do
-        sqlLiteral (VStr "O'Brien") `shouldBe` "'O''Brien'"
-        sqlLiteral (VStr "a\\b") `shouldBe` "'a\\b'"
-        sqlLiteral (VInt 7) `shouldBe` "7"
-        sqlLiteral (VBool True) `shouldBe` "TRUE"
-        sqlLiteral (VBool False) `shouldBe` "FALSE"
-    it "statement shapes for insert / update / delete / index" $ do
-        insertRowSql "t" [("id", VInt 1), ("name", VStr "a")]
-            `shouldBe` Right "INSERT INTO t (id, name) VALUES (1, 'a')"
-        insertRowsSql "t" [[("id", VInt 1)], [("id", VInt 2)]]
-            `shouldBe` Right "INSERT INTO t (id) VALUES (1), (2)"
-        updateRowSql "t" 3 [("age", VInt 9)]
-            `shouldBe` Right "UPDATE t SET age = 9 WHERE id = 3"
-        deleteRowSql "t" 3 `shouldBe` Right "DELETE FROM t WHERE id = 3"
-        createIndexSql "t" "sku" `shouldBe` Right "CREATE INDEX ON t (sku)"
-        dropIndexSql "t" "sku" `shouldBe` Right "DROP INDEX ON t (sku)"
-        dropTableSql "t" `shouldBe` Right "DROP TABLE t"
-    it "injection shapes cannot get in (the whitelist runs before SQL is built)" $ do
-        dropTableSql "users; DROP TABLE users" `shouldSatisfy` isLeftE
-        createIndexSql "t" "c) --" `shouldSatisfy` isLeftE
-        insertRowSql "t" [("id; DROP", VInt 1)] `shouldSatisfy` isLeftE
-        insertRowSql "t" [] `shouldSatisfy` isLeftE
-    it "JSON values coerce by column type: int takes numbers/numeric strings, str takes strings, bool takes booleans/true|false" $ do
-        coerceValue TInt (A.Number 3) `shouldBe` Right (VInt 3)
-        coerceValue TInt (A.String "42") `shouldBe` Right (VInt 42)
-        coerceValue TInt (A.String "x") `shouldSatisfy` isLeftE
-        coerceValue TStr (A.String "hi") `shouldBe` Right (VStr "hi")
-        coerceValue TStr (A.Number 1) `shouldSatisfy` isLeftE
-        coerceValue TBool (A.Bool True) `shouldBe` Right (VBool True)
-        coerceValue TBool (A.String "false") `shouldBe` Right (VBool False)
-        coerceValue TBool (A.String "maybe") `shouldSatisfy` isLeftE
-    it "column type parsing: int/bigint/smallint/str/text/varchar/char/float/double/decimal/date/timestamp/bool/blob are recognised" $ do
-        map columnTypeOf ["int", "INTEGER", "str", "text", "varchar", "bool", "boolean"]
-            `shouldBe` map Just [TInt, TInt, TStr, TStr, TStr, TBool, TBool]
-        columnTypeOf "blob" `shouldBe` Just (plainColumn CBlob)
-        -- 类型带参数时才认得出来，未知类型与空串都给 Nothing
-        map columnTypeOf ["bigint", "smallint", "float", "double", "date", "timestamp"]
-            `shouldBe` map Just [plainColumn CBigInt, plainColumn CSmallInt, plainColumn CFloat, plainColumn CDouble, plainColumn CDate, plainColumn CTimestamp]
-        map columnTypeOf ["varchar(20)", "char(3)", "decimal(8,2)"]
-            `shouldBe` map Just [plainColumn (CVarchar 20), plainColumn (CChar 3), plainColumn (CDecimal 8 2)]
-        map columnTypeOf ["nope", ""] `shouldBe` [Nothing, Nothing]
-
-oneClickSpec :: FilePath -> Spec
-oneClickSpec staticDir = describe "One-click action endpoints" $
-    withWorld staticDir $ \_ -> do
-        it "create -> insert -> update -> delete -> drop through the structured endpoints (incl. bool columns and quote escaping)" $ do
-            res <- loginAs "admin" "s3cret"
-            let hs = cookieHeaders res
-            created <-
-                postWith
-                    hs
-                    "/api/tables"
-                    "{\"name\":\"customers\",\"columns\":[{\"name\":\"id\",\"type\":\"int\"},{\"name\":\"name\",\"type\":\"str\"},{\"name\":\"vip\",\"type\":\"bool\"}]}"
-            check (hasStatus created 200)
-            inserted <- postWith hs "/api/tables/customers/rows" "{\"values\":{\"id\":1,\"name\":\"O'Brien\",\"vip\":true}}"
-            check (hasStatus inserted 200)
-            page <- getWith hs "/api/tables/customers/rows"
-            check (asInt (at "total" (jsonBody page)) `shouldBe` 1)
-            check (firstRow page `shouldBe` [A.Number 1, A.String "O'Brien", A.Bool True])
-            patched <-
-                request
-                    "PATCH"
-                    "/api/tables/customers/rows/1"
-                    (("Content-Type", "application/json") : hs)
-                    "{\"values\":{\"vip\":false,\"name\":\"O''Brien\"}}"
-            check (hasStatus patched 200)
-            afterEdit <- getWith hs "/api/tables/customers/rows"
-            check (firstRow afterEdit `shouldBe` [A.Number 1, A.String "O''Brien", A.Bool False])
-            removed <- request "DELETE" "/api/tables/customers/rows/1" hs ""
-            check (hasStatus removed 200)
-            empty <- getWith hs "/api/tables/customers/rows"
-            check (asInt (at "total" (jsonBody empty)) `shouldBe` 0)
-            dropped <- request "DELETE" "/api/tables/customers" hs ""
-            check (hasStatus dropped 200)
-            gone <- getWith hs "/api/tables/customers"
-            check (hasStatus gone 404)
-        it "bad input always gives 400/404, never a half-built SQL" $ do
-            res <- loginAs "admin" "s3cret"
-            let hs = cookieHeaders res
-            badName <- postWith hs "/api/tables" "{\"name\":\"bad name\",\"columns\":[{\"name\":\"id\",\"type\":\"int\"}]}"
-            check (hasStatus badName 400)
-            unknownColumn <- postWith hs "/api/tables/users/rows" "{\"values\":{\"nope\":1}}"
-            check (hasStatus unknownColumn 400)
-            nullableTable <- postWith hs "/api/tables" "{\"name\":\"nullable_t\",\"columns\":[{\"name\":\"id\",\"type\":\"int\"},{\"name\":\"name\",\"type\":\"str\"},{\"name\":\"age\",\"type\":\"int\"}]}"
-            check (hasStatus nullableTable 200)
-            partial <- postWith hs "/api/tables/nullable_t/rows" "{\"values\":{\"id\":99}}"
-            check (hasStatus partial 200)
-            filled <- getWith hs "/api/tables/nullable_t/rows"
-            check $ do
-                asInt (at "total" (jsonBody filled)) `shouldBe` 1
-                firstRow filled `shouldBe` [A.Number 99, A.Null, A.Null]
-            badBody <- postWith hs "/api/tables/users/rows" "not json"
-            check (hasStatus badBody 400)
-            badId <- request "PATCH" "/api/tables/users/rows/abc" (("Content-Type", "application/json") : hs) "{\"values\":{\"age\":1}}"
-            check (hasStatus badId 400)
-            noTable <- postWith hs "/api/tables/nope/rows" "{\"values\":{\"id\":1}}"
-            check (hasStatus noTable 404)
-            badType <- postWith hs "/api/tables/users/rows" "{\"values\":{\"id\":1,\"name\":\"x\",\"age\":\"old\"}}"
-            check (hasStatus badType 400)
-        it "index: any column type can be indexed, the built-in id index cannot be dropped" $ do
-            res <- loginAs "admin" "s3cret"
-            let hs = cookieHeaders res
-            okIndex <- postWith hs "/api/tables/users/indexes" "{\"column\":\"age\"}"
-            check (hasStatus okIndex 200)
-            stringIndex <- postWith hs "/api/tables/users/indexes" "{\"column\":\"name\"}"
-            check (hasStatus stringIndex 200)
-            droppedString <- request "DELETE" "/api/tables/users/indexes/name" hs ""
-            check (hasStatus droppedString 200)
-            dropped <- request "DELETE" "/api/tables/users/indexes/age" hs ""
-            check (hasStatus dropped 200)
-            builtIn <- request "DELETE" "/api/tables/users/indexes/id" hs ""
-            check (hasStatus builtIn 400)
-        it "drop column: the column is gone but rows stay; built-in id and unknown column/table are rejected" $ do
-            res <- loginAs "admin" "s3cret"
-            let hs = cookieHeaders res
-            created <- postWith hs "/api/tables" "{\"name\":\"drop_col_t\",\"columns\":[{\"name\":\"id\",\"type\":\"int\"},{\"name\":\"code\",\"type\":\"int\"},{\"name\":\"note\",\"type\":\"str\"}]}"
-            check (hasStatus created 200)
-            inserted <- postWith hs "/api/tables/drop_col_t/rows" "{\"values\":{\"id\":1,\"code\":7,\"note\":\"a\"}}"
-            check (hasStatus inserted 200)
-            droppedColumn <- request "DELETE" "/api/tables/drop_col_t/columns/code" hs ""
-            check (hasStatus droppedColumn 200)
-            info <- getWith hs "/api/tables/drop_col_t"
-            check $ do
-                let names = map (asText . at "name") (items (at "columns" (jsonBody info)))
-                names `shouldBe` ["id", "note"]
-            page <- getWith hs "/api/tables/drop_col_t/rows"
-            check (hasStatus page 200)
-            check (map asText (items (at "columns" (jsonBody page))) `shouldBe` ["id", "note"])
-            check (firstRow page `shouldBe` [A.Number 1, A.String "a"])
-            builtInColumn <- request "DELETE" "/api/tables/drop_col_t/columns/id" hs ""
-            check (hasStatus builtInColumn 400)
-            unknownColumn <- request "DELETE" "/api/tables/drop_col_t/columns/nope" hs ""
-            check (hasStatus unknownColumn 400)
-            unknownTable <- request "DELETE" "/api/tables/nope/columns/code" hs ""
-            check (hasStatus unknownTable 404)
-        it "demo data: fills what is missing, repeated clicks do not re-seed (users/orders already exist in memory)" $ do
-            res <- loginAs "admin" "s3cret"
-            let hs = cookieHeaders res
-            first <- postWith hs "/api/demo-data" "{}"
-            check (hasStatus first 200)
-            check (arrayLen (at "created" (jsonBody first)) + arrayLen (at "skipped" (jsonBody first)) `shouldBe` 3)
-            products <- getWith hs "/api/tables/products/rows?limit=100"
-            check (asInt (at "total" (jsonBody products)) `shouldBe` 8)
-            users <- getWith hs "/api/tables/users/rows?limit=100"
-            check (asInt (at "total" (jsonBody users)) `shouldBe` 5)
-            again <- postWith hs "/api/demo-data" "{}"
-            check (hasStatus again 200)
-            check (arrayLen (at "created" (jsonBody again)) `shouldBe` 0)
-            check (arrayLen (at "skipped" (jsonBody again)) `shouldBe` 3)
-            usersAgain <- getWith hs "/api/tables/users/rows?limit=100"
-            check (asInt (at "total" (jsonBody usersAgain)) `shouldBe` 5)
-
-authSpec :: FilePath -> Spec
-authSpec staticDir = do
-    describe "Auth: not logged in" $
-        withWorld staticDir $ \_ -> do
-            it "health check needs no login" $
-                get "/api/health" `shouldRespondWith` 200
-            it "table list gives 401" $
-                get "/api/tables" `shouldRespondWith` 401
-            it "status needs no login and reports storage up (the memory backend is always up)" $ do
-                res <- get "/api/status"
-                check (hasStatus res 200)
-                check (asText (at "storage" (jsonBody res)) `shouldBe` "up")
-            it "the home page needs no login (the frontend switches to the login view)" $
-                get "/" `shouldRespondWith` 200
-
-    describe "Auth: login" $
-        withWorld staticDir $ \_ -> do
-            it "correct password: 204 + session cookie (HttpOnly / SameSite=Strict)" $ do
-                res <- loginAs "admin" "s3cret"
-                check (hasStatus res 204)
-                let rawCookie = fmap TE.decodeUtf8 (lookup "Set-Cookie" (WT.simpleHeaders res))
-                check (rawCookie `shouldSatisfy` maybe False (T.isInfixOf "HttpOnly"))
-                check (rawCookie `shouldSatisfy` maybe False (T.isInfixOf "SameSite=Strict"))
-                check (sessionCookieOf res `shouldSatisfy` maybe False (not . T.null))
-            it "wrong password gives 401" $
-                loginAs "admin" "nope" `shouldRespondWith` 401
-            it "the username is case-insensitive but the password must match" $
-                loginAs "ADMIN" "s3cret" `shouldRespondWith` 204
-            it "non-JSON body gives 400" $
-                jsonRequest methodPost "/api/login" "{not json" `shouldRespondWith` 400
-            it "a cookie allows session lookup" $ do
-                res <- loginAs "admin" "s3cret"
-                cs <- getWith (cookieHeaders res) "/api/session"
-                check (hasStatus cs 200)
-                check (asText (at "user" (jsonBody cs)) `shouldBe` "admin")
-            it "logout invalidates the session immediately" $ do
-                res <- loginAs "admin" "s3cret"
-                out <- postWith (cookieHeaders res) "/api/logout" "{}"
-                check (hasStatus out 204)
-                gone <- getWith (cookieHeaders res) "/api/tables"
-                check (hasStatus gone 401)
-            it "a forged token gets nothing" $
-                getWith [("Cookie", "chusql_session=deadbeef")] "/api/tables" `shouldRespondWith` 401
-
-    describe "Auth: login failure rate limiting" $
-        withWorld staticDir $ \_ -> do
-            it "after 5 failures the 6th is 429 (even with the right password)" $ do
-                mapM_ (const (loginAs "admin" "wrong")) [1 :: Int, 2, 3, 4, 5]
-                blocked <- loginAs "admin" "s3cret"
-                check (hasStatus blocked 429)
-                check (lookup "Retry-After" (WT.simpleHeaders blocked) `shouldSatisfy` maybe False (not . BS.null))
-
--- | 免密管理员：只有管理员能用空口令进来，普通账号一律 403
-passwordlessSpec :: FilePath -> Spec
-passwordlessSpec staticDir = describe "Auth: passwordless administrator" $
-    withPasswordlessWorld staticDir $ \_ -> do
-        it "the administrator signs in with an empty password" $ do
-            res <- loginAs "admin" ""
-            check (hasStatus res 204)
-            check (sessionCookieOf res `shouldSatisfy` maybe False (not . T.null))
-        it "a non-empty password is refused with 401" $
-            loginAs "admin" "s3cret" `shouldRespondWith` 401
-        it "an ordinary account is refused with 403 while the server is passwordless" $ do
-            res <- loginAs "someone" "whatever"
-            check (hasStatus res 403)
-            check (asText (at "error" (jsonBody res)) `shouldBe` "forbidden")
-        it "an unknown account with an empty password is refused too" $ do
-            res <- loginAs "ghost" ""
-            check (hasStatus res 403)
-
-catalogSpec :: FilePath -> Spec
-catalogSpec staticDir = describe "Catalogue and paged browsing" $
-    withWorld staticDir $ \_ -> do
-        it "table list carries row counts, columns, indexes and stats" $ do
-            res <- loginAs "admin" "s3cret"
-            list <- getWith (cookieHeaders res) "/api/tables"
-            check (hasStatus list 200)
-            check $ do
-                let tables = items (jsonBody list)
-                map (asText . at "table") tables `shouldBe` ["users", "orders"]
-                case tables of
-                    [] -> expectationFailure "the table list is empty"
-                    (usersInfo : _) -> do
-                        asInt (at "rowCount" usersInfo) `shouldBe` 5
-                        map (asText . at "name") (items (at "columns" usersInfo)) `shouldBe` ["id", "name", "age"]
-                        let cols = items (at "columns" usersInfo)
-                        case cols of
-                            (firstCol : secondCol : _) -> do
-                                at "primaryKey" firstCol `shouldBe` A.Bool True
-                                at "prime" firstCol `shouldBe` A.Bool True
-                                asInt (at "distinct" firstCol) `shouldBe` 5
-                                at "primaryKey" secondCol `shouldBe` A.Bool False
-                                at "prime" secondCol `shouldBe` A.Bool False
-                                at "indexed" secondCol `shouldBe` A.Bool False
-                            _ -> expectationFailure "users should have three columns"
-        it "missing table gives 404" $ do
-            res <- loginAs "admin" "s3cret"
-            missing <- getWith (cookieHeaders res) "/api/tables/nope"
-            check (hasStatus missing 404)
-        it "invalid table name gives 400 (never built into SQL)" $ do
-            res <- loginAs "admin" "s3cret"
-            bad <- getWith (cookieHeaders res) "/api/tables/1bad/rows"
-            check (hasStatus bad 400)
-        it "paging: limit/offset apply and total is the full row count" $ do
-            res <- loginAs "admin" "s3cret"
-            page <- getWith (cookieHeaders res) "/api/tables/users/rows?limit=2&offset=1"
-            check (hasStatus page 200)
-            check $ do
-                let body = jsonBody page
-                asInt (at "total" body) `shouldBe` 5
-                asInt (at "limit" body) `shouldBe` 2
-                asInt (at "offset" body) `shouldBe` 1
-                let rows = items (at "rows" body)
-                length rows `shouldBe` 2
-                nth 0 rows `shouldBe` Just (A.Array (V.fromList [A.Number 2, A.String "user2", A.Number 22]))
-        it "non-integer limit gives 400" $ do
-            res <- loginAs "admin" "s3cret"
-            bad <- getWith (cookieHeaders res) "/api/tables/users/rows?limit=abc"
-            check (hasStatus bad 400)
-        it "empty tables are browsable too (columns come from the catalogue)" $ do
-            res <- loginAs "admin" "s3cret"
-            created <- postWith (cookieHeaders res) "/api/query" "{\"sql\":\"CREATE TABLE empty_t (id int, name str)\"}"
-            check (hasStatus created 200)
-            emptyPage <- getWith (cookieHeaders res) "/api/tables/empty_t/rows"
-            check (hasStatus emptyPage 200)
-            check $ do
-                asInt (at "total" (jsonBody emptyPage)) `shouldBe` 0
-                map asText (items (at "columns" (jsonBody emptyPage))) `shouldBe` ["id", "name"]
-        it "filter param: equality per column, multiple conditions are AND (the WHERE row above the data grid)" $ do
-            res <- loginAs "admin" "s3cret"
-            let hs = cookieHeaders res
-            one <- getWith hs "/api/tables/users/rows?filter=%5B%7B%22column%22%3A%22name%22%2C%22value%22%3A%22user2%22%7D%5D"
-            check (hasStatus one 200)
-            check $ do
-                asInt (at "total" (jsonBody one)) `shouldBe` 1
-                firstRow one `shouldBe` [A.Number 2, A.String "user2", A.Number 22]
-            two <-
-                getWith
-                    hs
-                    "/api/tables/users/rows?filter=%5B%7B%22column%22%3A%22age%22%2C%22value%22%3A%2223%22%7D%2C%7B%22column%22%3A%22id%22%2C%22value%22%3A%223%22%7D%5D"
-            check $ do
-                asInt (at "total" (jsonBody two)) `shouldBe` 1
-                firstRow two `shouldBe` [A.Number 3, A.String "user3", A.Number 23]
-        it "filter param: a blank cell counts as unfilled; unknown column / uncoercible value / non-JSON give 400" $ do
-            res <- loginAs "admin" "s3cret"
-            let hs = cookieHeaders res
-            blank <- getWith hs "/api/tables/users/rows?filter=%5B%7B%22column%22%3A%22name%22%2C%22value%22%3A%22%22%7D%5D"
-            check (asInt (at "total" (jsonBody blank)) `shouldBe` 5)
-            unknown <- getWith hs "/api/tables/users/rows?filter=%5B%7B%22column%22%3A%22nope%22%2C%22value%22%3A%22x%22%7D%5D"
-            check (hasStatus unknown 400)
-            badType <- getWith hs "/api/tables/users/rows?filter=%5B%7B%22column%22%3A%22age%22%2C%22value%22%3A%22old%22%7D%5D"
-            check (hasStatus badType 400)
-            notJson <- getWith hs "/api/tables/users/rows?filter=oops"
-            check (hasStatus notJson 400)
-
--- | 换一组更小的上限再跑
-limitsSpec :: FilePath -> Spec
-limitsSpec staticDir = describe "Paging and row limits follow the config" $ do
-    appEnv <- runIO (freshWorld staticDir)
-    runIO (setLive appEnv (defaultLive{lvPageSize = 1, lvMaxPageSize = 2, lvMaxRows = 2}))
-    with (webApp appEnv) $ do
-        it "a missing limit uses the configured page size" $ do
-            res <- loginAs "admin" "s3cret"
-            page <- getWith (cookieHeaders res) "/api/tables/users/rows"
-            check (hasStatus page 200)
-            check (asInt (at "limit" (jsonBody page)) `shouldBe` 1)
-        it "a limit above the cap is clamped to maxPageSize" $ do
-            res <- loginAs "admin" "s3cret"
-            page <- getWith (cookieHeaders res) "/api/tables/users/rows?limit=99"
-            check (asInt (at "limit" (jsonBody page)) `shouldBe` 2)
-        it "query results cap at maxRows rows and set truncated" $ do
-            res <- loginAs "admin" "s3cret"
-            out <- postWith (cookieHeaders res) "/api/query" "{\"sql\":\"SELECT * FROM users\"}"
-            check (hasStatus out 200)
-            check (length (items (at "rows" (jsonBody out))) `shouldBe` 2)
-            check (at "truncated" (jsonBody out) `shouldBe` A.Bool True)
-
-sqlSpec :: FilePath -> Spec
-sqlSpec staticDir = describe "SQL console" $
-    withWorld staticDir $ \_ -> do
-        it "SELECT returns columns and rows" $ do
-            res <- loginAs "admin" "s3cret"
-            out <- postWith (cookieHeaders res) "/api/query" "{\"sql\":\"SELECT name, age FROM users WHERE age > 22 ORDER BY age\"}"
-            check (hasStatus out 200)
-            check $ do
-                let body = jsonBody out
-                map asText (items (at "columns" body)) `shouldBe` ["name", "age"]
-                length (items (at "rows" body)) `shouldBe` 3
-                asInt (at "rowCount" body) `shouldBe` 3
-        it "multi-row INSERT is supported" $ do
-            res <- loginAs "admin" "s3cret"
-            _ <- postWith (cookieHeaders res) "/api/query" "{\"sql\":\"INSERT INTO users (id, name, age) VALUES (11, 'a', 1), (12, 'b', 2)\"}"
-            out <- postWith (cookieHeaders res) "/api/query" "{\"sql\":\"SELECT * FROM users WHERE id > 10\"}"
-            check (length (items (at "rows" (jsonBody out))) `shouldBe` 2)
-        it "syntax error: 400 + the original message" $ do
-            res <- loginAs "admin" "s3cret"
-            bad <- postWith (cookieHeaders res) "/api/query" "{\"sql\":\"SELECT FROM WHERE\"}"
-            check (hasStatus bad 400)
-            check $ do
-                asText (at "error" (jsonBody bad)) `shouldBe` "query_error"
-                asText (at "message" (jsonBody bad)) `shouldSatisfy` (not . T.null)
-        it "missing table gives 404" $ do
-            res <- loginAs "admin" "s3cret"
-            missing <- postWith (cookieHeaders res) "/api/query" "{\"sql\":\"SELECT * FROM nope\"}"
-            check (hasStatus missing 404)
-        it "empty sql gives 400" $ do
-            res <- loginAs "admin" "s3cret"
-            bad <- postWith (cookieHeaders res) "/api/query" "{\"sql\":\"   \"}"
-            check (hasStatus bad 400)
-
--- | 设置接口：读写配置与改口令
-settingsSpec :: FilePath -> Spec
-settingsSpec staticDir = do
-    describe "Settings endpoints" $
-        withWorldAt staticDir "settings" $ \appEnv -> do
-            it "not logged in gives 401" $
-                get "/api/settings" `shouldRespondWith` 401
-            it "read settings: every catalogue key is present and secrets only report whether set" $ do
-                res <- loginAs "admin" "s3cret"
-                body <- getWith (cookieHeaders res) "/api/settings"
-                check (hasStatus body 200)
-                check $ do
-                    let payload = jsonBody body
-                        entries = items (at "items" payload)
-                    at "owner" payload `shouldBe` A.Bool True
-                    T.null (asText (at "file" payload)) `shouldBe` False
-                    length entries `shouldBe` length settingCatalogue
-                    map (asText . at "key") entries `shouldBe` map siKey settingCatalogue
-                    let secrets = [i | i <- entries, asText (at "kind" i) == "secret"]
-                    secrets `shouldSatisfy` (not . null)
-                    map (asText . at "value") secrets `shouldSatisfy` all T.null
-                    let port = headEntry "port" entries
-                    asText (at "source" port) `shouldBe` "default"
-                    asText (at "value" port) `shouldBe` "7777"
-                    at "rootOnly" port `shouldBe` A.Bool True
-                    at "editable" port `shouldBe` A.Bool True
-                    at "restart" port `shouldBe` A.Bool True
-                    at "live" port `shouldBe` A.Bool False
-                    let rows = headEntry "rows-per-page" entries
-                    at "live" rows `shouldBe` A.Bool True
-                    at "restart" rows `shouldBe` A.Bool False
-            it "write settings: only catalogue keys are accepted and ints reject letters" $ do
-                res <- loginAs "admin" "s3cret"
-                unknown <- putWith (cookieHeaders res) "/api/settings" "{\"values\":{\"nope\":\"1\"}}"
-                check (hasStatus unknown 400)
-                badType <- putWith (cookieHeaders res) "/api/settings" "{\"values\":{\"rows-per-page\":\"abc\"}}"
-                check (hasStatus badType 400)
-                empty <- putWith (cookieHeaders res) "/api/settings" "{\"values\":{}}"
-                check (hasStatus empty 400)
-            it "write settings: live keys apply at once (page size + body limit)" $ do
-                res <- loginAs "admin" "s3cret"
-                saved <- putWith (cookieHeaders res) "/api/settings" "{\"values\":{\"rows-per-page\":\"2\",\"body-limit\":\"200\"}}"
-                check (hasStatus saved 200)
-                check (map asText (items (at "applied" (jsonBody saved))) `shouldMatchList` ["rows-per-page", "body-limit"])
-                page <- getWith (cookieHeaders res) "/api/tables/users/rows"
-                check (asInt (at "limit" (jsonBody page)) `shouldBe` 2)
-                live <- liftIO (readLive appEnv)
-                check (lvPageSize live `shouldBe` 2)
-                check (lvBodyLimit live `shouldBe` 200)
-                big <- jsonRequest methodPost "/api/query" (BL.fromStrict (BS.replicate 400 97))
-                check (hasStatus big 413)
-            it "write settings: restart-only keys are named" $ do
-                res <- loginAs "admin" "s3cret"
-                saved <- putWith (cookieHeaders res) "/api/settings" "{\"values\":{\"static-dir\":\"static\"}}"
-                check (hasStatus saved 200)
-                check (map asText (items (at "restartRequired" (jsonBody saved))) `shouldContain` ["static-dir"])
-            it "write settings: persisted values survive the next start (read back) and are sourced as settings file" $ do
-                res <- loginAs "admin" "s3cret"
-                _ <- putWith (cookieHeaders res) "/api/settings" "{\"values\":{\"max-rows\":\"77\"}}"
-                stored <- liftIO (readSettingsFile (aeSettingsFile appEnv))
-                check (Map.lookup "max-rows" stored `shouldBe` Just "77")
-                body <- getWith (cookieHeaders res) "/api/settings"
-                check $ do
-                    let entries = items (at "items" (jsonBody body))
-                    asText (at "source" (headEntry "max-rows" entries)) `shouldBe` "settings file"
-                    asText (at "value" (headEntry "max-rows" entries)) `shouldBe` "77"
-            it "changing the max-rows setting truncates query results" $ do
-                res <- loginAs "admin" "s3cret"
-                _ <- putWith (cookieHeaders res) "/api/settings" "{\"values\":{\"max-rows\":\"2\"}}"
-                out <- postWith (cookieHeaders res) "/api/query" "{\"sql\":\"SELECT * FROM users\"}"
-                check (hasStatus out 200)
-                check (length (items (at "rows" (jsonBody out))) `shouldBe` 2)
-                check (at "truncated" (jsonBody out) `shouldBe` A.Bool True)
-            it "non-config account: critical settings give 403, normal ones pass" $ do
-                admin <- loginAs "admin" "s3cret"
-                made <- postWith (systemHeaders (cookieHeaders admin)) "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"guest\",\"password\":\"guest-password\"}}"
-                check (hasStatus made 200)
-                guest <- loginAs "guest" "guest-password"
-                check (hasStatus guest 204)
-                let guestHeaders = cookieHeaders guest
-                forbidden <- putWith guestHeaders "/api/settings" "{\"values\":{\"port\":\"9999\"}}"
-                check (hasStatus forbidden 403)
-                check (asText (at "error" (jsonBody forbidden)) `shouldBe` "forbidden")
-                allowed <- putWith guestHeaders "/api/settings" "{\"values\":{\"rows-per-page\":\"4\"}}"
-                check (hasStatus allowed 200)
-                reloaded <- getWith guestHeaders "/api/settings"
-                check $ do
-                    let entries = items (at "items" (jsonBody reloaded))
-                        port = headEntry "port" entries
-                    asText (at "value" port) `shouldBe` "7777"
-                    at "editable" port `shouldBe` A.Bool False
-                    at "editable" (headEntry "rows-per-page" entries) `shouldBe` A.Bool True
-
-    describe "Account table (system table, administrator only)" $
-        withWorldAt staticDir "accounts" $ \appEnv -> do
-            it "not logged in gives 401 on every account-table route" $ do
-                getWith [] "/api/tables" `shouldRespondWith` 401
-                getWith (systemHeaders []) "/api/tables/__chusql_users" `shouldRespondWith` 401
-                getWith (systemHeaders []) "/api/tables/__chusql_users/rows" `shouldRespondWith` 401
-                postWith (systemHeaders []) "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"guest\",\"password\":\"guest-password\"}}" `shouldRespondWith` 401
-                patchWith (systemHeaders []) "/api/tables/__chusql_users/rows/guest" "{\"values\":{\"password\":\"guest-password\"}}" `shouldRespondWith` 401
-                deleteWith (systemHeaders []) "/api/tables/__chusql_users/rows/guest" `shouldRespondWith` 401
-            it "the retired account routes are gone" $ do
-                res <- loginAs "admin" "s3cret"
-                let hs = cookieHeaders res
-                switched <- postWith hs "/api/account/switch" "{\"user\":\"someone\",\"password\":\"someone-password\"}"
-                check (hasStatus switched 404)
-                listed <- getWith hs "/api/accounts"
-                check (hasStatus listed 404)
-                selfService <- postWith hs "/api/account/password" "{\"current\":\"s3cret\",\"next\":\"longenough\"}"
-                check (hasStatus selfService 404)
-            it "the administrator sees the account table with a secret password column" $ do
-                admin <- loginAs "admin" "s3cret"
-                body <- getWith (systemHeaders (cookieHeaders admin)) "/api/tables"
-                check (hasStatus body 200)
-                check $ do
-                    let entries = items (jsonBody body)
-                        account = tableEntry "__chusql_users" entries
-                        users = tableEntry "users" entries
-                    at "table" account `shouldBe` A.String "__chusql_users"
-                    at "kind" account `shouldBe` A.String "system"
-                    map (asText . at "name") (items (at "columns" account)) `shouldBe` ["id", "user", "password", "registered_at", "last_login_at"]
-                    map (asBool . at "secret") (items (at "columns" account)) `shouldBe` [False, False, True, False, False]
-                    map (asBool . at "primaryKey") (items (at "columns" account)) `shouldBe` [True, False, False, False, False]
-                    map (asText . at "type") (items (at "columns" account)) `shouldBe` ["int", "varchar(64)", "varchar(256)", "timestamp", "timestamp"]
-                    map (asBool . at "indexed") (items (at "columns" account)) `shouldBe` [True, True, False, False, False]
-                    at "kind" users `shouldBe` A.String "table"
-                detail <- getWith (systemHeaders (cookieHeaders admin)) "/api/tables/__chusql_users"
-                check (hasStatus detail 200)
-                check (at "kind" (jsonBody detail) `shouldBe` A.String "system")
-            it "insert, update and delete on the account table are CREATE, ALTER and DROP USER" $ do
-                admin <- loginAs "admin" "s3cret"
-                let hs = cookieHeaders admin
-                made <- postWith (systemHeaders hs) "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"Alice\",\"password\":\"alice-password\"}}"
-                check (hasStatus made 200)
-                page <- getWith (systemHeaders hs) "/api/tables/__chusql_users/rows"
-                check (hasStatus page 200)
-                check $ do
-                    let rows = items (at "rows" (jsonBody page))
-                    map asText (items (at "columns" (jsonBody page))) `shouldBe` ["id", "user", "password", "registered_at", "last_login_at"]
-                    map (asText . (V.! 1) . asArray) rows `shouldBe` ["alice"]
-                    length rows `shouldBe` 1
-                    case firstRow page of
-                        [_, _, _, A.String registered, lastLogin] -> do
-                            registered `shouldSatisfy` (/= "")
-                            lastLogin `shouldBe` A.Null
-                        other -> expectationFailure ("unexpected account row: " ++ show other)
-                repeated <- postWith (systemHeaders hs) "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"alice\",\"password\":\"alice-password\"}}"
-                check (hasStatus repeated 409)
-                alice <- loginAs "alice" "alice-password"
-                check (hasStatus alice 204)
-                adminAgain <- loginAs "admin" "s3cret"
-                let hsAgain = cookieHeaders adminAgain
-                stamped <- getWith (systemHeaders hsAgain) "/api/tables/__chusql_users/rows"
-                check $ do
-                    hasStatus stamped 200
-                    case firstRow stamped of
-                        [_, _, _, _, lastLogin] -> lastLogin `shouldSatisfy` (/= A.Null)
-                        other -> expectationFailure ("unexpected account row: " ++ show other)
-                changed <- patchWith (systemHeaders hsAgain) "/api/tables/__chusql_users/rows/alice" "{\"values\":{\"password\":\"alice-other-pass\"}}"
-                check (hasStatus changed 200)
-                stalePassword <- loginAs "alice" "alice-password"
-                check (hasStatus stalePassword 401)
-                freshPassword <- loginAs "alice" "alice-other-pass"
-                check (hasStatus freshPassword 204)
-                adminLast <- loginAs "admin" "s3cret"
-                let hsLast = cookieHeaders adminLast
-                renamed <- patchWith (systemHeaders hsLast) "/api/tables/__chusql_users/rows/alice" "{\"values\":{\"user\":\"bob\"}}"
-                check (hasStatus renamed 400)
-                unknown <- deleteWith (systemHeaders hsLast) "/api/tables/__chusql_users/rows/nobody"
-                check (hasStatus unknown 404)
-                dropped <- deleteWith (systemHeaders hsLast) "/api/tables/__chusql_users/rows/alice"
-                check (hasStatus dropped 200)
-                gone <- loginAs "alice" "alice-other-pass"
-                check (hasStatus gone 401)
-            it "the account table can be sorted and filtered by user but not by password" $ do
-                admin <- loginAs "admin" "s3cret"
-                let hs = cookieHeaders admin
-                _ <- postWith (systemHeaders hs) "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"bob\",\"password\":\"bob-password\"}}"
-                _ <- postWith (systemHeaders hs) "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"amy\",\"password\":\"amy-password\"}}"
-                sorted <- getWith (systemHeaders hs) "/api/tables/__chusql_users/rows?sort=user&dir=asc"
-                check (hasStatus sorted 200)
-                check $ do
-                    let names = map (asText . (V.! 1) . asArray) (items (at "rows" (jsonBody sorted)))
-                    names `shouldSatisfy` \ns -> ns == sort ns && all (`elem` ns) ["amy", "bob"]
-                filtered <- getWith (systemHeaders hs) "/api/tables/__chusql_users/rows?filter=%5B%7B%22column%22%3A%22user%22%2C%22value%22%3A%22bob%22%7D%5D"
-                check (hasStatus filtered 200)
-                check (map (asText . (V.! 1) . asArray) (items (at "rows" (jsonBody filtered))) `shouldBe` ["bob"])
-                byPassword <- getWith (systemHeaders hs) "/api/tables/__chusql_users/rows?sort=password"
-                check (hasStatus byPassword 400)
-                filterPassword <- getWith (systemHeaders hs) "/api/tables/__chusql_users/rows?filter=%5B%7B%22column%22%3A%22password%22%2C%22value%22%3A%22x%22%7D%5D"
-                check (hasStatus filterPassword 400)
-            it "the password column is stored as a hash, never in the settings file" $ do
-                admin <- loginAs "admin" "s3cret"
-                _ <- postWith (systemHeaders (cookieHeaders admin)) "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"dave\",\"password\":\"dave-password\"}}"
-                stored <- liftIO (beAccounts (aeBackend appEnv) ReqAccountsList)
-                check $ case stored of
-                    Left err -> expectationFailure err
-                    Right accounts -> case filter ((== "dave") . accountUser) accounts of
-                        [account] -> do
-                            accountRevision account `shouldBe` 1
-                            hashLooksValid (accountHash account) `shouldBe` True
-                            verifyPassword (accountHash account) "dave-password" `shouldBe` True
-                        _ -> expectationFailure "dave was not stored in the system table"
-                settings <- liftIO (readSettingsFile (aeSettingsFile appEnv))
-                check (Map.member "password" settings `shouldBe` False)
-                check (Map.member "password-hash" settings `shouldBe` False)
-            it "the account table has no indexes, cannot be dropped and cannot be renamed" $ do
-                admin <- loginAs "admin" "s3cret"
-                let hs = cookieHeaders admin
-                index <- postWith (systemHeaders hs) "/api/tables/__chusql_users/indexes" "{\"column\":\"user\"}"
-                check (hasStatus index 400)
-                dropIndex <- deleteWith (systemHeaders hs) "/api/tables/__chusql_users/indexes/user"
-                check (hasStatus dropIndex 400)
-                dropColumn <- deleteWith (systemHeaders hs) "/api/tables/__chusql_users/columns/password"
-                check (hasStatus dropColumn 400)
-                dropped <- deleteWith (systemHeaders hs) "/api/tables/__chusql_users"
-                check (hasStatus dropped 400)
-            it "an ordinary account never sees or touches the account table" $ do
-                admin <- loginAs "admin" "s3cret"
-                made <- postWith (systemHeaders (cookieHeaders admin)) "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"guest\",\"password\":\"guest-password\"}}"
-                check (hasStatus made 200)
-                guest <- loginAs "guest" "guest-password"
-                check (hasStatus guest 204)
-                let guestHeaders = cookieHeaders guest
-                listed <- getWith guestHeaders "/api/tables"
-                check (hasStatus listed 200)
-                check (map (asText . at "table") (items (jsonBody listed)) `shouldNotContain` ["__chusql_users"])
-                detail <- getWith (systemHeaders guestHeaders) "/api/tables/__chusql_users"
-                check (hasStatus detail 403)
-                rows <- getWith (systemHeaders guestHeaders) "/api/tables/__chusql_users/rows"
-                check (hasStatus rows 403)
-                created <- postWith (systemHeaders guestHeaders) "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"bob\",\"password\":\"bob-password\"}}"
-                check (hasStatus created 403)
-                reset <- patchWith (systemHeaders guestHeaders) "/api/tables/__chusql_users/rows/guest" "{\"values\":{\"password\":\"guest-other-pass\"}}"
-                check (hasStatus reset 403)
-                dropped <- deleteWith (systemHeaders guestHeaders) "/api/tables/__chusql_users/rows/guest"
-                check (hasStatus dropped 403)
-                stillThere <- loginAs "guest" "guest-password"
-                check (hasStatus stillThere 204)
-            it "CREATE USER / ALTER USER / DROP USER go through the SQL console" $ do
-                admin <- loginAs "admin" "s3cret"
-                created <- postWith (cookieHeaders admin) "/api/query" "{\"sql\":\"CREATE USER carol IDENTIFIED BY 'carol-password'\"}"
-                check (hasStatus created 200)
-                check (asInt (at "rowCount" (jsonBody created)) `shouldBe` 0)
-                changed <- postWith (cookieHeaders admin) "/api/query" "{\"sql\":\"ALTER USER carol IDENTIFIED BY 'carol-other-pass'\"}"
-                check (hasStatus changed 200)
-                dropped <- postWith (cookieHeaders admin) "/api/query" "{\"sql\":\"DROP USER carol\"}"
-                check (hasStatus dropped 200)
-                gone <- loginAs "carol" "carol-other-pass"
-                check (hasStatus gone 401)
-            it "an ordinary account cannot run account statements in the SQL console" $ do
-                admin <- loginAs "admin" "s3cret"
-                _ <- postWith (cookieHeaders admin) "/api/query" "{\"sql\":\"CREATE USER erin IDENTIFIED BY 'erin-password'\"}"
-                erin <- loginAs "erin" "erin-password"
-                check (hasStatus erin 204)
-                denials <- mapM (\sql -> postWith (cookieHeaders erin) "/api/query" (sqlBody sql))
-                    [ "DROP USER erin"
-                    , "ALTER USER erin IDENTIFIED BY 'erin-other-pass'"
-                    , "CREATE USER frank IDENTIFIED BY 'frank-password'"
-                    ]
-                check (map (statusCode . WT.simpleStatus) denials `shouldBe` [403, 403, 403])
-                stillThere <- loginAs "erin" "erin-password"
-                check (hasStatus stillThere 204)
-            it "the administrator credentials are locked in the settings API" $ do
-                admin <- loginAs "admin" "s3cret"
-                locked <- putWith (cookieHeaders admin) "/api/settings" "{\"values\":{\"password\":\"whatever\"}}"
-                check (hasStatus locked 403)
-                alsoLocked <- putWith (cookieHeaders admin) "/api/settings" "{\"values\":{\"user\":\"someone\"}}"
-                check (hasStatus alsoLocked 403)
-                body <- getWith (cookieHeaders admin) "/api/settings"
-                check $ do
-                    let entries = items (at "items" (jsonBody body))
-                    at "editable" (headEntry "user" entries) `shouldBe` A.Bool False
-                    at "locked" (headEntry "user" entries) `shouldBe` A.Bool True
-                    at "locked" (headEntry "rows-per-page" entries) `shouldBe` A.Bool False
-
-    describe "Databases (nothing is selected by default, system is administrator-only)" $
-        withWorldAt staticDir "databases" $ \_ -> do
-            it "lists exactly the databases that exist; the fixture database comes first" $ do
-                admin <- loginAs "admin" "s3cret"
-                body <- getWith (cookieHeaders admin) "/api/databases"
-                check (hasStatus body 200)
-                check (map asText (items (jsonBody body)) `shouldBe` ["test", "system"])
-            it "the account table is listed in system, never in test" $ do
-                admin <- loginAs "admin" "s3cret"
-                let hs = cookieHeaders admin
-                testList <- getWith hs "/api/tables"
-                check (map (asText . at "table") (items (jsonBody testList)) `shouldNotContain` ["__chusql_users"])
-                systemList <- getWith (systemHeaders hs) "/api/tables"
-                check (hasStatus systemList 200)
-                check (map (asText . at "table") (items (jsonBody systemList)) `shouldContain` ["__chusql_users"])
-            it "naming the account table from another database is a 400, not a silent lookup" $ do
-                admin <- loginAs "admin" "s3cret"
-                outside <- getWith (cookieHeaders admin) "/api/tables/__chusql_users/rows"
-                check (hasStatus outside 400)
-                check (asText (at "message" (jsonBody outside)) `shouldBe` "the account table lives in the system database")
-            it "an ordinary account gets 403 on system and never sees it in the list" $ do
-                admin <- loginAs "admin" "s3cret"
-                made <- postWith (systemHeaders (cookieHeaders admin)) "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"guest\",\"password\":\"guest-password\"}}"
-                check (hasStatus made 200)
-                guest <- loginAs "guest" "guest-password"
-                let guestHeaders = cookieHeaders guest
-                blocked <- getWith (systemHeaders guestHeaders) "/api/tables"
-                check (hasStatus blocked 403)
-                listed <- getWith guestHeaders "/api/databases"
-                check (hasStatus listed 200)
-                check (map asText (items (jsonBody listed)) `shouldBe` ["test"])
-            it "only the system database is reserved: test is an ordinary name" $ do
-                admin <- loginAs "admin" "s3cret"
-                let hs = cookieHeaders admin
-                reservedDrop <- deleteWith hs "/api/databases/system"
-                check (hasStatus reservedDrop 400)
-                check (asText (at "message" (jsonBody reservedDrop)) `shouldBe` "the system database cannot be dropped")
-                ordinaryDrop <- deleteWith hs "/api/databases/test"
-                check (hasStatus ordinaryDrop 400)
-                check (asText (at "message" (jsonBody ordinaryDrop)) `shouldSatisfy` T.isInfixOf "unavailable")
-            it "a request without a database header is a 400, not a silent default" $ do
-                admin <- loginAs "admin" "s3cret"
-                let _hs = cookieHeaders admin
-                bareTables <- request methodGet "/api/tables" [] ""
-                check (hasStatus bareTables 400)
-                check (asText (at "message" (jsonBody bareTables)) `shouldBe` "no database selected")
-                bareQuery <- request methodPost "/api/query" [("Content-Type", "application/json")] "{\"sql\":\"SELECT * FROM users\"}"
-                check (hasStatus bareQuery 400)
-                check (asText (at "error" (jsonBody bareQuery)) `shouldBe` "no_database")
-                stillListed <- request methodGet "/api/databases" [] ""
-                check (hasStatus stillListed 200)
-            it "CREATE DATABASE in the SQL console still goes to the storage layer" $ do
-                admin <- loginAs "admin" "s3cret"
-                created <- postWith (cookieHeaders admin) "/api/query" "{\"sql\":\"CREATE DATABASE sales\"}"
-                check (hasStatus created 400)
-                check (asText (at "message" (jsonBody created)) `shouldSatisfy` T.isInfixOf "unavailable")
-
--- | 角色与权限：REST 端点、SQL 语句、越权口径、内部表不可见
-privilegesSpec :: FilePath -> Spec
-privilegesSpec staticDir = withWorldAt staticDir "privileges" $ \_ -> do
-    -- 注意：wai-extra 的 Session 自带 Cookie 罐，罐里的令牌会盖过显式 Cookie 头，
-    -- 所以每个身份都得在动手前重新登录一次（和既有用例组同一套写法）。
-    let signIn user password = do
-            res <- loginAs user password
-            expectStatusWith ("sign in " <> T.unpack user) res 204
-    it "the administrator creates a role, grants SELECT and adds a member" $ do
-        signIn "admin" "s3cret"
-        made <- postWith [] "/api/roles" "{\"name\":\"analyst\"}"
-        check (hasStatus made 200)
-        granted <- postWith [] "/api/roles/analyst/grants" "{\"object\":\"users\",\"privileges\":[\"select\"]}"
-        check (hasStatus granted 200)
-        _ <- postWith [] "/api/query" (sqlBody "CREATE USER dana IDENTIFIED BY 'dana-password'")
-        joined <- postWith [] "/api/roles/analyst/members" "{\"user\":\"dana\"}"
-        check (hasStatus joined 200)
-        listed <- getWith [] "/api/roles"
-        check (hasStatus listed 200)
-        check $ do
-            let analyst = roleEntry "analyst" (items (jsonBody listed))
-            at "name" analyst `shouldBe` A.String "analyst"
-            map (asText . at "privilege") (items (at "grants" analyst)) `shouldBe` ["select"]
-            map (asText . at "object") (items (at "grants" analyst)) `shouldBe` ["test.users"]
-            map asText (items (at "members" analyst)) `shouldBe` ["dana"]
-        signIn "dana" "dana-password"
-        visible <- getWith [] "/api/tables"
-        check (hasStatus visible 200)
-        check (map (asText . at "table") (items (jsonBody visible)) `shouldBe` ["users"])
-        allowed <- postWith [] "/api/query" (sqlBody "SELECT * FROM users")
-        check (hasStatus allowed 200)
-        check (asInt (at "rowCount" (jsonBody allowed)) `shouldBe` 5)
-        denied <- postWith [] "/api/query" (sqlBody "SELECT * FROM orders")
-        check (hasStatus denied 403)
-        check (asText (at "error" (jsonBody denied)) `shouldBe` "forbidden")
-        joins <- postWith [] "/api/query" (sqlBody "SELECT u.name FROM users u JOIN orders o ON u.id = o.user_id")
-        check (hasStatus joins 403)
-        nested <- postWith [] "/api/query" (sqlBody "SELECT name FROM users WHERE id IN (SELECT user_id FROM orders)")
-        check (hasStatus nested 403)
-        detail <- getWith [] "/api/tables/orders/rows"
-        check (hasStatus detail 403)
-        rows <- getWith [] "/api/tables/users/rows"
-        check (hasStatus rows 200)
-        inserted <- postWith [] "/api/tables/users/rows" "{\"values\":{\"id\":9,\"name\":\"nine\",\"age\":30}}"
-        check (hasStatus inserted 403)
-    it "grants of insert/update/delete unlock the one-click writes, DDL stays administrator-only" $ do
-        signIn "admin" "s3cret"
-        _ <- postWith [] "/api/roles" "{\"name\":\"editor\"}"
-        _ <- postWith [] "/api/roles/editor/grants" "{\"object\":\"users\",\"privileges\":[\"insert\",\"update\",\"delete\"]}"
-        _ <- postWith [] "/api/query" (sqlBody "CREATE USER evan IDENTIFIED BY 'evan-password'")
-        _ <- postWith [] "/api/roles/editor/members" "{\"users\":[\"evan\"]}"
-        signIn "evan" "evan-password"
-        inserted <- postWith [] "/api/tables/users/rows" "{\"values\":{\"id\":99,\"name\":\"nine\",\"age\":30}}"
-        check (hasStatus inserted 200)
-        changed <- patchWith [] "/api/tables/users/rows/99" "{\"values\":{\"age\":31}}"
-        check (hasStatus changed 200)
-        removed <- deleteWith [] "/api/tables/users/rows/99"
-        check (hasStatus removed 200)
-        visible <- getWith [] "/api/tables"
-        check (hasStatus visible 200)
-        check (length (items (jsonBody visible)) `shouldBe` 0)
-        readDenied <- postWith [] "/api/query" (sqlBody "SELECT * FROM users")
-        check (hasStatus readDenied 403)
-        dropped <- deleteWith [] "/api/tables/users"
-        check (hasStatus dropped 403)
-        ddl <- postWith [] "/api/query" (sqlBody "CREATE TABLE t9 (id INT)")
-        check (hasStatus ddl 403)
-        roles <- getWith [] "/api/roles"
-        check (hasStatus roles 403)
-        roleSql <- postWith [] "/api/query" (sqlBody "CREATE ROLE sneak")
-        check (hasStatus roleSql 403)
-    it "a wildcard grant covers every table" $ do
-        signIn "admin" "s3cret"
-        _ <- postWith [] "/api/roles" "{\"name\":\"supervisor\"}"
-        _ <- postWith [] "/api/roles/supervisor/grants" "{\"object\":\"*\",\"privileges\":[\"select\"]}"
-        _ <- postWith [] "/api/query" (sqlBody "CREATE USER ivy IDENTIFIED BY 'ivy-password'")
-        _ <- postWith [] "/api/roles/supervisor/members" "{\"user\":\"ivy\"}"
-        signIn "ivy" "ivy-password"
-        visible <- getWith [] "/api/tables"
-        check (hasStatus visible 200)
-        check (sort (map (asText . at "table") (items (jsonBody visible))) `shouldBe` ["orders", "users"])
-        both <- postWith [] "/api/query" (sqlBody "SELECT * FROM orders")
-        check (hasStatus both 200)
-        innerJoin <- postWith [] "/api/query" (sqlBody "SELECT u.name FROM users u JOIN orders o ON u.id = o.user_id")
-        check (hasStatus innerJoin 200)
-    it "revoking membership and privileges closes the door again" $ do
-        signIn "admin" "s3cret"
-        _ <- postWith [] "/api/roles" "{\"name\":\"temp\"}"
-        _ <- postWith [] "/api/roles/temp/grants" "{\"object\":\"users\",\"privileges\":[\"select\"]}"
-        _ <- postWith [] "/api/query" (sqlBody "CREATE USER gina IDENTIFIED BY 'gina-password'")
-        _ <- postWith [] "/api/roles/temp/members" "{\"user\":\"gina\"}"
-        signIn "gina" "gina-password"
-        grantedSelect <- postWith [] "/api/query" (sqlBody "SELECT * FROM users")
-        expectStatusWith "gina selects after the grant" grantedSelect 200
-        signIn "admin" "s3cret"
-        evicted <- deleteWith [] "/api/roles/temp/members/gina"
-        expectStatusWith "evict gina" evicted 200
-        signIn "gina" "gina-password"
-        afterEviction <- postWith [] "/api/query" (sqlBody "SELECT * FROM users")
-        expectStatusWith "gina select after eviction" afterEviction 403
-        signIn "admin" "s3cret"
-        readded <- postWith [] "/api/roles/temp/members" "{\"user\":\"gina\"}"
-        expectStatusWith "re-add gina" readded 200
-        signIn "gina" "gina-password"
-        back <- postWith [] "/api/query" (sqlBody "SELECT * FROM users")
-        expectStatusWith "gina selects again" back 200
-        signIn "admin" "s3cret"
-        revoked <- deleteJsonWith [] "/api/roles/temp/grants" "{\"object\":\"users\",\"privileges\":[\"select\"]}"
-        expectStatusWith "revoke the grant" revoked 200
-        signIn "gina" "gina-password"
-        empty <- getWith [] "/api/tables"
-        expectStatusWith "gina table list after revoke" empty 200
-        check (items (jsonBody empty) `shouldBe` [])
-        afterRevoke <- postWith [] "/api/query" (sqlBody "SELECT * FROM users")
-        check (hasStatus afterRevoke 403)
-    it "role statements run in the SQL console and conflicts and unknown roles are reported" $ do
-        signIn "admin" "s3cret"
-        created <- postWith [] "/api/query" (sqlBody "CREATE ROLE auditor")
-        check (hasStatus created 200)
-        granted <- postWith [] "/api/query" (sqlBody "GRANT SELECT ON * TO auditor")
-        check (hasStatus granted 200)
-        listed <- getWith [] "/api/roles"
-        check $ do
-            let auditor = roleEntry "auditor" (items (jsonBody listed))
-            map (asText . at "privilege") (items (at "grants" auditor)) `shouldBe` ["select"]
-            map (asText . at "object") (items (at "grants" auditor)) `shouldBe` ["*"]
-        duplicate <- postWith [] "/api/roles" "{\"name\":\"auditor\"}"
-        check (hasStatus duplicate 409)
-        unknownGrant <- postWith [] "/api/roles/nobody/grants" "{\"object\":\"users\",\"privileges\":[\"select\"]}"
-        check (hasStatus unknownGrant 404)
-        unknownMember <- postWith [] "/api/roles/nobody/members" "{\"user\":\"dana\"}"
-        check (hasStatus unknownMember 404)
-        badPrivilege <- postWith [] "/api/query" (sqlBody "GRANT EXECUTE ON users TO auditor")
-        check (hasStatus badPrivilege 400)
-        revoked <- postWith [] "/api/query" (sqlBody "REVOKE SELECT ON * FROM auditor")
-        check (hasStatus revoked 200)
-        removed <- postWith [] "/api/query" (sqlBody "DROP ROLE auditor")
-        check (hasStatus removed 200)
-        gone <- getWith [] "/api/roles"
-        check (map (asText . at "name") (items (jsonBody gone)) `shouldNotContain` ["auditor"])
-    it "ALL expands into the four concrete privileges" $ do
-        signIn "admin" "s3cret"
-        _ <- postWith [] "/api/roles" "{\"name\":\"owner\"}"
-        _ <- postWith [] "/api/roles/owner/grants" "{\"object\":\"orders\",\"privileges\":[\"all\"]}"
-        listed <- getWith [] "/api/roles"
-        check $ do
-            let owner = roleEntry "owner" (items (jsonBody listed))
-            sort (map (asText . at "privilege") (items (at "grants" owner))) `shouldBe` ["delete", "insert", "select", "update"]
-            map (asText . at "object") (items (at "grants" owner)) `shouldBe` replicate 4 "test.orders"
-    it "the tables that hold roles and grants are invisible" $ do
-        signIn "admin" "s3cret"
-        testList <- getWith [] "/api/tables"
-        check (hasStatus testList 200)
-        check (map (asText . at "table") (items (jsonBody testList)) `shouldNotContain` ["sys_roles", "sys_grants", "sys_members"])
-        systemList <- getWith (systemHeaders []) "/api/tables"
-        check (hasStatus systemList 200)
-        check (map (asText . at "table") (items (jsonBody systemList)) `shouldNotContain` ["sys_roles", "sys_grants", "sys_members"])
-        hidden <- getWith [] "/api/tables/sys_roles"
-        check (hasStatus hidden 404)
-        peek <- postWith [] "/api/query" (sqlBody "SELECT * FROM sys_roles")
-        check (statusCode (WT.simpleStatus peek) `shouldSatisfy` (`elem` [400, 403, 404]))
-    it "an account with no role has no access at all" $ do
-        signIn "admin" "s3cret"
-        _ <- postWith [] "/api/query" (sqlBody "CREATE USER frank IDENTIFIED BY 'frank-password'")
-        signIn "frank" "frank-password"
-        visible <- getWith [] "/api/tables"
-        check (hasStatus visible 200)
-        check (items (jsonBody visible) `shouldBe` [])
-        forM_
-            [ "SELECT * FROM users"
-            , "INSERT INTO users (id, name, age) VALUES (7, 'seven', 7)"
-            , "UPDATE users SET age = 8 WHERE id = 7"
-            , "DELETE FROM users WHERE id = 7"
-            ]
-            $ \sql -> do
-                res <- postWith [] "/api/query" (sqlBody sql)
-                check (hasStatus res 403)
-        detail <- getWith [] "/api/tables/users/rows"
-        check (hasStatus detail 403)
-        databases <- getWith [] "/api/databases"
-        check (map asText (items (jsonBody databases)) `shouldBe` ["test"])
-
--- | 在角色清单里按名字找一项
-roleEntry :: Text -> [A.Value] -> A.Value
-roleEntry name entries = case [e | e <- entries, asText (at "name" e) == name] of
-    (e : _) -> e
-    [] -> A.Null
-
--- | 带 JSON 体的 DELETE（撤销授权要用）
-deleteJsonWith :: [Header] -> BS.ByteString -> BL.ByteString -> TestSession WT.SResponse
-deleteJsonWith headers path payload =
-    request "DELETE" path (fixtureHeaders (("Content-Type", "application/json") : headers)) payload
-
--- | 一条 SQL 请求体
-sqlBody :: Text -> BL.ByteString
-sqlBody sql = BL.fromStrict (TE.encodeUtf8 (T.concat ["{\"sql\":\"", sql, "\"}"]))
-
--- | 在表清单里按表名找一项（找不到给 Null）
-tableEntry :: Text -> [A.Value] -> A.Value
-tableEntry name entries = case [e | e <- entries, asText (at "table" e) == name] of
-    (e : _) -> e
-    [] -> A.Null
-
--- | JSON 当布尔看
-asBool :: A.Value -> Bool
-asBool (A.Bool b) = b
-asBool _ = False
-
--- | JSON 当数组看（不是数组给空）
-asArray :: A.Value -> V.Vector A.Value
-asArray (A.Array xs) = xs
-asArray _ = V.empty
-
--- | 一份完整的合法 IDE 设置请求体
-uiSettingsBody :: BL.ByteString
-uiSettingsBody = "{\"uiFonts\":[\"JetBrains Mono\",\"Consolas\"],\"gridFonts\":[\"Consolas\"],\"sqlFonts\":[\"Mono\"],\"uiFontSize\":13,\"gridFontSize\":12,\"gridRowHeight\":24,\"sqlFontSize\":13,\"sqlLineHeight\":20,\"sqlTabSize\":2,\"pageSize\":200,\"nullText\":\"NULL\",\"sqlLineNumbers\":true,\"autocomplete\":true,\"minimap\":false}"
-
--- | 上面那份设置解出来的值
-fullUISettings :: A.Value
-fullUISettings = fromMaybe A.Null (A.decode uiSettingsBody)
-
--- | 在合法设置上换掉一个字段（试坏值用）
-withUiField :: Text -> A.Value -> A.Value
-withUiField key value = case fullUISettings of
-    A.Object o -> A.Object (KM.insert (K.fromText key) value o)
-    other -> other
-
-uiSettingsSpec :: FilePath -> Spec
-uiSettingsSpec staticDir = do
-    describe "IDE settings validation" $ do
-        it "accepts a complete valid object" $
-            validateUISettings fullUISettings `shouldSatisfy` isRightE
-        it "rejects a string where an integer is expected" $
-            validateUISettings (withUiField "uiFontSize" (A.String "13")) `shouldSatisfy` isLeftE
-        it "rejects an integer outside its range" $ do
-            validateUISettings (withUiField "uiFontSize" (A.Number 10)) `shouldSatisfy` isLeftE
-            validateUISettings (withUiField "uiFontSize" (A.Number 17)) `shouldSatisfy` isLeftE
-        it "rejects a blank font name" $
-            validateUISettings (withUiField "gridFonts" (A.Array (V.fromList [A.String "  "]))) `shouldSatisfy` isLeftE
-        it "rejects a number where a boolean is expected" $
-            validateUISettings (withUiField "minimap" (A.Number 1)) `shouldSatisfy` isLeftE
-        it "names the offending key in the error" $
-            case validateUISettings (withUiField "pageSize" (A.Number 5)) of
-                Left err -> err `shouldSatisfy` isInfixOf "pageSize"
-                Right _ -> expectationFailure "expected a range error"
-
-    describe "IDE settings file" $ do
-        it "candidates look for the file in scripts/ first" $
-            uiSettingsFileCandidates
-                `shouldBe` [ "scripts" </> "chusql.ui.settings.json"
-                           , ".." </> "scripts" </> "chusql.ui.settings.json"
-                           , "chusql.ui.settings.json"
-                           ]
-        it "writing then reading round-trips the map and creates the directory" $ do
-            tmp <- getTemporaryDirectory
-            let dir = tmp </> "chusql-web-test-ui-file" </> "nested"
-                path = dir </> "chusql.ui.settings.json"
-                stored = Map.fromList [("minimap", A.Bool True), ("uiFontSize", A.Number 13)]
-            removeIfExists path
-            written <- writeUISettings path stored
-            written `shouldBe` Right ()
-            readUISettings path `shouldReturn` A.Object (KM.fromList [("minimap", A.Bool True), ("uiFontSize", A.Number 13)])
-
-    describe "IDE settings endpoints" $
-        withWorldAt staticDir "ui-settings" $ \appEnv -> do
-            it "not logged in: GET and PUT both give 401" $ do
-                get "/api/ui-settings" `shouldRespondWith` 401
-                putWith [] "/api/ui-settings" uiSettingsBody `shouldRespondWith` 401
-            it "a missing file reads back as an empty object" $ do
-                res <- loginAs "admin" "s3cret"
-                body <- getWith (cookieHeaders res) "/api/ui-settings"
-                check (hasStatus body 200)
-                check (jsonBody body `shouldBe` A.Object KM.empty)
-            it "a valid body is stored whole and read back unchanged" $ do
-                res <- loginAs "admin" "s3cret"
-                saved <- putWith (cookieHeaders res) "/api/ui-settings" uiSettingsBody
-                check (hasStatus saved 204)
-                body <- getWith (cookieHeaders res) "/api/ui-settings"
-                check (hasStatus body 200)
-                check (jsonBody body `shouldBe` fullUISettings)
-            it "an unknown key gives 400 bad_request" $ do
-                res <- loginAs "admin" "s3cret"
-                bad <- putWith (cookieHeaders res) "/api/ui-settings" "{\"nope\":1}"
-                check (hasStatus bad 400)
-                check (asText (at "error" (jsonBody bad)) `shouldBe` "bad_request")
-            it "a non-object JSON body gives 400" $ do
-                res <- loginAs "admin" "s3cret"
-                bad <- putWith (cookieHeaders res) "/api/ui-settings" "[]"
-                check (hasStatus bad 400)
-            it "a body over the live limit gives 413" $ do
-                res <- loginAs "admin" "s3cret"
-                check $ do
-                    live <- readLive appEnv
-                    setLive appEnv live{lvBodyLimit = 16}
-                big <- putWith (cookieHeaders res) "/api/ui-settings" uiSettingsBody
-                check (hasStatus big 413)
-
-sortSpec :: FilePath -> Spec
-sortSpec staticDir = describe "Sorting while browsing a table" $
-    withWorld staticDir $ \_ -> do
-        it "asc: the first row has the smallest age" $ do
-            res <- loginAs "admin" "s3cret"
-            page <- getWith (cookieHeaders res) "/api/tables/users/rows?sort=age&dir=asc"
-            check (hasStatus page 200)
-            check $ do
-                asText (at "sort" (jsonBody page)) `shouldBe` "age"
-                asText (at "dir" (jsonBody page)) `shouldBe` "asc"
-                firstRow page `shouldBe` [A.Number 1, A.String "user1", A.Number 21]
-        it "unknown column / invalid column name: 400" $ do
-            res <- loginAs "admin" "s3cret"
-            missing <- getWith (cookieHeaders res) "/api/tables/users/rows?sort=nope"
-            check (hasStatus missing 400)
-            invalid <- getWith (cookieHeaders res) "/api/tables/users/rows?sort=age%3B%20DROP%20TABLE%20users"
-            check (hasStatus invalid 400)
-        it "the direction accepts only asc/desc, anything else is asc" $ do
-            res <- loginAs "admin" "s3cret"
-            page <- getWith (cookieHeaders res) "/api/tables/users/rows?sort=age&dir=sideways"
-            check (hasStatus page 200)
-            check (asText (at "dir" (jsonBody page)) `shouldBe` "asc")
-
-securitySpec :: FilePath -> Spec
-securitySpec staticDir = do
-    describe "Security: response headers and static files" $
-        withWorld staticDir $ \_ -> do
-            it "the per-page style nonce differs each time and matches the CSP" $ do
-                first <- get "/"
-                second <- get "/static/index.html"
-                let responsePolicy res = fromMaybe "" (lookup "Content-Security-Policy" (WT.simpleHeaders res))
-                    nonce res = BSC.takeWhile (/= '\'') (BSC.drop 7 (snd (BSC.breakSubstring "'nonce-" (responsePolicy res))))
-                check $ do
-                    BS.length (nonce first) `shouldBe` 64
-                    nonce first `shouldNotBe` nonce second
-                    BL.toStrict (WT.simpleBody first) `shouldSatisfy` BS.isInfixOf (nonce first)
-                    BL.toStrict (WT.simpleBody second) `shouldSatisfy` BS.isInfixOf (nonce second)
-                    responsePolicy first `shouldSatisfy` (not . BS.isInfixOf "unsafe-inline")
-                    responsePolicy first `shouldSatisfy` BS.isInfixOf "script-src 'self';"
-                    length (filter ((== "Content-Security-Policy") . fst) (WT.simpleHeaders first)) `shouldBe` 1
-            it "every response carries CSP / nosniff / DENY / no-store" $ do
-                res <- get "/api/health"
-                let headerNames = map fst (WT.simpleHeaders res)
-                check $ do
-                    headerNames `shouldContain` ["Content-Security-Policy"]
-                    headerNames `shouldContain` ["X-Content-Type-Options"]
-                    headerNames `shouldContain` ["X-Frame-Options"]
-                    headerNames `shouldContain` ["Cache-Control"]
-            it "static JS uses the right Content-Type" $ do
-                res <- get "/static/app.js"
-                check (hasStatus res 200)
-                check (lookup "Content-Type" (WT.simpleHeaders res) `shouldBe` Just "text/javascript; charset=utf-8")
-            it "URL-encoded traversal is rejected" $
-                get "/static/%2e%2e%2fsecret.token" `shouldRespondWith` 404
-            it "files outside the whitelist are unreadable" $
-                get "/static/secret.token" `shouldRespondWith` 404
-            it "an unmatched path gives 404 (JSON)" $ do
-                res <- get "/api/nope"
-                check (hasStatus res 404)
-                check (asText (at "error" (jsonBody res)) `shouldBe` "not_found")
-    describe "Security: cross-site and body size" $
-        withWorld staticDir $ \_ -> do
-            it "a cross-site Origin POST gives 403" $
-                postWith
-                    [("Origin", "http://evil.example"), ("Host", "127.0.0.1:8080")]
-                    "/api/login"
-                    (loginBody "admin" "s3cret")
-                    `shouldRespondWith` 403
-            it "a same-origin Origin POST works as usual (204 with the right password)" $ do
-                res <-
-                    postWith
-                        [("Origin", "http://127.0.0.1:8080"), ("Host", "127.0.0.1:8080")]
-                        "/api/login"
-                        (loginBody "admin" "s3cret")
-                check (hasStatus res 204)
-            it "a genuinely large body gives 413" $
-                jsonRequest methodPost "/api/login" (BL.fromStrict (BS.replicate 70000 97))
-                    `shouldRespondWith` 413
-
--- | 端到端：真 HTTP + 真 Rust 存储进程
-e2eSpec :: FilePath -> Spec
-e2eSpec staticDir = describe "End-to-end: browser -> Haskell -> Rust" $ do
-    it "isolates database contexts across HTTP clients and supports qualified SQL" $ do
-        serverBin <- locateServerOrSkip
-        (pipe, _dataDir, cfg) <- makeServerConfig "iso"
-        started <- startStorageProcess serverBin cfg
-        running <- either fail pure started
-        bracket (pure running) stopStorageProcess $ \_sp -> do
-            backend <- ipcBackend
-            sessions <- newSessionStore getCurrentTime defaultSessionPolicy
-            limiter <- newRateLimiter getCurrentTime 50 300
-            env <- newAppEnv backend sessions testCredential limiter staticDir
-            app <- webApp env
-            Warp.testWithApplication (pure app) $ \port -> do
-                mgr <- newManager defaultManagerSettings
-                signedInResponse <- e2ePost mgr port "/api/login" (loginBody "admin" "s3cret") []
-                let auth = [("Cookie", fromMaybe "" (e2eCookie signedInResponse))]
-                    alpha = ("X-ChuSQL-Database", "alpha") : auth
-                    beta = ("X-ChuSQL-Database", "beta") : auth
-                    query headers sql = e2ePost mgr port "/api/query" (sqlBody sql) headers
-                mapM_ (\name -> do
-                    created <- query auth ("CREATE DATABASE " <> name)
-                    statusCode (responseStatus created) `shouldBe` 200) ["alpha", "beta"]
-                mapM_ (\headers -> do
-                    created <- query headers "CREATE TABLE items (id int)"
-                    statusCode (responseStatus created) `shouldBe` 200) [alpha, beta]
-                inserted <- query alpha "INSERT INTO items (id) VALUES (1)"
-                statusCode (responseStatus inserted) `shouldBe` 200
-                selected <- query beta "SELECT * FROM items"
-                asInt (at "rowCount" (fromMaybe A.Null (decode (responseBody selected)))) `shouldBe` 0
-                qualified <- query beta "SELECT * FROM alpha.items"
-                asInt (at "rowCount" (fromMaybe A.Null (decode (responseBody qualified)))) `shouldBe` 1
-                betaInsert <- query beta "INSERT INTO items (id) VALUES (1)"
-                statusCode (responseStatus betaInsert) `shouldBe` 200
-                joined <- query auth "SELECT a.id FROM alpha.items a JOIN beta.items b ON a.id = b.id"
-                asInt (at "rowCount" (fromMaybe A.Null (decode (responseBody joined)))) `shouldBe` 1
-                inherited <- getEnvironment
-                -- 构建好的 chusql-cli 也要能一条命令跑通（没构建就跳过）
-                locateCliExe >>= \found -> case found of
-                    Nothing -> pendingWith "csql is not built (run stack build chusql-cli:exe:csql)"
-                    Just cliExe -> do
-                        cliConfig <- makeCliHome port pipe "admin" "s3cret"
-                        (cliExit, cliOut, cliErr) <-
-                            readCreateProcessWithExitCode
-                                (proc cliExe ["--config", cliConfig, "--database", "alpha", "--format", "json", "-e", "SELECT * FROM items"])
-                                    { Process.env = Just inherited
-                                    }
-                                ""
-                        (cliExit, cliErr) `shouldBe` (ExitSuccess, "")
-                        asInt (at "rowCount" (fromMaybe A.Null (decode (BL.fromStrict (BSC.pack cliOut))))) `shouldBe` 1
-                switched <- query auth "USE alpha"
-                at "database" (fromMaybe A.Null (decode (responseBody switched))) `shouldBe` A.String "alpha"
-                -- 限定名不需要先选库；裸表名没有当前库就是 400
-                qualifiedWithoutDatabase <- query auth "SELECT * FROM alpha.items"
-                asInt (at "rowCount" (fromMaybe A.Null (decode (responseBody qualifiedWithoutDatabase)))) `shouldBe` 1
-                bareWithoutDatabase <- query auth "SELECT * FROM items"
-                statusCode (responseStatus bareWithoutDatabase) `shouldBe` 400
-                at "error" (fromMaybe A.Null (decode (responseBody bareWithoutDatabase))) `shouldBe` A.String "no_database"
-                listed <- e2eGet mgr port "/api/databases" auth
-                items (fromMaybe A.Null (decode (responseBody listed))) `shouldBe` map A.String ["alpha", "beta", "system"]
-                createdDb <- e2ePost mgr port "/api/databases" "{\"name\":\"gamma\"}" auth
-                statusCode (responseStatus createdDb) `shouldBe` 200
-                duplicateDb <- e2ePost mgr port "/api/databases" "{\"name\":\"gamma\"}" auth
-                statusCode (responseStatus duplicateDb) `shouldBe` 400
-                droppedDb <- e2eSend mgr port "DELETE" "/api/databases/gamma" "" auth
-                statusCode (responseStatus droppedDb) `shouldBe` 200
-                keptSystem <- e2eSend mgr port "DELETE" "/api/databases/system" "" auth
-                statusCode (responseStatus keptSystem) `shouldBe` 400
-                -- test 不再是保留名：能建也能删
-                madeTest <- e2ePost mgr port "/api/databases" "{\"name\":\"test\"}" auth
-                statusCode (responseStatus madeTest) `shouldBe` 200
-                droppedTest <- e2eSend mgr port "DELETE" "/api/databases/test" "" auth
-                statusCode (responseStatus droppedTest) `shouldBe` 200
-                bad <- query (("X-ChuSQL-Database", "../escape") : auth) "SELECT 1"
-                statusCode (responseStatus bad) `shouldBe` 400
-
-    it "login -> create table -> insert -> query -> logout all the way through" $ do
-        serverBin <- locateServerOrSkip
-        (_pipe, dataDir, cfg) <- makeServerConfig "flow"
-        started <- startStorageProcess serverBin cfg
-        running <- case started of
-            Left err -> do
-                expectationFailure err
-                fail "the storage process did not start"
-            Right ok -> pure ok
-        bracket (pure running) stopStorageProcess $ \_sp -> do
-            backend <- ipcBackend
-            clock <- newIORef =<< getCurrentTime
-            sessions <- newSessionStore (readIORef clock) defaultSessionPolicy
-            limiter <- newRateLimiter (readIORef clock) 50 300
-            appEnv <- newAppEnv backend sessions testCredential limiter staticDir
-            app <- webApp appEnv
-            Warp.testWithApplication (pure app) $ \boundPort -> do
-                mgr <- newManager defaultManagerSettings
-                anon <- e2eGet mgr boundPort "/api/tables" []
-                statusCode (responseStatus anon) `shouldBe` 401
-                signedIn <- e2ePost mgr boundPort "/api/login" (loginBody "admin" "s3cret") []
-                statusCode (responseStatus signedIn) `shouldBe` 204
-                let cookie = e2eCookie signedIn
-                cookie `shouldSatisfy` maybe False (not . BS.null)
-                let bare = [("Cookie", fromMaybe "" cookie)]
-                -- 服务不再自带默认库：先建一个自己的库，再把它当请求上下文
-                madeDb <- e2ePost mgr boundPort "/api/databases" "{\"name\":\"main\"}" bare
-                statusCode (responseStatus madeDb) `shouldBe` 200
-                let auth = ("X-ChuSQL-Database", "main") : bare
-                created <- e2ePost mgr boundPort "/api/query" "{\"sql\":\"CREATE TABLE web_e2e (id int, name str)\"}" auth
-                statusCode (responseStatus created) `shouldBe` 200
-                inserted <-
-                    e2ePost
-                        mgr
-                        boundPort
-                        "/api/query"
-                        "{\"sql\":\"INSERT INTO web_e2e (id, name) VALUES (1, 'a'), (2, 'b'), (3, 'c')\"}"
-                        auth
-                statusCode (responseStatus inserted) `shouldBe` 200
-                selected <- e2ePost mgr boundPort "/api/query" "{\"sql\":\"SELECT id, name FROM web_e2e ORDER BY id\"}" auth
-                statusCode (responseStatus selected) `shouldBe` 200
-                let body = fromMaybe A.Null (decode (responseBody selected))
-                asInt (at "rowCount" body) `shouldBe` 3
-                nth 2 (items (at "rows" body)) `shouldBe` Just (A.Array (V.fromList [A.Number 3, A.String "c"]))
-                listed <- e2eGet mgr boundPort "/api/tables" auth
-                statusCode (responseStatus listed) `shouldBe` 200
-                let tableNames = map (asText . at "table") (items (fromMaybe A.Null (decode (responseBody listed))))
-                tableNames `shouldContain` ["web_e2e"]
-                home <- e2eGet mgr boundPort "/" []
-                statusCode (responseStatus home) `shouldBe` 200
-                BL.toStrict (responseBody home) `shouldSatisfy` BS.isInfixOf "ChuSQL"
-                browsed <- e2eGet mgr boundPort "/api/tables/web_e2e/rows?limit=2" auth
-                statusCode (responseStatus browsed) `shouldBe` 200
-                asInt (at "total" (fromMaybe A.Null (decode (responseBody browsed)))) `shouldBe` 3
-                uiCreated <- e2ePost mgr boundPort "/api/tables" "{\"name\":\"web_ui\",\"columns\":[{\"name\":\"id\",\"type\":\"int\"},{\"name\":\"code\",\"type\":\"int\"}]}" auth
-                statusCode (responseStatus uiCreated) `shouldBe` 200
-                uiIns <- e2ePost mgr boundPort "/api/tables/web_ui/rows" "{\"values\":{\"id\":1,\"code\":5}}" auth
-                statusCode (responseStatus uiIns) `shouldBe` 200
-                uiIdx <- e2ePost mgr boundPort "/api/tables/web_ui/indexes" "{\"column\":\"code\"}" auth
-                statusCode (responseStatus uiIdx) `shouldBe` 200
-                uiInfo <- e2eGet mgr boundPort "/api/tables/web_ui" auth
-                let uiJson = fromMaybe A.Null (decode (responseBody uiInfo))
-                sort (map (asText . at "column") (items (at "indexes" uiJson))) `shouldBe` ["code", "id"]
-                map (at "builtIn") (items (at "indexes" uiJson)) `shouldSatisfy` elem (A.Bool True)
-                _ <- e2ePost mgr boundPort "/api/tables/web_ui/rows" "{\"values\":{\"id\":2,\"code\":5}}" auth
-                dupIdx <- e2ePost mgr boundPort "/api/tables/web_ui/indexes" "{\"column\":\"code\"}" auth
-                statusCode (responseStatus dupIdx) `shouldBe` 400
-                uiDel <- e2eSend mgr boundPort "DELETE" "/api/tables/web_ui/rows/2" "" auth
-                statusCode (responseStatus uiDel) `shouldBe` 200
-                uiRows <- e2eGet mgr boundPort "/api/tables/web_ui/rows" auth
-                asInt (at "total" (fromMaybe A.Null (decode (responseBody uiRows)))) `shouldBe` 1
-                droppedCol <- e2eSend mgr boundPort "DELETE" "/api/tables/web_ui/columns/code" "" auth
-                statusCode (responseStatus droppedCol) `shouldBe` 200
-                afterDrop <- e2eGet mgr boundPort "/api/tables/web_ui" auth
-                let afterJson = fromMaybe A.Null (decode (responseBody afterDrop))
-                map (asText . at "name") (items (at "columns" afterJson)) `shouldBe` ["id"]
-                map (asText . at "column") (items (at "indexes" afterJson)) `shouldBe` ["id"]
-                afterRows <- e2eGet mgr boundPort "/api/tables/web_ui/rows" auth
-                let afterRowsJson = fromMaybe A.Null (decode (responseBody afterRows))
-                asInt (at "total" afterRowsJson) `shouldBe` 1
-                map asText (items (at "columns" afterRowsJson)) `shouldBe` ["id"]
-                dropId <- e2eSend mgr boundPort "DELETE" "/api/tables/web_ui/columns/id" "" auth
-                statusCode (responseStatus dropId) `shouldBe` 400
-                demo <- e2ePost mgr boundPort "/api/demo-data" "{}" auth
-                statusCode (responseStatus demo) `shouldBe` 200
-                let demoJson = fromMaybe A.Null (decode (responseBody demo))
-                arrayLen (at "created" demoJson) `shouldBe` 3
-                demoProducts <- e2eGet mgr boundPort "/api/tables/products" auth
-                let prodJson = fromMaybe A.Null (decode (responseBody demoProducts))
-                map (asText . at "column") (items (at "indexes" prodJson)) `shouldContain` ["sku"]
-                demoUsers <- e2eGet mgr boundPort "/api/tables/users/rows?limit=100" auth
-                asInt (at "total" (fromMaybe A.Null (decode (responseBody demoUsers)))) `shouldBe` 10
-                out <- e2ePost mgr boundPort "/api/logout" "{}" auth
-                statusCode (responseStatus out) `shouldBe` 204
-                afterLogout <- e2eGet mgr boundPort "/api/tables" auth
-                statusCode (responseStatus afterLogout) `shouldBe` 401
-                exists <- doesDirectoryExist dataDir
-                exists `shouldBe` True
-
-    it "ordinary accounts survive restart, the administrator resets passwords and ordinary users cannot administer accounts" $ do
-        serverBin <- locateServerOrSkip
-        (_pipe, _dataDir, cfg) <- makeServerConfig "restart"
-        Right running <- startStorageProcess serverBin cfg
-        bracket (pure running) stopStorageProcess $ \sp -> do
-            backend <- ipcBackend
-            sessions <- newSessionStore getCurrentTime defaultSessionPolicy
-            limiter <- newRateLimiter getCurrentTime 50 300
-            env <- newAppEnv backend sessions testCredential limiter staticDir
-            app <- webApp env
-            Warp.testWithApplication (pure app) $ \port -> do
-                mgr <- newManager defaultManagerSettings
-                admin <- e2ePost mgr port "/api/login" (loginBody "admin" "s3cret") []
-                let auth = [("Cookie", fromMaybe "" (e2eCookie admin))]
-                    authSystem = ("X-ChuSQL-Database", "system") : auth
-                created <- e2ePost mgr port "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"alice\",\"password\":\"alice-password\"}}" authSystem
-                statusCode (responseStatus created) `shouldBe` 200
-                duplicate <- e2ePost mgr port "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"ALICE\",\"password\":\"alice-password\"}}" authSystem
-                statusCode (responseStatus duplicate) `shouldBe` 409
-                goneSwitch <- e2ePost mgr port "/api/account/switch" (loginBody "alice" "alice-password") auth
-                statusCode (responseStatus goneSwitch) `shouldBe` 404
-                stillAdmin <- e2eGet mgr port "/api/session" auth
-                statusCode (responseStatus stillAdmin) `shouldBe` 200
-                alice <- e2ePost mgr port "/api/login" (loginBody "alice" "alice-password") []
-                statusCode (responseStatus alice) `shouldBe` 204
-                let aliceAuth = [("Cookie", fromMaybe "" (e2eCookie alice))]
-                    aliceSystem = ("X-ChuSQL-Database", "system") : aliceAuth
-                misplaced <- e2ePost mgr port "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"other\",\"password\":\"other-password\"}}" aliceAuth
-                statusCode (responseStatus misplaced) `shouldBe` 400
-                forbidden <- e2ePost mgr port "/api/tables/__chusql_users/rows" "{\"values\":{\"user\":\"other\",\"password\":\"other-password\"}}" aliceSystem
-                statusCode (responseStatus forbidden) `shouldBe` 403
-                listed <- e2eGet mgr port "/api/tables/__chusql_users/rows" aliceSystem
-                statusCode (responseStatus listed) `shouldBe` 403
-                blockedSystem <- e2eGet mgr port "/api/tables" aliceSystem
-                statusCode (responseStatus blockedSystem) `shouldBe` 403
-                aliceDbs <- e2eGet mgr port "/api/databases" aliceAuth
-                items (fromMaybe A.Null (decode (responseBody aliceDbs))) `shouldSatisfy` not . elem (A.String "system")
-                tableList <- e2eGet mgr port "/api/tables" aliceAuth
-                statusCode (responseStatus tableList) `shouldBe` 400
-                at "error" (fromMaybe A.Null (decode (responseBody tableList))) `shouldBe` A.String "no_database"
-                _ <- e2ePost mgr port "/api/databases" "{\"name\":\"shop\"}" auth
-                shopTables <- e2eGet mgr port "/api/tables" (("X-ChuSQL-Database", "shop") : aliceAuth)
-                statusCode (responseStatus shopTables) `shouldBe` 200
-                BL.toStrict (responseBody shopTables) `shouldSatisfy` (not . BS.isInfixOf "__chusql_users")
-                settings <- e2eSend mgr port "PUT" "/api/settings" "{\"values\":{\"password-min-length\":\"8\"}}" aliceAuth
-                statusCode (responseStatus settings) `shouldBe` 403
-                hidden <- e2ePost mgr port "/api/query" "{\"sql\":\"SELECT * FROM __chusql_users\"}" aliceAuth
-                statusCode (responseStatus hidden) `shouldSatisfy` (>= 400)
-                BL.toStrict (responseBody hidden) `shouldSatisfy` (not . BS.isInfixOf "pbkdf2")
-                selfService <- e2ePost mgr port "/api/account/password" "{\"current\":\"alice-password\",\"next\":\"alice-new-password\"}" aliceAuth
-                statusCode (responseStatus selfService) `shouldBe` 404
-                adminAgain <- e2ePost mgr port "/api/login" (loginBody "admin" "s3cret") []
-                let authAgain = [("Cookie", fromMaybe "" (e2eCookie adminAgain))]
-                reset <- e2eSend mgr port "PATCH" "/api/tables/__chusql_users/rows/alice" "{\"values\":{\"password\":\"alice-new-password\"}}" (("X-ChuSQL-Database", "system") : authAgain)
-                statusCode (responseStatus reset) `shouldBe` 200
-            stopStorageProcess sp
-            (_, _, _, process) <- createProcess (proc serverBin ["--config", cfg]){std_out = NoStream, std_err = NoStream}
-            let restarted = StorageProcess process (spPipe sp)
-            bracket (pure restarted) stopStorageProcess $ \_ -> do
-                waitForStorage 200 >>= (`shouldBe` True)
-                backend2 <- ipcBackend
-                sessions2 <- newSessionStore getCurrentTime defaultSessionPolicy
-                limiter2 <- newRateLimiter getCurrentTime 50 300
-                env2 <- newAppEnv backend2 sessions2 testCredential limiter2 staticDir
-                app2 <- webApp env2
-                Warp.testWithApplication (pure app2) $ \port -> do
-                    mgr <- newManager defaultManagerSettings
-                    fresh <- e2ePost mgr port "/api/login" (loginBody "alice" "alice-new-password") []
-                    statusCode (responseStatus fresh) `shouldBe` 204
-                    stale <- e2ePost mgr port "/api/login" (loginBody "alice" "alice-password") []
-                    statusCode (responseStatus stale) `shouldBe` 401
-                    root <- e2ePost mgr port "/api/login" (loginBody "admin" "s3cret") []
-                    statusCode (responseStatus root) `shouldBe` 204
-
--- | 找构建好的 csql 可执行文件；没构建出可执行文件就返回 Nothing
-locateCliExe :: IO (Maybe FilePath)
-locateCliExe = do
-    let name = platformBinaryName os "csql"
-    firstFile . concat =<< mapM (\root -> findFileUnder 8 (root </> ".stack-work") name) cliRoots
-
--- | csql 可能落地的根：测试的 CWD 是 chusql-web/，所以两种相对位置都试
-cliRoots :: [FilePath]
-cliRoots = ["", "chusql-cli", ".." </> "chusql-cli", "chusql-web", ".." </> "chusql-web", ".."]
-
--- | 按名字在 .stack-work 里递进找可执行文件。
---   stack 会把它放在带平台、包哈希与编译器版本的多层目录里，写死路径会过期。
-findFileUnder :: Int -> FilePath -> FilePath -> IO [FilePath]
-findFileUnder depth dir name = do
-    exists <- doesDirectoryExist dir
-    if not exists || depth <= 0
-        then pure []
-        else do
-            entries <- System.Directory.listDirectory dir
-            let (named, rest) = partition (== name) entries
-            deeper <- mapM (\entry -> findFileUnder (depth - 1) (dir </> entry) name) (filter diggable rest)
-            pure ([dir </> entry | entry <- named] ++ concat deeper)
-  where
-    -- 只往可能放可执行文件的目录里钻，跳过编译中间产物与包索引
-    diggable entry =
-        not ("." `isPrefixOf` entry)
-            && entry `notElem` ["work", "tmp", "package-index", "snapshots", "pantry", "indices"]
-
--- | 一次端到端用例用的管名后缀：同一进程内唯一
+-- | Either 判错
+isLeftE :: Either a b -> Bool
+isLeftE = either (const True) (const False)
+
+-- | 临时文件
+tempFilePath :: String -> IO FilePath
+tempFilePath name = do
+    tmp <- getTemporaryDirectory
+    uniq <- uniqueSuffix
+    pure (tmp </> ("chusql-web-test-" ++ name ++ "-" ++ uniq ++ ".toml"))
+
+-- | 非重复后缀
 uniqueSuffix :: IO String
 uniqueSuffix = do
     u <- newUnique
     pure (show (hashUnique u))
 
--- | 造一份临时 chusql.toml（[server] pipe_name + [storage] data_dir），路径由调用方显式交给存储进程
-makeServerConfig :: String -> IO (String, FilePath, FilePath)
-makeServerConfig label = do
+-- | 文件不存在也算成功
+removeIfExists :: FilePath -> IO ()
+removeIfExists path = do
+    _ <- try (removeFile path) :: IO (Either IOException ())
+    pure ()
+
+-- | 临时静态目录，内容固定便于断言
+makeStaticDir :: IO FilePath
+makeStaticDir = do
     tmp <- getTemporaryDirectory
-    suffix <- uniqueSuffix
-    let pipe = "chusql-web-" ++ label ++ "-" ++ suffix
-        dataDir = tmp </> pipe
-        cfg = dataDir ++ ".toml"
-        -- TOML 的普通字符串会吃反斜杠，路径统一用正斜杠
-        slashed = map (\c -> if c == '\\' then '/' else c) dataDir
-    -- 临时路径在不同轮次可能重名，先扫干净，别把上一次的库带进来
-    removePathForcibly cfg
-    removePathForcibly dataDir
+    uniq <- uniqueSuffix
+    let dir = tmp </> ("chusql-web-static-" ++ uniq)
+    createDirectoryIfMissing True dir
+    BS.writeFile (dir </> "index.html") "<!DOCTYPE html><html lang=\"zh-CN\"><head></head><body>ChuSQL Console</body></html>"
+    BS.writeFile (dir </> "app.js") "// test bundle\n"
+    BS.writeFile (dir </> "style.css") "body{}\n"
+    BS.writeFile (dir </> "secret.token") "do-not-serve\n"
+    pure dir
+
+-- | 只做静态交付的环境，不连 server
+staticOnlyEnv :: FilePath -> IO AppEnv
+staticOnlyEnv staticDir = do
+    limiter <- newRateLimiter getCurrentTime 5 (5 * 60)
+    settings <- tempFilePath "static"
+    removeIfExists settings
+    newAppEnvAt settings "127.0.0.1" 1 limiter staticDir
+
+-- 真 server 世界 --------------------------------------------------------------
+
+-- | 一个真 server 进程及其端口、配置和数据目录
+data LiveWorld = LiveWorld
+    { lwProcess :: ProcessHandle
+    , lwPort :: Int
+    , lwConfig :: FilePath
+    , lwDataDir :: FilePath
+    }
+
+-- | 起 server 进程并从横幅读回端口
+startLiveWorld :: String -> IO LiveWorld
+startLiveWorld label = do
+    bin <- locateServerExe
+    tmp <- getTemporaryDirectory
+    uniq <- uniqueSuffix
+    let root = tmp </> ("chusql-web-live-" ++ label ++ "-" ++ uniq)
+        dataDir = root </> "data"
+        config = root </> "chusql.toml"
     createDirectoryIfMissing True dataDir
-    writeFile
-        cfg
-        ( unlines
-            [ "[server]"
-            , "pipe_name = \"" ++ pipe ++ "\""
-            , "[storage]"
-            , "data_dir = \"" ++ slashed ++ "\""
-            ]
-        )
-    setPipeName pipe
-    pure (pipe, dataDir, cfg)
+    writeFile config (serverConfigText dataDir)
+    (_, Just out, _, process) <-
+        createProcess (proc bin ["--config", config]){std_out = CreatePipe, std_err = NoStream}
+    port <- readListeningPort out
+    _ <- forkIO (drainHandle out)
+    pure (LiveWorld process port config dataDir)
 
--- | 给 CLI 子进程造一份临时 chusql.toml：管名与 root 凭据都在里面，返回配置文件路径
-makeCliHome :: Int -> String -> String -> String -> IO FilePath
-makeCliHome port pipe user password = do
-    tmp <- getTemporaryDirectory
-    let home = tmp </> ("chusql-cli-" ++ show port)
-        cfg = home </> "chusql.toml"
-    createDirectoryIfMissing True home
-    writeFile
-        cfg
-        ( unlines
-            [ "[server]"
-            , "pipe_name = \"" ++ pipe ++ "\""
-            , "[web]"
-            , "user = \"" ++ user ++ "\""
-            , "password = \"" ++ password ++ "\""
-            ]
-        )
-    pure cfg
+-- | 生成夹具 server 的配置文本
+serverConfigText :: FilePath -> String
+serverConfigText dataDir =
+    unlines
+        [ "[web]"
+        , "user = \"" ++ T.unpack adminUser ++ "\""
+        , "password = \"" ++ T.unpack adminPassword ++ "\""
+        , "password-min-length = 8"
+        , "password-classes = 2"
+        , ""
+        , "[server]"
+        , "host = \"127.0.0.1\""
+        , "port = 0"
+        , ""
+        , "[storage]"
+        , "data_dir = \"" ++ slashed dataDir ++ "\""
+        ]
+  where
+    -- | 反斜杠换成正斜杠
+    slashed = map (\c -> if c == '\\' then '/' else c)
 
--- | 找存储进程，cargo 不可用则 pending
-locateServerOrSkip :: IO FilePath
-locateServerOrSkip = do
-    found <- firstDir [".." </> "chusql-storage", "chusql-storage"]
+-- | 逐行读 stdout 直到读出端口
+readListeningPort :: Handle -> IO Int
+readListeningPort handle = do
+    line <- hGetLine handle
+    case portFromBanner line of
+        Just port -> pure port
+        Nothing -> readListeningPort handle
+
+-- | 取一行里最后一串数字
+portFromBanner :: String -> Maybe Int
+portFromBanner line
+    | not ("listening:" `isInfixOf` line) = Nothing
+    | otherwise = case span isDigit (dropWhile (not . isDigit) (reverse line)) of
+        ([], _) -> Nothing
+        (digits, _) -> Just (read (reverse digits))
+
+-- | 抽干 server 的 stdout
+drainHandle :: Handle -> IO ()
+drainHandle handle = do
+    result <- try (hGetLine handle) :: IO (Either IOException String)
+    case result of
+        Left _ -> pure ()
+        Right _ -> drainHandle handle
+
+-- | 按平台补上 .exe 后缀
+binaryName :: String -> String
+binaryName stem = if os == "mingw32" then stem ++ ".exe" else stem
+
+-- | 在 PATH 上查找 chusql-server
+locateServerExe :: IO FilePath
+locateServerExe = do
+    found <- findExecutable (binaryName "chusql-server")
     case found of
-        Nothing -> do
-            expectationFailure "cannot find the chusql-storage directory (tests must run inside the repository)"
-            pure ""
-        Just storageDir -> do
-            built <- buildServer storageDir
-            case built of
-                Left err
-                    | "cannot run cargo" `isInfixOf` err -> do
-                        pendingWith err
-                        pure ""
-                    | otherwise -> do
-                        expectationFailure err
-                        pure ""
-                Right bin -> pure bin
+        Just path -> pure path
+        Nothing -> fail "chusql-server was not found on PATH: run `stack build` first"
 
--- | 编译 Rust 存储并找可执行文件
-buildServer :: FilePath -> IO (Either String FilePath)
-buildServer storageDir = do
-    built <-
-        try (createProcess (proc "cargo" ["build", "--bin", "chusql-storage"]){cwd = Just storageDir, std_out = NoStream, std_err = NoStream}) ::
-            IO (Either IOException (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle))
-    case built of
-        Left e -> pure (Left ("cannot run cargo (Rust is required for the IPC tests): " ++ show e))
-        Right (_, _, _, ph) -> do
-            code <- waitForProcess ph
-            case code of
-                ExitFailure n -> pure (Left ("cargo build --bin chusql-storage failed with exit code " ++ show n))
-                ExitSuccess -> do
-                    found <-
-                        firstFile
-                            [ storageDir </> "target" </> "debug" </> platformBinaryName os "chusql-storage"
+-- | 构造指向真 server 的 Web 环境
+liveEnv :: LiveWorld -> FilePath -> Int -> IO AppEnv
+liveEnv world staticDir attempts = do
+    limiter <- newRateLimiter getCurrentTime attempts (5 * 60)
+    uiPath <- tempFilePath "ui-settings"
+    removeIfExists uiPath
+    base <- newAppEnvAt (lwConfig world) "127.0.0.1" (lwPort world) limiter staticDir
+    pure base{aeUISettingsFile = uiPath}
+
+-- | 收摊：杀进程、清数据目录
+stopServer :: LiveWorld -> IO ()
+stopServer world = do
+    terminateProcess (lwProcess world)
+    _ <- try (waitForProcess (lwProcess world)) :: IO (Either IOException ExitCode)
+    _ <- try (removePathForcibly (lwDataDir world)) :: IO (Either IOException ())
+    pure ()
+
+-- 纯函数 ---------------------------------------------------------------------
+
+-- | 纯函数用例
+unitSpec :: Spec
+unitSpec = describe "pure helpers" $ do
+    it "parses the session cookie out of a Cookie header" $ do
+        parseCookieHeader sessionCookieName "a=1; chusql_session=abc123; b=2" `shouldBe` Just "abc123"
+        parseCookieHeader sessionCookieName "other=1" `shouldBe` Nothing
+        parseCookieHeader sessionCookieName "" `shouldBe` Nothing
+    it "accepts plain identifiers and rejects everything else" $ do
+        isIdentifier "users" `shouldBe` True
+        isIdentifier "_9" `shouldBe` True
+        isIdentifier "" `shouldBe` False
+        isIdentifier "1users" `shouldBe` False
+        isIdentifier "user-name" `shouldBe` False
+        isIdentifier (T.replicate 65 "a") `shouldBe` False
+    it "keeps static delivery inside the asset whitelist" $ do
+        safeRelative "index.html" `shouldBe` Just "index.html"
+        safeRelative "app.js" `shouldBe` Just "app.js"
+        safeRelative "../secret.html" `shouldBe` Nothing
+        safeRelative "asset/app.js" `shouldBe` Nothing
+        safeRelative "secret.token" `shouldBe` Nothing
+        safeRelative "index.htmlx" `shouldBe` Nothing
+    it "maps extensions to content types" $ do
+        contentTypeOf "index.html" `shouldBe` "text/html; charset=utf-8"
+        contentTypeOf "app.js" `shouldBe` "text/javascript; charset=utf-8"
+        contentTypeOf "x.woff2" `shouldBe` "font/woff2"
+        contentTypeOf "x.bin" `shouldBe` "application/octet-stream"
+    it "ships the documented live defaults" $ do
+        lvMaxRows defaultLive `shouldBe` 1000
+        lvPageSize defaultLive `shouldBe` 25
+        lvBodyLimit defaultLive `shouldBe` 65536
+    it "round-trips settings through a real TOML file" $ do
+        path <- tempFilePath "settings"
+        removeIfExists path
+        writeSettingsFile path (Map.fromList [("rows-per-page", "50"), ("user", "admin"), ("password", "s3cret")])
+            >>= (`shouldSatisfy` isRightE)
+        values <- readSettingsFile path
+        Map.lookup "rows-per-page" values `shouldBe` Just "50"
+        Map.lookup "user" values `shouldBe` Just "admin"
+    it "rejects unknown settings and out-of-range limits" $ do
+        applySettings Map.empty (Map.fromList [("nope", "1")]) `shouldSatisfy` isLeftE
+        applySettings Map.empty (Map.fromList [("password-min-length", "3")]) `shouldSatisfy` isLeftE
+        applySettings Map.empty (Map.fromList [("password-min-length", "12")]) `shouldSatisfy` isRightE
+    it "marks root credentials as locked and lists the live keys" $ do
+        isLockedSetting "password" `shouldBe` True
+        isLockedSetting "rows-per-page" `shouldBe` False
+        ("rows-per-page" `elem` liveKeys) `shouldBe` True
+        length settingCatalogue `shouldSatisfy` (> 20)
+        defaultOf "rows-per-page" `shouldBe` "25"
+    it "validates IDE settings" $ do
+        validateUISettings (object ["sqlFontSize" .= (13 :: Int), "minimap" .= False])
+            `shouldSatisfy` isRightE
+        validateUISettings (object ["nope" .= (1 :: Int)]) `shouldSatisfy` isLeftE
+        validateUISettings (A.String "nope") `shouldSatisfy` isLeftE
+
+-- 静态交付 -------------------------------------------------------------------
+
+-- | 静态交付用例
+staticSpec :: FilePath -> Spec
+staticSpec staticDir = describe "static delivery" $ do
+    env <- runIO (staticOnlyEnv staticDir)
+    withApp (webApp env) $ do
+        it "serves the console page with a content-security-policy" $ do
+            res <- requestAs methodGet "/" [] BL.empty
+            expectStatusWith "index" res 200
+            check (responseHeader ("Content-Type", "") res `shouldBe` Just "text/html; charset=utf-8")
+            check (responseHeader ("Content-Security-Policy", "") res `shouldSatisfy` (/= Nothing))
+            check (BSC.isInfixOf "chusql-style-nonce" (BL.toStrict (WT.simpleBody res)) `shouldBe` True)
+        it "serves an asset inside the whitelist" $ do
+            res <- requestAs methodGet "/static/app.js" [] BL.empty
+            expectStatusWith "app.js" res 200
+            check (responseHeader ("Content-Type", "") res `shouldBe` Just "text/javascript; charset=utf-8")
+        it "refuses assets outside the whitelist" $ do
+            res <- requestAs methodGet "/static/secret.token" [] BL.empty
+            expectStatusWith "secret.token" res 404
+        it "answers unknown routes with a JSON 404" $ do
+            res <- requestAs methodGet "/api/nope" [] BL.empty
+            expectStatusWith "unknown route" res 404
+            check (asText (at "error" (jsonBody res)) `shouldBe` "not_found")
+        it "reports the process is alive without touching the storage link" $ do
+            res <- requestAs methodGet "/api/health" [] BL.empty
+            expectStatusWith "health" res 200
+            check (at "status" (jsonBody res) `shouldBe` A.String "ok")
+
+-- 会话 -----------------------------------------------------------------------
+
+-- | 登录与会话用例
+sessionSpec :: AppEnv -> Spec
+sessionSpec env = describe "sign-in and sessions (web -> TCP -> server)" $ do
+    withApp (webApp env) $ do
+        it "refuses protected endpoints without a cookie" $ do
+            res <- requestAs methodGet "/api/databases" [] BL.empty
+            expectStatusWith "no cookie" res 401
+            check (asText (at "error" (jsonBody res)) `shouldBe` "unauthorized")
+        it "refuses a wrong password" $ do
+            res <- loginAs adminUser "not-the-password"
+            expectStatusWith "wrong password" res 401
+        it "signs in, reports the session policy from the server, and signs out" $ do
+            res <- loginAs adminUser adminPassword
+            expectStatusWith "sign-in" res 204
+            token <- case sessionCookieOf res of
+                Just t -> pure t
+                Nothing -> do
+                    check (expectationFailure "no session cookie after sign-in")
+                    pure ""
+            me <- getAs [cookieHeader token] "/api/session"
+            expectStatusWith "session" me 200
+            check (at "user" (jsonBody me) `shouldBe` A.String adminUser)
+            check (at "administrator" (jsonBody me) `shouldBe` A.Bool True)
+            check (asInt (at "minLength" (at "policy" (jsonBody me))) `shouldSatisfy` (>= 8))
+            out <- requestAs "POST" "/api/logout" [cookieHeader token] BL.empty
+            expectStatusWith "sign-out" out 204
+            afterSignOut <- getAs [cookieHeader token] "/api/session"
+            expectStatusWith "session after sign-out" afterSignOut 401
+        it "reports the storage link through a fresh connection" $ do
+            res <- requestAs methodGet "/api/status" [] BL.empty
+            expectStatusWith "status" res 200
+            check (at "storage" (jsonBody res) `shouldBe` A.String "up")
+
+-- 门禁 -----------------------------------------------------------------------
+
+-- | 门禁用例
+gatingSpec :: AppEnv -> Spec
+gatingSpec env = describe "gate keeping" $ do
+    withApp (webApp env) $ do
+        it "rejects an illegal database name in the request header" $ do
+            hs <- adminHeaders
+            res <- requestAs methodGet "/api/tables" (withDb "bad-name" hs) BL.empty
+            expectStatusWith "illegal database" res 400
+        it "rejects the account table outside the system database" $ do
+            hs <- adminHeaders
+            ensureDatabase hs testDatabaseName
+            res <- getAs (withDb testDatabaseName hs) "/api/tables/__chusql_users/rows"
+            expectStatusWith "account table outside system" res 400
+        it "rejects role management without a cookie" $ do
+            res <- getAs [] "/api/roles"
+            expectStatusWith "roles without a cookie" res 401
+
+-- 库、表、行 -----------------------------------------------------------------
+
+-- | 库、表、行用例
+catalogSpec :: AppEnv -> Spec
+catalogSpec env = describe "databases, tables and rows" $ do
+    withApp (webApp env) $ do
+        it "creates a database, lists it and drops it" $ do
+            hs <- adminHeaders
+            created <- postAs hs "/api/databases" (encode (object ["name" .= ("shop" :: Text)]))
+            expectStatusWith "create shop" created 200
+            listed <- getAs hs "/api/databases"
+            expectStatusWith "list databases" listed 200
+            check (("shop" `elem` map asText (items (jsonBody listed))) `shouldBe` True)
+            dropped <- deleteAs hs "/api/databases/shop"
+            expectStatusWith "drop shop" dropped 200
+        it "refuses to drop the system database" $ do
+            hs <- adminHeaders
+            res <- deleteAs hs "/api/databases/system"
+            expectStatusWith "drop system" res 400
+        it "creates a table, inserts a row, reads it back and updates it" $ do
+            hs <- adminHeaders
+            ensureDatabase hs testDatabaseName
+            ensureTable
+                hs
+                "people"
+                ( encode
+                    ( object
+                        [ "name" .= ("people" :: Text)
+                        , "columns"
+                            .= [ column "id" "int"
+                               , column "name" "varchar(64)"
+                               , column "note" "varchar(64)"
+                               ]
+                        ]
+                    )
+                )
+            inserted <-
+                postAs
+                    (withDb testDatabaseName hs)
+                    "/api/tables/people/rows"
+                    ( encode
+                        ( object
+                            [ "values"
+                                .= object
+                                    [ "id" .= (1 :: Int)
+                                    , "name" .= ("alice" :: Text)
+                                    , "note" .= ("first" :: Text)
+                                    ]
                             ]
-                    pure (maybe (Left "cargo build finished but no storage executable was found") Right found)
+                        )
+                    )
+            expectStatusWith "insert row" inserted 200
+            rows <- getAs (withDb testDatabaseName hs) "/api/tables/people/rows?limit=10"
+            expectStatusWith "read rows" rows 200
+            check (asText (at "table" (jsonBody rows)) `shouldBe` "people")
+            check (arrayLen (at "columns" (jsonBody rows)) `shouldBe` 3)
+            check (arrayLen (at "rows" (jsonBody rows)) `shouldBe` 1)
+            check (asInt (at "total" (jsonBody rows)) `shouldBe` 1)
+            check (asInt (maybe A.Null id (nth 0 (firstRow rows))) `shouldBe` 1)
+            check (asText (maybe A.Null id (nth 1 (firstRow rows))) `shouldBe` "alice")
+            updated <-
+                patchAs
+                    (withDb testDatabaseName hs)
+                    "/api/tables/people/rows/1"
+                    (encode (object ["values" .= object ["note" .= ("changed" :: Text)]]))
+            expectStatusWith "update row" updated 200
+            again <- getAs (withDb testDatabaseName hs) "/api/tables/people/rows?limit=10"
+            check (asText (maybe A.Null id (nth 2 (firstRow again))) `shouldBe` "changed")
+        it "deletes the row and then the table" $ do
+            hs <- adminHeaders
+            ensureDatabase hs testDatabaseName
+            ensureTable hs "scratch" (encode (object ["name" .= ("scratch" :: Text), "columns" .= [column "id" "int", column "label" "varchar(64)"]]))
+            inserted <- postAs (withDb testDatabaseName hs) "/api/tables/scratch/rows" (encode (object ["values" .= object ["id" .= (2 :: Int), "label" .= ("x" :: Text)]]))
+            expectStatusWith "insert scratch row" inserted 200
+            deleted <- deleteAs (withDb testDatabaseName hs) "/api/tables/scratch/rows/2"
+            expectStatusWith "delete row" deleted 200
+            rows <- getAs (withDb testDatabaseName hs) "/api/tables/scratch/rows"
+            check (asInt (at "total" (jsonBody rows)) `shouldBe` 0)
+            dropped <- deleteAs (withDb testDatabaseName hs) "/api/tables/scratch"
+            expectStatusWith "drop table" dropped 200
+        it "manages indexes and columns of a table" $ do
+            hs <- adminHeaders
+            ensureDatabase hs testDatabaseName
+            ensureTable hs "metrics" (encode (object ["name" .= ("metrics" :: Text), "columns" .= [column "id" "int", column "score" "int", column "tag" "varchar(64)"]]))
+            made <- postAs (withDb testDatabaseName hs) "/api/tables/metrics/indexes" (encode (object ["column" .= ("score" :: Text)]))
+            expectStatusWith "create index" made 200
+            builtIn <- deleteAs (withDb testDatabaseName hs) "/api/tables/metrics/indexes/id"
+            expectStatusWith "built-in index is refused" builtIn 400
+            dropped <- deleteAs (withDb testDatabaseName hs) "/api/tables/metrics/indexes/score"
+            expectStatusWith "drop index" dropped 200
+            idColumn <- deleteAs (withDb testDatabaseName hs) "/api/tables/metrics/columns/id"
+            expectStatusWith "built-in column is refused" idColumn 400
+            columnDropped <- deleteAs (withDb testDatabaseName hs) "/api/tables/metrics/columns/tag"
+            expectStatusWith "drop column" columnDropped 200
 
--- | 找第一个存在的目录
-firstDir :: [FilePath] -> IO (Maybe FilePath)
-firstDir [] = pure Nothing
-firstDir (d : ds) = do
-    ok <- doesDirectoryExist d
-    if ok then pure (Just d) else firstDir ds
+-- 设置与口令策略 -------------------------------------------------------------
 
--- | 找第一个存在的文件
-firstFile :: [FilePath] -> IO (Maybe FilePath)
-firstFile [] = pure Nothing
-firstFile (p : ps) = do
-    ok <- doesFileExist p
-    if ok then pure (Just p) else firstFile ps
+-- | 设置与口令策略用例
+settingsSpec :: AppEnv -> Spec
+settingsSpec env = describe "settings and password policy" $ do
+    withApp (webApp env) $ do
+        it "shows the catalogue to the administrator" $ do
+            hs <- adminHeaders
+            res <- getAs hs "/api/settings"
+            expectStatusWith "settings" res 200
+            let entries = items (at "items" (jsonBody res))
+            check (length entries `shouldSatisfy` (> 20))
+            check (asText (at "value" (headEntry "rows-per-page" entries)) `shouldBe` "25")
+            check (at "locked" (headEntry "password" entries) `shouldBe` A.Bool True)
+        it "writes a setting, makes the server reload the policy, and reports it applied" $ do
+            hs <- adminHeaders
+            res <-
+                putAs
+                    hs
+                    "/api/settings"
+                    ( encode
+                        ( object
+                            [ "values"
+                                .= object
+                                    [ "password-min-length" .= ("16" :: Text)
+                                    , "password-classes" .= ("3" :: Text)
+                                    ]
+                            ]
+                        )
+                    )
+            expectStatusWith "write settings" res 200
+            let applied = map asText (items (at "applied" (jsonBody res)))
+            check (("password-min-length" `elem` applied) `shouldBe` True)
+            me <- getAs hs "/api/session"
+            check (asInt (at "minLength" (at "policy" (jsonBody me))) `shouldBe` 16)
+            values <- liftIO (readSettingsFile (aeSettingsFile env))
+            check (Map.lookup "password-min-length" values `shouldBe` Just "16")
+            check (Map.lookup "user" values `shouldBe` Just adminUser)
+        it "refuses unknown settings and the locked root credentials" $ do
+            hs <- adminHeaders
+            unknown <- putAs hs "/api/settings" (encode (object ["values" .= object ["nope" .= ("1" :: Text)]]))
+            expectStatusWith "unknown setting" unknown 400
+            locked <- putAs hs "/api/settings" (encode (object ["values" .= object ["password" .= ("hacked" :: Text)]]))
+            expectStatusWith "locked credential" locked 403
 
--- | 从响应头里取会话 Cookie
-e2eCookie :: Response BL.ByteString -> Maybe BS.ByteString
-e2eCookie resp = case lookup "Set-Cookie" (responseHeaders resp) of
-    Nothing -> Nothing
-    Just raw -> Just (BSC.takeWhile (/= ';') raw)
+-- 账号表 ---------------------------------------------------------------------
 
--- | 端到端：任意方法的 JSON 请求
-e2eSend :: Manager -> Int -> BS.ByteString -> BS.ByteString -> BL.ByteString -> [Header] -> IO (Response BL.ByteString)
-e2eSend mgr port httpMethod path payload headers = do
-    base <- parseRequest ("http://127.0.0.1:" ++ show port ++ BSC.unpack path)
+-- | 账号表用例
+accountSpec :: AppEnv -> Spec
+accountSpec env = describe "the account table (system database, admin only)" $ do
+    withApp (webApp env) $ do
+        it "lists the account table in the system database" $ do
+            hs <- adminHeaders
+            res <- getAs (withDb "system" hs) "/api/tables"
+            expectStatusWith "system tables" res 200
+            check (("__chusql_users" `elem` map (asText . at "table") (items (jsonBody res))) `shouldBe` True)
+        it "creates an account, changes its password, signs in as it and drops it" $ do
+            hs <- adminHeaders
+            ensureAccount hs "alice" "alice-Secret-1234"
+            duplicate <-
+                postAs
+                    (withDb "system" hs)
+                    "/api/tables/__chusql_users/rows"
+                    (encode (object ["values" .= object ["user" .= ("alice" :: Text), "password" .= ("alice-Secret-9999" :: Text)]]))
+            expectStatusWith "duplicate account" duplicate 409
+            alice <- ordinaryHeaders "alice" "alice-Secret-1234"
+            forbidden <- getAs (withDb "system" alice) "/api/tables"
+            expectStatusWith "ordinary account cannot enter system" forbidden 403
+            visible <- getAs alice "/api/databases"
+            expectStatusWith "ordinary account lists databases" visible 200
+            check (("system" `elem` map asText (items (jsonBody visible))) `shouldBe` False)
+            changed <-
+                patchAs
+                    (withDb "system" hs)
+                    "/api/tables/__chusql_users/rows/alice"
+                    (encode (object ["values" .= object ["password" .= ("alice-Secret-5678" :: Text)]]))
+            expectStatusWith "change password" changed 200
+            _ <- ordinaryHeaders "alice" "alice-Secret-5678"
+            dropped <- deleteAs (withDb "system" hs) "/api/tables/__chusql_users/rows/alice"
+            expectStatusWith "drop account" dropped 200
+        it "refuses account writes without a cookie" $ do
+            res <- getAs (withDb "system" []) "/api/tables/__chusql_users/rows"
+            expectStatusWith "account rows without a cookie" res 401
+
+-- 角色 -----------------------------------------------------------------------
+
+-- | 角色与授权用例
+roleSpec :: AppEnv -> Spec
+roleSpec env = describe "roles and grants" $ do
+    withApp (webApp env) $ do
+        it "creates a role, grants a privilege, adds a member and drops it" $ do
+            hs <- adminHeaders
+            ensureDatabase hs testDatabaseName
+            ensureAccount hs "bob" "bob-Secret-123456"
+            created <- postAs hs "/api/roles" (encode (object ["name" .= ("analyst" :: Text)]))
+            expectStatusWith "create role" created 200
+            granted <-
+                postAs
+                    hs
+                    "/api/roles/analyst/grants"
+                    (encode (object ["object" .= testDatabaseName, "privileges" .= (["select"] :: [Text])]))
+            expectStatusWith "grant privilege" granted 200
+            member <- postAs hs "/api/roles/analyst/members" (encode (object ["user" .= ("bob" :: Text)]))
+            expectStatusWith "add member" member 200
+            listed <- getAs hs "/api/roles"
+            expectStatusWith "list roles" listed 200
+            check (("analyst" `elem` map (asText . at "name") (items (jsonBody listed))) `shouldBe` True)
+            removed <- deleteAs hs "/api/roles/analyst/members/bob"
+            expectStatusWith "remove member" removed 200
+            revoked <-
+                deleteAs
+                    hs
+                    "/api/roles/analyst/grants"
+            expectStatusWith "revoke without a body" revoked 400
+            dropped <- deleteAs hs "/api/roles/analyst"
+            expectStatusWith "drop role" dropped 200
+
+-- SQL 控制台 -----------------------------------------------------------------
+
+-- | SQL 控制台用例
+querySpec :: AppEnv -> Spec
+querySpec env = describe "the SQL console" $ do
+    withApp (webApp env) $ do
+        it "runs DDL and DML and returns positional rows" $ do
+            hs <- adminHeaders
+            ensureDatabase hs testDatabaseName
+            made <- postAs (withDb testDatabaseName hs) "/api/query" (encode (object ["sql" .= ("CREATE TABLE console_probe (id int, label varchar(64))" :: Text)]))
+            expectStatusWith "create table by SQL" made 200
+            inserted <- postAs (withDb testDatabaseName hs) "/api/query" (encode (object ["sql" .= ("INSERT INTO console_probe (id, label) VALUES (7, 'seven')" :: Text)]))
+            expectStatusWith "insert by SQL" inserted 200
+            res <- postAs (withDb testDatabaseName hs) "/api/query" (encode (object ["sql" .= ("SELECT * FROM console_probe" :: Text)]))
+            expectStatusWith "select by SQL" res 200
+            check (asInt (at "rowCount" (jsonBody res)) `shouldBe` 1)
+            check (arrayLen (at "columns" (jsonBody res)) `shouldBe` 2)
+            check (asText (maybe A.Null id (nth 1 (firstRow res))) `shouldBe` "seven")
+        it "refuses an empty statement" $ do
+            hs <- adminHeaders
+            ensureDatabase hs testDatabaseName
+            res <- postAs (withDb testDatabaseName hs) "/api/query" (encode (object ["sql" .= ("" :: Text)]))
+            expectStatusWith "empty sql" res 400
+        it "refuses an oversized body" $ do
+            hs <- adminHeaders
+            res <- postAs (withDb testDatabaseName hs) "/api/query" (BL.replicate 70000 32)
+            expectStatusWith "oversized body" res 413
+        it "reports a syntax error as a bad request" $ do
+            hs <- adminHeaders
+            ensureDatabase hs testDatabaseName
+            res <- postAs (withDb testDatabaseName hs) "/api/query" (encode (object ["sql" .= ("SELEC nonsense" :: Text)]))
+            expectStatusWith "syntax error" res 400
+
+-- IDE 设置 -------------------------------------------------------------------
+
+-- | IDE 设置用例
+uiSettingsSpec :: AppEnv -> Spec
+uiSettingsSpec env = describe "IDE settings" $ do
+    withApp (webApp env) $ do
+        it "round-trips a valid payload" $ do
+            hs <- adminHeaders
+            initialUi <- getAs hs "/api/ui-settings"
+            expectStatusWith "read IDE settings" initialUi 200
+            saved <- putAs hs "/api/ui-settings" (encode (object ["sqlFontSize" .= (13 :: Int), "minimap" .= False]))
+            expectStatusWith "write IDE settings" saved 204
+            updatedUi <- getAs hs "/api/ui-settings"
+            check (at "sqlFontSize" (jsonBody updatedUi) `shouldBe` A.Number 13)
+        it "refuses an unknown key" $ do
+            hs <- adminHeaders
+            bad <- putAs hs "/api/ui-settings" (encode (object ["nope" .= (1 :: Int)]))
+            expectStatusWith "unknown IDE setting" bad 400
+        it "needs a session" $ do
+            res <- getAs [] "/api/ui-settings"
+            expectStatusWith "IDE settings without a cookie" res 401
+
+-- 限流 -----------------------------------------------------------------------
+
+-- | 登录限流用例
+rateLimitSpec :: AppEnv -> Spec
+rateLimitSpec env = describe "sign-in rate limiting" $ do
+    withApp (webApp env) $ do
+        it "locks the account after the configured failures" $ do
+            first <- loginAs adminUser "wrong-one"
+            expectStatusWith "first failure" first 401
+            second <- loginAs adminUser "wrong-two"
+            expectStatusWith "locked out" second 429
+            third <- loginAs adminUser adminPassword
+            expectStatusWith "still locked out" third 429
+
+-- 真 socket 端到端 -----------------------------------------------------------
+
+-- | 真 socket 端到端用例
+e2eSpec :: AppEnv -> Spec
+e2eSpec env = describe "end to end (HTTP socket -> web -> TCP -> server -> storage)" $ do
+    it "signs in over a real socket and lists databases" $ do
+        Warp.testWithApplication (webApp env) $ \port -> do
+            manager <- newManager defaultManagerSettings
+            login <- httpJson manager port methodPost "/api/login" [] (encode (object ["user" .= adminUser, "password" .= adminPassword]))
+            statusCode (responseStatus login) `shouldBe` 204
+            let cookie = case cookieOf login of
+                    Just token -> [cookieHeader token]
+                    Nothing -> []
+            listed <- httpJson manager port methodGet "/api/databases" cookie BL.empty
+            statusCode (responseStatus listed) `shouldBe` 200
+            let body = fromMaybe A.Null (A.decode (responseBody listed))
+            ("system" `elem` map asText (items body)) `shouldBe` True
+
+-- | 走真 HTTP 客户端打出去的一个请求
+httpJson :: Manager -> Int -> Method -> BS.ByteString -> [Header] -> BL.ByteString -> IO (Response BL.ByteString)
+httpJson manager port httpMethod path headers payload = do
+    baseRequest <- parseRequest ("http://127.0.0.1:" ++ show port ++ BSC.unpack path)
     httpLbs
-        base
+        baseRequest
             { method = httpMethod
+            , requestHeaders = jsonHeaders headers
             , requestBody = RequestBodyLBS payload
-            , requestHeaders = ("Content-Type", "application/json") : headers
             }
-        mgr
+        manager
 
--- | 端到端 POST
-e2ePost :: Manager -> Int -> BS.ByteString -> BL.ByteString -> [Header] -> IO (Response BL.ByteString)
-e2ePost mgr port path payload headers = e2eSend mgr port "POST" path payload headers
+-- | 从响应里取会话令牌
+cookieOf :: Response BL.ByteString -> Maybe Text
+cookieOf res = do
+    raw <- lookup "Set-Cookie" (responseHeaders res)
+    parseCookieHeader sessionCookieName (TE.decodeUtf8 raw)
 
--- | 端到端 GET
-e2eGet :: Manager -> Int -> BS.ByteString -> [Header] -> IO (Response BL.ByteString)
-e2eGet mgr port path headers = do
-    base <- parseRequest ("http://127.0.0.1:" ++ show port ++ BSC.unpack path)
-    httpLbs base{requestHeaders = headers} mgr
+-- | 入口：起夹具并跑全部用例
+main :: IO ()
+main = do
+    staticDir <- makeStaticDir
+    -- server 用 bracket 兜底收摊：断言抛异常、用例被过滤器全跳过，都不会留下孤儿进程占着 exe
+    bracket (startLiveWorld "main") stopServer $ \world ->
+        bracket (startLiveWorld "limited") stopServer $ \limitedWorld -> do
+            env <- liveEnv world staticDir 5
+            limitedEnv <- liveEnv limitedWorld staticDir 1
+            hspec (spec staticDir env limitedEnv)
+
+-- | 汇总挂载全部用例组
+spec :: FilePath -> AppEnv -> AppEnv -> Spec
+spec staticDir env limitedEnv = do
+    unitSpec
+    staticSpec staticDir
+    gateSpec
+    sessionSpec env
+    gatingSpec env
+    catalogSpec env
+    settingsSpec env
+    accountSpec env
+    roleSpec env
+    querySpec env
+    uiSettingsSpec env
+    e2eSpec env
+    rateLimitSpec limitedEnv
diff --git a/doc/architecture.md b/doc/architecture.md
index c192c9f..d76c0a3 100644
--- a/doc/architecture.md
+++ b/doc/architecture.md
@@ -1,34 +1,43 @@
 # 架构与组件
 
-ChuSQL 由三个可执行文件组成，共用同一份配置：
+ChuSQL 由三个面向用户的程序、几个共享库与一份配置组成：
 
-| 组件               | 作用                                                    |
-| ------------------ | ------------------------------------------------------- |
-| `chusql-storage`   | 存储进程：页面与索引、WAL、崩溃恢复                      |
-| `chusql-web`       | Web 管理端：REST 接口 + 浏览器里的数据库 IDE             |
-| `csql`             | 命令行客户端                                            |
+| 组件                            | 作用                                                                 |
+| ------------------------------- | -------------------------------------------------------------------- |
+| `chusql-server`                 | 数据库服务：进程内装入引擎与存储动态库、独占数据目录，对外只开一个 TCP 端口 |
+| `chusql-web`                    | Web 管理端：浏览器里的数据库 IDE，自己开 HTTP 端口，后端经 TCP 连 `chusql-server` |
+| `csql`                          | 命令行客户端，经 TCP 连 `chusql-server`                              |
+| `chusql-core/engine`（库）      | SQL 解析、语义检查、优化与执行，链进 `chusql-server`                  |
+| `chusql-core/storage`（动态库） | 存储：页面与索引、WAL、崩溃恢复                                      |
+| `chusql-interface`（库）        | 接口层：线上协议、配置与设置、口令与限流、语句构造、TCP 客户端与会话，`chusql-web` 与 `csql` 共用 |
+| `chusql-core/model`（库）       | 共享类型：表与列、结果集、权限枚举                                    |
+
+安装时把可执行文件与存储动态库（`libchusql_core_storage.so` / `chusql_core_storage.dll`）放进同一个目录，
+进程按 exe 所在目录就能找到库。
 
 ## 数据流
 
-SQL → 前端（`chusql-web` 或 `csql`）→ 本地端点 → `chusql-storage` → 磁盘。
+浏览器、`csql` 或别的程序 → TCP → `chusql-server` → 同一进程里调 `chusql-core/engine`
+（经 FFI 再调 `chusql-core/storage` 动态库）→ 磁盘。
 
-Web 与命令行是两个并列的前端：Web 走 HTTP，命令行直连本地端点，两者共用同一份
-[`chusql.toml`](config.md)、同一个管理员账号与同一张账号表——任意一端改的账号与权限，
-另一端立刻生效。
+**数据目录只有 `chusql-server` 一个进程碰**：`chusql-web` 与 `csql` 自己不开存储，它们把 SQL 与数据字典请求
+交给 TCP 服务执行，拿到结果再渲染。因此库文件同一时刻只有一个持有者；进程内的并发先用一把锁串起来，
+完整事务与 MVCC 见后续计划。
+
+`chusql-web` 是「自己开 HTTP 服务、同时又是 `chusql-server` 的 TCP 客户端」：浏览器只跟 Web 说话，
+Web 后端在需要认证、鉴权、读数据或改数据的时候，才把请求发给 `chusql-server`。
+
+三种用法共用同一份 [`chusql.toml`](config.md)、同一个管理员账号与同一张账号表——任意一端改的账号与权限，
+另外两端立刻生效。
 
 ## 一次请求经过什么
 
-1. 浏览器或命令行发起 SQL；
-2. 解析与语义检查（表/列是否存在、类型是否匹配、权限是否足够）在这里完成，不合格的语句不会落到磁盘；
-3. 合格语句通过本地端点交给 `chusql-storage`；
-4. 存储进程读写页面与索引，写之前先记 WAL；
+1. 浏览器、命令行或别的程序发起 SQL；
+2. 解析与语义检查（表/列是否存在、类型是否匹配、权限是否足够）在 `chusql-server` 里完成，不合格的语句不会落到磁盘；
+3. 合格语句经 FFI 交给同一进程里的存储库；
+4. 存储库读写页面与索引，写之前先记 WAL；
 5. 结果原路返回。
 
-## 本地端点
-
-前端与存储进程之间只有一个端点，由 `[server] pipe_name` 决定：Windows 是具名管道，
-Linux / macOS 是套接字文件（规则见 [config.md](config.md) 的「端点」一节）。
-
 ## 数据在哪里
 
 数据都在 `[storage] data_dir` 下。不写这个键就按平台惯例：Windows `%LOCALAPPDATA%\ChuSQL\data`，
@@ -40,3 +49,31 @@ Linux / macOS `${XDG_DATA_HOME:-~/.local/share}/chusql/data`。
 | `databases/<库名>/`   | 各自建的库                   |
 
 服务启动后只建 `system`，**没有默认工作库**；其余库由你自己 `CREATE DATABASE` 创建。
+
+## TCP 数据库服务（`chusql-server`）
+
+给别的程序用的接口：一条 TCP 连接一条 SQL 会话，请求和应答都是**一行一个 JSON 对象**，编码 UTF-8。
+
+| 请求            | 字段                        | 应答 `status`                                                    |
+| --------------- | --------------------------- | ---------------------------------------------------------------- |
+| `hello`         | `protocol`（可选，默认 1）  | `hello`：带 `protocol`、`server`                                 |
+| `login`         | `user`、`password`          | `ok`：带 `user`、`admin`                                         |
+| `query`         | `sql`                       | `result`：带 `columns`、`rows`、`rowCount`、`truncated`、`database` |
+| `catalog`       | —                           | `catalog`：带 `schemas`（表与列）                                |
+| `databases`     | —                           | `databases`：带库名列表                                          |
+| `roles`         | —                           | `roles`：带角色与授权视图                                        |
+| `accounts`      | —                           | `accounts`：带账号表（仅管理员）                                 |
+| `policy`        | —                           | `policy`：带 `minLength`、`classes`（仅管理员）                  |
+| `reload-policy` | —                           | `policy`：重新读设置里的口令策略（仅管理员）                     |
+| `storage`       | `request`（存储层的原始请求） | `storage`：带 `response`（存储层的原始应答，仅管理员）          |
+| `ping`          | —                           | `pong`                                                           |
+| `quit`          | —                           | `bye`，随后连接关闭                                              |
+
+方法名大小写不敏感，认不出的字段忽略。任何一端出错都回 `{"status":"error","code":...,"message":...}`
+且**连接不断**，客户端可以接着发下一条；`code` 取值有 `bad_request`（协议号不符、SQL 为空、行太长）、
+`unauthorized`（没登录就查询、口令不对）、`forbidden`、`too_many_attempts`（登录失败被限流）、
+`too_large`、`no_database`、`not_found`、`query_error`、`conflict`、`storage_error`。
+
+登录之前只能 `hello` / `ping` / `quit`；`storage`、`accounts`、`policy`、`reload-policy` 与系统库只对管理员开放。
+每条连接各有一份会话，数据库选择（`USE <库>`）不跨连接。监听参数在 `[server]` 分区（见 [config.md](config.md)），
+默认只听本机 `127.0.0.1:7777`。
diff --git a/doc/commands.md b/doc/commands.md
index 624470a..d99314b 100644
--- a/doc/commands.md
+++ b/doc/commands.md
@@ -4,10 +4,10 @@
 
 | 命令 | 作用 | 选项 |
 | ---- | ---- | ---- |
-| `chusql-storage` | 存储进程：页面与索引、WAL | 只有 `--config <path>` |
+| `chusql-server` | 数据库服务：装入引擎与存储动态库、独占数据目录，对外是 TCP | 见「`chusql-server` 选项」 |
 | `chusql-web` | Web 管理端：REST 接口 + 浏览器里的数据库 IDE | 见「`chusql-web` 选项」 |
-| `csql` | 命令行客户端，直连存储进程，不经过 HTTP | 见「`csql` 选项」 |
-| `csql-web` | 一键启动器：按配置拉起存储进程 + Web，日志写 `<install-dir>/logs` | 无选项（`host`/`port` 从配置读） |
+| `csql` | 命令行客户端，连数据库服务的 TCP 端点 | 见「`csql` 选项」 |
+| `csql-web` | 一键启动器：按配置拉起 Web 服务，日志写 `<install-dir>/logs` | 无选项（`host`/`port` 从配置读） |
 
 四个命令共用同一份 [`chusql.toml`](config.md)；`--config` 都是用来临时读另一份配置的。
 
@@ -23,8 +23,6 @@
 | `-f, --format FORMAT` | `table` | 输出格式：`table` / `json` / `csv` |
 | `-e, --execute SQL` | — | 跑一条语句就退出（脚本化用） |
 | `--history FILE` | `~/.chusql_history` | 历史文件位置 |
-| `--pipe NAME` | 配置 `[server] pipe_name` | 端点名（Windows 具名管道 / Unix 套接字文件） |
-| `--storage SERVER` | — | 端点没人应答时，拉起这个存储进程可执行文件 |
 | `--config FILE` | 固定位置的 `chusql.toml` | 读另一份配置 |
 | `-h, --help` | — | 帮助 |
 
@@ -105,10 +103,9 @@ Web 端对应的接口是 `/api/roles` 系列（`GET` 列表、`POST` 建角色
 | ---- | ---------- | ---- |
 | `--config FILE` | — | 固定位置的 `chusql.toml` |
 | `--host H` | `[web] host` | `127.0.0.1` |
-| `--port N` | `[web] port` | `7777` |
+| `--port N` | `[web] port` | `7778` |
 | `--static DIR` | `[web] static_dir` | `static` |
 | `--user NAME` | `[web] user` | `root` |
-| `--storage SERVER` | `[web] storage_server` | — |
 | `--cookie-secure BOOL` | `[web] cookie_secure` | `false` |
 | `--body-limit N` | `[web] body_limit` | `65536` |
 | `--session-idle N` | `[web] session_idle` | `28800` |
@@ -140,3 +137,29 @@ REST 接口（界面的一键操作全走结构化接口）：
 除探活、登录和首页（`GET /`、`GET /static/:file`）外都要带会话 Cookie。选库用 `X-ChuSQL-Database` 头：
 **不带这个头就是"没选库"**，此时只有限定名语句（`db.table`）能跑，裸表名会得到 400 `no_database`；
 `GET /api/databases` 和 `POST`/`DELETE /api/databases/:name` 不需要选库。普通身份碰 `system` 库一律 403。
+
+## `chusql-server` 选项
+
+    chusql-server [options]
+
+| 选项 | 对应配置键 | 默认 |
+| ---- | ---------- | ---- |
+| `--config FILE` | — | 固定位置的 `chusql.toml` |
+| `--host H` | `[server] host` | `127.0.0.1` |
+| `--port N` | `[server] port` | `7777` |
+| `--user NAME` | `[web] user` | `root` |
+| `--max-message N` | `[server] max_message` | `1048576` |
+| `--max-rows N` | `[server] max_rows` | `1000` |
+| `-h, --help` | — | 帮助 |
+
+启动后打印实际监听地址，它同时是数据目录的唯一持有者：Web 与 `csql` 不开存储，把存储请求交给它转发。
+客户端按**一行一个 JSON** 说话，方法与错误码见
+[architecture.md](architecture.md) 的「TCP 数据库服务」；用 `nc` 手敲一个会话是这样：
+
+    {"method":"hello","protocol":1}
+    {"method":"login","user":"root","password":"..."}
+    {"method":"query","sql":"USE test"}
+    {"method":"query","sql":"SELECT * FROM users"}
+    {"method":"quit"}
+
+对话里每条 SQL 走的是和 Web、`csql` 同一套解析与权限检查，账号与库选择互不共享。
diff --git a/doc/config.md b/doc/config.md
index 6d89595..eb3a24c 100644
--- a/doc/config.md
+++ b/doc/config.md
@@ -2,7 +2,7 @@
 
 ## 文件在哪
 
-整条链路（存储进程 / Web / 命令行）共用一份 `chusql.toml`，位置固定，**没有环境变量可以覆盖**：
+整条链路（数据库服务 / Web / 命令行）共用一份 `chusql.toml`，位置固定，**没有环境变量可以覆盖**：
 
 | 平台         | 路径 |
 | ------------ | ---- |
@@ -10,7 +10,7 @@
 | Linux / macOS | `$XDG_CONFIG_HOME/ChuSQL/chusql.toml`，没设就是 `~/.config/ChuSQL/chusql.toml`（`HOME` 也没有才退相对路径 `ChuSQL/chusql.toml`） |
 
 安装脚本就是把 [`scripts/chusql.toml`](../scripts/chusql.toml) 这份模板写到上面的位置，并把安装时给的
-`user` / `password` / `data_dir` 填进去。想临时读另一份文件，`chusql-storage`、`chusql-web`、`csql`
+`user` / `password` / `data_dir` 填进去。想临时读另一份文件，`chusql-server`、`chusql-web`、`csql`
 都认 `--config <path>`（启动器 `csql-web` 没有选项，只读固定路径）。
 
 优先级：**命令行选项 > 配置文件 > 内置默认**，也就是配置文件写什么，命令行随时能盖掉
@@ -20,12 +20,13 @@
 
 | 分区 | 谁读 |
 | ---- | ---- |
-| `[page]` `[btree]` `[buffer]` `[storage]` `[server]` `[log]` | 存储进程 `chusql-storage` |
-| `[web]` | Web 服务 `chusql-web` 与命令行 `csql`（账号、会话、限流、分页上限、静态目录、存储进程路径） |
+| `[page]` `[btree]` `[buffer]` `[storage]` `[log]` | 存储层 `chusql-core/storage`（由 `chusql-server` 装入的动态库） |
+| `[server]` | TCP 数据库服务 `chusql-server`（监听地址、端口、单行上限、结果行数上限） |
+| `[web]` | Web 服务 `chusql-web` 与命令行 `csql`（账号、会话、限流、分页上限、静态目录） |
 
-端点与数据目录只有一份配置：前端读它来决定怎么连，存储进程读它来监听与落盘。
+数据目录只有一份配置：`chusql-server` 读它来落盘，别的进程不碰。
 
-## 存储进程的分区
+## 存储的分区
 
 | 键 | 默认 | 说明 |
 | -- | ---- | ---- |
@@ -33,25 +34,23 @@
 | `[btree] order` | `4` | B+ 树阶 |
 | `[buffer] pool_size` | `1024` | 缓冲池页数 |
 | `[storage] data_dir` | Windows `%LOCALAPPDATA%\ChuSQL\data`，Linux / macOS `${XDG_DATA_HOME:-~/.local/share}/chusql/data` | 数据落哪（模板里那行是安装时替换的占位） |
-| `[server] pipe_name` | `chusql-joint` | 端点名（见下） |
 | `[log] level` | `info` | 日志级别 |
 
 数据目录跟着平台惯例走，跟安装脚本装的位置是同一处（Windows 装到 `%LOCALAPPDATA%\ChuSQL`、Unix 装到
 `~/.local/share/chusql`，数据放在它下面的 `data/`）；`LOCALAPPDATA`/`XDG_DATA_HOME`/`HOME` 都没有时才退相对路径。
 要固定就写绝对路径。
 
-存储进程只认一个命令行开关：`--config <path>`（`--help` 看帮助）。
+存储层没有自己的命令行选项：它是 `chusql-server` 进程内装入的动态库。
 
 ## `[web]` 分区
 
 | 键 | 命令行（`chusql-web`） | 默认 | 说明 |
 | -- | ---------------------- | ---- | ---- |
 | `host` | `--host` | `127.0.0.1` | 监听地址 |
-| `port` | `--port` | `7777` | 监听端口 |
+| `port` | `--port` | `7778` | 监听端口 |
 | `static_dir` | `--static` | `static` | 静态资源目录（候选：给定值、`static`、`chusql-web/static`、`../chusql-web/static`、`../static`，取第一个存在的） |
 | `user` | `--user` | 配置文件缺失时 `root` | 管理员账号名 |
 | `password` | — | 文件里**没有**这一项时用内置演示口令 `root` / `chusql` | 管理员口令（明文，启动时哈希；见「口令与安全」） |
-| `storage_server` | `--storage` | 空 | 存储进程可执行文件；留空＝存储已在别处运行，只按 `[server] pipe_name` 去连 |
 | `cookie_secure` | `--cookie-secure` | `false` | 给会话 Cookie 加 `Secure`（HTTPS 部署时开） |
 | `body_limit` | `--body-limit` | `65536` | 请求体上限（字节） |
 | `session_idle` | `--session-idle` | `28800` | 会话空闲超时（秒） |
@@ -77,23 +76,22 @@
 对应关系：`static_dir`→`static-dir`、`session_idle`→`session-idle`、`session_max`→`session-max`、
 `login_max_attempts`→`login-max-attempts`、`login_window`→`login-window`、`body_limit`→`body-limit`、
 `rows_per_page`→`rows-per-page`、`max_page_size`→`max-page-size`、`max_rows`→`max-rows`、
-`max_sql_length`→`max-sql-length`、`storage_server`→`storage-server`、
+`max_sql_length`→`max-sql-length`、
 `password_min_length`→`password-min-length`、`password_classes`→`password-classes`。
 `host`、`port`、`user`、`password`、`seed` 只有一种写法。
 
-## 端点（`pipe_name`）
+## `[server]` 分区
 
-端点只有 `pipe_name` 一个配置，两个平台各一条规则：
+TCP 数据库服务 `chusql-server` 的监听参数。单独一段：别层的进程不认这一段，也不需要认。
 
-| 平台 | 实际地址 |
-| ---- | -------- |
-| Windows | `\\.\pipe\<pipe_name>`（具名管道） |
-| Linux / macOS | `<socket_dir>/<pipe_name>.sock`（文件系统套接字） |
+| 键 | 命令行（`chusql-server`） | 默认 | 说明 |
+| -- | ------------------------- | ---- | ---- |
+| `host` | `--host` | `127.0.0.1` | 监听地址 |
+| `port` | `--port` | `7777` | 监听端口；写 `0` 让系统分配，实际端口打在启动横幅里 |
+| `max_message` | `--max-message` | `1048576` | 单行请求上限（字节），超了回 `too_large` |
+| `max_rows` | `--max-rows` | `1000` | 单次查询返回行数上限，超了截断并置 `truncated` |
 
-`socket_dir` 按 `$XDG_RUNTIME_DIR` → `$TMPDIR` → `/tmp` 依次取。**前端和存储进程必须在同一套环境变量
-下启动**，否则两边算出来的路径不一样。Unix 套接字路径上限约 100 字节，`$XDG_RUNTIME_DIR` 太长时会退到
-`/tmp`；上一次崩溃残留的 `.sock` 会被下次启动清掉，若还有进程在听同一个端点，启动会报
-`another storage server already listens on ...`。
+这四项改完要重启 `chusql-server` 才生效（Web 设置页也把它们标成需要重启）。
 
 ## 口令与安全
 
diff --git a/doc/install.md b/doc/install.md
index 27d0475..508642d 100644
--- a/doc/install.md
+++ b/doc/install.md
@@ -11,18 +11,28 @@
 | 包内安装 | 手里已有归档（离线、内网） | 解压后在包根跑 `./install.sh --component web`             |
 | 源码安装 | 没有对应平台资源，或要改代码 | `./install.sh --component web --from-source`            |
 
-`--component web` 装 Web 管理端，`--component cli` 装命令行客户端 `csql`；两种都会带上存储进程
-`chusql-storage`，因为它是后端。
+Linux / macOS 用 `install.sh`，Windows 用 `install.ps1`；一个平台的发行包里 Web 管理端和命令行
+客户端 `csql` 都有。`--component web` / `cli` / `both` 直接指定装哪几个；不写就**逐个问**
+（英文提示，回答 `y` / `n`，直接回车取方括号里的默认值）：
+
+    Install the command line client (csql)? [Y/n]
+    Install the web front end (browser UI)? [y/N]
+
+默认装 `csql`、不装 Web；可以都装、可以只装一个，也可以两个都不选（那就只装存储库
+`libchusql_core_storage.so` / `chusql_core_storage.dll` 和 `chusql-server`）。**没选的组件一个文件都不会释放**。选完再提示设置管理员的初始口令
+（`--password` / `-RootPassword` 给了就不问）。没有终端、又在跑脚本（比如 `curl | sh`）时问不了，
+那时必须显式给 `--component`。
 
 ## 一、发行包
 
-归档由项目在打 tag 时按平台构建上传，名字是 `<component>-<os>-<arch>`，并附 `.sha256`：
+归档由项目在打 tag 时按平台构建上传，名字是 `chusql-<os>-<arch>`，并附 `.sha256`。一个归档里
+Web 和 cli 两部分都有，装哪几个由包内脚本当场问：
 
-| 平台         | 资源名                                                                    |
-| ------------ | ------------------------------------------------------------------------- |
-| Linux x86_64 | `chusql-web-linux-x86_64.tar.gz`、`chusql-cli-linux-x86_64.tar.gz`        |
-| Windows x86_64 | `chusql-web-windows-x86_64.zip`、`chusql-cli-windows-x86_64.zip`        |
-| macOS        | `chusql-web-macos-x86_64.tar.gz`、`chusql-web-macos-arm64.tar.gz`（cli 同理） |
+| 平台           | 资源名                                                     |
+| -------------- | ---------------------------------------------------------- |
+| Linux x86_64   | `chusql-linux-x86_64.tar.gz`                               |
+| Windows x86_64 | `chusql-windows-x86_64.zip`                                |
+| macOS          | `chusql-macos-x86_64.tar.gz`、`chusql-macos-arm64.tar.gz`  |
 
 ### 在线安装
 
@@ -35,12 +45,35 @@
 
     sh -s -- --component cli --repo OWNER/NAME --version v0.3.0
 
+`--version` 不写就是 `latest`：脚本先问 GitHub API 要 release 列表，挑**最新的、正式版、且确实带本平台归档**
+的那个；列表里一个都不合适就不猜。预发布版（prerelease）不会自动选中——要装就显式写 tag。先看有哪些版本：
+
+    sh -s -- --list-versions
+
+自建站点（GitHub Enterprise、镜像）用环境变量换基地址，取包和查版本都跟着走：
+
+    CHUSQL_GITHUB_BASE=https://git.example.com sh -s -- --component web
+
+查版本用的接口未认证时限制 60 次/小时，超了会自动退回 GitHub 的 `latest` 重定向（还能装，但挑不了"最新正式版"）。
+CI 里或装得频繁时给个 token，两个脚本都认（`GITHUB_TOKEN` 也可以）：
+
+    CHUSQL_GITHUB_TOKEN=ghp_xxx sh -s -- --list-versions
+
+Windows 是同一套玩法，`install.ps1` 自己下 zip、校验 sha256、解包：
+
+    irm https://raw.githubusercontent.com/TheBadRoger/ChuSQL/main/scripts/install.ps1 -OutFile install.ps1
+    .\install.ps1 -Component web
+    .\install.ps1 -ListVersions
+    .\install.ps1 -Component cli -Repo OWNER/NAME -Version v0.3.0
+
+在线模式只在脚本旁边没有包时才走：`bin\chusql_core_storage.dll` 在脚本旁边就是包内安装，不碰网络。
+
 ### 指定归档
 
 不碰网络下载逻辑，直接指一个归档（本地路径、`file://` 或任意 URL）：
 
-    ./install.sh --component web --url dist/chusql-web-linux-x86_64.tar.gz
-    ./install.sh --component cli --url https://example.com/chusql-cli-linux-x86_64.tar.gz
+    ./install.sh --component web --url dist/chusql-linux-x86_64.tar.gz
+    ./install.sh --component cli --url https://example.com/chusql-linux-x86_64.tar.gz
 
 ### 包内安装
 
@@ -49,21 +82,28 @@
     ./install.sh --component web --user root --password '...'        # Linux / macOS
     ./install.ps1 -Component web -RootUser root -RootPassword '...'   # Windows
 
-Windows 的 `install.ps1` **只支持包内安装**（没有在线 / 源码模式）；要在线装就先手动下载归档。
+不给 `--component` 就是交互模式，脚本一个个问：
+
+    ./install.sh
+    .\install.ps1
+
+Windows 的 `install.ps1` 两种模式都支持（包内 + 在线），只有源码模式没有——要改代码就在仓库里编。
 
 ## 二、安装选项
 
 | `install.sh`            | `install.ps1`    | 默认            | 说明 |
 | ----------------------- | ---------------- | --------------- | ---- |
-| `--component web\|cli`  | `-Component`     | 必填            | 装哪个前端 |
+| `--component web\|cli\|both` | `-Component` | 逐个问（没有终端时必填） | 装哪个前端 |
+| `--interactive`         | `-Interactive`   | 有终端就问      | 强制从标准输入收答案（`curl \| sh`、自动化里用） |
 | `--install-dir DIR`     | `-InstallDir`    | Linux/macOS `$HOME/.local/share/chusql`；Windows `%LOCALAPPDATA%\ChuSQL` | 程序装到哪 |
 | `--data-dir DIR`        | `-DataDir`       | `<install-dir>/data` | 数据落哪 |
 | `--user NAME`           | `-RootUser`      | `root`          | 管理员账号名 |
 | `--password PW`         | `-RootPassword`  | 空              | 管理员口令；留空＝只允许管理员免密登录 |
 | `--keep-package`        | `-KeepPackage`   | 否              | 装完不删安装包 |
-| `--url URL\|PATH`       | —                | —               | 从这个归档装 |
-| `--repo OWNER/NAME`     | —                | `TheBadRoger/ChuSQL` | 从哪个仓库取发行包 |
-| `--version TAG`         | —                | `latest`        | 下载模式是 release tag，源码模式是 git ref |
+| `--url URL\|PATH`       | —                | —               | 从这个归档装（只有 `install.sh` 有；Windows 直接解压 zip 走包内安装） |
+| `--repo OWNER/NAME`     | `-Repo`          | `TheBadRoger/ChuSQL` | 从哪个仓库取发行包 |
+| `--version TAG`         | `-Version`       | `latest`        | 下载模式是 release tag（`latest`＝最新的、带本平台包的正式版），源码模式是 git ref |
+| `--list-versions`       | `-ListVersions`  | —               | 列出仓库里的发行 tag（预发布带标记），然后退出 |
 | `--from-source`         | —                | —               | 从源码编译安装 |
 | `--source-dir DIR`      | —                | —               | 用本地 checkout 编译，不克隆 |
 
@@ -78,13 +118,13 @@ Windows 的 `install.ps1` **只支持包内安装**（没有在线 / 源码模
 
 ## 四、装完是什么样
 
-以 Linux、`--component web`、默认目录为例：
+以 Linux、`--component web`、默认目录为例（选了 cli 就多一份 `bin/csql` 和一个 `csql` 命令入口）：
 
 | 位置 | 内容 |
 | ---- | ---- |
-| `~/.local/share/chusql/bin/` | `chusql-storage`、`chusql-web` |
-| `~/.local/share/chusql/static/` | Web 前端静态资源 |
-| `~/.local/share/chusql/csql-web`、`csql-web.sh` | 启动器与命令入口（`cli` 组件则是 `csql`） |
+| `~/.local/share/chusql/bin/` | `libchusql_core_storage.so`（一定装）、`chusql-server`（一定装，TCP 数据库服务）、`chusql-web`（选了 Web 才有）、`csql`（选了 cli 才有） |
+| `~/.local/share/chusql/static/` | Web 前端静态资源（选 Web 才有） |
+| `~/.local/share/chusql/csql-web`、`csql-web.sh` | 启动器与命令入口（选 Web 才有；cli 则是 `csql`） |
 | `~/.local/share/chusql/init.sql` | 初始化脚本 |
 | `~/.local/share/chusql/logs/` | 日志 |
 | `~/.local/share/chusql/data/` | 数据目录（Windows 是 `%LOCALAPPDATA%\ChuSQL\data`；可在 `[storage] data_dir` 改） |
@@ -93,8 +133,9 @@ Windows 的 `install.ps1` **只支持包内安装**（没有在线 / 源码模
 
 装完开新终端：
 
-    csql-web        # 起 Web 前端，默认 http://127.0.0.1:7777
+    csql-web        # 起 Web 前端，默认 http://127.0.0.1:7778
     csql            # 进命令行
+    chusql-server   # 起 TCP 数据库服务，默认 127.0.0.1:7777（客户端连接方式见 commands.md）
 
 口令留空时只有管理员能进。账号与权限见 [commands.md](commands.md)，配置项见 [config.md](config.md)。
 
diff --git a/scripts/chusql.toml b/scripts/chusql.toml
index e9d1f8a..04fba01 100644
--- a/scripts/chusql.toml
+++ b/scripts/chusql.toml
@@ -1,10 +1,10 @@
 # ChuSQL 全局配置。
 #
 # 整条链路共用这一份文件，按分区各管各的，互不影响：
-#   存储进程：[page] [btree] [buffer] [storage] [server] [log]
-#   Web / 命令行：[web]（账号口令、会话、分页上限、静态目录、存储进程路径）
-# 端点也在这里：[server] pipe_name 是管名，[storage] data_dir 是数据目录，
-# 谁需要谁读，不再靠环境变量传递。data_dir 这行是安装时会替换的占位：
+#   数据库服务：[server]（TCP 监听地址、端口、单行上限、单次结果行数上限）
+#     —— 只有它装入 chusql_core_storage 动态库并独占数据目录
+#   Web / 命令行：[web]（账号口令、会话、分页上限、静态目录），都经 [server] 走
+# 数据目录在 [storage] data_dir；这一行是安装时会替换的占位：
 # 不写就按平台惯例（Windows %LOCALAPPDATA%\ChuSQL\data，
 # Unix ${XDG_DATA_HOME:-$HOME/.local/share}/chusql/data）。
 # 每一层只读自己那几段，读完就关，不长期占着文件句柄，别的层照样能读。
@@ -27,18 +27,20 @@ pool_size = 1024
 # Windows %LOCALAPPDATA%\ChuSQL\data，Unix ${XDG_DATA_HOME:-$HOME/.local/share}/chusql/data
 data_dir = "../localdata"
 
+# TCP 数据库服务（chusql-server）。单独一段，别层的进程不认识它、也不需要认识。
 [server]
-pipe_name = "chusql-joint"
+host = "127.0.0.1"
+port = 7777
+max_message = 1048576
+max_rows = 1000
 
 [log]
 level = "info"
 
 [web]
 host = "127.0.0.1"
-port = 7777
+port = 7778
 static_dir = "static"
-# 存储进程的可执行文件；留空表示存储已在别处运行，只按 [server] pipe_name 去连
-storage_server = ""
 # 管理员账号与口令。口令留空表示"只允许管理员免密登录"，普通账号一律不能登录。
 user = "root"
 password = ""
diff --git a/scripts/csql-web.ps1 b/scripts/csql-web.ps1
index fc863dc..18e4493 100644
--- a/scripts/csql-web.ps1
+++ b/scripts/csql-web.ps1
@@ -1,9 +1,10 @@
-# csql-web：只负责启动 Web 前端（先拉起存储进程，再起 Web 服务）。
-# 配置走 chusql.toml，两层各读各的分区；这里只取 [web] 的 host/port 拼地址。
-
 $ErrorActionPreference = 'Stop'
 
+# csql-web：先起独占数据目录的 server，再起 Web 服务，配置读 chusql.toml。
+
+# 打印错误并退出 1。
 function Fail([string]$msg) { Write-Host "!! $msg" -ForegroundColor Red; exit 1 }
+# 打印一行输出。
 function Say([string]$msg) { Write-Host $msg }
 
 $home_dir = Split-Path -Parent $MyInvocation.MyCommand.Path
@@ -13,6 +14,7 @@ $config_dir = if ($env:APPDATA) { Join-Path $env:APPDATA 'ChuSQL' } else { Join-
 $config = Join-Path $config_dir 'chusql.toml'
 if (-not (Test-Path $config)) { Fail "config not found: $config" }
 
+# 从配置里取一个 [web] 段的值。
 function Get-WebSetting([string]$Key, [string]$Default) {
     $section = ''
     $pattern = '^\s*' + [regex]::Escape($Key) + '\s*='
@@ -27,21 +29,22 @@ function Get-WebSetting([string]$Key, [string]$Default) {
     return $Default
 }
 
-$storage_exe = Join-Path $bin 'chusql-storage.exe'
+$server_exe = Join-Path $bin 'chusql-server.exe'
 $web_exe = Join-Path $bin 'chusql-web.exe'
-if (-not (Test-Path $storage_exe)) { Fail "storage binary not found in $bin" }
+if (-not (Test-Path $server_exe)) { Fail "server binary not found in $bin" }
 if (-not (Test-Path $web_exe)) { Fail "web binary not found in $bin" }
 
 $host_addr = Get-WebSetting 'host' '127.0.0.1'
-$port = Get-WebSetting 'port' '7777'
+$port = Get-WebSetting 'port' '7778'
 $log_dir = Join-Path $home_dir 'logs'
 New-Item -ItemType Directory -Force -Path $log_dir | Out-Null
 
-$storage = $null
+$server = $null
 $web = $null
 try {
-    $storage = Start-Process -FilePath $storage_exe -WorkingDirectory $home_dir -PassThru -RedirectStandardOutput (Join-Path $log_dir 'storage.log') -RedirectStandardError (Join-Path $log_dir 'storage.err.log')
-    $web = Start-Process -FilePath $web_exe -WorkingDirectory $home_dir -PassThru -RedirectStandardOutput (Join-Path $log_dir 'web.log') -RedirectStandardError (Join-Path $log_dir 'web.err.log')
+    # server 先起来：它进程内装入存储库、独占数据目录，Web 的存储请求都经它转发
+    $server = Start-Process -FilePath $server_exe -ArgumentList '--config', $config -WorkingDirectory $home_dir -PassThru -RedirectStandardOutput (Join-Path $log_dir 'server.log') -RedirectStandardError (Join-Path $log_dir 'server.err.log')
+    $web = Start-Process -FilePath $web_exe -ArgumentList '--config', $config -WorkingDirectory $home_dir -PassThru -RedirectStandardOutput (Join-Path $log_dir 'web.log') -RedirectStandardError (Join-Path $log_dir 'web.err.log')
 
     Say 'starting web ...'
     Say "ready: http://${host_addr}:${port}/"
@@ -51,7 +54,7 @@ try {
     Say "!! web exited with code $($web.ExitCode)"
 }
 finally {
-    foreach ($proc in @($web, $storage)) {
+    foreach ($proc in @($web, $server)) {
         if ($proc -and -not $proc.HasExited) { Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue }
     }
     Say 'stopped.'
diff --git a/scripts/csql-web.sh b/scripts/csql-web.sh
index 2af7b0d..ff65e89 100644
--- a/scripts/csql-web.sh
+++ b/scripts/csql-web.sh
@@ -1,8 +1,8 @@
 #!/bin/sh
-# csql-web：只负责启动 Web 前端（先拉起存储进程，再起 Web 服务）。
-# 配置走 chusql.toml，两层各读各的分区；这里只取 [web] 的 host/port 拼地址。
 set -eu
 
+# csql-web：先起独占数据目录的 server，再起 Web 服务，配置读 chusql.toml。
+
 home_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
 bin="$home_dir/bin"
 
@@ -14,6 +14,7 @@ config_dir="${XDG_CONFIG_HOME:-$HOME/.config}/ChuSQL"
 config="$config_dir/chusql.toml"
 [ -f "$config" ] || { echo "!! config not found: $config" >&2; exit 1; }
 
+# 从配置里取一个 [web] 段的值。
 web_setting() {
     awk -v key="$1" -v def="$2" '
         /^[[:space:]]*\[/ { section = $0; gsub(/[][[:space:]]/, "", section); next }
@@ -34,24 +35,26 @@ web_setting() {
     ' "$config"
 }
 
-storage_exe="$bin/chusql-storage"
+server_exe="$bin/chusql-server"
 web_exe="$bin/chusql-web"
-[ -x "$storage_exe" ] || { echo "!! storage binary not found in $bin" >&2; exit 1; }
+[ -x "$server_exe" ] || { echo "!! server binary not found in $bin" >&2; exit 1; }
 [ -x "$web_exe" ] || { echo "!! web binary not found in $bin" >&2; exit 1; }
 
 host=$(web_setting host 127.0.0.1)
-port=$(web_setting port 7777)
+port=$(web_setting port 7778)
 log_dir="$home_dir/logs"
 mkdir -p "$log_dir"
 
-"$storage_exe" >>"$log_dir/storage.log" 2>>"$log_dir/storage.err.log" &
-storage_pid=$!
-"$web_exe" >>"$log_dir/web.log" 2>>"$log_dir/web.err.log" &
+# server 先起来：它进程内装入存储库、独占数据目录，Web 的存储请求都经它转发
+"$server_exe" --config "$config" >>"$log_dir/server.log" 2>>"$log_dir/server.err.log" &
+server_pid=$!
+"$web_exe" --config "$config" >>"$log_dir/web.log" 2>>"$log_dir/web.err.log" &
 web_pid=$!
 
+# 退出时杀掉 web 与 server 进程。
 cleanup() {
-    kill "$web_pid" "$storage_pid" 2>/dev/null || true
-    wait "$web_pid" "$storage_pid" 2>/dev/null || true
+    kill "$web_pid" "$server_pid" 2>/dev/null || true
+    wait "$web_pid" "$server_pid" 2>/dev/null || true
     echo stopped.
 }
 trap cleanup INT TERM EXIT
diff --git a/scripts/init.sql b/scripts/init.sql
index 9f2d494..9e9881b 100644
--- a/scripts/init.sql
+++ b/scripts/init.sql
@@ -1,7 +1,7 @@
 -- ChuSQL 系统库 schema。
 --
 -- 系统库（system）不存在就自动建，里面的表都是系统表；这份脚本是它们唯一的定义，
--- 存储进程启动时按它声明表结构（见 chusql-storage/src/initsql.rs）。
+-- 存储进程启动时按它声明表结构（见 chusql-core/storage/src/initsql.rs）。
 -- 这里只描述"应该长什么样"，不包含任何历史数据搬迁。
 
 CREATE TABLE __chusql_users (
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index 60d250f..e8137eb 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -1,60 +1,299 @@
-# ChuSQL 安装脚本（Windows）。
-#
-# 包目录结构（解压后就是这个样子）：
-#   bin/         chusql-storage.exe（必装）、chusql-web.exe 或 csql.exe（二选一）
-#   static/      Web 前端静态资源（装 web 组件时带）
-#   scripts/     chusql.toml、init.sql
-#   csql-web.ps1
-#   install.ps1
-#
-# 安装 = 释放到目标目录 + 配好环境变量 + 写全局配置，装完把包目录删掉。
-# storage/engine 一定装；web 与 cli 二选一。
-
 [CmdletBinding()]
 param(
-    [Parameter(Mandatory = $true)][ValidateSet('web', 'cli')][string]$Component,
+    [string]$Component = '',
     [string]$InstallDir = '',
     [string]$DataDir = '',
     [string]$RootUser = 'root',
     [string]$RootPassword = '',
+    [string]$Version = 'latest',
+    [string]$Repo = 'TheBadRoger/ChuSQL',
+    [switch]$ListVersions,
+    [switch]$Interactive,
     [switch]$KeepPackage
 )
 
 $ErrorActionPreference = 'Stop'
 
-function Fail([string]$msg) { Write-Host "!! $msg" -ForegroundColor Red; exit 1 }
+# Windows 安装脚本：从包内或 GitHub 发行版装 cli/web，
+# 写全局配置、改用户 PATH，装完删除安装包。
+
+$script:tempDir = ''
+
+# 报错退出，并清掉半截临时目录。
+function Fail([string]$msg) {
+    Write-Host "!! $msg" -ForegroundColor Red
+    if ($script:tempDir -and (Test-Path $script:tempDir)) {
+        Remove-Item -Recurse -Force $script:tempDir -ErrorAction SilentlyContinue
+    }
+    exit 1
+}
+# 打印步骤标题。
 function Step([string]$msg) { Write-Host ''; Write-Host "==> $msg" -ForegroundColor Cyan }
+# 打印一行输出。
 function Say([string]$msg) { Write-Host $msg }
+# 打印缩进提示行。
+function Note([string]$msg) { Write-Host "  note: $msg" }
+
+# ---- 发行站、平台标签 ----
+$githubBase = if ($env:CHUSQL_GITHUB_BASE) { $env:CHUSQL_GITHUB_BASE.TrimEnd('/') } else { 'https://github.com' }
+$apiBase = if ($githubBase -match '^https?://github\.com$') { 'https://api.github.com' } else { "$githubBase/api/v3" }
+# 查版本走 API，未认证只有 60 次/小时；给了 token 就带上（CI 里 GITHUB_TOKEN 一般就有）
+$githubToken = if ($env:CHUSQL_GITHUB_TOKEN) { $env:CHUSQL_GITHUB_TOKEN } elseif ($env:GITHUB_TOKEN) { $env:GITHUB_TOKEN } else { '' }
+$apiHeaders = @{ 'User-Agent' = 'chusql-install'; 'Accept' = 'application/vnd.github+json' }
+if ($githubToken) { $apiHeaders['Authorization'] = "Bearer $githubToken" }
+$arch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'arm64' } else { 'x86_64' }
+$labels = @("windows-$arch", 'windows')
+
+# 取一份 release 的资源文件名列表。
+function Get-AssetNames($release) { @($release.assets | ForEach-Object { $_.name }) }
+
+# 这份 release 里有没有本平台的包。
+function Test-HasPackage($release) {
+    $names = Get-AssetNames $release
+    foreach ($label in $labels) {
+        if ($names -contains "chusql-$label.zip") { return $true }
+    }
+    return ($names -contains 'chusql.zip')
+}
+
+# 按正式版与带包两档条件挑第一个 tag。
+function Select-Tag([bool]$stableOnly, [bool]$needPackage, $releases) {
+    foreach ($release in $releases) {
+        if ($stableOnly -and $release.prerelease) { continue }
+        if ($needPackage -and -not (Test-HasPackage $release)) { continue }
+        return $release.tag_name
+    }
+    return ''
+}
+
+# 取 URL 的文本内容（字节数组先转字符串）。
+function Get-ResponseText([string]$url) {
+    $response = Invoke-WebRequest -Uri $url -Headers $apiHeaders -UseBasicParsing
+    if ($response.Content -is [byte[]]) { return [System.Text.Encoding]::UTF8.GetString($response.Content) }
+    return [string]$response.Content
+}
+
+# 拉取 release 列表并逐个输出。
+function Get-Releases {
+    try { $text = Get-ResponseText "$apiBase/repos/$Repo/releases?per_page=100" } catch { return }
+    try { $parsed = ConvertFrom-Json -InputObject $text } catch { return }
+    if ($null -eq $parsed) { return }
+    foreach ($release in @($parsed)) {
+        if ($null -ne $release) { Write-Output $release }
+    }
+}
+
+# ---- 列版本 ----
+if ($ListVersions) {
+    Say ("ChuSQL releases in {0}" -f $Repo)
+    $releases = @(Get-Releases)
+    if ($releases.Count -eq 0) {
+        Fail "cannot list the releases of $Repo from $apiBase`n   (offline, rate limited, or the repository has no release yet)`n   open $githubBase/$Repo/releases and pass a tag: -Version <tag>"
+    }
+    foreach ($release in $releases) {
+        $mark = ''
+        if ($release.prerelease) { $mark += ' (prerelease)' }
+        if (-not (Test-HasPackage $release)) { $mark += " (no package for windows-$arch)" }
+        Say ("  {0}{1}" -f $release.tag_name, $mark)
+    }
+    Say ''
+    Say 'install one with: .\install.ps1 -Version <tag>'
+    exit 0
+}
+
+if ($Component -notin @('web', 'cli', 'both', '')) { Fail "pass -Component web, cli or both (got: $Component)" }
+
+# ---- 交互：控制台里直接问答；-Interactive 时没有终端也从 stdin 逐行读（自动化用）----
+$askFromStdin = $false
+$canPrompt = $false
+if ($Interactive) { $askFromStdin = $true; $canPrompt = $true }
+elseif (-not [Console]::IsInputRedirected) { $canPrompt = $true }
+
+# 读一行输入（可选从 stdin 读）。
+function Ask-Line([string]$prompt) {
+    if ($askFromStdin) {
+        Write-Host $prompt -NoNewline
+        $line = [Console]::In.ReadLine()
+        if ($null -eq $line) { $line = '' }
+        return $line
+    }
+    return (Read-Host $prompt)
+}
+
+# 问 y/n，回车用缺省值，返回布尔。
+function Ask-YesNo([string]$prompt, [bool]$defaultYes) {
+    while ($true) {
+        $answer = (Ask-Line $prompt).Trim()
+        if ($answer -eq '') { return $defaultYes }
+        if ($answer -match '^(y|yes)$') { return $true }
+        if ($answer -match '^(n|no)$') { return $false }
+        Write-Host '  please answer y or n'
+    }
+}
+
+# 读取隐藏输入的密码。
+function Ask-Secret([string]$prompt) {
+    if ($askFromStdin) { return (Ask-Line $prompt) }
+    $secure = Read-Host $prompt -AsSecureString
+    $bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
+    try { return [System.Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr) }
+    finally { [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr) }
+}
+
+$wantWeb = $false
+$wantCli = $false
+if ($Component -eq 'web') { $wantWeb = $true }
+if ($Component -eq 'cli') { $wantCli = $true }
+if ($Component -eq 'both') { $wantWeb = $true; $wantCli = $true }
+
+if (-not $Component) {
+    if (-not $canPrompt) {
+        Fail '-Component is required (web, cli or both) when there is no terminal to ask on'
+    }
+    Write-Host ''
+    Write-Host 'ChuSQL installer: which parts do you want?'
+    $wantCli = Ask-YesNo 'Install the command line client (csql)? [Y/n]' $true
+    $wantWeb = Ask-YesNo 'Install the web front end (browser UI)? [y/N]' $false
+    if (-not $wantWeb -and -not $wantCli) {
+        Say '  neither selected: only the storage library and the server get installed'
+    }
+}
+
+if (-not $PSBoundParameters.ContainsKey('RootPassword') -and $canPrompt) {
+    Write-Host ''
+    Write-Host ('The administrator account is "{0}".' -f $RootUser)
+    $firstPassword = Ask-Secret ('Root password for {0} (empty means no password) []:' -f $RootUser)
+    if ($firstPassword) {
+        $againPassword = Ask-Secret 'Repeat the root password:'
+        if ($firstPassword -ne $againPassword) { Fail 'the two passwords do not match' }
+        Write-Host 'root password set'
+    } else {
+        Write-Host 'no root password: administrator-only sign-in'
+    }
+    $RootPassword = $firstPassword
+}
+
+$wanted = @()
+if ($wantCli) { $wanted += 'cli' }
+if ($wantWeb) { $wanted += 'web' }
+$componentLabel = ($wanted -join '+')
+if (-not $componentLabel) { $componentLabel = 'none (storage only)' }
 
 $pack = Split-Path -Parent $MyInvocation.MyCommand.Path
+$downloaded = $false
+$tempDir = ''
+
 if (-not $InstallDir) { $InstallDir = Join-Path $env:LOCALAPPDATA 'ChuSQL' }
 if (-not $DataDir) { $DataDir = Join-Path $InstallDir 'data' }
 $InstallDir = [System.IO.Path]::GetFullPath($InstallDir)
 $DataDir = [System.IO.Path]::GetFullPath($DataDir)
 
+# ---- 取包：脚本旁边有包就装本地的，否则去发行站下载 ----
+if (-not (Test-Path (Join-Path $pack 'bin\chusql_core_storage.dll'))) {
+    Step 'Looking for the package'
+
+    if ($Version -eq 'latest') {
+        $releases = @(Get-Releases)
+        if ($releases.Count -eq 0) {
+            Note "version    latest (cannot reach $apiBase; using the latest release redirect)"
+        } else {
+            $picked = Select-Tag $true $true $releases
+            if (-not $picked) { $picked = Select-Tag $false $true $releases }
+            if (-not $picked) { $picked = Select-Tag $true $false $releases }
+            if (-not $picked) { $picked = Select-Tag $false $false $releases }
+            if ($picked) { $Version = $picked; Note "version    $Version" }
+            else { Note 'no release lists a matching package; falling back to the latest release redirect' }
+        }
+    }
+
+    $tempDir = Join-Path ([System.IO.Path]::GetTempPath()) ("chusql-install-" + [Guid]::NewGuid().ToString('N'))
+    $script:tempDir = $tempDir
+    New-Item -ItemType Directory -Force -Path $tempDir | Out-Null
+
+    # 一个平台一个包：web 和 cli 都在里面，装哪几个由上面的选择决定
+    Step "Looking for a chusql package for windows-$arch"
+    $zip = Join-Path $tempDir 'chusql.zip'
+    $asset = ''
+    $assetUrl = ''
+    $candidates = @()
+    foreach ($label in $labels) { $candidates += "chusql-$label.zip" }
+    $candidates += 'chusql.zip'
+    foreach ($candidate in $candidates) {
+        $tryUrl = if ($Version -eq 'latest') { "$githubBase/$Repo/releases/latest/download/$candidate" }
+        else { "$githubBase/$Repo/releases/download/$Version/$candidate" }
+        try {
+            Invoke-WebRequest -Uri $tryUrl -Headers $apiHeaders -OutFile $zip -UseBasicParsing
+            $asset = $candidate
+            $assetUrl = $tryUrl
+            break
+        } catch {
+            continue
+        }
+    }
+    if (-not $asset) {
+        Fail "no package for windows-$arch in $Repo ($Version); try -ListVersions, or install from an archive you downloaded yourself"
+    }
+    Note "asset      $asset"
+
+    $published = ''
+    try { $published = Get-ResponseText "$assetUrl.sha256" } catch { $published = '' }
+    if ($published) {
+        $expected = ($published.Trim() -split '\s+')[0].ToLower()
+        $actual = (Get-FileHash -Path $zip -Algorithm SHA256).Hash.ToLower()
+        if ($actual -ne $expected) { Fail "checksum mismatch: expected $expected, got $actual" }
+        Note "checksum   $expected (ok)"
+    } else {
+        Note 'checksum   no .sha256 published for this asset (skipped)'
+    }
+
+    Step 'Unpacking the package'
+    $expanded = Join-Path $tempDir 'package'
+    New-Item -ItemType Directory -Force -Path $expanded | Out-Null
+    Expand-Archive -Path $zip -DestinationPath $expanded -Force
+    if (-not (Test-Path (Join-Path $expanded 'bin\chusql_core_storage.dll'))) {
+        # 归档里多包了一层目录也能装
+        $inner = Get-ChildItem -Path $expanded -Directory | Select-Object -First 1
+        if ($inner -and (Test-Path (Join-Path $inner.FullName 'bin\chusql_core_storage.dll'))) { $expanded = $inner.FullName }
+    }
+    $pack = $expanded
+    $downloaded = $true
+}
+
 # ---- 校验包内容 ----
-$storageExe = Join-Path $pack 'bin\chusql-storage.exe'
-if (-not (Test-Path $storageExe)) { Fail "package is incomplete: bin\chusql-storage.exe not found in $pack" }
-if ($Component -eq 'web') {
+$storageLib = Join-Path $pack 'bin\chusql_core_storage.dll'
+if (-not (Test-Path $storageLib)) { Fail "package is incomplete: bin\chusql_core_storage.dll not found in $pack" }
+if (-not (Test-Path (Join-Path $pack 'bin\chusql-server.exe'))) { Fail 'package is incomplete: bin\chusql-server.exe not found' }
+if ($wantWeb) {
     if (-not (Test-Path (Join-Path $pack 'bin\chusql-web.exe'))) { Fail 'package is incomplete: bin\chusql-web.exe not found' }
     if (-not (Test-Path (Join-Path $pack 'static'))) { Fail 'package is incomplete: static\ not found' }
-} else {
+}
+if ($wantCli) {
     if (-not (Test-Path (Join-Path $pack 'bin\csql.exe'))) { Fail 'package is incomplete: bin\csql.exe not found' }
 }
 $template = Join-Path $pack 'scripts\chusql.toml'
 if (-not (Test-Path $template)) { Fail 'package is incomplete: scripts\chusql.toml not found' }
 
 Say "ChuSQL installer"
-Say ("  component  {0}" -f $Component)
+Say ("  version    {0}" -f $Version)
+Say ("  components {0}" -f $componentLabel)
+if ($downloaded) { Say ("  release    {0}" -f $Version) }
 Say ("  install to {0}" -f $InstallDir)
 Say ("  data dir   {0}" -f $DataDir)
 Say ("  root user  {0}{1}" -f $RootUser, $(if ($RootPassword) { '' } else { ' (no password: administrator-only sign-in)' }))
 
 # ---- 释放文件 ----
+# 包是合在一起的（web 和 cli 都在），这里按这次的选择逐个释放：没选的组件不落地
 Step 'Installing files'
 New-Item -ItemType Directory -Force -Path (Join-Path $InstallDir 'bin'), (Join-Path $InstallDir 'logs'), $DataDir | Out-Null
-Copy-Item (Join-Path $pack 'bin\*') (Join-Path $InstallDir 'bin') -Recurse -Force
-if ($Component -eq 'web') {
+Copy-Item $storageLib (Join-Path $InstallDir 'bin') -Force
+Copy-Item (Join-Path $pack 'bin\chusql-server.exe') (Join-Path $InstallDir 'bin') -Force
+Get-ChildItem (Join-Path $pack 'bin') -Filter '*.dll' -File -ErrorAction SilentlyContinue |
+    ForEach-Object { Copy-Item $_.FullName (Join-Path $InstallDir 'bin') -Force }
+if ($wantCli) {
+    Copy-Item (Join-Path $pack 'bin\csql.exe') (Join-Path $InstallDir 'bin') -Force
+}
+if ($wantWeb) {
+    Copy-Item (Join-Path $pack 'bin\chusql-web.exe') (Join-Path $InstallDir 'bin') -Force
     New-Item -ItemType Directory -Force -Path (Join-Path $InstallDir 'static') | Out-Null
     Copy-Item (Join-Path $pack 'static\*') (Join-Path $InstallDir 'static') -Recurse -Force
     $launcher = Join-Path $pack 'csql-web.ps1'
@@ -80,12 +319,13 @@ Copy-Item (Join-Path $pack 'scripts\init.sql') $InstallDir -Force -ErrorAction S
 
 # ---- 命令入口 ----
 Step 'Creating commands'
-if ($Component -eq 'web') {
+if ($wantWeb) {
     Set-Content -Path (Join-Path $InstallDir 'csql-web.cmd') -Encoding ASCII -Value @'
 @echo off
 powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0csql-web.ps1" %*
 '@
-} else {
+}
+if ($wantCli) {
     Set-Content -Path (Join-Path $InstallDir 'csql.cmd') -Encoding ASCII -Value @'
 @echo off
 "%~dp0bin\csql.exe" %*
@@ -108,17 +348,28 @@ if ($entries -notcontains $InstallDir) {
 # ---- 删掉安装包 ----
 if (-not $KeepPackage) {
     Step 'Removing the package'
-    $marker = Join-Path $pack 'bin\chusql-storage.exe'
-    $safe = (Test-Path $marker) -and ($pack -ne $InstallDir) -and (-not $InstallDir.StartsWith($pack, [StringComparison]::OrdinalIgnoreCase))
-    if ($safe) {
-        Remove-Item -Recurse -Force $pack
+    if ($downloaded) {
+        Remove-Item -Recurse -Force $tempDir -ErrorAction SilentlyContinue
         Say 'package removed'
     } else {
-        Say ("kept the package (not safe to delete automatically): {0}" -f $pack)
+        $marker = Join-Path $pack 'bin\chusql_core_storage.dll'
+        $safe = (Test-Path $marker) -and ($pack -ne $InstallDir) -and (-not $InstallDir.StartsWith($pack, [StringComparison]::OrdinalIgnoreCase))
+        if ($safe) {
+            Remove-Item -Recurse -Force $pack
+            Say 'package removed'
+        } else {
+            Say ("kept the package (not safe to delete automatically): {0}" -f $pack)
+        }
     }
+} elseif ($downloaded) {
+    Say ("kept the downloaded package: {0}" -f $tempDir)
 }
 
 Step 'Done'
 Say ("  chusql.toml  {0}" -f $configFile)
 Say ("  data         {0}" -f $DataDir)
-if ($Component -eq 'web') { Say '  start with   csql-web' } else { Say '  start with   csql' }
+$startWith = @()
+if ($wantWeb) { $startWith += 'csql-web' }
+if ($wantCli) { $startWith += 'csql' }
+Say ("  start with   {0}" -f ($startWith -join ', '))
+Say ("  tcp server   {0} (listens on [server] host/port, defaults 127.0.0.1:7777)" -f (Join-Path $InstallDir 'bin\chusql-server.exe'))
diff --git a/scripts/install.sh b/scripts/install.sh
index 677786d..f76de47 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -1,55 +1,60 @@
 #!/bin/sh
-# ChuSQL 安装脚本（Linux / macOS / POSIX sh）。
-#
-# 三种来源，脚本自己判断走哪条：
-#
-#   1) 包内安装：解压一个发行包，脚本旁边就是 bin/，直接装本地文件
-#        ./install.sh --component web
-#
-#   2) 在线安装：脚本从 GitHub 取发行包（也可用 --url 指任意 URL 或本地归档）
-#        curl -fsSL https://raw.githubusercontent.com/TheBadRoger/ChuSQL/main/scripts/install.sh \
-#            | sh -s -- --component web
-#        sh install.sh --component web --url dist/chusql-web-linux-x86_64.tar.gz
-#
-#   3) 源码安装：拉仓库、本地编译（要有 git + cargo + stack + ghc）
-#        ./install.sh --component web --from-source
-#        ./install.sh --component web --from-source --source-dir ../ChuSQL
-#
-# 安装 = 释放到目标目录 + 配好环境变量 + 写全局配置，装完把包目录删掉。
-# storage/engine 一定装；web 与 cli 二选一。
-#
-# 包目录结构（解压后就是这个样子）：
-#   bin/         chusql-storage（必装）、chusql-web 或 csql（二选一）
-#   static/      Web 前端静态资源（装 web 组件时带）
-#   scripts/     chusql.toml、init.sql
-#   csql-web.sh
-#   install.sh
-
 set -eu
 
+# ChuSQL 安装脚本（Linux/macOS）：从包内、发行版或源码装 cli/web，
+# 写全局配置、改 PATH，装完删除安装包。
+
 default_repo='TheBadRoger/ChuSQL'
 
+# GitHub 站点：github.com 用 api.github.com；其它（GitHub Enterprise、镜像、本地夹具）
+# 按 GHE 的约定走 <base>/api/v3，下载也走 <base>/<owner>/<repo>/releases/download/。
+github_base="${CHUSQL_GITHUB_BASE:-https://github.com}"
+github_base="${github_base%/}"
+case "$github_base" in
+    https://github.com|http://github.com) api_base='https://api.github.com' ;;
+    *) api_base="$github_base/api/v3" ;;
+esac
+
+# 查版本走 API，未认证只有 60 次/小时；给了 token 就带上（CI 里 GITHUB_TOKEN 一般就有）
+github_token="${CHUSQL_GITHUB_TOKEN:-${GITHUB_TOKEN:-}}"
+
+# 打印用法、选项与环境变量说明。
 usage() {
     cat <<'EOF'
-usage: ./install.sh --component web|cli [options]
+usage: ./install.sh [--component web|cli|both] [options]
 
-  --component web|cli     which front end to install (required)
+  --component web|cli|both
+                          which parts to install. Leave it out and the installer
+                          asks (English, y/n), command line client first:
+                            command line client (csql)?   default yes [Y/n]
+                            web front end (browser UI)?   default no  [y/N]
 
+  --interactive           ask even when there is no terminal; the answers are
+                          read from stdin (one per line)
   --install-dir DIR       where to install   (default: $HOME/.local/share/chusql)
   --data-dir DIR          where to keep data (default: <install-dir>/data)
   --user NAME             administrator name (default: root)
   --password PW           administrator password, empty means no password
-                          (administrator-only sign-in)
+                          (administrator-only sign-in). Leave it out and the
+                          installer asks for it, twice, with the echo off.
   --keep-package          do not delete the downloaded/extracted package
 
 where the files come from:
   (default)               a package next to this script, else the newest GitHub release
   --url URL|PATH          install from this archive (URL, file:// URL or local path)
   --repo OWNER/NAME       GitHub repository (default: TheBadRoger/ChuSQL)
-  --version TAG           release tag to download / git ref to build (default: latest)
+  --version TAG           release tag to download / git ref to build
+                          (default: latest = the newest release that has your package)
+  --list-versions         list the release tags in the repository, then exit
   --from-source           clone and build locally (needs git, cargo, stack, ghc)
   --source-dir DIR        build from this checkout instead of cloning
   -h, --help              this text
+
+environment:
+  CHUSQL_GITHUB_BASE      GitHub base URL: GitHub Enterprise, a mirror, or a
+                          local test fixture (default: https://github.com)
+  CHUSQL_GITHUB_TOKEN     token for the version API (or GITHUB_TOKEN); without
+                          one the API allows 60 requests per hour
 EOF
 }
 
@@ -64,6 +69,11 @@ version='latest'
 url_arg=''
 from_source='no'
 source_dir=''
+list_versions='no'
+interactive_flag='no'
+password_given='no'
+want_web='no'
+want_cli='no'
 
 while [ $# -gt 0 ]; do
     case "$1" in
@@ -71,11 +81,13 @@ while [ $# -gt 0 ]; do
         --install-dir) install_dir="${2:-}"; shift 2 ;;
         --data-dir) data_dir="${2:-}"; shift 2 ;;
         --user) root_user="${2:-}"; shift 2 ;;
-        --password) root_password="${2:-}"; shift 2 ;;
+        --password) root_password="${2:-}"; password_given='yes'; shift 2 ;;
         --keep-package) keep_package='yes'; shift ;;
         --url) url_arg="${2:-}"; shift 2 ;;
         --repo) repo="${2:-}"; shift 2 ;;
         --version) version="${2:-}"; shift 2 ;;
+        --list-versions) list_versions='yes'; shift ;;
+        --interactive) interactive_flag='yes'; shift ;;
         --from-source) from_source='yes'; shift ;;
         --source-dir) source_dir="${2:-}"; shift 2 ;;
         -h|--help) usage; exit 0 ;;
@@ -83,15 +95,23 @@ while [ $# -gt 0 ]; do
     esac
 done
 
+# 打印错误并退出 1。
 fail() { echo "!! $1" >&2; exit 1; }
+# 打印步骤标题。
 step() { echo; echo "==> $1"; }
+# 打印缩进提示行。
 note() { echo "  $1"; }
 
-case "$component" in
-    web|cli) ;;
-    '') fail '--component is required (web or cli)' ;;
-    *) fail "--component must be web or cli, got: $component" ;;
-esac
+# --list-versions 只问仓库有什么版本，不需要 --component
+if [ "$list_versions" = 'no' ]; then
+    case "$component" in
+        web)  want_web='yes' ;;
+        cli)  want_cli='yes' ;;
+        both) want_web='yes'; want_cli='yes' ;;
+        '')   : ;;   # 没给就交互询问（下面），问不了才报错
+        *) fail "--component must be web, cli or both, got: $component" ;;
+    esac
+fi
 
 # ---- 本脚本在哪（管道进来时 $0 是 sh，这时没有本地包）----
 self=$0
@@ -104,27 +124,137 @@ esac
 [ -n "$install_dir" ] || install_dir="$HOME/.local/share/chusql"
 [ -n "$data_dir" ] || data_dir="$install_dir/data"
 
+# ---- 交互：先确定答案从哪来 ----
+# 管道安装（curl ... | sh -s --）时 stdin 是脚本本身，所以优先开 /dev/tty；
+# 没有控制终端时只认 --interactive（答案按行从 stdin 读），否则保持原来的非交互行为。
+answers=''
+can_prompt='no'
+if [ "$interactive_flag" = 'yes' ]; then
+    answers='stdin'
+    can_prompt='yes'
+elif (exec 3</dev/tty) 2>/dev/null; then
+    answers='/dev/tty'
+    can_prompt='yes'
+elif [ -t 0 ]; then
+    answers='stdin'
+    can_prompt='yes'
+fi
+
+read_line() {   # -> $line（读到空行也算成功）
+    if [ "$answers" = 'stdin' ]; then
+        IFS= read -r line || line=''
+    else
+        IFS= read -r line < "$answers" || line=''
+    fi
+}
+
+read_secret() { # read_secret PROMPT -> 值写到 stdout（提示和换行都走 stderr，回显关掉）
+    printf '%s' "$1" >&2
+    if [ "$answers" = 'stdin' ]; then
+        IFS= read -r secret_line || secret_line=''
+    else
+        saved=''
+        if command -v stty >/dev/null 2>&1; then
+            saved=$(stty -g < "$answers" 2>/dev/null) || saved=''
+            stty -echo < "$answers" 2>/dev/null || true
+        fi
+        IFS= read -r secret_line < "$answers" || secret_line=''
+        if [ -n "$saved" ]; then
+            stty "$saved" < "$answers" 2>/dev/null || true
+        elif command -v stty >/dev/null 2>&1; then
+            stty echo < "$answers" 2>/dev/null || true
+        fi
+    fi
+    printf '\n' >&2
+    printf '%s' "$secret_line"
+}
+
+ask_yes_no() {  # ask_yes_no PROMPT DEFAULT(y|n) -> $reply = yes|no
+    while :; do
+        printf '%s ' "$1" >&2
+        read_line
+        case "$line" in
+            '') reply="$2" ;;
+            [Yy]|[Yy][Ee][Ss]) reply='yes' ;;
+            [Nn]|[Nn][Oo]) reply='no' ;;
+            *) echo '  please answer y or n' >&2; continue ;;
+        esac
+        return 0
+    done
+}
+
+if [ "$component" = '' ] && [ "$list_versions" = 'no' ]; then
+    if [ "$can_prompt" = 'no' ]; then
+        fail '--component is required (web, cli or both) when there is no terminal to ask on'
+    fi
+    echo
+    echo 'ChuSQL installer: which parts do you want?'
+    ask_yes_no 'Install the command line client (csql)? [Y/n]' yes
+    want_cli="$reply"
+    ask_yes_no 'Install the web front end (browser UI)? [y/N]' no
+    want_web="$reply"
+    if [ "$want_web" = 'no' ] && [ "$want_cli" = 'no' ]; then
+        echo '  neither selected: only the storage library and the server get installed' >&2
+    fi
+fi
+
+if [ "$list_versions" = 'no' ] && [ "$password_given" = 'no' ] && [ "$can_prompt" = 'yes' ]; then
+    echo
+    echo "The administrator account is $root_user."
+    first=$(read_secret "Root password for $root_user (empty means no password) []: ")
+    if [ -n "$first" ]; then
+        again=$(read_secret 'Repeat the root password: ')
+        [ "$first" = "$again" ] || fail 'the two passwords do not match'
+        echo 'root password set' >&2
+    else
+        echo 'no root password: administrator-only sign-in' >&2
+    fi
+    root_password="$first"
+fi
+
+# 选中的组件：空格分隔的清单，外加一个显示名（cli 或 web，两个就是 cli+web）
+wanted=''
+if [ "$want_cli" = 'yes' ]; then wanted='cli'; fi
+if [ "$want_web" = 'yes' ]; then
+    if [ -n "$wanted" ]; then wanted="$wanted web"; else wanted='web'; fi
+fi
+component_label=''
+for comp in $wanted; do
+    if [ -n "$component_label" ]; then component_label="$component_label+$comp"; else component_label="$comp"; fi
+done
+if [ -z "$component_label" ]; then component_label='none (storage only)'; fi
+
 tmp=''
+# 退出时删掉临时目录。
 cleanup() { if [ -n "$tmp" ]; then rm -rf "$tmp"; fi; }
+# 建临时目录并登记退出清理。
 new_tmp() {
     tmp=$(mktemp -d "${TMPDIR:-/tmp}/chusql-install.XXXXXX") || fail 'cannot create a temporary directory'
     # --keep-package 时不注册清理，临时目录就留着
     if [ "$keep_package" = 'no' ]; then trap cleanup EXIT INT TERM HUP; fi
 }
 
+# 用 curl 或 wget 把 URL 下载到文件。
 download() {
-    # download URL FILE
     if command -v curl >/dev/null 2>&1; then
-        curl -fsSL -o "$2" "$1" || return 1
+        if [ -n "${3:-}" ]; then
+            curl -fsSL -H "$3" -H 'Accept: application/vnd.github+json' -o "$2" "$1" || return 1
+        else
+            curl -fsSL -o "$2" "$1" || return 1
+        fi
     elif command -v wget >/dev/null 2>&1; then
-        wget -q -O "$2" "$1" || return 1
+        if [ -n "${3:-}" ]; then
+            wget -q --header="$3" --header='Accept: application/vnd.github+json' -O "$2" "$1" || return 1
+        else
+            wget -q -O "$2" "$1" || return 1
+        fi
     else
         fail 'need curl or wget to download the package'
     fi
 }
 
+# 校验包的 sha256，没有就跳过。
 verify_checksum() {
-    # verify_checksum ASSET_URL FILE —— 发布带 .sha256 就校验，没带就说明一下
     sums="$tmp/asset.sha256"
     if ! download "$1.sha256" "$sums" 2>/dev/null; then
         note 'checksum   no .sha256 published for this asset (skipped)'
@@ -142,13 +272,13 @@ verify_checksum() {
     note "checksum   $expected (ok)"
 }
 
+# 按扩展名解包 zip 或 tar.gz。
 unpack() {
-    # unpack ARCHIVE DEST
     mkdir -p "$2"
     case "$1" in
         *.zip)
             command -v unzip >/dev/null 2>&1 || fail 'unzip is required to open a .zip package'
-            unzip -q "$1" -d "$2"
+            unzip -q -o "$1" -d "$2"
             ;;
         *)
             tar -xzf "$1" -C "$2"
@@ -156,7 +286,7 @@ unpack() {
     esac
 }
 
-# 平台标签（全局：os、arch、ext、labels）
+# 探测平台标签（os、arch、ext、labels）。
 detect_platform() {
     os=$(uname -s 2>/dev/null || echo unknown)
     case "$os" in
@@ -173,13 +303,127 @@ detect_platform() {
     labels="$os-$arch $os"
 }
 
-# 发行资源（全局：url、archive），成功返回 0
+# ---- 发行 tag：问 GitHub API（不依赖 jq，用 awk 读 JSON）----
+# 请求 GitHub API 并落盘。
+api_get() {
+    if [ -n "$github_token" ]; then
+        download "$api_base$1" "$2" "Authorization: Bearer $github_token"
+    else
+        download "$api_base$1" "$2"
+    fi
+}
+
+# 把 release JSON 解析成 tag 与资源行。
+parse_releases() {
+    awk '
+        in_assets {
+            if ($0 ~ /^[[:space:]]*\]/) { in_assets = 0; next }
+            if ($0 ~ /"name":/) {
+                s = $0; sub(/.*"name": *"/, "", s); sub(/".*/, "", s)
+                if (s != "") { assets = assets " " s }
+            }
+            next
+        }
+        /"assets": *\[\]/ { next }
+        /"assets": *\[/ { in_assets = 1; next }
+        /"tag_name":/ {
+            if (tag != "") { print tag "\t" pre "\t" assets }
+            s = $0; sub(/.*"tag_name": *"/, "", s); sub(/".*/, "", s)
+            tag = s; pre = 0; assets = ""
+            next
+        }
+        /"prerelease":/ { pre = ($0 ~ /true/) ? 1 : 0; next }
+        END { if (tag != "") { print tag "\t" pre "\t" assets } }
+    ' "$1"
+}
+
+# 这份 release 里有没有本平台的包。
+tag_has_asset() {
+    for label in $labels; do
+        case " $1 " in
+            *" chusql-$label.$ext "*) return 0 ;;
+        esac
+    done
+    case " $1 " in
+        *" chusql.$ext "*) return 0 ;;
+    esac
+    return 1
+}
+
+# 从 tags.txt 里挑第一个符合条件的 tag。
+pick_tag() {
+    [ -s "$tmp/tags.txt" ] || return 1
+    while IFS="$(printf '\t')" read -r tag pre assets; do
+        [ -n "$tag" ] || continue
+        if [ "$1" = 'yes' ] && [ "$pre" = '1' ]; then continue; fi
+        if [ "$2" = 'yes' ] && ! tag_has_asset "$assets"; then continue; fi
+        printf '%s\n' "$tag"
+        return 0
+    done < "$tmp/tags.txt"
+    return 1
+}
+
+# 列出仓库的 release tag 与预发布标记。
+list_release_versions() {
+    new_tmp
+    json="$tmp/releases.json"
+    if ! api_get "/repos/$repo/releases?per_page=100" "$json" 2>/dev/null ||
+        ! parse_releases "$json" > "$tmp/tags.txt" 2>/dev/null ||
+        [ ! -s "$tmp/tags.txt" ]; then
+        echo "!! cannot list the releases of $repo from $api_base" >&2
+        echo '   (offline, rate limited, or the repository has no release yet)' >&2
+        echo "   open $github_base/$repo/releases and pass a tag: --version <tag>" >&2
+        exit 1
+    fi
+    echo "ChuSQL releases in $repo"
+    while IFS="$(printf '\t')" read -r tag pre assets; do
+        [ -n "$tag" ] || continue
+        marker=''
+        if [ "$pre" = '1' ]; then marker=' (prerelease)'; fi
+        if ! tag_has_asset "$assets"; then
+            marker="$marker (no package for $os-$arch)"
+        fi
+        echo "  $tag$marker"
+    done < "$tmp/tags.txt"
+    echo
+    echo "install one with: ./install.sh --version <tag>"
+}
+
+# 把 version=latest 解析成具体 tag。
+resolve_version() {
+    [ "$version" = 'latest' ] || return 0
+    json="$tmp/releases.json"
+    if ! api_get "/repos/$repo/releases?per_page=100" "$json" 2>/dev/null; then
+        note "version    latest (cannot reach $api_base; using the latest release redirect)"
+        return 0
+    fi
+    parse_releases "$json" > "$tmp/tags.txt" 2>/dev/null || true
+    picked=''
+    for want_stable in yes no; do
+        picked=$(pick_tag "$want_stable" 'yes') && break
+        picked=''
+    done
+    if [ -z "$picked" ]; then
+        for want_stable in yes no; do
+            picked=$(pick_tag "$want_stable" 'no') && break
+            picked=''
+        done
+    fi
+    if [ -n "$picked" ]; then
+        version="$picked"
+        note "version    $version"
+    else
+        note 'version    latest (no release lists a matching package; trying the latest release)'
+    fi
+}
+
+# 下载本平台的发行包归档。
 fetch_asset() {
     asset="$1"
     if [ "$version" = 'latest' ]; then
-        url="https://github.com/$repo/releases/latest/download/$asset"
+        url="$github_base/$repo/releases/latest/download/$asset"
     else
-        url="https://github.com/$repo/releases/download/$version/$asset"
+        url="$github_base/$repo/releases/download/$version/$asset"
     fi
     archive="$tmp/$asset"
     if download "$url" "$archive" 2>/dev/null; then
@@ -193,6 +437,12 @@ pack=''
 url=''
 archive=''
 
+if [ "$list_versions" = 'yes' ]; then
+    detect_platform
+    list_release_versions
+    exit 0
+fi
+
 if [ "$from_source" = 'yes' ]; then
     # ---------- 源码安装 ----------
     if [ -z "$source_dir" ]; then
@@ -208,17 +458,17 @@ if [ "$from_source" = 'yes' ]; then
     else
         src="$tmp/src"
         if [ "$version" = 'latest' ]; then
-            step "Cloning https://github.com/$repo.git"
-            git clone --depth 1 "https://github.com/$repo.git" "$src" >/dev/null 2>&1 ||
-                fail "cannot clone https://github.com/$repo.git"
+            step "Cloning $github_base/$repo.git"
+            git clone --depth 1 "$github_base/$repo.git" "$src" >/dev/null 2>&1 ||
+                fail "cannot clone $github_base/$repo.git"
         else
-            step "Cloning https://github.com/$repo.git at $version"
-            git clone --depth 1 --branch "$version" "https://github.com/$repo.git" "$src" >/dev/null 2>&1 ||
+            step "Cloning $github_base/$repo.git at $version"
+            git clone --depth 1 --branch "$version" "$github_base/$repo.git" "$src" >/dev/null 2>&1 ||
                 fail "cannot clone $repo at $version"
         fi
         note "source     $src"
     fi
-    [ -f "$src/chusql-storage/Cargo.toml" ] || fail "not a ChuSQL checkout (chusql-storage/Cargo.toml missing): $src"
+    [ -f "$src/chusql-core/storage/Cargo.toml" ] || fail "not a ChuSQL checkout (chusql-core/storage/Cargo.toml missing): $src"
     [ -f "$src/scripts/chusql.toml" ] || fail "not a ChuSQL checkout (scripts/chusql.toml missing): $src"
 
     if command -v pkg-config >/dev/null 2>&1 && ! pkg-config --exists zlib 2>/dev/null; then
@@ -226,39 +476,48 @@ if [ "$from_source" = 'yes' ]; then
     fi
 
     step 'Building the Rust storage (cargo build --release)'
-    ( cd "$src/chusql-storage" && cargo build --release ) || fail 'cargo build --release failed'
-    storage_bin="$src/chusql-storage/target/release/chusql-storage"
-    [ -f "$storage_bin" ] || fail "storage binary not found after the build: $storage_bin"
-
-    if [ "$component" = 'web' ]; then
-        comp_dir='chusql-web'; front_name='chusql-web'
-    else
-        comp_dir='chusql-cli'; front_name='csql'
-    fi
-    step "Building the Haskell binaries (stack build --fast in $comp_dir)"
-    note 'the first build downloads the Hackage index (about 139 MB)'
-    ( cd "$src/$comp_dir" && stack build --fast ) || fail "stack build failed in $comp_dir"
-    stack_root=$( cd "$src/$comp_dir" && stack path --local-install-root 2>/dev/null | tr -d '\r' )
-    [ -n "$stack_root" ] || fail 'cannot ask stack for --local-install-root'
-    front_bin="$stack_root/bin/$front_name"
-    [ -f "$front_bin" ] || fail "front end binary not found after the build: $front_bin"
+    ( cd "$src/chusql-core/storage" && cargo build --release ) || fail 'cargo build --release failed'
+    storage_lib="$src/chusql-core/storage/target/release/libchusql_core_storage.so"
+    [ -f "$storage_lib" ] || fail "storage library not found after the build: $storage_lib"
 
     step 'Staging the package'
     pack="$tmp/stage"
     mkdir -p "$pack/bin" "$pack/scripts"
-    cp "$storage_bin" "$pack/bin/"
-    cp "$front_bin" "$pack/bin/"
-    for extra in "$stack_root/bin/"*.so "$stack_root/bin/"*.dll; do
-        if [ -f "$extra" ]; then cp "$extra" "$pack/bin/"; fi
-    done
+    cp "$storage_lib" "$pack/bin/"
     cp "$src/scripts/chusql.toml" "$src/scripts/init.sql" "$pack/scripts/"
     cp "$src/scripts/install.sh" "$pack/"
-    if [ "$component" = 'web' ]; then
-        [ -d "$src/chusql-web/static" ] || fail "static assets not found: $src/chusql-web/static"
-        mkdir -p "$pack/static"
-        cp -R "$src/chusql-web/static/." "$pack/static/"
-        cp "$src/scripts/csql-web.sh" "$pack/"
-    fi
+    for comp in $wanted; do
+        if [ "$comp" = 'web' ]; then
+            comp_dir='chusql-web'; front_name='chusql-web'
+        else
+            comp_dir='chusql-cli'; front_name='csql'
+        fi
+        step "Building the Haskell binaries (stack build --fast in $comp_dir)"
+        note 'the first build downloads the Hackage index (about 139 MB)'
+        ( cd "$src/$comp_dir" && stack build --fast ) || fail "stack build failed in $comp_dir"
+        stack_root=$( cd "$src/$comp_dir" && stack path --local-install-root 2>/dev/null | tr -d '\r' )
+        [ -n "$stack_root" ] || fail 'cannot ask stack for --local-install-root'
+        front_bin="$stack_root/bin/$front_name"
+        [ -f "$front_bin" ] || fail "front end binary not found after the build: $front_bin"
+        cp "$front_bin" "$pack/bin/"
+        for extra in "$stack_root/bin/"*.so "$stack_root/bin/"*.dll; do
+            if [ -f "$extra" ]; then cp "$extra" "$pack/bin/"; fi
+        done
+        if [ "$comp" = 'web' ]; then
+            [ -d "$src/chusql-web/static" ] || fail "static assets not found: $src/chusql-web/static"
+            mkdir -p "$pack/static"
+            cp -R "$src/chusql-web/static/." "$pack/static/"
+            cp "$src/scripts/csql-web.sh" "$pack/"
+        fi
+    done
+
+    # TCP 数据库服务必装，跟组件选择无关：它住在 chusql-server 这个 stack 工程里
+    step 'Building the TCP database server (stack build --fast chusql-server:exe:chusql-server)'
+    ( cd "$src/chusql-server" && stack build --fast chusql-server:exe:chusql-server ) || fail 'stack build failed in chusql-server'
+    server_root=$( cd "$src/chusql-server" && stack path --local-install-root 2>/dev/null | tr -d '\r' )
+    [ -n "$server_root" ] || fail 'cannot ask stack for --local-install-root'
+    [ -f "$server_root/bin/chusql-server" ] || fail "chusql-server not found after the build: $server_root/bin/chusql-server"
+    cp "$server_root/bin/chusql-server" "$pack/bin/"
 elif [ -n "$url_arg" ]; then
     # ---------- 指定 URL / 本地归档 ----------
     new_tmp
@@ -278,43 +537,48 @@ elif [ -n "$url_arg" ]; then
     step 'Unpacking'
     unpack "$archive" "$tmp/pkg"
     pack="$tmp/pkg"
-elif [ -n "$script_dir" ] && [ -f "$script_dir/bin/chusql-storage" ]; then
+elif [ -n "$script_dir" ] && ls "$script_dir/bin/"libchusql_core_storage.* >/dev/null 2>&1; then
     # ---------- 包内安装 ----------
     pack="$script_dir"
 else
     # ---------- 从 GitHub 发行版下载 ----------
     new_tmp
     detect_platform
-    step "Looking for a ChuSQL package for $os-$arch (component $component) in $repo"
+    resolve_version
+    mkdir -p "$tmp/pkg"
+    step "Looking for a ChuSQL package for $os-$arch in $repo"
     found=''
     for label in $labels; do
-        if fetch_asset "chusql-$component-$label.$ext"; then
+        if fetch_asset "chusql-$label.$ext"; then
             found="$asset"
             break
         fi
     done
     if [ -z "$found" ]; then
-        if fetch_asset "chusql-$component.$ext"; then found="$asset"; fi
+        if fetch_asset "chusql.$ext"; then found="$asset"; fi
     fi
-    [ -n "$found" ] || fail "no package for $os-$arch in $repo ($version); try --url or --from-source"
+    [ -n "$found" ] || fail "no package for $os-$arch in $repo ($version); try --list-versions, --url or --from-source"
     verify_checksum "$url" "$archive"
-    step 'Unpacking'
+    step "Unpacking $found"
     unpack "$archive" "$tmp/pkg"
     pack="$tmp/pkg"
 fi
 
 # ---- 校验包内容 ----
-[ -f "$pack/bin/chusql-storage" ] || fail "package is incomplete: bin/chusql-storage not found in $pack"
-if [ "$component" = 'web' ]; then
+ls "$pack/bin/"libchusql_core_storage.* >/dev/null 2>&1 || fail "package is incomplete: bin/libchusql_core_storage.* not found in $pack"
+[ -f "$pack/bin/chusql-server" ] || fail "package is incomplete: bin/chusql-server not found in $pack"
+if [ "$want_web" = 'yes' ]; then
     [ -f "$pack/bin/chusql-web" ] || fail 'package is incomplete: bin/chusql-web not found'
     [ -d "$pack/static" ] || fail 'package is incomplete: static/ not found'
-else
+fi
+if [ "$want_cli" = 'yes' ]; then
     [ -f "$pack/bin/csql" ] || fail 'package is incomplete: bin/csql not found'
 fi
 [ -f "$pack/scripts/chusql.toml" ] || fail 'package is incomplete: scripts/chusql.toml not found'
 
 echo 'ChuSQL installer'
-echo "  component  $component"
+echo "  version    $version"
+echo "  components $component_label"
 echo "  install to $install_dir"
 echo "  data dir   $data_dir"
 if [ -n "$root_password" ]; then
@@ -324,11 +588,21 @@ else
 fi
 
 # ---- 释放文件 ----
+# 包是合在一起的（web 和 cli 都在），这里按这次的选择逐个释放：没选的组件不落地
 step 'Installing files'
 mkdir -p "$install_dir/bin" "$install_dir/logs" "$data_dir"
-cp -R "$pack/bin/." "$install_dir/bin/"
-chmod +x "$install_dir/bin/"* 2>/dev/null || true
-if [ "$component" = 'web' ]; then
+cp "$pack/bin/chusql-server" "$install_dir/bin/"
+for lib in "$pack/bin/"libchusql_core_storage.*; do
+    if [ -f "$lib" ]; then cp "$lib" "$install_dir/bin/"; fi
+done
+for lib in "$pack/bin/"*.so "$pack/bin/"*.dylib "$pack/bin/"*.dll; do
+    if [ -f "$lib" ]; then cp "$lib" "$install_dir/bin/"; fi
+done
+if [ "$want_cli" = 'yes' ]; then
+    cp "$pack/bin/csql" "$install_dir/bin/"
+fi
+if [ "$want_web" = 'yes' ]; then
+    cp "$pack/bin/chusql-web" "$install_dir/bin/"
     mkdir -p "$install_dir/static"
     cp -R "$pack/static/." "$install_dir/static/"
     if [ -f "$pack/csql-web.sh" ]; then
@@ -336,6 +610,7 @@ if [ "$component" = 'web' ]; then
         chmod +x "$install_dir/csql-web.sh"
     fi
 fi
+chmod +x "$install_dir/bin/"* 2>/dev/null || true
 
 # ---- 写全局配置 ----
 step 'Writing chusql.toml'
@@ -351,13 +626,14 @@ if [ -f "$pack/scripts/init.sql" ]; then cp "$pack/scripts/init.sql" "$install_d
 
 # ---- 命令入口 ----
 step 'Creating commands'
-if [ "$component" = 'web' ]; then
+if [ "$want_web" = 'yes' ]; then
     cat > "$install_dir/csql-web" <<'EOF'
 #!/bin/sh
 exec "$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)/csql-web.sh" "$@"
 EOF
     chmod +x "$install_dir/csql-web"
-else
+fi
+if [ "$want_cli" = 'yes' ]; then
     cat > "$install_dir/csql" <<'EOF'
 #!/bin/sh
 exec "$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)/bin/csql" "$@"
@@ -387,7 +663,7 @@ if [ "$keep_package" = 'no' ]; then
     case "$install_dir" in
         "$pack"*|"$pack") echo "kept the package (install dir is inside it): $pack" ;;
         *)
-            if [ -f "$pack/bin/chusql-storage" ]; then
+            if ls "$pack/bin/"libchusql_core_storage.* >/dev/null 2>&1; then
                 ( cd / && rm -rf "$pack" )
                 echo 'package removed'
             else
@@ -403,4 +679,10 @@ fi
 step 'Done'
 echo "  chusql.toml  $config_file"
 echo "  data         $data_dir"
-if [ "$component" = 'web' ]; then echo '  start with   csql-web'; else echo '  start with   csql'; fi
+start_with=''
+if [ "$want_web" = 'yes' ]; then start_with='csql-web'; fi
+if [ "$want_cli" = 'yes' ]; then
+    if [ -n "$start_with" ]; then start_with="$start_with, csql"; else start_with='csql'; fi
+fi
+echo "  start with   $start_with"
+echo "  tcp server   $install_dir/bin/chusql-server (listens on [server] host/port, defaults 127.0.0.1:7777)"
diff --git a/scripts/package.ps1 b/scripts/package.ps1
new file mode 100644
index 0000000..09871fd
--- /dev/null
+++ b/scripts/package.ps1
@@ -0,0 +1,241 @@
+[CmdletBinding()]
+param(
+    [string]$OutDir = '',
+    [string]$Platform = '',
+    [string]$Version = '',
+    [switch]$NoBuild,
+    [switch]$NoVerify
+)
+
+$ErrorActionPreference = 'Stop'
+
+# Windows 打包脚本：构建、装配、打 zip、出 sha256，产物落 releases\，命名与 CI 一致。
+
+$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+if (-not $OutDir) { $OutDir = Join-Path $repoRoot 'releases' }
+$OutDir = [System.IO.Path]::GetFullPath($OutDir)
+
+# 打印错误并退出 1。
+function Fail([string]$msg) {
+    Write-Host "!! $msg" -ForegroundColor Red
+    exit 1
+}
+# 打印步骤标题。
+function Step([string]$msg) { Write-Host ''; Write-Host "==> $msg" -ForegroundColor Cyan }
+# 打印一行输出。
+function Say([string]$msg) { Write-Host $msg }
+
+if (-not $Platform) {
+    $arch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'arm64' } else { 'x86_64' }
+    $Platform = "windows-$arch"
+}
+if ($Platform -notlike 'windows-*') {
+    Fail 'the Linux / macOS package is scripts/package.sh; this script only makes windows-* zips'
+}
+if (-not $Version) {
+    $Version = ''
+}
+
+# 算文件的 sha256（小写）。
+function Get-Sha256([string]$path) {
+    (Get-FileHash -Path $path -Algorithm SHA256).Hash.ToLower()
+}
+
+# 归档里该有什么，这里先对一遍：两部分都得在，装配漏了东西别等发布出去才发现
+# 核对归档里必需的文件都在。
+function Assert-Stage([string]$stage) {
+    $must = @(
+        'bin\chusql_core_storage.dll',
+        'bin\csql.exe',
+        'bin\chusql-web.exe',
+        'bin\chusql-server.exe',
+        'static\index.html',
+        'csql-web.ps1',
+        'scripts\chusql.toml',
+        'install.ps1',
+        'install.sh'
+    )
+    foreach ($rel in $must) {
+        if (-not (Test-Path (Join-Path $stage $rel))) {
+            Fail "$rel is missing from the package"
+        }
+    }
+    # bin 里带 chusql 名字的文件只能是已知产物；改名前的残留或别的垃圾都算装配错误
+    $known = @('chusql_core_storage.dll', 'chusql-server.exe', 'chusql-web.exe')
+    $unknown = @(Get-ChildItem (Join-Path $stage 'bin') -Filter 'chusql*' -File -ErrorAction SilentlyContinue |
+        Where-Object { $known -notcontains $_.Name })
+    if ($unknown.Count -gt 0) {
+        $names = ($unknown | ForEach-Object Name) -join ', '
+        Fail "unexpected artifacts in bin/: $names"
+    }
+}
+
+# 真装一遍，核对落地与未选组件。
+function Test-Installed([string]$name, [string]$comp) {
+    $archive = Join-Path $OutDir "$name.zip"
+    $vtmp = Join-Path ([System.IO.Path]::GetTempPath()) ("chusql-packcheck-" + [Guid]::NewGuid().ToString('N'))
+    $pkg = Join-Path $vtmp 'pkg'
+    $opt = Join-Path $vtmp 'opt'
+    $data = Join-Path $vtmp 'data'
+    $appdata = Join-Path $vtmp 'appdata'
+    New-Item -ItemType Directory -Force -Path $pkg, $opt, $appdata | Out-Null
+
+    $oldAppData = $env:APPDATA
+    $oldLocalAppData = $env:LOCALAPPDATA
+    $oldUserPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+    $log = Join-Path $vtmp 'install.log'
+    try {
+        Expand-Archive -Path $archive -DestinationPath $pkg -Force
+        $env:APPDATA = $appdata
+        $env:LOCALAPPDATA = $vtmp
+        $pwsh = Join-Path $PSHOME 'pwsh.exe'
+        if (-not (Test-Path $pwsh)) { $pwsh = 'powershell' }
+        & $pwsh -NoProfile -File (Join-Path $pkg 'install.ps1') -Component $comp -InstallDir $opt `
+            -DataDir $data -RootUser root -RootPassword package-check *>&1 | Out-File -FilePath $log -Encoding UTF8
+        if ($LASTEXITCODE -ne 0) {
+            Get-Content $log | Select-Object -First 120 | Write-Host
+            Fail "$name`: installing the $comp part from the package failed (log above)"
+        }
+        $ok = $true
+        $checks = @(
+            (Join-Path $opt 'bin\chusql_core_storage.dll'),
+            (Join-Path $opt 'bin\chusql-server.exe'),
+            (Join-Path $opt 'init.sql'),
+            (Join-Path $appdata 'ChuSQL\chusql.toml')
+        )
+        $forbidden = @()
+        if ($comp -eq 'web') {
+            $checks += @(
+                (Join-Path $opt 'bin\chusql-web.exe'),
+                (Join-Path $opt 'static\index.html'),
+                (Join-Path $opt 'csql-web.ps1'),
+                (Join-Path $opt 'csql-web.cmd')
+            )
+            $forbidden = @((Join-Path $opt 'bin\csql.exe'), (Join-Path $opt 'csql.cmd'))
+        } else {
+            $checks += @(
+                (Join-Path $opt 'bin\csql.exe'),
+                (Join-Path $opt 'csql.cmd')
+            )
+            $forbidden = @((Join-Path $opt 'bin\chusql-web.exe'), (Join-Path $opt 'static'), (Join-Path $opt 'csql-web.cmd'))
+        }
+        foreach ($f in $checks) { if (-not (Test-Path $f)) { $ok = $false; Write-Host "  missing: $f" } }
+        foreach ($f in $forbidden) { if (Test-Path $f) { $ok = $false; Write-Host "  should not be there: $f" } }
+        $config = Join-Path $appdata 'ChuSQL\chusql.toml'
+        $expectDataDir = $data -replace '\\', '/'
+        if (-not (Test-Path $config) -or -not (Select-String -Path $config -SimpleMatch "data_dir = ""$expectDataDir""" -Quiet)) {
+            $ok = $false
+            Write-Host "  config does not point at $expectDataDir"
+        }
+        if (-not $ok) {
+            Get-Content $log | Select-Object -First 120 | Write-Host
+            Fail "$name`: the $comp part is not what the installer promises (log above)"
+        }
+        # 装的时候往用户 PATH 里写过一行，收尾要原样写回
+        $nowUserPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+        if ($nowUserPath -ne $oldUserPath) {
+            [Environment]::SetEnvironmentVariable('Path', $oldUserPath, 'User')
+            Write-Host "  note: the installer touched the user PATH; restored it"
+        }
+    } finally {
+        $env:APPDATA = $oldAppData
+        $env:LOCALAPPDATA = $oldLocalAppData
+        Remove-Item -Recurse -Force $vtmp -ErrorAction SilentlyContinue
+    }
+    Say "  ok         $name installs the $comp part, and only the $comp part"
+}
+
+# ---------- 构建 ----------
+if (-not $NoBuild) {
+    Step 'Building storage (Rust)'
+    Push-Location (Join-Path $repoRoot 'chusql-core\storage')
+    try {
+        & cargo build --release
+        if ($LASTEXITCODE -ne 0) { Fail 'cargo build --release failed' }
+    } finally { Pop-Location }
+
+    foreach ($target in @('chusql-web:exe:chusql-web', 'chusql-cli:exe:csql', 'chusql-server:exe:chusql-server')) {
+        Step "Building $target (Haskell)"
+        Push-Location (Join-Path $repoRoot 'chusql-cli')
+        try {
+            & stack build --fast $target
+            if ($LASTEXITCODE -ne 0) { Fail "stack build --fast $target failed" }
+        } finally { Pop-Location }
+    }
+}
+
+# ---------- 装配 + 打归档 ----------
+$name = "chusql-$Platform"
+$stageRoot = Join-Path $OutDir '.stage'
+$stage = Join-Path $stageRoot $name
+$zip = Join-Path $OutDir "$name.zip"
+New-Item -ItemType Directory -Force -Path $OutDir | Out-Null
+
+try {
+    Step "Packing $name"
+    if (Test-Path $stageRoot) { Remove-Item -Recurse -Force $stageRoot }
+    New-Item -ItemType Directory -Force -Path (Join-Path $stage 'bin'), (Join-Path $stage 'scripts') | Out-Null
+
+    $storage = Join-Path $repoRoot 'chusql-core\storage\target\release\chusql_core_storage.dll'
+    if (-not (Test-Path $storage)) { Fail 'chusql-core\storage\target\release\chusql_core_storage.dll is not built (run without -NoBuild)' }
+    Copy-Item $storage (Join-Path $stage 'bin')
+
+    # 从真正用于构建的工程目录取安装根（package.sh 同样锚在 chusql-cli），别靠调用者的当前目录
+    Push-Location (Join-Path $repoRoot 'chusql-cli')
+    try { $stackRoot = (& stack path --local-install-root | Select-Object -Last 1).Trim() } finally { Pop-Location }
+    foreach ($frontName in @('chusql-web.exe', 'chusql-server.exe', 'csql.exe')) {
+        $front = Join-Path $stackRoot "bin/$frontName"
+        if (-not (Test-Path $front)) {
+            $front = Get-ChildItem -Path (Join-Path $repoRoot 'chusql-web\.stack-work'), (Join-Path $repoRoot 'chusql-cli\.stack-work'), (Join-Path $repoRoot 'chusql-server\.stack-work') `
+                -Recurse -Filter $frontName -File -ErrorAction SilentlyContinue |
+                Sort-Object LastWriteTime -Descending | Select-Object -First 1 -ExpandProperty FullName
+        }
+        if (-not $front -or -not (Test-Path $front)) { Fail "$frontName is not built (run without -NoBuild)" }
+        Copy-Item $front (Join-Path $stage 'bin')
+    }
+
+    # 第三方 dll 才要连带上：名字带 chusql 的是本 crate 产物或改名前的残留，上面已按名拷过
+    Get-ChildItem (Join-Path $repoRoot 'chusql-core\storage\target\release') -Filter '*.dll' -File -ErrorAction SilentlyContinue |
+        Where-Object { $_.Name -notlike 'chusql*' } |
+        ForEach-Object { Copy-Item $_.FullName (Join-Path $stage 'bin') }
+
+    Copy-Item (Join-Path $repoRoot 'scripts\chusql.toml'), (Join-Path $repoRoot 'scripts\init.sql') (Join-Path $stage 'scripts')
+    Copy-Item (Join-Path $repoRoot 'scripts\install.ps1'), (Join-Path $repoRoot 'scripts\install.sh') $stage
+    New-Item -ItemType Directory -Force -Path (Join-Path $stage 'static') | Out-Null
+    Copy-Item (Join-Path $repoRoot 'chusql-web\static\*') (Join-Path $stage 'static') -Recurse
+    Copy-Item (Join-Path $repoRoot 'scripts\csql-web.sh') $stage
+    $webPs1 = Join-Path $repoRoot 'scripts\csql-web.ps1'
+    if (Test-Path $webPs1) { Copy-Item $webPs1 $stage }
+
+    Assert-Stage $stage
+
+    if (Test-Path $zip) { Remove-Item -Force $zip }
+    if (Test-Path "$zip.sha256") { Remove-Item -Force "$zip.sha256" }
+    Compress-Archive -Path (Join-Path $stage '*') -DestinationPath $zip -Force
+    Remove-Item -Recurse -Force $stageRoot
+
+    $hash = Get-Sha256 $zip
+    Set-Content -Path "$zip.sha256" -Value ("{0}  {1}" -f $hash, "$name.zip") -NoNewline -Encoding ASCII
+    Say "  wrote      $zip"
+    Say "  checksum   $hash"
+
+    if (-not $NoVerify) {
+        Test-Installed $name 'cli'
+        Test-Installed $name 'web'
+    }
+} finally {
+    if (Test-Path $stageRoot) { Remove-Item -Recurse -Force $stageRoot }
+}
+
+# ---------- 收尾 ----------
+Step 'Done'
+Get-ChildItem (Join-Path $OutDir "$name.zip*") | Select-Object Name, Length | Format-Table
+if ($Version) {
+    Say ''
+    Say "release $Version with (tag 必须是真实存在的 git tag):"
+    Say "  gh release create $Version `"$OutDir\*`" --generate-notes"
+} else {
+    Say ''
+    Say 'publish with (先用 -Version 指定 tag):'
+    Say "  gh release create <tag> `"$OutDir\*`" --generate-notes"
+}
diff --git a/scripts/package.sh b/scripts/package.sh
new file mode 100644
index 0000000..9b4f1a2
--- /dev/null
+++ b/scripts/package.sh
@@ -0,0 +1,236 @@
+#!/bin/sh
+#   sh scripts/package.sh                          # 本机平台，web + cli 合成一个包
+#   sh scripts/package.sh --no-build               # 用已有编译产物（快）
+#   sh scripts/package.sh --no-verify              # 跳过「装一遍试试」
+#   sh scripts/package.sh --out-dir /tmp/rel       # 换输出目录
+#   sh scripts/package.sh --platform linux-x86_64  # 覆盖平台标签（默认按 uname 猜）
+#   sh scripts/package.sh --version v0.1.0         # 只用于发布提示，不写进文件名
+#
+# 打完发出去（资源名必须跟这里一致，install.sh 才认得）：
+#   gh release create v0.1.0 releases/* --generate-notes
+#
+# 收尾会按「只要 cli」「只要 web」各装一遍：核对落盘文件，也核对没选的组件没被释放。
+# Windows 包用 scripts/package.ps1 打（这个脚本只出 tar.gz）。
+set -eu
+
+# 本机打发行包：构建、装配、打 tar.gz、出 sha256，产物落 releases/，命名与 CI 一致。
+repo_root=$(cd "$(dirname "$0")/.." && pwd)
+out_dir=$repo_root/releases
+platform=''
+version=''
+build=yes
+verify=yes
+
+# 打印一行输出。
+Say() { printf '%s\n' "$*"; }
+# 打印步骤标题。
+Step() { printf '\n== %s\n' "$*"; }
+# 报错到 stderr 并退出 1。
+Fail() {
+    printf 'error: %s\n' "$*" >&2
+    exit 1
+}
+
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --platform)
+            shift; [ "$#" -gt 0 ] || Fail '--platform needs a label like linux-x86_64'
+            platform=$1; shift ;;
+        --version)
+            shift; [ "$#" -gt 0 ] || Fail '--version needs a tag like v0.1.0'
+            version=$1; shift ;;
+        --out-dir)
+            shift; [ "$#" -gt 0 ] || Fail '--out-dir needs a path'
+            out_dir=$1; shift ;;
+        --no-build) build=no; shift ;;
+        --no-verify) verify=no; shift ;;
+        -h|--help) usage=yes; shift ;;
+        *) Fail "unknown option: $1 (try --no-build, --out-dir DIR, --platform LABEL)" ;;
+    esac
+done
+
+if [ "${usage:-no}" = 'yes' ]; then
+    sed -n '2,/^set -eu$/p' "$0" | sed -e 's/^# \{0,1\}//' -e '$d'
+    exit 0
+fi
+
+if [ -z "$platform" ]; then
+    case "$(uname -s)" in
+        Linux) os=linux ;;
+        Darwin) os=macos ;;
+        *) Fail "cannot tell the platform from $(uname -s); pass --platform linux-x86_64" ;;
+    esac
+    case "$(uname -m)" in
+        x86_64|amd64) arch=x86_64 ;;
+        arm64|aarch64) arch=arm64 ;;
+        *) Fail "cannot tell the architecture from $(uname -m); pass --platform $os-x86_64" ;;
+    esac
+    platform=$os-$arch
+fi
+
+case "$platform" in
+    windows-*) Fail 'the Windows package is scripts/package.ps1; this script only makes tar.gz archives' ;;
+esac
+
+# 用可用的工具算文件 sha256。
+sha256_of() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "$1" | awk '{print $1}'
+    elif command -v shasum >/dev/null 2>&1; then
+        shasum -a 256 "$1" | awk '{print $1}'
+    else
+        openssl dgst -sha256 "$1" | awk '{print $NF}'
+    fi
+}
+
+# 核对归档里必需的文件都在。
+check_stage() {
+    stage=$1
+    ls "$stage/bin/"libchusql_core_storage.* >/dev/null 2>&1 || Fail 'bin/libchusql_core_storage.* is missing from the package'
+    [ -f "$stage/bin/csql" ] || Fail 'bin/csql is missing from the package'
+    [ -f "$stage/bin/chusql-web" ] || Fail 'bin/chusql-web is missing from the package'
+    [ -f "$stage/bin/chusql-server" ] || Fail 'bin/chusql-server is missing from the package'
+    [ -f "$stage/static/index.html" ] || Fail 'static/index.html is missing from the package'
+    [ -f "$stage/csql-web.sh" ] || Fail 'csql-web.sh is missing from the package'
+    [ -f "$stage/scripts/chusql.toml" ] || Fail 'scripts/chusql.toml is missing from the package'
+    [ -f "$stage/install.sh" ] || Fail 'install.sh is missing from the package'
+    [ -f "$stage/install.ps1" ] || Fail 'install.ps1 is missing from the package'
+    # bin 里带 chusql 名字的文件只能是已知产物；改名前的残留或别的垃圾都算装配错误
+    for f in "$stage"/bin/chusql* "$stage"/bin/libchusql*; do
+        [ -e "$f" ] || continue
+        case "$(basename "$f")" in
+            libchusql_core_storage.so|libchusql_core_storage.dylib|libchusql_core_storage.dll|chusql-server|chusql-web) ;;
+            *) Fail "unexpected artifact in bin/: $(basename "$f")" ;;
+        esac
+    done
+}
+
+# 按 cli / web 各装一遍，核对落地文件。
+verify_package() {
+    name=$1
+    archive="$out_dir/$name.tar.gz"
+    for comp in cli web; do
+        vtmp=$(mktemp -d)
+        mkdir -p "$vtmp/pkg" "$vtmp/home" "$vtmp/opt"
+        if ! tar -xzf "$archive" -C "$vtmp/pkg"; then
+            rm -rf "$vtmp"
+            Fail "$name: the archive does not unpack"
+        fi
+        if ! ( cd "$vtmp/pkg" && HOME="$vtmp/home" sh install.sh --component "$comp" \
+                --install-dir "$vtmp/opt" --data-dir "$vtmp/data" --user root --password package-check ) \
+                >"$vtmp/log" 2>&1; then
+            sed -n '1,120p' "$vtmp/log" >&2
+            rm -rf "$vtmp"
+            Fail "$name: installing the $comp part from the package failed (log above)"
+        fi
+        ok=yes
+        ls "$vtmp/opt/bin/"libchusql_core_storage.* >/dev/null 2>&1 || ok=no
+        [ -f "$vtmp/opt/bin/chusql-server" ] || ok=no
+        [ -f "$vtmp/opt/init.sql" ] || ok=no
+        [ -f "$vtmp/home/.config/ChuSQL/chusql.toml" ] || ok=no
+        grep -q "data_dir = \"$vtmp/data\"" "$vtmp/home/.config/ChuSQL/chusql.toml" || ok=no
+        if [ "$comp" = web ]; then
+            [ -f "$vtmp/opt/bin/chusql-web" ] || ok=no
+            [ -f "$vtmp/opt/static/index.html" ] || ok=no
+            [ -f "$vtmp/opt/csql-web.sh" ] || ok=no
+            [ -f "$vtmp/opt/csql-web" ] || ok=no
+            # 没要 cli，就不许把 csql 释放出去
+            if [ -f "$vtmp/opt/bin/csql" ] || [ -f "$vtmp/opt/csql" ]; then ok=no; fi
+        else
+            [ -f "$vtmp/opt/bin/csql" ] || ok=no
+            [ -f "$vtmp/opt/csql" ] || ok=no
+            # 没要 web，就不许把 chusql-web / static / 启动器释放出去
+            if [ -f "$vtmp/opt/bin/chusql-web" ] || [ -e "$vtmp/opt/static" ] || [ -f "$vtmp/opt/csql-web" ]; then
+                ok=no
+            fi
+        fi
+        if [ "$ok" != yes ]; then
+            sed -n '1,120p' "$vtmp/log" >&2
+            rm -rf "$vtmp"
+            Fail "$name: the $comp part is not what the installer promises (log above)"
+        fi
+        rm -rf "$vtmp"
+        Say "  ok         $name installs the $comp part, and only the $comp part"
+    done
+}
+
+# ---------- 构建 ----------
+if [ "$build" = yes ]; then
+    Step 'Building storage (Rust)'
+    ( cd "$repo_root/chusql-core/storage" && cargo build --release )
+    Step 'Building the web front end (Haskell)'
+    ( cd "$repo_root/chusql-cli" && stack build --fast chusql-web:exe:chusql-web )
+    Step 'Building the command line client (Haskell)'
+    ( cd "$repo_root/chusql-cli" && stack build --fast chusql-cli:exe:csql )
+    Step 'Building the TCP database server (Haskell)'
+    ( cd "$repo_root/chusql-cli" && stack build --fast chusql-server:exe:chusql-server )
+fi
+
+# ---------- 装配 + 打归档 ----------
+name="chusql-$platform"
+stage="$out_dir/.stage/$name"
+archive="$out_dir/$name.tar.gz"
+mkdir -p "$out_dir"
+trap 'rm -rf "$out_dir/.stage"' EXIT INT TERM
+
+Step "Packing $name"
+rm -rf "$out_dir/.stage"
+mkdir -p "$stage/bin" "$stage/scripts"
+
+cp "$repo_root/chusql-core/storage/target/release/"libchusql_core_storage.* "$stage/bin/" \
+    || Fail "chusql-core/storage/target/release/libchusql_core_storage.* is not built (run without --no-build)"
+
+stack_root=$(cd "$repo_root/chusql-cli" && stack path --local-install-root | tail -n 1 | tr -d '\r')
+for front_name in chusql-web chusql-server csql; do
+    front="$stack_root/bin/$front_name"
+    if [ ! -f "$front" ]; then
+        front=$(find "$repo_root/chusql-web/.stack-work" "$repo_root/chusql-cli/.stack-work" "$repo_root/chusql-server/.stack-work" \
+            -name "$front_name" -type f 2>/dev/null | head -n 1 || true)
+    fi
+    [ -n "$front" ] && [ -f "$front" ] || Fail "$front_name is not built (run without --no-build)"
+    cp "$front" "$stage/bin/"
+done
+
+# Haskell 一般静态链接，靶目录里真有共享库就一起带上；改名前的旧库（libchusql_storage.*）不能进包
+for lib in "$repo_root"/chusql-core/storage/target/release/*.so "$repo_root"/chusql-core/storage/target/release/*.dylib; do
+    [ -f "$lib" ] || continue
+    case "$(basename "$lib")" in
+        libchusql_storage.*|libchusql_storage-*) continue ;;
+    esac
+    cp "$lib" "$stage/bin/"
+done
+
+cp "$repo_root/scripts/chusql.toml" "$repo_root/scripts/init.sql" "$stage/scripts/"
+cp "$repo_root/scripts/install.sh" "$repo_root/scripts/install.ps1" "$stage/"
+mkdir -p "$stage/static"
+cp -R "$repo_root"/chusql-web/static/. "$stage/static/"
+cp "$repo_root/scripts/csql-web.sh" "$stage/"
+if [ -f "$repo_root/scripts/csql-web.ps1" ]; then cp "$repo_root/scripts/csql-web.ps1" "$stage/"; fi
+chmod +x "$stage/install.sh" "$stage/csql-web.sh"
+
+check_stage "$stage"
+
+rm -f "$archive" "$archive.sha256"
+( cd "$stage" && tar -czf "$archive" . )
+rm -rf "$out_dir/.stage"
+hash=$(sha256_of "$archive")
+printf '%s  %s\n' "$hash" "$name.tar.gz" > "$archive.sha256"
+Say "  wrote      $archive"
+Say "  checksum   $hash"
+
+if [ "$verify" = yes ]; then
+    verify_package "$name"
+fi
+
+# ---------- 收尾 ----------
+Step 'Done'
+ls -l "$out_dir/$name.tar.gz" "$out_dir/$name.tar.gz.sha256"
+if [ -n "$version" ]; then
+    Say ''
+    Say "release $version with (tag 必须是真实存在的 git tag):"
+    Say "  gh release create $version \"$out_dir\"/* --generate-notes"
+else
+    Say ''
+    Say 'publish with (先用 --version 指定 tag):'
+    Say "  gh release create <tag> \"$out_dir\"/* --generate-notes"
+fi