ROADMAP 历史归档

本文件归档 SonnetDB 早期路线图的详细正文，避免主路线图被已完成实现细节淹没。

当前路线图见 ROADMAP.md。

Milestone 0 — 项目脚手架 ✅

Milestone 1 — 内存与二进制基础设施（Safe-only） ✅

Milestone 2 — 逻辑模型与目录 ✅

Milestone 3 — 写入路径 ✅

磁盘布局（M3 落地）：

<root>/
  catalog.SDBCAT
  wal/active.SDBWAL
  segments/{id:X16}.SDBSEG

Milestone 4 — 查询路径 ✅

注：原计划中的 PR #15（"QueryEngine.QueryRaw"）已合并进 PR #16；新 PR #15 替换为查询所需的多段索引层。

Milestone 5 — 稳定性与性能（写入侧）

磁盘布局（M5 落地后）：

<root>/
  catalog.SDBCAT
  tombstones.tslmanifest
  wal/{startLsn:X16}.SDBWAL             # 多 segment 滚动
  segments/{id:X16}.SDBSEG

Milestone 6 — SQL 前端 + Tag 倒排索引

Milestone 7 — 压缩编码

注：BlockEncoding 字段 PR #6 已预留；本 Milestone 真正启用 Delta / Gorilla。

Milestone 8 — 服务器模式

进入条件：PR #21（Retention TTL）与 PR #35（嵌入式模式 BenchmarkDotNet 基准）必须先完成，建立性能基线后再服务化，避免后续无法归因 HTTP / 序列化 / 引擎本身的性能差异。

设计要点（PR #32）

• 运行时形态：AOT-friendly Minimal API（net10.0 + PublishAot=true），单进程；项目位于 src/SonnetDB/，引用 SonnetDB。
• 多租户隔离：进程内 ConcurrentDictionary<string, Tsdb> 注册表，一个数据库 = 一个子目录 + 一个 Tsdb 实例，复用现有 BackgroundFlushWorker / CompactionWorker。CREATE DATABASE <name> 创建子目录并注册；DROP DATABASE 通过引用计数 + Dispose 回收。不采用子进程隔离（与 AOT min api 风格冲突且开销过大）。
• 协议（仅 HTTP，先不做 WebSocket）：
  • POST /v1/db/{db}/sql 提交单条 SQL；请求体 application/json，包含 sql 与可选 parameters。
  • POST /v1/db/{db}/sql/batch 批量 INSERT（直接走 ADO.NET 的 batch 接口，零额外解析）。
  • 结果集采用 application/x-ndjson 流式输出，配合 System.Text.Json AOT source generator，避免 JIT 反射 + 全量缓冲；这是 AOT + 大结果集场景下吞吐最佳的组合。
  • WebSocket 推后评估：仅当出现真实的"订阅 / 长查询流"需求再加（订阅语义本身需要引擎层支持，目前不具备）。
• 认证（极简）：单层 Authorization: Bearer <token> + 配置文件里的静态 token 列表（角色仅 admin / readwrite / readonly）。不实现 SQL 级 CREATE USER / GRANT，避免引入控制面元数据。等到真有多用户场景再升级。
• 可观测性：/healthz、/metrics（Prometheus 文本格式，最少包含 per-db 写入速率、Flush/Compaction 次数、活跃 segment 数）。

PR 列表

Milestone 9 — 性能与发布

| PR | 主题 | 状态 | |----|------|------| | #35 | BenchmarkDotNet：写入 / 查询 / 聚合 / Compaction 基准，编写评测 InfluxDB TDengine SQLite SonnetDB SonnetDB 等五个时序数据库的各项指标对比， 并连同机器性能都写在readme.md 里面。 | ✅| | #36 | SonnetDB Docker 性能测试：补齐 src/SonnetDB/Dockerfile、基准用 docker-compose 环境、ServerBenchmark（写入 / 查询 / 聚合）与 README 中的服务端性能基线。 | ✅ | | #37a | 文档完善（已落地部分）：重写 README.md / README.en.md，补齐 docs/getting-started.md / docs/data-model.md / docs/sql-reference.md / docs/file-format.md 及发布文档，使用 JekyllNet 构建内置 /help 帮助站点，核对路线图与当前代码/功能，清理过时说明。 | ✅ | | #37b | 文档发布：将 JekyllNet 文档站点接入 GitHub Pages 自动构建与发布流水线，支持从同一套 docs/ 源码同时产出服务端 /help 站点与 Pages 静态站点，避免文档仅内置在 SonnetDB 镜像中。 | ✅ | | #38 | 发布 NuGet 包 SonnetDB 0.1.0 + .github/workflows/publish.yml，打包生成一套包含 SonnetDB、SonnetDB.Data、SonnetDB.Cli 的 SDK Bundle，并附带使用说明；发布 Windows 和 Linux 版本；再打包 SonnetDB 完整 Bundle，包含前端、SonnetDB.Cli、SonnetDB.Data 等，能够一键启动；同时生成 Windows msi 与 Linux deb / rpm 安装包。 | ✅ | | #39 | Docker 服务端模式镜像自动发布：新增 GitHub Actions 工作流，自动构建并推送 SonnetDB 镜像到 iotsharp/sonnetdb 与 ghcr.io/<owner>/sonnetdb，补齐标签策略、运行说明与 Secrets 要求。 | ✅ |

Milestone 10 — 批量入库快路径（原扩展和第三方占位已拆分）

Milestone 11 — 写入快路径（PR #45 瓶颈收收尾）

背景：PR #45 实测发现 100k 点下嵌入式 LP/JSON/Bulk 三路与 SQL VALUES baseline 吞吐几乎打平（~170–200ms），内存仅节省 25～42%； 服务端 /sql/batch 1M 点 ~21s vs 嵌入式 0.62s，差 33.8×。调用链详细剖析定位出三个主要瓶颈：

1. Tsdb.WriteMany(IEnumerable<Point>) 是假批量，逐点 lock + 逐字段 WAL record；
2. 服务端 LP/Bulk payload Encoding.UTF8.GetString + JsonPointsReader.ToArray() 二次拷贝；
3. 端点默认 flush=true 同步落盘占用 RTT。

目标：嵌入式 100k 点 ≤ 80ms（1M 点 ≤ 300ms），服务端 LP/Bulk 达到 ≥ 700k pts/s。

• ✅ README 「写入：100 万点」表新增 PR #47 服务端 LP/JSON/Bulk 三行（1.10–1.20 s / 34–71 MB / ~1.77–1.93× vs 嵌入式）；
• ✅ README 「嵌入式 vs SonnetDB」同机对比表拆分为 SQL Batch + LP/JSON/Bulk 四行；
• ✅ README 「批量入库快路径」补充 PR #48 ?flush= 三档位表（None / Async / Sync 语义与适用场景）；
• ✅ 新增 InsertBenchmark.TDengine_InsertSchemaless_1M + TDengineRestClient.WriteLineProtocolAsync(db, lp, precision)，走 TDengine InfluxDB-compat POST /influxdb/v1/write?precision=ms，按 100k 行/批切片；
• ✅ 全量重跑 24 个基准（i9-13900HX / .NET 10.0.6 / Docker WSL2，~20 分钟）并把真实数字写进 tests/SonnetDB.Benchmarks/README.md：Insert SonnetDB 545 ms / 530 MB、SQLite 811 ms / 465 MB、InfluxDB 5,222 ms / 1,457 MB（9.58×）、TDengine REST 44,137 ms / 156 MB（81×）、TDengine schemaless LP 996 ms / 61 MB（1.83×）〔同库 schemaless 比 REST INSERT 子表路径快 44× / 分配缩到 39%〕；Query SonnetDB 6.71 ms、Aggregate 42.3 ms、Compaction 16.3 ms；
• ✅ 重建 iotsharp/sonnetdb:bench 镜像后首次跑通 ServerInsertBenchmark 全部 4 个路径：SQL Batch 19.80 s / 655 MB、LP 1.293 s / 52 MB、JSON 1.352 s / 71 MB、Bulk 1.120 s / 34 MB——PR #47 三端点稳定进入「秒级 1M 点 + ≤ 80 MB 分配」区间，比 SQL Batch 快 15–7×、分配缩到 5–11%，比嵌入式仅多 ~2.0–2.5×额外开销。 | ✅ |

推进顺序：PR #46 ✅ → PR #47 ✅ → PR #48 ✅ → PR #49 ✅。Milestone 11 「写入快路径」专题完整收尾：嵌入式写入达到 ~1.83 M pts/s（545 ms / 1M 点）；服务端三端点 LP/JSON/Bulk 全部重跑通过后仍保持 1.12–1.35 s / 34–71 MB，远超 Milestone 11 原定 ≥ 700k pts/s 目标；对外同机粗略对比表明 SonnetDB 写入比 InfluxDB 快 9.6×、比 TDengine REST INSERT 快 81×、比 TDengine schemaless LP 快 1.83×，范围查询比 InfluxDB 快 61×、比 SQLite 快 6.6×。

Milestone 12 — 函数与算子扩展（PID / Forecast / UDF）

背景：当前 Aggregator 是 enum（7 个内置聚合）+ AggregateResult 单累加器结构，已经无法承载 stddev / percentile / derivative / PID / forecast 等函数族。本里程碑把"函数"提升为一等公民，引入 FunctionRegistry + IAggregateFunction + WindowOperator + TableValuedFunction 四类扩展点，并以 PID 与 Forecast 作为首批内置示例，建立 SonnetDB 在工业 / IoT / 可观测性场景的差异化能力。

设计原则：

1. 零破坏：现有 7 个聚合迁移到 IAggregateFunction，对外 SQL / ADO.NET / Server 行为不变。
2. 贴合现有架构：复用 AggregateResult.Merge 的 mergeable accumulator 模型，与 MemTable + N 路堆合并 + 跨段聚合天然兼容。
3. AOT 友好：内置函数 sealed class + 静态注册，零反射，与 SonnetDB 的 PublishAot=true 路线兼容。
4. Dogfooding：PID / Forecast 自身使用 UDF 接口实现，验证 API 设计合理性。

Tier 划分

PR 列表

SQL 用法预览

-- Tier 2：扩展聚合
SELECT time_bucket('1m', time) AS minute,
       avg(usage), p95(usage), stddev(usage), spread(usage)
FROM cpu WHERE host = 'server-01' AND time > now() - 1h
GROUP BY minute;

-- Tier 3：速率与平滑
SELECT time, host,
       rate(bytes_in, 1s) AS bps,
       ewma(temperature, 0.2) AS temp_smooth
FROM nic WHERE time > now() - 5m;

-- Tier 4：PID 控制律回写
INSERT INTO actuator (time, device, valve)
SELECT time, device,
       pid_series(temperature, 75.0, 0.6, 0.1, 0.05) AS valve
FROM reactor WHERE time > now() - 1m;

-- Tier 4：预测
SELECT * FROM forecast(
    (SELECT time, value FROM meter WHERE device='m1' AND time > now()-7d),
    horizon => 1440, algo => 'holt_winters', season => 1440);

嵌入式 UDF 注册预览（Tier 5）

using var db = Tsdb.Open(new TsdbOptions { RootDirectory = "./data" });

db.Functions.RegisterScalar("c2f",
    args => FieldValue.Float64(args[0].AsDouble() * 9 / 5 + 32));

db.Functions.RegisterAggregate(new KalmanAggregate()); // 实现 IAggregateFunction

推进顺序：PR #50 → #51 → #52 → #53 → #54 → #55 → #56 → #57。 其中 PR #50 是基础设施重构，必须先合并；PR #54 / #55 / #56 是对外差异化卖点，建议在 Milestone 9（发布）完成后立刻推进。

Milestone 13 — 向量类型与嵌入式向量索引（Copilot 知识库底座）

背景：Milestone 14 的 SonnetDB Copilot（智能体）需要一个"零外部依赖"的向量召回能力。我们已经决定 dogfooding——把向量库做到 SonnetDB 自己里，而不是引入 SQLite/sqlite-vec / Qdrant 等外部组件。这样既能复用 WAL/Segment/Compaction 的存储栈，也能成为 SonnetDB 的对外差异化能力（"时序 + 向量"二合一）。

设计原则：

1. Safe-only 仍生效：首版距离计算保持 unsafe-free；当前以安全的 Span<float> / for 循环实现，后续可在不破坏 Safe-only 的前提下演进到 System.Numerics.Tensors.TensorPrimitives 等 SIMD 加速路径。
2. 零破坏：新增 VECTOR(dim) 字段类型，复用 FieldValue 的 union 结构（新增 Vector 分支），现有 schema / 写入 / 查询路径保持兼容。
3. AOT 友好：内置距离函数 + 索引算子均为 sealed class，不引入反射或动态代码生成。
4. 可演进：第一版用 brute-force 顺扫 + 段内裁剪，足够覆盖 Copilot 知识库（< 50k 切片）；HNSW 留到 PR #61 按需追加。

PR 列表

推进顺序：PR #58 ✅ → #59 ✅ → #60 ✅ → #61 ✅ → #62 ✅。Milestone 13 的向量检索前置已闭环；后续若具备合适的长测 / 外部数据库环境，可继续补 1M 与 sqlite-vec / pgvector 结果，但不再阻塞 Milestone 14。

Milestone 14 — SonnetDB Copilot：MCP 工具 + 知识库 + 智能体

2026-07-14 实现核查勘误：本节最初记录的是设计目标，不能作为当前实现证明。仓库目前使用 Microsoft.Extensions.AI 抽象和自研 CopilotAgent，没有引用 Microsoft Agent Framework；LocalOnnxEmbeddingProvider 尚未执行 ONNX 模型；公开 Web Copilot chat 端点走云端 Gateway，未接到本地 IChatProvider。这些缺口转入当前 ROADMAP M27。

背景：当前服务端 /mcp/{db} 已经暴露只读 MCP 工具（query_sql / list_measurements / describe_measurement）+ 三个 schema/stats 资源。在此之上，我们要构建一个真正能"对话操作 SonnetDB"的智能体，目标是让用户用自然语言完成"看 schema → 写 SQL → 解释结果 → 调优 / 排错 / 预测"全链路。

架构总览：

[Web Admin Chat / 第三方 MCP Host]
          │
          ▼
    SonnetDB（命名空间 SonnetDB.Copilot，当前为自研 CopilotAgent）
          │
    ┌─────┼──────────────────────────┐
    ▼     ▼                          ▼
Skills 库   Knowledge 检索      MCP Tool 调用
(剧本/Prompt) (向量召回 ← M13)    (本进程内复用 MCP 工具)
          │
          ▼
    SonnetDB Engine（Tsdb / SQL / Schema）

设计原则：

1. Agent 编排现状 = 自研 CopilotAgent；Microsoft Agent Framework 是后续方向，尚未集成。
2. 知识库存储 = SonnetDB 自身（依赖 Milestone 13 的 VECTOR + knn(...)，自我 dogfooding）。
3. 嵌入模型多供应商兼容：
   • 本地 ONNX（未完成）：配置和类型已存在，但执行方法仍抛出 NotSupportedException，不能据此声明模型可用。
   • OpenAI 兼容端点——同一套 IEmbeddingProvider 接口，URL + Key + Model 即可切换；天然支持"国际版"（OpenAI / Azure OpenAI）和"国内版"（DashScope / 智谱 GLM / 月之暗面 Moonshot / DeepSeek / SiliconFlow / 火山方舟 等任何 OpenAI-compat 网关）。
   • 配置 SonnetDBServer__Copilot__Embedding__Provider = local|openai，Endpoint / ApiKey / Model 三件套；对话模型走同一抽象，复用同一套 provider 切换逻辑。
4. 零破坏：内容放在 SonnetDB.Copilot 命名空间下， 不新增项目， 不污染 SonnetDB.Core；服务端默认启用。
5. 技能库 = 文件系统 + 前置语义召回：copilot/skills/*.md（带 frontmatter description / triggers），第一轮根据用户问题做向量召回，命中后再加载到上下文。

PR 列表

配置预览

// appsettings.json
"SonnetDBServer": {
  "Copilot": {
    "Enabled": true,
    "Embedding": {
      "Provider": "local",                    // local | openai
      "LocalModelPath": "./models/bge-small-zh-v1.5-int8.onnx",
      "Endpoint": "https://api.openai.com/v1",
      "ApiKey": "${OPENAI_API_KEY}",
      "Model": "text-embedding-3-small"
    },
    "Chat": {
      "Provider": "openai",                   // openai
      "Endpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "ApiKey": "${DASHSCOPE_API_KEY}",
      "Model": "qwen-max"
    },
    "Docs": { "AutoIngestOnStartup": true, "Roots": [ "./docs", "./web/admin/help" ] },
    "Skills": { "Root": "./copilot/skills" }
  }
}

推进顺序

PR #63（骨架 + Provider 抽象）→ #64（文档摄入）→ #65（技能库）→ #66（工具增强）→ #67（Agent 单轮）→ #68（多轮 + Web）→ #69（Eval）。 前置依赖：Milestone 13 的 PR #58 / #59 / #60 至少需要先合并，PR #64 才能在 SonnetDB 自身上落库。

Milestone 15 — 地理空间类型与轨迹分析

背景：IoT / 车联网 / 户外运动等场景大量产生带时间戳的经纬度序列（轨迹）。SonnetDB 已有时序存储底座与 SQL 函数扩展能力（Milestone 12），在此之上引入原生 GEOPOINT 字段类型，可以用一句 INSERT 写入轨迹点、一句 SELECT 做地理围栏过滤或总里程聚合，并在 Web Admin 地图页上实时回放。

设计原则：

1. 新增 GEOPOINT 字段类型（纬度 lat + 经度 lon，各 8 字节 float64，little-endian），存为 FieldType.GeoPoint = 6；BlockEncoding.GeoPointRaw = 16 字节定长编码，SegmentFormatVersion 升级到 v4，保留对 v3 只读回退。
2. 轨迹 = 带时间戳的 GEOPOINT 序列，无需新增专用存储层——直接用现有 Measurement + time 列建模即可（CREATE MEASUREMENT vehicle (time, device TAG, position GEOPOINT, altitude FLOAT64)）。
3. Safe-only 继续遵守：Haversine 等地理计算全部用普通 C# double 运算；可选 System.Numerics.Tensors.TensorPrimitives 做 SIMD 批量距离计算（向量化 lat/lon 数组）。
4. 零第三方运行时依赖：不引入 NetTopologySuite / GeoJSON.Net；GeoJSON 序列化在服务端 JSON 层手写 GeoJsonConverter（~100 行）。
5. UI 地图层零破坏：Vue3 Web Admin 新增独立"轨迹地图"标签页，复用现有 Naive UI 框架 + MapLibre GL（前端 npm 依赖，不影响 core 库）。

PR 列表

SQL 用法预览

-- 车辆轨迹查询（返回 GeoJSON 用于前端地图渲染）
SELECT time, device, position,
       geo_speed(position, LAG(position) OVER w, 1000) AS speed
FROM vehicle
WHERE device = 'truck-01' AND time > now() - 6h
WINDOW w AS (PARTITION BY device ORDER BY time);

-- 地理围栏：查找进入北京五环内的车辆
SELECT DISTINCT device
FROM vehicle
WHERE geo_within(position, 39.9042, 116.4074, 18500)   -- 北京中心 18.5km 近似五环
  AND time > now() - 1h;

-- 各设备今日总里程
SELECT device,
       trajectory_length(position)          AS distance_m,
       trajectory_speed_max(position, time) AS max_speed_ms
FROM vehicle
WHERE time >= today()
GROUP BY device;

-- 户外运动：海拔 + 速度曲线（前端双轴折线图）
SELECT time,
       lat(position) AS lat, lon(position) AS lon,
       altitude,
       geo_speed(position, LAG(position) OVER (ORDER BY time), 1000) AS speed
FROM workout WHERE session_id = 'run-2026-04-22';

推进顺序

PR #70（GEOPOINT 类型）
  → PR #71（标量地理函数）
    → PR #72（轨迹聚合）
    → PR #73（GeoJSON 序列化 + REST 端点）
      → PR #74（Web Admin 地图页）
        → PR #75（SQL 控制台地图集成）
  → PR #76（Geohash 段内索引）   ← 可与 #74/#75 并行
  → PR #77（基准 + 文档）        ← 最后收尾

前置依赖：无硬性前置，Milestone 13/14 不需要完成即可开始 Milestone 15。但若 PR #58（VECTOR 类型 + SegmentFormatVersion v3）已合并，本 Milestone PR #70 需在其基础上升级到 v4。

Milestone 16 — Copilot 产品化升级（嵌入式 AI 助手 UX）

背景：Milestone 14 已经把 Copilot 的服务端能力（MCP 工具 / 知识库摄入 / Agent 编排 / Eval）全部跑通，但用户在实际使用时仍遇到三类问题：

1. 首次启动 503：默认 local provider 需要手工下载 ONNX，导致开箱即用失败；
2. 知识库不可见：docs/ 已自动摄入但 UI 没有展示，用户以为没建；
3. UX 散落：Copilot 入口只在"AI 设置"页 chat tab，且 SQL Console 生成的 SQL 是 MySQL 方言、不带 SonnetDB 语法（CREATE MEASUREMENT / VECTOR / TAG / FIELD）。

本 Milestone 把 Copilot 推进到真正可日常使用的一等公民：零依赖就绪、全局浮窗、会话历史、上下文感知、权限审批、模型可选、SQL 生成对齐 SonnetDB 方言。

PR 列表

已落地补充

• Web Admin SQL Console 首版升级为 SonnetDB Workbench：保持原有 /admin/app/sql 路由和 Vue + CodeMirror + Naive UI 技术栈不变，把页面重构为 Schema Explorer / SQL Editor / Staged Preview / Result Grid 双栏工作台；读语句可直接执行，写语句必须先 staging，DELETE / DROP / GRANT / REVOKE / USER / TOKEN 类危险操作需要勾选确认。Copilot 继续使用右下角全局 CopilotDock 浮窗，不在 Workbench 内单独占栏。

推进顺序

PR #78 ✅ → #79 ✅ → #80 ✅ → #81 ✅ → #82 ✅
  → #83（M5 会话历史）✅ → #84（M6 上下文）✅
  → #85（M7 权限）✅ → #86（M8 模型）✅
  → #87（M9 高亮）✅ → #88（M10 引导）✅

前置依赖：Milestone 14 已合并；本 Milestone 不破坏 SonnetDB Core 的二进制格式，全部为 src/SonnetDB（API 层）+ web/（前端）+ Copilot 子系统的扩展。

与原路线图的差异说明

1. PR #15 重定义：从原"QueryEngine.QueryRaw"改为"多段索引层（SegmentIndex / MultiSegmentIndex / SegmentManager）"；原 QueryRaw 内容并入新 PR #16。
2. Milestone 5 重定义：从原"SQL 前端"改为"稳定性与性能（写入侧）"，新增 PR #17（后台 Flush + Checkpoint replay 跳过） / #18（Compaction） / #19（多 WAL 滚动） / #20（DELETE/Tombstone） / #21（Retention TTL，待派单）。
3. SQL 前端整体后移到 Milestone 6，并扩充 Tag 倒排索引（PR #27）与 ADO.NET API（PR #28）。
4. 压缩编码独立为 Milestone 7（原 Milestone 6 的 PR #22 / #23 / #24 中，Compaction 已在新 PR #18 完成；保留的 Delta / Gorilla 编码工作迁入此处）。
5. 单文件容器方案放弃：当前多文件布局（catalog.SDBCAT + wal/*.SDBWAL + segments/*.SDBSEG + tombstones.tslmanifest）已稳定且对运维/备份/排错友好；单文件需新增 page manager + shadow paging，会重写 M3~M5 的崩溃恢复矩阵，收益不足以覆盖成本。原 M8 改为"服务器模式"。
6. Milestone 8 重定义为服务器模式：仅 HTTP（POST /v1/db/{db}/sql + ndjson 流式结果），WebSocket 推后评估；多租户采用进程内 Tsdb 注册表；权限仅 Bearer token + 三角色，不做 SQL 级 GRANT。
7. 执行顺序前置：PR #21（Retention TTL）与 PR #35（嵌入式 Benchmark 基线）必须先于 M8 完成。
8. 发布顺延到 Milestone 9。
9. 新增 Milestone 12 — 函数与算子扩展：将 enum Aggregator 重构为 FunctionRegistry + IAggregateFunction，引入 Tier 1–5 共 ~50 个函数；以 PID 与 Forecast 作为内置差异化能力，并开放 UDF 注册 API 给嵌入式生态。该里程碑独立于原路线图，定位为 SonnetDB 在工业 / IoT / 可观测性场景的横向扩展层。
10. 新增 Milestone 13 — 向量类型与嵌入式向量索引：引入 VECTOR(dim) 数据类型与 cosine_distance / l2_distance / inner_product 标量函数 + knn(...) 表值函数，第一版以 brute-force + 并行顺扫实现，HNSW 作为可选段内 sidecar 索引（SDBVIDX）。定位为 Milestone 14 Copilot 知识库的存储底座，同时让 SonnetDB 形成"时序 + 向量"二合一的对外差异化能力；后续可在继续遵守 Safe-only 原则的前提下演进到 System.Numerics.Tensors.TensorPrimitives 等 SIMD 加速路径。
11. 新增 Milestone 14 — SonnetDB Copilot：历史目标是引入 Microsoft Agent Framework、本地 ONNX 和 OpenAI-compatible provider。2026-07-14 核查确认实际交付为自研 CopilotAgent、Microsoft.Extensions.AI 风格 provider 抽象、MCP 工具、知识库与 skills；Microsoft Agent Framework 未引用，本地 ONNX 未执行，公开 Web chat 仍走云端 Gateway。未完成部分转入当前路线图 M27。
12. 新增 Milestone 15 — 地理空间类型与轨迹分析：引入原生 GEOPOINT 字段类型（FieldType.GeoPoint = 6，lat/lon 各 8 字节 little-endian，SegmentFormatVersion v4）；Tier 1 地理标量函数（geo_distance / geo_bearing / geo_within / geo_bbox / geo_speed，含 PostGIS 兼容别名）；Tier 2 轨迹聚合函数（trajectory_length / trajectory_centroid / trajectory_bbox / 速度统计）；GeoJSON 序列化 + GET /v1/db/{db}/geo/{measurement}/trajectory 端点；Vue3 Web Admin 轨迹地图标签页（MapLibre GL + ECharts 时间轴联动）；SQL 控制台三视图（表格 / 图表 / 地图）；Geohash 段内剪枝索引（SegmentFormatVersion v5）。全程遵守 Safe-only 与零第三方运行时依赖原则。
13. 新增 Milestone 17 — 可观测性与运行时可见性：为 SonnetDB 补齐生产可运维三大支柱（指标 / 追踪 / 日志）。SonnetDB.Core 继续堅持零运行时第三方依赖，仅用 BCL System.Diagnostics.Metrics / ActivitySource 提供 Meter 与 Activity；OpenTelemetry SDK / Prometheus Exporter 仅出现在 src/SonnetDB（Server 程序集）。附带交付：Slow Query Log 与 Top-N 查询统计、Diagnostic Dump 端点、Health Live/Ready 拆分、Copilot token / tool 调用量指标与服务端会话持久化（M16 M5 二阶段）、Web Admin 内嵌监控面板（零图表第三方）。docker-compose 补 profile: observability 依需启动 otel-collector + prometheus + grafana 供本地联调。
14. 细化原 Milestone 10 的 #40 占位需求为独立的 Milestone 18 — VS Code 数据库扩展：保留 #40 作为 Epic，占位层面明确为“SonnetDB for VS Code”；具体实现拆分为 #99 ~ #108，采用 TypeScript-first + Remote-first 路线，首版直接复用现有 /v1/db、/v1/db/{db}/schema、/v1/db/{db}/sql、/v1/copilot/chat/stream 等 HTTP contract。本地目录支持不走 Node 直嵌引擎，而是后续通过“扩展托管本地 SonnetDB Server”方式接入，降低 VS Code 宿主与 .NET 运行时耦合。
15. 新增 Milestone 19 — IoTSharp 生态数据底座选项：把 SonnetDB 从“时序 + 管理后台 + Copilot”扩展为 IoTSharp 的可选数据底座。该里程碑覆盖关系型数据库、时序数据库、KV/缓存、S3-compatible 对象桶、向量搜索、全文搜索和大量物理分表长稳七条线，并把 EF Core provider、EasyCaching/IDistributedCache provider、S3 API、搜索索引生命周期、迁移双写、分层文件布局、compaction manifest、长稳压测作为同等重要的交付物。路线明确要求先做兼容矩阵和回滚策略，避免把不完整 table/KV/搜索能力过早宣称为 PostgreSQL/Redis/S3/搜索后端的生产级完整兼容。
16. 新增 Milestone 20 — 多模能力对齐与平移测试 (Parity)：用一份 docker-compose 同时拉起 SonnetDB 与开源全家桶（PostgreSQL / Redis / InfluxDB / VictoriaMetrics / MinIO / NATS / Mosquitto / Meilisearch / Qdrant / ClickHouse），用同一套 IDataPlane 适配器跑同一套场景，证明"一台 SonnetDB 在边缘 / 单机场景能替掉这一组组件"。显式不做协议兼容（自有 SndbConnection / SndbMqClient / SndbObjectStorageClient / EF Core provider，竞品走它们的官方 .NET 客户端），显式不做替代主张（不对齐 Redis Cluster / Kafka / Postgres HA / MinIO 集群），三类对齐边界为：能力对齐、可靠性对齐、算法准确度对齐；性能数字写报告不做 gating。本里程碑同时连带把 KV INCR/CAS/EXPIRE/PERSIST/TTL、SonnetMQ RecordTypeTombstone 段滚动 + FlushOnPublish=true 默认、对象桶 ListObjectsV2 ContinuationToken 分页、tests/SonnetDB.CrashTests/ 真子进程 SIGKILL 注杀、README 措辞与代码同步落地。详细设计见 docs/parity-roadmap.md。
17. 新增 Milestone 21 — Document Store 单机能力升级（MongoDB-like，不做协议兼容）：在 MM5 JSON 文档能力、MM6 全文索引、MM8 Hybrid Search 与 Milestone 20 parity 基础上，把 SonnetDB Document Store 推进到 MongoDB 单机常用能力子集。范围仅保留能力和功能实现：Document API / client、find filter、projection、sort、cursor、局部更新操作符、复合 / unique / sparse / partial / TTL 索引、aggregation pipeline 子集、单文档原子性、批量写轻事务、validator 执行能力与文档容量底座。该里程碑明确不做 MongoDB wire protocol / BSON command / 官方 driver 直连兼容，也不交付 Studio 管理面、MongoDB 参考 parity、长稳报告或发布文档。
18. 新增 Milestone 22 — Agent Memory / Codebase Intelligence（代码知识库与 MCP Memory 后端）：吸收 codebase-memory-mcp 代表的“代码库结构记忆 + MCP 工具”产品形态，把 SonnetDB 定位为 Agent 的长期记忆与代码知识底座，而不是仅供 SonnetDB Copilot 自用的内部 RAG。范围包括 Code Memory 标准 schema、Git/files/chunks ingest、C# 符号与调用边索引、只读 MCP typed tools、Hybrid Search 融合、Agent Memory 持久化 API、Web Admin Code Memory Explorer、VS Code / Copilot 接入样例与规模报告。该里程碑明确 src/SonnetDB.Core 不引入 tree-sitter/Roslyn/libgit2 等大型运行时依赖，语言解析与 Git 扫描放在 CLI/扩展/测试/示例工具层。
19. 新增 Milestone 23 — 搜索与向量引擎合并：DotSearch / DotVector 不再作为 SonnetDB 之外的独立产品线继续扩张。BM25、分词、距离计算、HNSW / IVF / Vamana、量化和索引序列化逐步收编到 src/SonnetDB.Core；Microsoft.Extensions.VectorData adapter 迁移到 src/SonnetDB.Data。路线见 docs/search-vector-engine-consolidation-roadmap.md。
20. 新增 Milestone 24 — SonnetDB Studio 管理体验升级（Document 管理面）：承接从 Milestone 21 迁出的管理相关内容，集中做 Document Explorer、validator governance、索引管理、JSONL/NDJSON 导入导出、rebuild / dry-run / 审批等 Studio 体验；本里程碑只补必要 metadata / maintenance contract，不新增 Document Store 查询、索引、事务或存储能力。
21. 新增 Milestone 25 — Document Store 验收、文档与发布治理：承接从 Milestone 21 迁出的文档和发布治理内容，集中做 MongoDB 参考 parity、百万 / 千万文档长稳 profile、容量报告、README / docs 能力矩阵、MongoDB-like 迁移指南、不支持项和推荐规模说明。

已完成里程碑详细正文（归档）

以下为主路线图 ROADMAP.md 中已完成里程碑的详细正文归档，含逐 PR 拆分、缺陷附录与落地说明。

Milestone 20 — 多模能力对齐与平移测试 (Parity)

目标：用一份 docker-compose 同时拉起 SonnetDB 与开源组件全家桶（PostgreSQL / Redis / InfluxDB / VictoriaMetrics / MinIO / NATS / Mosquitto / Meilisearch / Qdrant / ClickHouse），用同一份场景脚本两边各跑一遍，证明"一台 SonnetDB 在边缘 / 单机场景能替掉这一组组件"。详细设计见 docs/parity-roadmap.md。

设计原则：

1. 不做协议兼容。SonnetDB 走自有 SndbConnection / SndbMqClient / SndbObjectStorageClient / EF Core provider；竞品走它们的官方 .NET 客户端（Npgsql / StackExchange.Redis / InfluxDB.Client / Minio / NATS.Client.Core / Meilisearch.Net / Qdrant.Client / ClickHouse.Client）。
2. 不做替代主张。对齐"一台开源组件、单进程、单节点"的能力面，不对齐 Redis Cluster / Kafka / Postgres HA / MinIO 分布式集群。
3. 三类对齐：能力对齐（同场景两边都跑通）、可靠性对齐（同注入两边恢复语义一致）、算法准确度对齐（同数据两边统计量在容差内）。
4. 分布式留作下一步。本里程碑不引入复制 / 副本 / Raft；待客户和长稳数据要求后再启动。
5. 够用即可。性能数字写报告不做 gating；只对"在数量级以内"做健全性检查。

关键产出：tests/SonnetDB.Parity/ 测试项目 + tests/SonnetDB.Parity/docker-compose.parity.yml + GitHub Actions nightly + README parity badge + 八大支柱 × 至少 3 场景 = 24+ 场景红绿门槛。

连带产出（不另立 PR）：KV INCR/DECR/CAS/EXPIRE/PERSIST/TTL、SonnetMQ RecordTypeTombstone 段滚动 + FlushOnPublish=true 默认、对象桶 ListObjectsV2 ContinuationToken 分页、tests/SonnetDB.CrashTests/ 真子进程 SIGKILL、README 措辞与代码同步。

PR 拆分

推进顺序

#127 (compose 骨架 + IDataPlane + 第一对适配器)
  → #128 (关系型 vs Postgres)
  → #129 (TSDB vs InfluxDB/VictoriaMetrics + 算法准确度)
  → #130 (KV vs Redis + 向量 vs Qdrant，连带 INCR/CAS/TTL 落地)
  → #131 (对象桶 vs MinIO，连带 ContinuationToken)
  → #132 (MQ vs NATS，连带 SonnetMQ Tombstone + 段滚动)
  → #133 (全文 vs Meilisearch)
  → #134 (分析 vs ClickHouse)
  → #135 (可靠性套件 + tests/SonnetDB.CrashTests/)
  → #136 (CI gating + nightly + badge)

验收标准

• 八大支柱 × 至少 3 场景 = 24+ 场景全部 PASS（含 SKIPPED 但有 gap_reason 字段）。
• docker compose --profile full up 在干净 ubuntu-latest 5 分钟内全部 healthy。
• nightly 连续 7 天通过率 ≥ 95%（剩下 5% 留给容器抖动）。
• README 新增 "Parity vs Open-Source Stack" 段落 + 链接到最新 nightly 报告 + 通过率 badge。
• tests/SonnetDB.Parity/reports/sample-run.md 产出可读样例报告（含 24+ 场景表格 + diff 列）。
• 至少 1 个真实算法精度差异被 parity 抓出来并修复（证明判定有效，不是橡皮图章）。
• 可靠性套件用 Process.Kill(true) 真崩溃，不再依赖 CrashSimulationCloseWal；torn-record / 半重命名段 / disk-full 三个剧本必须通过。
• KV INCR / DECR / CompareAndSet / EXPIRE / PERSIST / TTL 与 SonnetMQ RecordTypeTombstone + 段滚动作为本里程碑连带产出落地。
• Parity 项目设 <IsAotCompatible>false</IsAotCompatible>，不进 SonnetDB.slnx，不污染主仓 AOT 流水线；竞品官方客户端依赖隔离在 adapters 各自 csproj。

不做的事

• 不实现 SigV4 / MQTT 3.1.1 / RESP / Postgres wire / Kafka wire 等协议兼容（永久不做）。
• 不测试 aws-cli / mosquitto_pub / redis-cli 直连 SonnetDB（不在能力对齐范围内）。
• 不做上层产品专用迁移工具（属于对应上层项目路线图；SonnetDB 仅保留 Milestone 19 的通用迁移与校验原语）。
• 不做绝对性能 gating（已在 tests/SonnetDB.Benchmarks 处理）。
• 不引入 Testcontainers / k6 / Gatling / Allure / TestRail，不引入 Java/Go/Python 客户端。

Milestone 21 — Document Store 单机能力升级（MongoDB-like，不做协议兼容）

目标：把现有 KV-backed Documents 能力从"JSON 文档集合 MVP"升级到MongoDB 单机常用能力子集：集合 CRUD、文档查询、局部更新、二级索引、聚合、游标分页、单文档原子性和单机可靠性都达到日常应用可用水平。SonnetDB 继续使用自有 SQL / HTTP / SndbDocumentClient / ADO.NET 能力面，明确不实现 MongoDB wire protocol，不承诺官方 MongoDB Driver 直连兼容。

设计原则：

1. 不做协议兼容。不实现 MongoDB wire protocol / BSON command 协议 / replica set 握手；对比 MongoDB 时仅作为参考后端，SonnetDB 走自有 API。
2. 做常用语义兼容。对齐单机应用最常用的 document CRUD、filter、projection、sort、limit、update operators、index、aggregation 子集，但允许 SQL / JSON API 语法不同。
3. 先单机，后分布式。本里程碑不做 replica set、sharding、change streams、oplog、read preference、write concern majority。
4. 索引可解释、可重建。所有 document index 都必须能在 EXPLAIN、schema endpoint、maintenance endpoint 和 backup manifest 中呈现，并支持离线 / 在线 rebuild。
5. 存储边界说清楚。若 KV 底座仍以内存字典为主，本里程碑必须给出容量边界；若引入磁盘有序 KV/LSM，则作为独立 PR 明确文件格式、恢复和 compaction 验收。

关键产出：SonnetDB.Documents 查询/更新/索引执行层升级 + SndbDocumentClient + 文档 REST API + 文档校验执行层 + 文档容量底座。MongoDB 参考 parity、Studio 管理界面、长稳报告和发布文档后移到独立里程碑，不再作为 Milestone 21 的交付范围。

PR 拆分（仅能力 / 功能）

已迁出范围

• Studio 管理面：原 #145 中的 schema governance 查看 / 编辑，以及原 #148 Document Explorer、索引管理、JSONL/NDJSON 导入导出，迁入 Milestone 24。
• 验收、长稳和发布文档：原 #147 MongoDB 参考 parity，以及原 #149 百万 / 千万文档长稳报告、README / docs 能力矩阵和迁移指南，迁入 Milestone 25。

推进顺序

#137 (Document API + client 契约)
  → #138 (Find/filter/projection/sort)
  → #139 (cursor pagination)
  → #140 (update operators)
  → #141 (index体系)
  → #142 (planner + explain)
  → #143 (aggregation pipeline 子集)
  → #144 (原子性 + 批量写轻事务)
  → #145 (validator 执行能力)
  → #146 (磁盘有序 KV / 容量底座)

验收标准

• Document API 覆盖常用 CRUD：单条 / 批量 insert、find、update、delete、count、distinct、aggregate。
• find 支持嵌套字段过滤、数组包含、projection、sort、limit/skip 和 cursor 分页；百万文档场景下索引查询不退化为全表扫描。
• $set/$unset/$inc/$push/$pull/$addToSet 等局部更新能正确维护主数据、JSON path index、fulltext index 和 TTL index。
• 单字段、复合、unique、sparse、partial、TTL index 均可创建、删除、展示、解释、重建，并进入 backup manifest。
• EXPLAIN 能清楚显示 _id lookup、document index scan、fulltext candidate、document scan、sort in-memory 等访问路径。
• Aggregation 子集至少覆盖 $match → $project → $group → $sort → $limit 常见链路，并与 SonnetDB 文档 API 语义契约一致。
• 并发写入、崩溃恢复、索引 rebuild、TTL 清理、backup/restore 后文档主数据与索引一致。
• collection validator 对 SQL / HTTP / client 写入路径行为一致，校验失败返回稳定错误码，warn 模式不阻塞写入但可被调用方观测。
• 文档主数据和索引的容量边界清晰；若引入磁盘有序 KV，冷启动、range scan、compaction、崩溃恢复和 backup/restore 均有对应测试。

不做的事

• 不实现 MongoDB wire protocol、BSON command 协议、mongosh / Compass / 官方 MongoDB Driver 直连 SonnetDB。
• 不实现 replica set、sharding、oplog、change streams、transactions across databases、read concern / write concern majority。
• 不承诺 MongoDB 查询语言逐字兼容；SonnetDB 可以提供 SQL / JSON API / client builder 三种自有入口。
• 不把 MongoDB 作为运行时依赖；MongoDB 只允许出现在 parity / benchmark / migration reference 测试环境中。
• 不为了兼容 MongoDB 引入 src/SonnetDB.Core 第三方运行时依赖。
• 不在本里程碑交付 SonnetDB Studio 管理界面、MongoDB 参考 parity、长稳报告或发布 / 迁移文档；这些分别进入 Milestone 24 / 25。

Milestone 26 — 连接器路线独立化（C ABI + 多模型 API）

目标：把连接器从“嵌入式示例”升级为独立产品路线。C ABI 继续作为跨语言稳定底座，当前保持 SQL-only；随后按 bulk / KV / Document / Object / MQ 分组扩展，不把多模型能力塞进单个 execute 函数。

边界：

1. C ABI 只暴露 opaque handle、primitive、UTF-8 / byte buffer，不暴露 C# 对象、内部 engine 指针或磁盘格式结构体。
2. 先保证 sonnetdb_open 能通过 SonnetDB.Data 同时支持嵌入式与远程连接；若 NativeAOT 因项目引用失败，才使用链接文件方式引入必要 Data 层源码。
3. 新能力必须以独立 ABI 函数组落地，再由 Go / Rust / Java / Python / VB6 / PureBasic 等语言包装。
4. 不做 Redis / MongoDB / S3 / Kafka / Postgres wire protocol 兼容；连接器走 SonnetDB 自有 API。

验收标准

• C ABI SQL-only 旧 quickstart 不改代码仍能运行。
• C ABI 可以通过 Data Source=sonnetdb+http://...;Mode=Remote 连接远程服务执行 SQL。
• 每个新增 ABI 分组都有 C quickstart 和至少一个上层语言 smoke。
• NativeAOT publish、CMake quickstart、Java JNI/FFM quickstart 在 Windows/Linux 能继续通过可用工具链验证。

Milestone 28 — 可靠性、并发正确性与热路径加固（Reliability / Concurrency / Performance Hardening）

背景：2026 年对 SonnetDB 做了一轮跨子系统深度审计（存储/持久化、索引、SQL 引擎、并发/性能四条线并行走查），共确认 54 项缺陷与优化点。其中若干在 Windows 默认配置下会真实丢数据或使数据"复活"，另有一批 SQL 层"返回错误结果 / 崩进程"的正确性 bug。本里程碑把这些发现按"先止血、再正确、再吞吐、再能力"的顺序拆成可逐一交付的 PR，逐步收口。

核心判断：引擎架构方向正确（LSM 写路径、不可变 segment、CRC 校验、reader-lease 快照隔离、SIMD 聚合、有界 LRU 缓存底子都在），但多处为了吞吐牺牲了持久性与并发正确性，且这些取舍没有在默认值或文档中充分暴露。本里程碑不是重写，而是把这些取舍要么修正、要么显式化并文档化。

设计原则：

1. 数据安全优先于吞吐。P0 阶段所有改动以"不丢数据、不复活、不损坏"为唯一验收硬门槛，即使牺牲写吞吐也先修正，再在 P2 用双缓冲把吞吐补回来。
2. 不破坏二进制格式。段头/尾 CRC（#195）走版本化可选字段或新 footer 版本，保留旧库读取兼容；FileHeader.Version 升级必须携带向后兼容读路径。
3. 复用既有机制。后台 worker 的并发修复直接复用查询路径已验证的 AcquireSnapshot() 租约，不发明新同步原语。
4. 每个 PR 自带回归测试。崩溃/掉电类缺陷必须有 tests/SonnetDB.CrashTests/（M20 #135 已建，真子进程 Process.Kill(true)）覆盖；SQL 正确性缺陷必须有确定性单测，附"修复前返回错误结果"的证据用例。
5. 默认值变更需显式声明。凡改动默认持久性/并发语义（如 group-commit 默认开、Delete 强制 sync）都要在 CHANGELOG、docs/architecture.md 写入路径章节和 TsdbOptions XML 注释三处同步说明。

不变约束：不引入 src/SonnetDB.Core 第三方运行时依赖；不改动对外 SQL / HTTP / ADO.NET / Document API 契约（能力增强除外）；Windows 目录 fsync 通过 P/Invoke CreateFile(FILE_FLAG_BACKUP_SEMANTICS) + FlushFileBuffers 实现，隔离在平台适配层。

阶段总览

收官状态（归档）：P0_P5（#189#244）+ SDK 补口 #261/#262 全部完成——SonnetMQ 四个 🔴 全部关闭（含 MQ3 无界内存/OOM），帧协议覆盖 MQ / 时序 / SQL / 向量 / KV / 对象 / 文档七个 service，SDK 帧/REST parity 已横向收口，MQTT broker/client 双形态就位。

P0 — 数据可靠性止血

P1 — 正确性与稳定性

P2 — 写路径吞吐

P3 — 查询与 SQL 能力

P4 — 索引与向量能力

P5 — 消息队列吞吐 + 全模型高吞吐接入

背景：本阶段合并两条主线。(1) SonnetMQ 热路径（src/SonnetDB.Core/Mq/SonnetMqStore.cs）——审计发现与 P2 写路径同类的问题（单一全局锁、锁内 I/O、每消息多次拷贝），且有一处架构级隐患：所有未裁剪消息全量常驻内存、段文件从不被读、SegmentCacheSize 明写「保留未实现」，长期高吞吐会 OOM。(2) 全模型接入层——SonnetDB 的时序 bulk-ingest、SQL/关系结果集、向量检索、KV、对象、文档、MQ 全部走同一套 HTTP+JSON 端点，二进制/数值负载被 JSON 编码课税：MQ/对象 payload 走 Base64（+33% 体积 + 编解码 CPU），向量 float[] 走 JSON 数字文本（比 Base64 更浪费），大 SQL 结果集序列化是真瓶颈，且全部只能请求-响应、无推送/流式。

核心判断：与 M28 其余阶段一致——方向对（各模型引擎本身没问题），但接入层用「一套 JSON 打天下」牺牲了二进制/数值/大结果集场景的吞吐，且 MQ 自身热路径为「先做出来」牺牲了并发与内存边界。P5 不重写任何引擎，而是修正 MQ 热路径并补一条覆盖全模型的高吞吐通用接入通道，现有 REST/JSON 全部保留向后兼容。

两段式结构：

• P5a MQ 热路径硬化（#230~#234）：基准先行，然后去全局锁、零拷贝写、组提交、冷数据下沉。纯 SonnetDB.Core 内改动，与接入层解耦。
• P5b 全模型高吞吐接入（#235~#244）：设计通用二进制帧（帧头带 service+op+stream-id 多路复用字段），承载于 Kestrel HTTP/2（复用现有鉴权/路由/TLS/流控/多路复用，Core 与 Server 均零第三方依赖），先落 MQ，再逐个模型接入（时序列式批量写 → SQL 流式结果集 → 向量检索 → KV/对象/文档）；IoT 设备侧兼容 MQTT 双形态（#242 内建 broker 设备直连 + #243 client 订阅外部 broker，均用 IoTSharp/MQTTnet.AspNetCore.Routing）。不做裸 TCP——评估表明其相对 HTTP/2 的收益（小消息高频约 1.2_{2×）不足以抵消重写分帧/鉴权/心跳/TLS/流控的复杂度，且本仓 #230 基线显示传输层开销（个位数 µs）被 store 的锁/flush（几十}几百 µs）碾压，传输不是当前瓶颈。

行业对标依据（2026-07 走查主流数据库 / MQ / 时序库线协议）：

• 二进制 + 长度分帧是铁律：PostgreSQL(pgwire)、MySQL、MongoDB(OP_MSG+BSON)、Redis(RESP)、Cassandra(CQL)、Kafka、Pulsar、TDengine(taosc)、IoTDB(Thrift) 的数据面无一用 HTTP/1.1+JSON。→ 印证 #235 二进制帧方向，收益主要来自消灭 JSON/Base64，与本仓 #230 基线一致（传输层开销是个位数 µs，被 store 的锁/flush 几十~几百 µs 碾压）。
• 时序写入收敛到列式批 + Line Protocol：IoTDB insertTablet(列式 Tablet)、TDengine STMT binary、PG COPY BINARY、InfluxDB Line Protocol——没有一个用行式 JSON。IoTDB/TDengine/QuestDB 都兼容 InfluxDB Line Protocol（本仓已有 InfluxLineProtocolEndpointHandler）。→ 支撑 #237 列式二进制批量写。
• 新系统的传输在倒向 HTTP/2，而非自造裸 TCP：InfluxDB v3(IOx) 从 HTTP 演进选了 Arrow Flight SQL over gRPC(HTTP/2) + 列式 Arrow（大 payload 走列式二进制、控制面走 RPC）；etcd、Google Pub/Sub 走 gRPC(HTTP/2)；连 TDengine 都为跨语言易用补了 WebSocket 层。裸 TCP 自定义协议（pgwire/taosc/Kafka）多是十余年历史资产 + 巨量分帧/流控/TLS/心跳工程投入。→ SonnetDB 处境最像 InfluxDB v3，故传输选 HTTP/2；帧内大 payload 学 Arrow Flight「控制面 RPC + 数据面列式二进制」的分层。
• 设备接入普遍内建 MQTT：IoTDB、TDengine 都内建 MQTT broker 供设备直连；InfluxDB 则靠 Telegraf 作 MQTT client 订阅外部 broker。IoTSharp 是 IoT 场景，设备侧真正在说 MQTT。→ 新增 #242（内建 broker）+ #243（client 订阅外部 broker）两形态，统一用 IoTSharp/MQTTnet.AspNetCore.Routing。

传输决策（自定义 HTTP/2 帧，非 gRPC，非裸 TCP）：评估 gRPC(grpc-dotnet 纯托管、无 C/C++ native、可省跨语言 codegen) vs 自定义 HTTP/2 帧后，选自定义帧——理由：(a) SonnetDB 重负载是列式时序批与向量 float[]，protobuf 行式 field-tag 编码对其不友好，塞进 bytes 字段等于绕过 protobuf（这正是 InfluxDB 用 Arrow Flight 而非裸 gRPC 的原因），自定义帧对列式/向量零拷贝完全自由；(b) 维持 Core 与 Server 双零第三方依赖的一贯约束；(c) 代价是跨语言客户端需自写（#241 保留），但本仓已有 C ABI 连接器底座可承接。

设计原则：

1. 复用引擎与传输已验证的机制。MQ 组提交借鉴 WalGroupCommitCoordinator 窗口化批量 fsync；冷数据下沉借鉴 segment reader 按需读取；推送/流式借鉴既有 SseEndpointHandler 并走 HTTP/2 流（多路复用、流控、TLS 由 Kestrel 提供，不自造）。不发明新原语、不重造传输层能力。
2. Core 纯 C# + BCL 零第三方依赖不变；传输承载于 Kestrel HTTP/2。帧编解码用 System.IO.Pipelines / System.Buffers；向量化 I/O 用 System.IO.RandomAccess；进程内解耦/背压用 System.Threading.Channels。二进制帧作为 HTTP/2 请求/响应体或长生命周期 HTTP/2 流传输，鉴权/路由/TLS/多路复用复用 Kestrel。不引入 gRPC / 裸 TCP / AMQP / 第三方 MQ 运行时；MQTT 设备接入允许在 Server 层引入成熟托管库（如 MQTTnet）——QoS/retain/will/session 协议细节多、自造不划算，且 SonnetDB.Core 仍保持零依赖。
3. 通用帧、多路复用、payload 自由。二进制帧头携带 service（mq/tsdb/sql/vector/kv/object/doc）+ op + stream-id（一条 HTTP/2 连接多请求交错）+ 长度；帧体承载各 service 自定义的列式/二进制编码（时序列式批、向量 float[] MemoryMarshal、SQL 列式结果块），零 JSON/Base64。帧协议一次设计，各模型逐 PR 挂载 opcode。
4. 契约新增而非替换。二进制帧、MQTT 都是并列新增，所有现有 REST/JSON 端点保留向后兼容；选型交由客户端按 docs/ 矩阵决定。契约在 CHANGELOG + docs/ 标注「新增」。
5. 先基准后优化。每段第一件事是建立吞吐/延迟/编码开销基准（P5a #230 已完成 MQ 基线），用数字驱动，避免拍脑袋优化。

P5a — MQ 热路径硬化

P5b — 全模型高吞吐接入（自定义二进制帧 over HTTP/2 + MQTT 设备接入）

传输统一为自定义二进制帧承载于 Kestrel HTTP/2（复用鉴权/路由/TLS/多路复用/流控），不做裸 TCP、不引入 gRPC；帧体各 service 自定义列式/二进制编码，零 JSON/Base64。IoT 设备侧另开 MQTT 内建 broker（服务端形态，用 IoTSharp/MQTTnet.AspNetCore.Routing，Server 层托管、Core 仍零依赖；topic db/{db}/m/{measurement}、payload=measurement 内容复用 BulkIngest 三格式）。

推进顺序

P0 止血：#189（Win 目录 fsync + 顺序）→ #190（add-then-reset）→ #191（worker 租约 + 串行锁）
        → #192（FTS manifest 原子）→ #193（HNSW 快照跳 tombstone）→ #194（Delete 持久化）
        → #195（段头尾 CRC）→ #196（默认持久性决策 + 文档）
P1 正确：#197（NULL 三值）→ #198（count(*)）→ #199（事务覆盖）→ #200（解析递归上限）
        → #201（worker 兜底）→ #202（批内 backpressure）→ #203（fsync 移出锁 + 排空）
P2 吞吐：#204（MemTable 双缓冲）→ #205（去锁内分配/装箱）→ #206（写路径同步精简）
        → #207（增量段索引）→ #208（tombstone 免拷贝）→ #209（catalog 防抖）
        → #210（manifest 修剪）→ #211（孤儿清理 + WAL footer 不变式）
P3 查询：#212（plan cache）→ #213（参数化）→ #214（LIMIT 下推）→ #215（hash join）
        → #216（子查询去关联）→ #217（时序 WHERE 字段/OR）→ #218（事务隔离）
        → #219（DISTINCT/大小写/DELETE/聚合类型）→ #220（流式合并）
P4 索引：#221（文档惰性 scan）→ #222（FTS 批量成段）→ #223（向量度量/efConstruction）
        → #224（KNN skip-index）→ #225（compaction 向量 catalog）→ #226（HNSW ef/回收）
        → #227（文档 ANN）→ #228（删遗留 HNSW）→ #229（文档索引原子性）
P5a MQ：#230（MQ 基准基线）→ #231（去全局锁 per-topic 分片）→ #232（写路径零拷贝 + RandomAccess）
        → #233（group-commit 组提交 + 批量入口）→ #234（冷数据下沉修无界内存）
P5b 接入：#235（通用二进制帧 + MQ service / HTTP-2）→ #236（HTTP-2 流式推送订阅）→ #237（时序列式批量写）
        → #238（SQL 流式结果集）→ #239（向量检索接入）→ #240（KV/对象/文档接入）
        → #241（客户端 SDK 帧贯通）→ #242（MQTT 内建 broker）→ #243（MQTT client 订阅外部 broker）
        → #244（全模型收口 + 文档 + parity）
        补口：#261（SDK 时序写帧贯通，补 #241）✅ ∥ #262（对象存储客户端帧贯通，补 #241）✅

阶段间可并行度：P0 内 #189~#196 相互独立，可并行推进但建议 #189/#190/#191 最先（数据安全影响面最大）。P1_{P4 各阶段建议顺序推进，但 P3/P4 的能力增强类 PR 与 P2 吞吐类 PR 之间无强依赖，可按团队带宽穿插。P5（#230}#244）独立于 P0_{P4；内部约束：**P5a（#230}#234）纯 Core MQ 硬化与 P5b 接入层解耦，可并行**；P5a 内 #230 基准必须最先；P5b 内 #235 通用帧编解码是 #236~#240 所有 service 接入的前置（#235 已 ✅，前置解除），各 service opcode（#237~#240）之间无强依赖可穿插，#236 推送订阅依赖 #235（复用其 TryReadFrame 增量解析循环，响应侧换 Channels），#241 SDK 贯通需至少一个 service 落地后，#242 内建 broker 可与 #237~#241 并行（复用 #236 推送管线），#243 MQTT client 订阅与 #242 共享路由 controller、宜紧随 #242，#244 收口最后。#261（SDK 时序写帧）与 #262（对象存储客户端帧）是 #241 SDK 贯通遗漏的两条补口——服务端 #237/#240 已 ✅，纯客户端 SonnetDB.Data 改动，二者互不依赖可并行，且不阻塞 #242~#244；#244 的 parity 平移测试宜在 #261/#262 落地后一并覆盖时序写与对象两条帧路径。

缺陷完整附录（54 项，确保无遗漏）

编号规则：S=存储/持久化（13）、I=索引（15）、Q=SQL 引擎（15）、C=并发/性能（11）。严重度：🔴 Critical（丢数据/损坏/崩溃）、🟠 High、🟡 Medium、⚪ Low。"—" 表示该发现已并入同一 PR。

P5 消息队列 / 接入协议附录（本轮新增，独立于上表 54 项）

编号规则：MQ=SonnetMQ 存储/并发/内存、N=接入协议/网络传输（覆盖全模型：MQ/时序/关系/向量/KV/对象/文档）。严重度同上。这批是围绕 P5 主题单独走查 MQ 热路径与全模型接入层的发现，不计入原审计 54 项。

验收标准

• P0：tests/SonnetDB.CrashTests/ 新增剧本证明——(a) Windows 掉电后 segment 与 WAL 不会同时丢失已 flush 数据；(b) flush 期间并发查询不返回不完整结果；(c) Compaction+Retention 并发下无 ObjectDisposedException 且过期数据不复活；(d) FTS manifest 崩溃后索引可从 segment 重建；(e) HNSW 删除+重插后持久化索引可正常加载；(f) Delete 后崩溃恢复数据不复活；(g) 段头/尾位翻转被 CRC 检出。默认持久性语义在 CHANGELOG + architecture.md + XML 注释三处一致。
• P1：每个 SQL 正确性缺陷有"修复前返回错误结果 / 崩溃"的确定性回归用例；NULL != 0 不再返回 null 行，count(*) 返回行数，BEGIN…ROLLBACK 不再持久化时序/文档写，深层嵌套 SQL 抛 SqlParseException 而非崩溃；Compaction/KvExpirer 后台异常可在诊断事件观测。
• P2：tests/SonnetDB.Benchmarks 显示写吞吐在双缓冲后不再随 flush 周期性塌陷；持续 ingest 下 P99 写延迟显著下降；高基数 series（百万级）ingest 不再 O(N²)；WriteMany 大批量不 OOM。基准数字进报告不做主 CI gating。
• P3：plan cache 命中路径不再重复 parse；参数化查询贯通 lexer→executor；ORDER BY…LIMIT k 内存与延迟不随数据量线性增长；等值 JOIN 走 hash；WHERE temp>30、WHERE a OR b 可用；EF Core 关系查询翻译在这些能力上回归通过。
• P4：文档索引点查不再 O(collection)；FTS 批量写不再 N 文件 + O(N²) manifest；声明 L2/IP 的向量索引真正走对应度量的 ANN；文档集合 vector_search 有可用加速路径；遗留 HnswVectorBlockIndex 移除后测试全绿。
• P5a（MQ 硬化）：tests/SonnetDB.Benchmarks 显示——多 topic 并发 publish 吞吐随 topic 数近线性扩展（去全局锁后不再互相阻塞）；单条 publish 分配数与拷贝次数下降（零冗余 ToArray、空 header 免分配）；group-commit 下持续 publish 的 P99 延迟显著优于每写 flush；长期高吞吐运行内存有界（冷数据下沉，不再 OOM）。MQ 默认持久性语义在 CHANGELOG + docs/ + XML 注释三处一致。
• P5b（全模型接入）：通用二进制帧 over HTTP/2 覆盖 MQ/时序/关系/向量/KV/对象/文档各 service，帧头 service+op+stream-id 多路复用可用；相比 JSON/Base64——MQ/对象 payload 与向量 float[] 的线上体积与 CPU 明显下降，时序批量写走列式二进制、大 SQL 结果集走流式二进制不再全量物化；HTTP/2 流式推送订阅端到端延迟低于轮询、支持一条连接并发多请求/多订阅；MQTT 内建 broker 设备可直连发布落库并订阅推送、client 可订阅外部 EMQX/Mosquitto 拉数落库（两形态共享 db/{db}/m/{measurement} 路由与 BulkIngest 落库逻辑）；每个 service 的二进制帧路径与 REST 路径通过 tests/SonnetDB.Parity 等价性平移；客户端 SDK 能协商传输并回落 REST。REST/JSON 端点全部保留向后兼容。基准数字进报告不做主 CI gating。

不做的事

• 不引入分布式复制 / 副本 / Raft / 多写节点（超出单机可靠性范围）。
• 不为兼容而在 src/SonnetDB.Core 引入第三方运行时依赖（Windows 目录 fsync 只用 BCL P/Invoke）。
• 不在本里程碑重写 SQL 引擎为完整成本模型优化器；P3 只做规则级下推、plan cache、hash join 与能力补齐，成本模型留后续里程碑论证。
• 不改动对外 SQL / HTTP / ADO.NET / Document API 已有契约语义（三值逻辑等属修正错误行为，需在 CHANGELOG 明确"行为变更"并给迁移说明）。
• 不把默认持久性从"性能优先"切到"每写 fsync"而不给关闭开关——#196 的决策必须保留可配置项与明确的吞吐/持久性权衡文档。
• 不为 P5b 引入 gRPC、裸 TCP 或 AMQP；传输统一为自定义二进制帧 over Kestrel HTTP/2（复用鉴权/路由/TLS/流控/多路复用），帧编解码用 BCL（System.IO.Pipelines/System.Buffers）。裸 TCP 经评估收益（约 1.2~2×）不抵重写分帧/心跳/TLS 的复杂度且传输非当前瓶颈；gRPC 的 protobuf 行式编码对列式/向量负载不友好且引入第三方栈——故均不采用。
• MQTT 例外：MQTT 接入以内建 broker（#242，服务端，对标 IoTDB/TDengine 设备直连）+ client 订阅外部 broker（#243，对标 InfluxDB+Telegraf）双形态落地，二者统一经 Server 层 IoTSharp 自家 MQTTnet.AspNetCore.Routing 实现（MVC 风格 topic 路由，运行时纯 C#、无 native，共享 db/{db}/m/{measurement} 路由 controller 与 BulkIngestEndpointHandler 三格式落库逻辑），因 QoS/retain/will/session/重连协议细节多、自造不划算；src/SonnetDB.Core 零第三方依赖不变。不做 broker 集群 / 桥接 / 跨节点 session。
• 不为 P5 引入分布式 broker / 分区副本 / 跨节点消费者组 rebalance；SonnetMQ 保持单机嵌入式队列定位，per-topic 锁分片只解并发不引入集群。
• 不删除任何现有 REST/JSON 端点（MQ/时序/SQL/向量/KV/对象/文档）；二进制帧与 MQTT 是并列新增，JSON/Base64 路径全部保留向后兼容，选型交由客户端按 docs/ 矩阵决定。
• 不为 P5b 新帧协议改动任何模型引擎的查询/写入语义；帧层只是传输编码，service/op opcode 一一映射到既有 API 行为，不借机改语义。