feat: publish Dever core with project scaffolding and versioned AI skills

2026-10-04 13:37:30 +00:00
1 parent 70fa73cdc2
commit ac458ffa7f
@@ -0,0 +1,19 @@
+# Bootstrap project guidelines
+
+## Scope
+
+This repository is a Rust workspace for the Dever language compiler, runtime,
+CLI and repository-root tests. `AGENTS.md` and the actual implementation are
+the source of truth for `.trellis/spec/backend/`. There is no frontend package
+or UI source in this repository; frontend scaffolding from `trellis init` is
+not applicable and must not prescribe hypothetical conventions.
+
+## Completion
+
+- [x] Document compiler/runtime/CLI ownership and real source examples in
+  `.trellis/spec/backend/directory-structure.md`.
+- [x] Document compiler contracts, ORM, errors, logging, toolchain and focused
+  checks in `.trellis/spec/backend/`, backed by source and tests.
+- [x] Remove unused frontend template specs; no frontend rules are claimed.
+- [x] Keep the backend index in sync and verify no template placeholders remain
+  in applicable backend specs.
@@ -0,0 +1,28 @@
+{
+  "id": "00-bootstrap-guidelines",
+  "name": "00-bootstrap-guidelines",
+  "title": "Bootstrap Guidelines",
+  "description": "Fill in project development guidelines for AI agents",
+  "status": "completed",
+  "dev_type": "docs",
+  "scope": null,
+  "package": null,
+  "priority": "P1",
+  "creator": "Antigravity",
+  "assignee": "Antigravity",
+  "createdAt": "2026-09-04",
+  "completedAt": "2026-09-18",
+  "branch": null,
+  "base_branch": null,
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [
+    ".trellis/spec/backend/"
+  ],
+  "notes": "Rust compiler workspace; frontend template specs are not applicable.",
+  "meta": {}
+}
@@ -0,0 +1 @@
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Focused checks"}
@@ -0,0 +1,17 @@
+# 设计
+
+## 归属与复用
+
+源码格式和 Markdown 内容区间由 core 拥有。使用 CommonMark 解析库识别真实顶层围栏，避免自造解析器误执行列表、HTML 或外层示例内的伪代码。新依赖仅用于编译器，不进入最小运行时。
+
+SourceFile 保留原文，词法 token span 使用原字节位置。Markdown 提取不能让缓存、诊断、运行故障指向合成文件。词法/格式化共用程序区间；语义包路径接受 `.dever.md`，重复检测沿用声明注册。
+
+## 格式化
+
+先解析全包，验证完整声明不跨围栏。复用 AST 格式化方法，按块选择包头/声明/注释生成内容，原位替换内部文本。不能合并代码块或移动说明。CLI 快照检查与 staging 原样复用。
+
+## 分工与契约
+
+主代理负责 CLI 文案、实际 CLI 验证、示例、文档、规范与任务记录。实现代理负责 core/加载/解析/格式化、必要依赖和 core 定向测试。完成后独立审查，主代理复核关键证据。
+
+程序围栏须顶层、闭合，信息字符串为 `dever`；无标记及其他语言只展示。每个类型、函数分句和 package 头完整位于一块内。若不支持缩进围栏，应明确诊断，不静默改变归属。
@@ -0,0 +1 @@
+{"file": ".trellis/spec/backend/index.md", "reason": "Compiler conventions"}
@@ -0,0 +1,24 @@
+# 执行与验证
+
+用户已在双格式方案后确认并选择 `.dever.md`，无需重复请求实施授权。
+
+- [x] Core：程序块识别、原文位置、加载与包路径、共用解析和格式化。
+- [x] 定向测试：提取/拒绝边界、中文换行定位、混用/重复包/契约、格式化保留说明和幂等。
+- [x] 示例和 CLI：结算示例、空源码提示、实际 check/fmt/run/build 的隔离定向验证。
+- [x] 文档规范：语言说明、实现说明、过时草案、AGENTS 源码规则。
+- [x] 检查：相关 Rust 格式、定向 Clippy/Markdown/formatter 测试及独立复核。
+
+`/root/.cargo/bin` 不在 PATH 时只设置命令级 PATH。持久测试放根 `test/`，临时程序归测试所有；无服务或网络操作，无全量/集成测试，无提交。仓库大部分文件原本未跟踪，diff 以本轮前快照为准。
+
+## 完成证据（2026-09-09）
+
+- `cargo test --offline -p dever-tests --test markdown_source --test formatter --test syntax_and_format`：45 项通过（12 + 11 + 22）。主代理已检查原始日志 `/tmp/dever-markdown-checks.log`。
+- 同目标 `cargo-clippy clippy --offline ... -- -D warnings` 通过；CLI 单独 `-p dever-cli --bin deverc -- -D warnings` 通过。10 个修改 Rust 文件的定向 rustfmt 检查通过。
+- 实际 CLI 对 `examples/markdown` 的 check/fmt/run 通过，输出 `customer = 小明`、`subtotal = 47.5`、`discount = 4.75`、`payable = 42.75`。普通 `.dever` 计价包被 Markdown 包调用。
+- 根 test/ 下临时程序验证：无 rustc 时 check 仍可用、两种格式的 API 相同、普通 README 忽略、fmt --check 不写、第二文件错误阻止所有改写、CRLF/说明/围栏保持及幂等、run/build、PATH 不含工具链时独立运行、已有输出不覆盖、重复包 C002、C005 精确到 Markdown 第 11 行第 20 列、运行除零定位 Markdown 第 11 行。临时文件和二进制已清理。
+- 最终 core 的实际 CLI 裸 CR/缩进围栏验证通过：中文原文 C005 第 10 行第 31 列、格式化无新增 LF、说明保持、check 和 fmt --check 通过。首次手写列号预期少算一列，按原文核对修正，非实现缺陷。
+- 独立只读审查无阻塞。补充验证包头前后独立注释块、跨块 Bool 分句、同一文件各块 LF/CRLF/CR、围栏/正文保持和幂等通过。
+- 新编译器依赖 `pulldown-cmark = 0.13.4`（关闭默认特性）及三个传递依赖已获取并锁定；不进入运行时，验证全部离线。复用已有 target/verification-tools 中的 rustfmt/Clippy，未安装全局组件。
+- 更新过时标题语法草案、当前说明和旧主任务源码格式限制。28 个实现/文档变更文件空白检查通过；未修改现有无关删除项。
+
+无未解决阻塞。未运行全量、集成或服务测试，未提交 Git；开发工作区改动保留供审查。
@@ -0,0 +1,25 @@
+# Dever Markdown 程序源码支持
+
+## 目标与确认决定
+
+用户希望用 Markdown 组织易读的 AI 程序，继续由 Dever 类型与契约约束执行。2026-09-09 用户批准同时保留 `.dever` 和 Markdown 源码，并明确选择 `.dever.md` 后缀。
+
+- `.dever` 行为兼容；`account/user.dever.md` 对应 `account.user` 包。
+- 标题、说明、表格不参与程序定义；只有标为 `dever` 的顶层围栏代码块属于程序，按顺序处理。代码保留完整 Dever 包、类型和函数声明。
+- 一个文件拥有一个包；格式可跨包混用，同包重复必须报错。
+- 复用现有语法、语义、契约、API 与原生编译路径。
+- 诊断和运行故障定位到原 `.dever.md` 文件及准确行列。
+- `fmt` 只格式化程序代码块，保留其它 Markdown 和围栏；整批检查后逐文件原子写入规则不变。
+
+## 验收
+
+1. 只加载 `.dever`/`.dever.md`，普通 `.md` 中的示例忽略。
+2. 同一程序两种格式的执行结果一致；混用包可调用，重复包、类型错误、分句缺失、失败义务仍拒绝。
+3. 多代码块、中文、不同换行、注释和原生故障位置正确；普通示例、嵌套围栏、引用、列表与 HTML 内的伪程序不执行。
+4. 程序围栏闭合，各块包含完整顶层声明（允许纯注释或空块）；无程序块、跨块声明报错，避免格式化移动代码跨说明。
+5. 格式化只更新代码块内部、幂等；语法或程序结构错误时无文件改写。
+6. 提供可读的结算 Markdown 示例，更新语言说明和过时草案。
+
+## 范围与验证限制
+
+不增加新语言语法、浏览器运行时、编辑器扩展或多语言执行。不改无关文件，不提交或安装全局命令。只跑离线定向检查和自有临时程序，不跑全量、集成测试或现有服务。开发依赖获取明确记录，最终程序编译保持离线。
@@ -0,0 +1,8 @@
+# 源码事实
+
+- source.rs 只收集 `.dever`，保存原文、SourceId 和行开始位置；符号链接全部拒绝。
+- lib.rs 的 parse_uncached 共用 lexer→parser；lexer 当前读取 SourceFile.text()。
+- check.rs 的 check_package 固定 `.dever` 路径；注册阶段已有重复包检测。
+- format.rs 从 token 注释和 AST 生成整个包；CLI 先准备全部字符串，再快照核验和逐文件原子替换。
+- check/cache.rs 键含源码全文/路径，文档改动仍需重新建立准确诊断位置。
+- pulldown-cmark 提供带偏移的块事件：https://docs.rs/pulldown-cmark/0.13.4/pulldown_cmark/struct.Parser.html 。当前未缓存，新增这一个编译器依赖用于避免不完整的 Markdown 自制解析器。
@@ -0,0 +1,26 @@
+{
+  "id": "markdown-source",
+  "name": "markdown-source",
+  "title": "Dever Markdown 程序源码支持",
+  "description": "保留 .dever，新增 .dever.md 源码加载、原文诊断、保留文档的格式化与定向验证",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "Antigravity",
+  "assignee": "Antigravity",
+  "createdAt": "2026-09-09",
+  "completedAt": "2026-09-09",
+  "branch": "main",
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
@@ -0,0 +1,3 @@
+{"file":".trellis/spec/backend/error-handling.md","reason":"检查错误、OOM、计数和进程退出都显式传播"}
+{"file":".trellis/spec/backend/quality-guidelines.md","reason":"核对 CPU 隔离、测量矩阵、最小测试和结果边界"}
+{"file":".trellis/tasks/09-13-http2-ceiling-soak/research/client-bottleneck.md","reason":"检查实现没有引入重复负载器或错误分位数聚合"}
@@ -0,0 +1,70 @@
+# 设计
+
+## 1. 最小改动边界
+
+本阶段只扩展 `test/performance` 的负载进程配置和测量文档。现有 Rust `network_bench` 已具备多线程 runtime、固定 HTTP/2 连接拓扑、速率调度、完整响应校验和延迟直方图，因此不修改 Rust 负载器，更不修改生产运行时。
+
+多进程客户端会产生多组独立直方图。只合并 p99 会得到错误分位数，输出全部 4096 个桶再聚合又会扩大协议和实现范围。一个多线程进程已经能把请求 worker 分布到多个 CPU，同时保留单一调度和精确的进程内直方图，因此采用该方案。
+
+## 2. CPU 与 worker 合同
+
+`Process` 的亲和性参数从单个 `cpu` 改为可空的 `cpus` 集合，并在 fork 后、exec 前一次性调用：
+
+```text
+os.sched_setaffinity(0, cpus)
+```
+
+服务端仍把 `--server-cpu` 转为单元素集合。运行器将 `--client-cpu` 直接迁移为 `--client-cpus`，接受无重复的逗号分隔非负整数；新增 `--client-workers`，默认 1。运行前集中校验：
+
+- 所有指定 CPU 必须属于当前进程允许集合；
+- 服务 CPU 不得出现在客户端 CPU 集合；
+- 正式压测显式使用 `--client-workers 4 --client-cpus 1,2,3,4`。
+
+不强制 worker 数等于 CPU 数，避免把合理的欠订阅/超订阅变成运行器错误；报告必须同时记录两者，使结果可解释。HTTP `load()` 和 `live.load_live()` 都把 `BENCH_WORKERS` 设置为同一个 `args.client_workers`，并把同一个 CPU 集合交给 `Process`。
+
+## 3. 数据流与复用
+
+```text
+run.py 参数与集中校验
+  -> Process(cpus=client_cpus)
+  -> BENCH_WORKERS=client_workers
+  -> 现有 network_bench 单进程 Tokio runtime
+  -> 现有 H2 连接/请求槽、调度、校验、Histogram
+  -> 现有 load JSON、进程采样、case/report 汇总
+```
+
+`Process` 继续只负责子进程生命周期、亲和性和采样；它不解释 server/client 角色。`run.py` 负责参数合同与服务/客户端隔离。`live.py` 只消费已经校验的参数，不新增一套 CPU 解析逻辑。
+
+## 4. 测量阶段
+
+所有正式场景只测 Dever，服务绑定 CPU 0、1 worker、1 CPU quota、swap 0；客户端绑定 CPU 1–4、4 workers，位于服务 cgroup 之外。使用现存 `typed-orm-build-v2` 指纹产物和 16 流配置；先验证其 HTTP/2 二进制、TLS 文件和清单，不重建生产产物。
+
+### 饱和扫描
+
+- 预算：128 MiB
+- 路径：`/plain`
+- 传输：h2c、TLS+h2
+- 拓扑：16x16（256 请求槽）
+- offered rate：30000、45000、60000、90000 req/s
+- 每 case：1 秒预热、5 秒测量、2 个 repeat
+
+若 90000 仍未出现平台，则只报告“扫描上界不足”，不继续无界提高负载。观测平台取成功 QPS 不再随 offered rate 近似线性增长的区间，不把容量丢弃计为服务错误。
+
+### 60 秒稳态
+
+从扫描得到的 h2c/TLS+h2 较低平台值向下取整到不高于 80% 的明确整数 rate，确保两种传输使用相同负载。128 MiB 和 64 MiB 各运行 h2c/TLS+h2 一个 60 秒 case。99% 成功率门槛只用于证明选定 rate 可持续，不用于定义服务极限。
+
+### 连接恢复耐久
+
+128 MiB 下，h2c/TLS+h2 各在同一服务进程运行 100 轮；每轮 16 条物理连接、每连接 16 流、0.1 秒、1000 req/s，随后使用既有 0.3 秒断开观测。每轮校验握手、请求错误和 FD 回落，整组检查 cgroup OOM 与 RSS 序列。
+
+## 5. 风险与解释
+
+- 多线程负载器仍有单一速率调度协程。如果扫描中客户端 CPU 未扩展、dispatch expired 显著而服务端未满 1 核，本阶段应如实判定压测器仍受调度器限制；是否实现分片调度另建任务，不能伪称服务端平台。
+- 客户端和服务端仍共享同一虚拟机，只是 CPU 集合隔离；缓存、内存带宽和宿主机噪声仍然共享。
+- 64 MiB cgroup 的文件页计费受热缓存影响，继续同时报告进程 RSS/PSS 和 cgroup peak，不以任一单值替代另一个。
+- 100 轮是分钟级重复回收证据，不是小时级泄漏或生产网络稳定性证明。
+
+## 6. 回退
+
+改动不涉及生产代码。若 CPU 集合支持造成回归，回退 Python 运行器、测试和文档即可；已有构建产物和历史报告不修改，新测量始终写入新输出目录。
@@ -0,0 +1,3 @@
+{"file":".trellis/spec/backend/directory-structure.md","reason":"保持 Python runner、进程采样和 Rust 协议负载的职责边界"}
+{"file":".trellis/spec/backend/quality-guidelines.md","reason":"遵守性能测量公平性、资源预算、报告和最小验证要求"}
+{"file":".trellis/tasks/09-13-http2-ceiling-soak/research/client-bottleneck.md","reason":"复用已有多线程能力并避免不可合并的多进程分位数"}
@@ -0,0 +1,32 @@
+# 执行计划
+
+## 1. 启动与上下文
+
+- [x] 用户确认后运行 `task.py start`；启动前不修改基准源码。
+- [x] 使用 `trellis-before-dev` 重新加载 backend 规范，核对当前 diff、磁盘、CPU、cgroup 和正式构建产物；`build-http2-final` 已不在工作树，改用参数满足需求的 `typed-orm-build-v2`，仍须校验指纹。
+
+## 2. 客户端并行配置
+
+- [x] 将 `Process(cpu=...)` 收敛为 `Process(cpus=...)`，所有调用者一次性迁移；保持亲和性只作用于自有子进程。
+- [x] 在 `run.py` 增加 CPU 集合解析、集中分配校验、`--client-cpus` 和 `--client-workers`，删除旧 `--client-cpu`。
+- [x] 让 HTTP/HTTP2 与 live 客户端共同使用相同 worker 数和 CPU 集合；更新 report environment/arguments。
+- [x] 清理重复解析与分支，确保进程生命周期、运行器合同和协议负载职责仍分离。
+
+## 3. 定向验证
+
+- [x] 扩展 `test_runner.py`，覆盖 CPU 集合解析、重复/越界/重叠拒绝、子进程实际亲和性和报告配置。
+- [x] Python 语法解析与 runner 34/34 通过；HTTP/2 产物指纹校验通过，未运行全量测试。
+- [x] `http2-ceiling-smoke-09-18`：h2c/TLS+h2 各 30/30 成功、16/16 握手、FD 差 0、OOM 0，报告确认 4 workers、CPU 1–4、客户端 5 线程。
+
+## 4. 有界正式测量
+
+- [x] `http2-ceiling-scan-09-18`：128 MiB、16x16、30k/45k/60k/90k、h2c/TLS+h2、5 秒、2 repeats 共 16/16 完成，错误/OOM/FD 差为 0。
+- [x] 30k 档 h2c/TLS+h2 吞吐约 29.9k/29.8k；45k 以上 h2c 约 34–40k、TLS+h2 约 37–39k，服务端接近 1 核、客户端 1.4–2.0 核，请求槽丢弃主导，调度过期很少。28k 的 60 秒首轮分别只有 98.68%/97.91% 成功；24k 的 10 秒校准 TLS+h2 只有 99.18%。20k 的 10 秒校准分别为 99.96%/99.92%，据此将正式共同稳态输入定为 20,000 req/s（低于较低观测平台的 80%）。
+- [x] `http2-ceiling-steady-128m-20k-09-18` 与 `http2-ceiling-steady-64m-20k-09-18`：h2c/TLS+h2 各 60 秒，成功率依次为 99.77%/99.92% 和 99.94%/99.80%，吞吐约 19.95k–19.99k req/s；全部零错误/OOM、FD 差 0。28k 首轮两项不足 99%，保留该报告为探索证据。
+- [x] `http2-ceiling-recovery-09-18`：128 MiB 下 h2c/TLS+h2 各 100/100 轮，分别成功 9,944/10,000 请求，余下 56 次/组为调度过期；每轮至少成功 95/98 个，16 次握手、FD 差 0，请求错误/OOM 为 0。首末轮断开后 RSS 为 4,845,568→5,357,568 B / 5,959,680→6,647,808 B，完整逐轮序列保留。
+
+## 5. 收尾
+
+- [x] 更新 `test/performance/README.md` 与 backend 性能规范中的 CLI、测量结果和限制；HTTP/HTTPS 30/30、TCP/WS/SSE 16/16 最小相邻入口回归通过。
+- [x] 检查了入口到子进程的 CPU/worker 传递、重复、职责、命名和无关改动；未改生产运行时或覆盖历史报告，空 frontend 模板是单独已归档的 bootstrap 任务。
+- [x] `trellis-check`：runner 定向单测 34/34、Python AST、构建清单指纹、扫描/稳态/恢复报告计数与 OOM/FD/握手不变量、空白检查均通过；HTTP/HTTPS 与 TCP/WS/SSE 最小回归通过。未运行全量测试、Cargo build、rustfmt/clippy；未提交 Git。
@@ -0,0 +1,42 @@
+# HTTP/2 饱和边界与耐久压测
+
+## 目标
+
+解除现有 HTTP/2 压测客户端的单核限制，在服务端固定 1 CPU、128 MiB/64 MiB、无 swap 的条件下，测量 Dever HTTP/2 小响应的本机饱和边界、60 秒稳态表现和重复连接恢复表现。结果用于判断后续是否存在值得单独优化的生产热路径，不把本机 loopback 数字外推为跨机器或生产环境上限。
+
+## 已确认事实
+
+- `network_bench` 已使用 Tokio 多线程 runtime，并通过 `BENCH_WORKERS` 控制 worker 数；HTTP/2 请求调度、响应校验、计数守恒和延迟直方图已有单一实现。
+- `test/performance/run.py:258` 把负载端 `BENCH_WORKERS` 固定为 1，`test/performance/process.py:104` 只允许子进程绑定一个 CPU。此前 30000 req/s 的 Dever 4x16 场景中，服务端和客户端均约占 0.9 核，因此现有数据不能区分两端上限。
+- 已构建清单允许 32 条物理连接、每连接 16 流、任务容量 272；16x16 需要 272 个服务任务，正好落在已有容量内，无需重新配置生产运行时。
+- Rust 负载结果只有一个进程内的完整直方图。拆成多个客户端进程后，现有 p50/p95/p99 摘要无法无损合并；使用一个多线程负载进程可以保留现有统计合同。
+- 当前机器允许 CPU 0–4；正式测量可将服务绑定 CPU 0，将负载端限制到 CPU 1–4。现有构建产物生命周期为 3600 秒，足以完成单个 60 秒场景和 100 轮恢复场景。
+
+## 需求
+
+- 将基准进程的单 CPU 亲和性扩展为明确的 CPU 集合；服务端继续使用单 CPU，客户端可使用多个互不重复且不与服务 CPU 重叠的 CPU。
+- 运行器新增明确的客户端 worker 数和客户端 CPU 集合参数，统一用于 HTTP、HTTP/2 和长连接负载；报告记录实际 worker 数和 CPU 集合。
+- 仓库内调用者一次性迁移到新的客户端 CPU 集合参数，不保留旧 `--client-cpu` 别名或兼容分支。
+- 多线程客户端继续复用一个 `network_bench` 进程、一套请求调度和一组原始直方图；不新增协议实现，不增加多进程结果拼接器。
+- 使用现存 `typed-orm-build-v2` 指纹产物（原 `build-http2-final` 已不在工作树，HTTP/2 配置仍为 32 连接、16 流、272 任务），先对 Dever `/plain`、h2c 和 TLS+h2、16x16 拓扑扫描多个 offered rate，区分客户端限制、请求槽限制和服务端饱和。
+- 根据扫描结果选择不高于观测平台 80% 的整数 offered rate，分别完成 h2c 和 TLS+h2 的 60 秒稳态测量；128 MiB 与 64 MiB 服务预算均覆盖，服务 CPU 固定为 1 核，swap 为 0。
+- 在同一 Dever 服务进程上对 h2c 和 TLS+h2 分别完成 100 轮 16x16 建连、请求、断开，逐轮保留计数、FD 和 RSS 回落数据。
+- 所有正式 case 必须保留请求计数、延迟、服务端/客户端 CPU 与内存、cgroup peak/OOM、握手数和断开后 FD 数据；失败时保留已完成结果与日志。
+
+## 验收标准
+
+- [x] 定向测试证明进程可绑定 CPU 集合，CPU 参数拒绝空值、重复值、越界值以及与服务 CPU 重叠的配置。
+- [x] 报告中的 `client_workers` 与 `client_cpus` 等于实际配置；负载进程采样可报告超过单核的总 CPU 使用率，且服务端仍只绑定一个 CPU。
+- [x] HTTP/1、HTTP/2 和长连接负载共用同一客户端并行配置入口；现有协议调度、响应校验和直方图实现未复制。
+- [x] 16x16 饱和扫描覆盖 h2c/TLS+h2 和至少四个递增 rate；全部请求计数守恒、请求错误为 0、握手数等于物理连接数、无 OOM，报告能识别吞吐平台或确认扫描上界仍不足。
+- [x] 128 MiB 与 64 MiB 下各完成 h2c/TLS+h2 的 60 秒稳态 case；请求错误和 OOM 为 0，成功率不低于计划请求的 99%，结束后 FD 回到 READY 基线。
+- [x] h2c/TLS+h2 各完成 100 轮 16x16 恢复；每轮至少有成功请求、错误为 0、握手数正确、FD 回到 READY 基线，RSS 序列如实记录且不把短时平台误称为无泄漏证明。
+- [x] 文档记录命令、机器约束、扫描结果、稳态/恢复结果和限制；明确区分本机观测饱和点、可持续负载与跨机器性能。
+- [x] 只运行受影响的 Python 单元测试、最小 loopback smoke、现有产物指纹校验和显式有界压测；不运行全量测试，不接触已有服务，不提交 Git。
+
+## 排除项
+
+- 修改 `crates/dever-runtime`、编译器、语言 API 或 HTTP/2 生产协议路径。
+- 多进程客户端、跨进程直方图合并、新压测依赖或第二套结果格式。
+- 跨主机、公网、丢包/限速注入、HTTP/3、RFC 8441 或小时级 soak。
+- 预设固定 QPS 门槛、与 Go/Fiber 的跨机器数字比较，或根据一次短测直接修改生产热路径。
@@ -0,0 +1,27 @@
+# 客户端瓶颈证据
+
+## 现有实现
+
+- `test/dever-tests/examples/network_bench/load.rs` 从 `BENCH_WORKERS` 创建 Tokio multi-thread runtime，范围为 1–64。HTTP/2 的物理连接、请求 worker、速率调度、响应校验和三组 Histogram 均在该进程内完成。
+- `test/performance/run.py` 的 `load()` 无条件写入 `BENCH_WORKERS=1`，并通过 `args.client_cpu` 把负载进程绑定到一个 CPU；`live.py` 使用相同单 worker/单 CPU 方式。
+- `test/performance/process.py` 的 `Process` 已集中拥有 fork 后亲和性设置，只需把单元素集合推广为调用方提供的集合，不需要新增进程封装。
+
+## 现有结果
+
+`target/performance/http2-plain-128m/report.json` 中，Dever 4x16、30000 req/s 的三轮结果为：
+
+- h2c 成功 QPS 29506–29804，服务端约 0.87–0.92 CPU，客户端约 0.89–0.91 CPU；
+- TLS+h2 成功 QPS 28673–29865，服务端约 0.91–0.93 CPU，客户端约 0.92 CPU；
+- 请求错误均为 0，但存在容量丢弃，因此该档位不能确定是哪一端首先饱和。
+
+## 方案比较
+
+| 方案 | 优点 | 问题 | 结论 |
+| --- | --- | --- | --- |
+| 多进程客户端 | 调度器天然分片，可跨多个 CPU | 每进程独立直方图，现有分位数无法正确合并；还需拆分 rate、连接和生命周期 | 本阶段不采用 |
+| 单进程多线程 | 已有 Tokio 支持；保留单一计数、校验和直方图；改动只在 Python 配置 | 单一调度协程仍可能成为更高档位瓶颈 | 先采用并用结果验证 |
+| 引入 h2load 等外部工具 | 成熟、高吞吐 | 新依赖、响应合同和报告格式不同，破坏现有可比性 | 不采用 |
+
+## 结论
+
+当前最小实验不是重写负载器，而是解除 Python 对已有多线程能力的限制。只有在多 CPU 客户端仍显示调度端瓶颈时，才有证据支持后续分片调度或多进程直方图协议。
@@ -0,0 +1,26 @@
+{
+  "id": "http2-ceiling-soak",
+  "name": "http2-ceiling-soak",
+  "title": "HTTP/2 ceiling and soak",
+  "description": "解除 HTTP/2 压测客户端单核限制，测量单核小内存服务的饱和边界、稳态表现与连接恢复耐久性。",
+  "status": "completed",
+  "dev_type": null,
+  "scope": "test/performance + performance docs/spec; reuse existing network_bench and production runtime unchanged",
+  "package": null,
+  "priority": "P2",
+  "creator": "Antigravity",
+  "assignee": "Antigravity",
+  "createdAt": "2026-09-13",
+  "completedAt": "2026-09-18",
+  "branch": "main",
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "09-04-dever-language-mvp",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
@@ -0,0 +1,3 @@
+{"file":".trellis/spec/backend/quality-guidelines.md","reason":"定向验收与代码审查"}
+{"file":".trellis/spec/backend/database-guidelines.md","reason":"配置、Model、事务和迁移不变量"}
+{"file":".trellis/spec/backend/compiler-contracts.md","reason":"双源码和错误合同"}
@@ -0,0 +1,26 @@
+# 设计边界
+
+- 复用同一 source/parser/check/native 流程；Markdown 只负责抽取及文档合同，不另建 ORM。
+- Model 字面量约束收敛在已有 normalize_value 所有者；覆盖 default/seed 两种调用者。
+- ORM 错误复用现有 choice/error 隐式失败机制；数据库错误身份不得通过文本猜测，非数据库故障仍走 Fault。
+- 标准库 `dever.database.Error` 对应 runtime ErrorKind 的十个 error 分支，每个保留 message。调用方结果类型可用一个 error-only choice 载荷包装原错误，例如 `error Failed(error: dever.database.Error)`；checker/native/reference 共用捕获映射，显式抛出的外层错误仍保留名义身份，重叠包装及不匹配错误集合均拒绝。
+- 数据迁移扩展已有命名 migration 与参数化 SQL 校验/运行流程，不新增迁移框架。
+- CMS 两套源文件具有相同包名和声明，Markdown 补充所需中文文档；共同测试防漂移。普通 CRUD 直接调用 Model，业务状态校验留在 service。
+- CMS 演示管理员 Seed、编辑注册与文章发布；注册规范化邮箱/显示名并检查必填数据，单次 create 不增加空事务包装。发布事务验证作者 Active，再按 slug upsert。入口首次注册编辑、重复运行复用编辑，稳定输出 users=2/news=1；哈希仅为演示值，不实现登录或密码算法。
+- 旧 examples/dever/cms 移至 examples/cms/dever；其余 dever/markdown 示例整体放 examples/old 下。更新维护中的路径，历史日志保留事实。
+- 基准 Python 驱动按受控测试目录写 config/setting.json，Rust peers 使用统一读取规则；工具链配置不混入业务配置。
+- 不触及 HTTP API 设计、路由、认证协议或新增 API 配置。现有编译器 dever.api 合同快照仍是编译器能力，并非用户延期的业务接口。
+
+实现分工：Model/Markdown 与基准配置分别独立处理；主线程负责错误链、迁移、CMS 与集成。相邻文件修改前明确交接。
+
+## 命名数据迁移
+
+`migrate name` 保留 `drop field`，增加可重复的 `before { sqlite = "..."; postgres = "..."; parameters = [...] }` 与 `after { ... }` 块；这里的分号仅表示文档分隔，实际源码使用换行。每块必须显式给出两个方言与参数列表，参数用现有绑定编码，不做字符串插值。
+
+- SQL 只接受一条 INSERT、UPDATE 或 DELETE；扫描器跳过引号/注释后检查首关键字及语句终止符，拒绝多语句、事务控制、DDL、PRAGMA。占位符继续复用现有方言扫描与连续参数覆盖检查。
+- `_dever_`、`sqlite_`、`pg_` 前缀及 `information_schema` 是保留对象，普通、引用和 SQLite 单引号名称都不能出现在迁移 SQL 中；同名业务文本使用绑定参数。PostgreSQL Unicode 转义标识符不接受，防止绕开保留名称检查。
+- 无类型上下文的绑定常量支持 Bool、Int、Text、null 和指数形式 Float；无指数小数属于 Decimal，缺少目标精度/scale 时拒绝，不隐式改为 Float。
+- 已有表先校验已应用迁移与实际 catalog，再按源码中迁移/块的顺序执行全部未应用 before，执行自动结构变更，再执行全部未应用 after，最后 Seed/history。所有步骤在现有单 Model 迁移事务中完成；失败整体回滚。
+- 新表直接建立最终结构和 Seed，登记迁移已应用，不重放旧数据转换。无 SQL 的 drop-only revision 保持原算法；包含 SQL 的 revision 纳入名字、drop、方言文本、参数类型/值、phase 与块顺序，以有边界的规范表示计算，避免拼接歧义。修改或删除已应用迁移继续拒绝。
+- 运行语句放 `Model.data_migrations`，历史 Schema 仍保存声明名、revision、drop；复用 `orm::Value` 和数据库绑定，不新增通用值系统。
+- 事务边界是同一数据库中的单 Model 初始化；跨表变换只能引用届时已存在的表。编译器现有 Model 初始化顺序不变，不承诺跨 Model 原子升级、任意对象拓扑或跨数据库迁移。
@@ -0,0 +1,3 @@
+{"file":".trellis/spec/backend/quality-guidelines.md","reason":"定向离线验证及测试目录"}
+{"file":".trellis/spec/backend/database-guidelines.md","reason":"Model、事务、配置与迁移合同"}
+{"file":".trellis/spec/backend/compiler-contracts.md","reason":"源码格式、错误和效应一致性"}
@@ -0,0 +1,38 @@
+# 执行记录
+
+用户已授权实施；API 明确延期。沿用上一轮审查已验证的缺口。
+
+## 顺序
+
+- [x] Model 字面量与 Markdown 声明合同、对应定向测试。
+- [x] 基准配置迁移到 config/setting.json，Python/Rust 定向检查。
+- [x] ORM 恢复错误的类型/效应/生成器贯通及事务捕获回归。
+- [x] 命名数据迁移扩展及历史/事务定向回归。
+- [x] examples 重排、CMS 双源码业务实现、路径与文档同步。
+- [x] 双源码 check/run/build 与打包定向验证、独立审查、规范更新。
+
+## 验证边界
+
+仅当前合同及示例的离线定向测试。SQLite 数据库使用测试临时目录。若需要 loopback 短时 peer 验证，运行前说明；不连接外部数据库、不运行全量集成或压力测试。未安装的 lint 工具如实记录。
+
+## 当前证据
+
+- Model default/Seed 定向 3/3；Markdown 静态/格式化 18/18（包括新 Model 声明支持）。
+- 基准 runner 37/37；network/live 无网络配置测试 2/2；Rust peers offline check/build 通过。现有根 setting.json 未修改。构建产物协议标记 setting-json-v1，旧产物必须重建。
+- error_effects 原有 8 项通过；新增共享错误包装/native+reference 1 项通过（含显式外层错误身份保持）。
+- SQLite 共享 ORM fixture 通过；新增 NotFound/Constraint 经任务和事务回滚捕获通过，最终记录 0 条。
+- 所有迁移后示例统一合同检查通过。两套 CMS 声明、Model、API、配置 parity 通过。
+- CMS 实际 native 首次运行发现 first() 行解码裸块的 ?/return 错误边界问题，已在共用 decode_included_row 修复；关联查询 native 回归 1/1，通过。
+- CMS CLI/打包验收 1/1（392.43 秒）：两格式各 check、2 次 CLI run、build、2 次无 module 独立打包运行，均 users=2/news=1。业务 probe 确认邮箱/显示名规范化，重复注册 Constraint 后数据不增加，禁用作者后发布 AuthorDisabled 且文章不增加。临时项目和 SQLite 已清理。
+- 两套 CMS 经 deverc fmt 整理后，fmt --check 和 parity 再次通过。CMS 基准 fixture 与当前业务入口的静态检查 1/1；旧 system 示例移除配置环境变量后的 native 检查 1/1。
+- 命名数据迁移 7/7（包括真实 native 双版本 SQLite 升级）；既有 orm_migration 7/7；最后增加 dollar-quote 回归后，静态/SQLite 7/7、共享 typed SQL 3/3 通过。native 升级未因纯扫描器边界修正重复运行。
+- 默认 core 及 core + PostgreSQL runtime cargo check 通过；最终扫描器修正后再次通过。
+- 独立审查确认 1 项 P2：PostgreSQL SQL 以未闭合 $tag 结束时，then_some 急切切片越界。最小回归先复现 panic，再修正共用扫描器；未闭合 delimiter/body 均给出 C014，合法 Unicode tag 和含 $ 的标识符保留。修复已独立复核，无剩余阻塞。
+- rustfmt/clippy 未安装。性能没有重测，旧 CMS 报告对应旧业务入口，不能替代新实现验收。
+
+## 收口
+
+- examples 仅保留 cms、old 两个目录：cms/dever 与 cms/md 同步；历史示例位于 old/dever、old/markdown。正式测试仍在 test/。
+- README、LANGUAGE、MARKDOWN-SYNTAX、示例说明和 backend specs 已同步。维护中的路径及配置环境变量搜索无旧入口；历史任务/日志保留原始事实。
+- 本次验收完成。业务 HTTP API 等用户重新设计；真实 PostgreSQL、性能/体积/64/128 MiB 压测不属于本轮验收。命名迁移只保证单 Model 事务，不承诺跨 Model 原子升级。
+- 本地任务未关联 PR；按项目要求不创建 commit，归档和日志均使用 no-commit。
@@ -0,0 +1,18 @@
+# 双源码 CMS 与语言合同修正
+
+## 需求
+
+用户要求 examples 最终只有 cms、old 两个目录；cms/md 与 cms/dever 同步实现同一 CMS，旧示例移到 old。API 留待用户重新设计，本任务不实现 HTTP API。
+
+承接源码审查：修复 Markdown Model 识别/声明合同、Model 默认值与 Seed 字面量校验、ORM 可恢复错误传播与捕获；补齐命名迁移的数据变换能力；示例与基准配置统一从 config/setting.json 读取；同步过期的语言返回值说明。
+
+## 验收
+
+- 两套 CMS 执行相同的注册、发布业务，数据库结构和可观察结果等价；重复执行可预测，禁用作者不能发布。
+- 所有旧示例移动到 examples/old；正式测试留在 test；当前代码与文档没有悬空路径。
+- Markdown Model 支持普通 Model 的声明，仍执行文档合同校验。
+- 不合法 Int/Float/Decimal/Text 默认值与 Seed 在编译期拒绝，不推迟到 Rust 编译或生成器 panic。
+- ORM 故障保留错误类别，进入既有隐式失败传播与 result 捕获合同；事务边界不抹掉错误。
+- 命名迁移支持参数化、按数据库方言选择的数据变换；事务、历史一致性约束不降级。
+- 无应用/基准配置环境变量入口；保留构建工具自身环境及通用 process.environment 语言能力。
+- 定向离线检查与最小测试通过，明确未运行的验证。不做全量测试或性能重测，不改全局工具、不提交 Git。
@@ -0,0 +1,26 @@
+{
+  "id": "cms-dual-source-contracts",
+  "name": "cms-dual-source-contracts",
+  "title": "双源码 CMS 与语言合同修正",
+  "description": "CMS 的 Dever/Markdown 双实现、旧示例归档和已确认语言合同问题；API 延后",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "Antigravity",
+  "assignee": "Antigravity",
+  "createdAt": "2026-09-18",
+  "completedAt": "2026-09-18",
+  "branch": "main",
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "09-04-dever-language-mvp",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
				`@@ -0,0 +1 @@`
				`{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Focused checks"}`
				`@@ -0,0 +1 @@`
				`{"file": ".trellis/spec/backend/index.md", "reason": "Compiler conventions"}`