@antprofuse/saddle-skill 0.3.9 → 0.3.11

package/references/local-integration.md

@@ -38,7 +38,7 @@ target/release/my-saddle-app --config /etc/my-saddle-app/saddle.toml
 
 生产推荐传绝对配置路径。`--config saddle.toml` 与 `--config ./saddle.toml` 也合法，它们都相对进程当前工作目录定位配置文件；配置中的 `mappingDir` 和业务 `resolve_path()` 则相对 `saddle.toml` 所在目录解析。进程只接受这一对参数，不从默认位置搜索、不合并多文件、不热更新。
 
-0.3.9 部署配置只接受 `[framework.profusecontract].authority`。有业务配置的完整最小文件是 [saddle-configured.toml](../assets/saddle-configured.toml)，`business_config ();` 应用使用不含 `[business]` 的 [saddle-unit.toml](../assets/saddle-unit.toml)：
+0.3.11 部署配置只接受 `[framework.profusecontract].authority`。有业务配置的完整最小文件是 [saddle-configured.toml](../assets/saddle-configured.toml)，`business_config ();` 应用使用不含 `[business]` 的 [saddle-unit.toml](../assets/saddle-unit.toml)：
 
 ```toml
 [framework]
@@ -82,7 +82,7 @@ dataPath = "fixtures/data"
 - `[framework.lifecycle].shutdownTimeoutMs`：可选正整数，默认 `30000` 毫秒；从 SIGTERM 起算，共同覆盖停止接收、请求 drain、逆序 shutdown、post-driver 和资源 ZERO 的唯一总预算。超时记录 typed 阶段并 fail-closed，不伪报 clean shutdown。
 - `[framework.admission].cpuCores`：必填正整数、无默认值；是部署分配给进程的 CPU 核数，不是业务期望并发。
 - `[framework.admission].memoryMb`：必填正整数、无默认值；按十进制 MB 冻结部署内存预算。
-- `[framework.admission].requestTimeoutMs`：可选正整数；省略时固定为 `5000` 毫秒。它覆盖同一请求的 ingress、外部调用与资源终结绝对期限，不是重试间隔。
+- `[framework.admission].requestTimeoutMs`：可选正整数；省略时固定为 `5000` 毫秒。仅当 ingress 没有绝对 deadline 时用它形成请求期限；已有 deadline 原样贯穿 body、handler、连接、unary 与 terminal，不能分阶段重置或延长。
 - `[framework.admission.dependencies].databaseConcurrency`：必填正整数、无默认值；是进程可同时占用的 Database 依赖额度。
 - `[framework.admission.dependencies].profusecontractConcurrency`：必填正整数、无默认值；是进程可同时占用的 ProfuseContract 依赖额度。
 - `[framework.profusecontract].authority`：必填字符串、无默认值；必须是 plaintext `http://host:port` 固定地址，或只含一个 `{zone}` 的模板。模板由同一请求的 LDC zone 在调用前解析；禁止 path、query、fragment、userinfo、凭据和其他模板。
@@ -94,9 +94,9 @@ dataPath = "fixtures/data"
 
 所有配置在 listener 建立前一次解析和冻结。普通字段不能由环境变量覆盖；secret 只能通过 `[secrets]` 中明确声明的环境变量引用注入。文件不可读、未知/旧键、缺失字段、类型错误、非法 bind/authority、secret 缺失、数据库配置不完整或映射目录非法都必须 fail-fast，并返回稳定的 `saddle.process.*` 错误码。
 
-配置中没有 `maxActiveRequests`。框架从冻结输入确定唯一 active capacity：`min(CPU、封闭单请求内存额度、Database concurrency、ProfuseContract concurrency)`；wait capacity 固定为 `W=0`。超出任一维度时，请求在业务 handler 之前立即拒绝，不进入等待队列，也不执行框架后台重试。
+配置中没有 `maxActiveRequests`。框架从冻结输入确定唯一 active capacity：`min(CPU、封闭单请求内存额度、Database concurrency、ProfuseContract concurrency)`；wait capacity 固定为 `W=0`。超出任一维度时同步返回 HTTP 503，不进入等待队列，也不执行框架后台重试。socket 已 accept 后的慢读/断连或响应背压也只能形成有界 HTTP 503 或正常终态，不能出现 0-byte EOF。
 
-每个 ingress body、ProfuseContract 请求与 ProfuseContract 响应都受 1 MiB 边界约束，框架还把解码、响应和固定开销计入同一封闭内存额度。正常完成、客户端断连和绝对 timeout 均归还原请求的准入资源。无 DB route 由框架形成 `NotUsed`；真实 DB route 由生成的 query/write/单层 transaction 执行链形成 `Returned` 或 `Discarded`。DB 值返回 handler 生成响应后，框架在写回、断连或 timeout 终态到达时才 finish 请求；业务不得提前终结或丢弃资源 owner。
+每个 ingress body、ProfuseContract 请求与 ProfuseContract 响应都受 1 MiB 边界约束，框架还把解码、响应和固定开销计入同一封闭内存额度。正常完成、客户端断连和绝对 timeout 均归还原请求的准入资源。无 DB route 由框架形成 `NotUsed`；真实 DB route 由生成的 query/write/单层 transaction 执行链形成 `Returned` 或 `Discarded`。DB timeout 污染并 discard 当前连接，框架补回池槽；transaction 只有成功路径 commit，失败、timeout、cancel rollback，rollback 不能证明完成时 discard。DB 值返回 handler 生成响应后，框架在写回、断连或 timeout 终态到达时才 finish 请求；业务不得提前终结或丢弃资源 owner。terminal 后四维及 aggregate used metrics 必须归零。
 
 ## 管理探针与退出顺序
 
@@ -104,10 +104,11 @@ dataPath = "fixtures/data"
 - `GET /ready`：只有所有受管组件启动完成后的 Ready 阶段为 HTTP 200 与 `{"ready":true}`；Starting、Draining 等非 Ready 阶段为 HTTP 503 与 `{"ready":false}`。
 - `GET /metrics`：在同一独立 management listener 返回 OpenMetrics-compatible 进程内有界快照。指标名与 label 集合固定、低基数；禁止 request/trace/rpc/user/payload/authority/error text、secret 或业务值作为 label。
 - SIGTERM 到达后，框架先原子清除 readiness，使负载均衡停止新流量，再等待已准入请求 drain。drain 期间 management listener 与 `/live` 保持可用；业务 listener 先停止，management listener 最后停止，进程退出后两者均不可达。
+- `shutdownTimeoutMs` 从 SIGTERM 到达起只计算一次，是停止接收、drain、资源归还和组件停止共享的总预算；任一阶段不得重置。
 
 这些端点是框架生命周期的只读投影，不执行数据库查询、profusecontract RPC、磁盘探测或任意业务自检。不得在 handler 中写健康状态，不得增加动态 management route。部署系统负责探针调度、失败阈值、摘流和重启策略。
 
-该 authority 是部署输入，不进入业务 spec、request 或 handler。TLS、鉴权、服务发现、负载均衡和生产凭据不属于 0.3.9；需要其中任一能力时立即停止，不得在业务 crate 自建 client。
+该 authority 是部署输入，不进入业务 spec、request 或 handler。TLS、鉴权、服务发现、负载均衡和生产凭据不属于 0.3.11；需要其中任一能力时立即停止，不得在业务 crate 自建 client。
 
 ## 联调完成条件
 
@@ -119,6 +120,8 @@ dataPath = "fixtures/data"
 4. 返回 `Completed` 或八类 `TechnicalFailure × ExecutionCertainty` 之一；业务代码显式处理，不自动重试。
 5. 受管请求只形成一个 terminal；DB 物理资源先收敛，但准入 finish 仅在 HTTP response 写回、断连或 timeout 之后完成。
 
-结构化日志至少按正式 API 暴露的字段记录 trace/rpc、span/parent、request/call、app/interface、zone、outcome 与 duration；不得记录 payload、Cookie、session、原始 context、PII、secret 或数据库值。业务不得安装第二日志 subscriber。`saddle.log` 是框架结构化日志；stdout/stderr 是独立进程流，运维采集时不得与文件日志拼接成同一记录源。Saddle 0.3.9 不提供按大小轮转、归档压缩或历史清理；目录容量、外部采集、压缩与保留期由业务运维环境负责。
+结构化日志至少按正式 API 暴露的字段记录 trace/rpc、span/parent、request/call、app/interface、zone、outcome 与 duration；不得记录 payload、Cookie、session、原始 context、PII、secret 或数据库值。业务不得安装第二日志 subscriber。`saddle.log` 是框架结构化日志；stdout/stderr 是独立进程流，运维采集时不得与文件日志拼接成同一记录源。Saddle 0.3.11 不提供按大小轮转、归档压缩或历史清理；目录容量、外部采集、压缩与保留期由业务运维环境负责。
 
 联调 harness 可托管 listener 与受控 profusecontract server；业务源码不得复制 harness、直接依赖中间件 crate或注册第二入口。
+
+长期 deadline、慢读、DB 锁等待与日志队列背压专项由 Saddle 框架回归运行。业务部署只需运行本 Skill 的正式 Gate 与代表性流量验证，不应复制或定期运行该重型专项。

package/references/operations-observability.md

@@ -1,6 +1,6 @@
 # 生产日志还原与排障
 
-Saddle 0.3.9 的框架事件只写入同一 `saddle.log`。运维应以 ingress 提供的 `trace_id` 为主键，在单个进程文件顺序内还原请求，不依赖请求 body、Header 或数据库细节。
+Saddle 0.3.11 的框架事件只写入同一 `saddle.log`。运维应以 ingress 提供的 `trace_id` 为主键，在单个进程文件顺序内还原请求，不依赖请求 body、Header 或数据库细节。
 
 ## 还原一条请求
 
@@ -33,10 +33,11 @@ jq -c 'select(
 
 ## 容量与终态判断
 
-- capacity 事件提供四项安全 budget、统一 active `limit`、当前 `used`、确定性 `bottleneck` 与封闭 `reject_reason`。同一请求 accepted 或 rejected 的四维记录必须一致；超限拒绝发生在 body 物化和 handler 之前。
+- capacity 事件提供四项安全 budget、统一 active `limit`、当前 `used`、确定性 `bottleneck` 与封闭 `reject_reason`。同一请求 accepted 或 rejected 的四维记录必须一致；`W=0` 超限同步返回 HTTP 503。已 accept socket 的响应背压不得产生 0-byte EOF。
 - resource finalization 只接受 `NotUsed`、`Returned`、`Discarded`，并在 Admission 完成资源归还后记录 `credit=released`。断连和 timeout 也必须能观察到最终归还。
 - lifecycle 使用 Starting、Running、Draining、Stopped；健康状态使用 Healthy、Degraded、Failed。SIGTERM 后应先看到 Draining/readiness 清除，再看到资源终结和 Stopped。
-- logger health 包含 dropped 数与 output failure stage。日志队列丢弃不能改变业务结果；底层输出失败无法依赖同一个已失败文件自证，必须同时检查前台进程的 flush/shutdown 错误返回。
+- logger health 包含 dropped 数与 output failure stage。队列满只 drop 并计数，不能阻塞请求、改变业务结果或资源终态；底层输出失败无法依赖同一个已失败文件自证，必须同时检查前台进程的 flush/shutdown 错误返回。
+- 请求 terminal 后，CPU、memory、database、profusecontract 与 aggregate `used` 均应回到零；DB timeout/discard 后池容量必须恢复，不能用进程重启掩盖泄漏。
 
 ## 安全字段边界
 

package/references/programming-model.md

@@ -2,7 +2,7 @@
 
 ## 应用显式声明
 
-业务应用使用 `saddle-framework = "=0.3.9"` 的公开编程面：
+业务应用使用 `saddle-framework = "=0.3.11"` 的公开编程面：
 
 ```rust
 saddle::application! {
@@ -13,7 +13,7 @@ saddle::application! {
 
     profusecontract {
         contract_dir "contracts";
-        capability PucProfuseContract;
+        capability Capabilities;
         response_code BusinessCode;
         functions {
             QueryBoundAccounts => query_bound_accounts {
@@ -40,7 +40,7 @@ saddle::application! {
 
 `deployment_app` 是本部署唯一固定应用身份。profusegw body 的 `target.app` 必须逐字匹配它；每个 service 的 `operation_type` 是对应 `target.interfaceId` 的静态身份。两者都是声明期字面量，不是 handler 参数或动态路由键。
 
-0.3.9 起，handler 的第三参数是同一个应用能力聚合：所有 route 都保留声明过的
+handler 的第三参数是同一个应用能力聚合：所有 route 都保留声明过的
 ProfuseContract 强类型方法；需要数据库的 route 另外在 service 声明中选择唯一静态
 operation，例如 `database query_optional find_user (generated::FindUser);`、
 `database write save_user (generated::SaveUser);`、`database transaction_commit save_user
@@ -107,6 +107,24 @@ database transaction_commit transaction (generated::SaveUserCommit);
 database transaction_rollback rollback (generated::SaveUserRollback);
 ```
 
+生成步骤就是正常 `cargo build`：在业务源码使用公开 `saddle::database_operations!`，声明逻辑表及具名 Params/Row。完整声明、字段规则与调用示例见 [数据库声明与映射](database-name-mapping.md)。不需要独立生成器、build.rs、手写 SQL 或隐藏 trait。
+
+DB 方法只消费一次 DB 能力，并返回结果与剩余外呼能力：
+
+```rust
+let (result, c) = c.read(ops::ReadParams { id: request.id }.into_parameters()).await;
+match result {
+    Ok(row) => {
+        let row = ops::ReadRow::from_database(row);
+        // 显式处理 Some/None；用具名行字段构造强类型外呼请求。
+        // c 的外呼继续沿用本请求；c 已无 read/write 等 DB 方法。
+    }
+    Err(error) => { /* 映射为封闭失败响应，不把错误当成无行 */ }
+}
+```
+
+同一个 operation 可被多个 route 引用。`transaction_commit` 与 `transaction_rollback` 是静态 route 决策，不代表可在 handler 内动态开始、多步组合、commit 或 rollback 的事务 API。
+
 - 无 DB route 没有数据库方法，框架以 `NotUsed` 结束。query 和 write 只消费生成的有界参数/行类型。
 - 单层 transaction 的操作与 commit/rollback 决策都是 route 的生成期事实；同一连接成功后 commit，失败、timeout 或 cancel 时 rollback，无法证明可复用时 discard。业务不得调用 commit/rollback，不得嵌套 transaction。
 - DB 物理终态后，handler 先使用返回值形成响应；框架保留私有 post-DB terminal，直到响应写回成功、断连或 timeout 后才 finish 原请求并归还准入资源。

package/references/response-model.md

@@ -2,6 +2,8 @@
 
 ## 唯一响应
 
+响应还受框架现有 1MiB 编码与 framing 边界约束；超界形成技术失败，不截断为成功数据。这个边界不等于全进程 RSS、driver/TLS 或任意业务分配的绝对硬上限。
+
 handler 必须直接返回 `saddle::ingress::ProfuseGwResponse<Data, BusinessCode>`。合法语义只有两支：成功 `Success { data }`，失败 `Failure { failure: { code, message } }`。标准 JSON 投影为：
 
 ```json

package/references/validation.md

@@ -1,4 +1,4 @@
-# Saddle 0.3.9 Skill 正式业务 Gate
+# Saddle 0.3.11 Skill 正式业务 Gate
 
 ## 依赖与锁
 
@@ -12,7 +12,7 @@ edition = "2024"
 rust-version = "1.95"
 
 [dependencies]
-saddle-framework = "=0.3.9"
+saddle-framework = "=0.3.11"
 ```
 
 在允许访问正式 registry 的依赖准备阶段生成并提交 `Cargo.lock`。禁止 `path`、`git`、`[patch]`、source replacement 或宽松 Saddle 版本。
@@ -25,16 +25,18 @@ saddle-framework = "=0.3.9"
 npx --no-install saddle-03-gate --manifest-path Cargo.toml
 ```
 
-命令由已安装的 `@antprofuse/saddle-skill@0.3.9` 提供，不需要 Saddle 源码仓库。它会检查：
+命令由已安装的 `@antprofuse/saddle-skill@0.3.11` 提供，不需要 Saddle 源码仓库。它会检查：
 
 - facade 精确版本、禁止直接中间件依赖和 Cargo source 旁路；
-- `Cargo.lock` 中 admission、boundary、core、db、framework、macros、observability、runtime、service 九包统一精确映射 `0.3.9`；
+- `Cargo.lock` 中 admission、boundary、core、db、framework、macros、observability、runtime、service 九包统一精确映射 `0.3.11`；
 - 唯一 `contract_dir`、目录存在、禁止旧单文件 contract 声明；
 - 目录根部 `saddle_external_function.proto` 与 Skill 权威模板逐字一致且仅出现一次，使用 option 的业务 proto 必须 direct import 根文件；
 - 编译期递归扫描/import 闭包、option-only 索引、身份唯一、请求结果类型匹配，以及所有 function 均有实际 `uses`；
 - 固定 `ProfuseGwContext`、应用声明、八类技术失败与三种 certainty 均被显式引用；
 - handler 第三参数统一为生成 `Capabilities`，DB route 只选择 query/write/单层 transaction 的生成静态 operation；
 - lifecycle 只有两个正整数超时（省略均为 30000），management 固定包含 `/live`、`/ready`、`/metrics`；
+- ingress absolute deadline 优先且跨 body/handler/connect/unary/terminal 不重置；缺失时才使用默认 5000ms；
+- 四维 `W=0` 同步 503、DB timeout/discard 恢复、terminal metrics 归零、日志队列满只 drop 计数及 SIGTERM 单一总预算均由框架长期回归覆盖；业务 Gate 不复制该重型专项；
 - `application/2` 显式 `business_config Type`（无配置为 `()`），handler 四参数接收同型冻结 `BusinessConfig<Type>`；
 - 部署配置使用唯一正式键 `[framework.profusecontract].authority`；有配置与 unit 应用分别使用 Skill 的完整样例，unit 文件不得出现 `[business]`；旧长键与旧配置类型模块路径均拒绝；
 - handler 直接返回框架 `ProfuseGwResponse`，应用声明封闭 `response_code`，业务码实现 `ProfuseGwCode` 并注册无碰撞稳定机器码；

package/scripts/saddle-03-gate.js

@@ -30,8 +30,8 @@ if (/^\s*\[(patch|replace)\b/m.test(cargo) || /\b(path|git|branch|tag)\s*=/.test
   stop("DEPENDENCY_SOURCE", "禁止 path/git/patch/replace 依赖旁路");
 }
 const facade = cargo.match(/^\s*saddle-framework\s*=\s*(.+)$/m);
-if (!facade || !/^"=0\.3\.9"\s*(?:#.*)?$/.test(facade[1].trim())) {
-  stop("SADDLE_VERSION", '必须直接且精确依赖 saddle-framework = "=0.3.9"');
+if (!facade || !/^"=0\.3\.11"\s*(?:#.*)?$/.test(facade[1].trim())) {
+  stop("SADDLE_VERSION", '必须直接且精确依赖 saddle-framework = "=0.3.11"');
 }
 const internals = ["saddle-core","saddle-admission","saddle-boundary","saddle-db","saddle-macros","saddle-observability","saddle-runtime","saddle-service"];
 for (const name of internals) {
@@ -44,8 +44,8 @@ if (!fs.existsSync(lockPath)) {
   const publicClosure = ["saddle-admission", "saddle-boundary", "saddle-core", "saddle-db", "saddle-framework", "saddle-macros", "saddle-observability", "saddle-runtime", "saddle-service"];
   for (const name of publicClosure) {
     const escaped = name.replaceAll("-", "\\-");
-    if (!new RegExp(`name = "${escaped}"\\nversion = "0\\.3\\.9"`).test(lock)) {
-      stop("LOCK", `Cargo.lock 未绑定 ${name} 0.3.9`);
+    if (!new RegExp(`name = "${escaped}"\\nversion = "0\\.3\\.11"`).test(lock)) {
+      stop("LOCK", `Cargo.lock 未绑定 ${name} 0.3.11`);
     }
   }
 }
@@ -161,6 +161,7 @@ if (!/\bcapability\s+Capabilities\s*;/.test(source)) stop("CAPABILITIES", "appli
 if (!/\bcapabilities\s*:\s*Capabilities(?:\s*<[^>]+>)?/.test(source)) stop("CAPABILITIES", "handler 第三参数必须使用生成 Capabilities");
 if (/\b(?:contract|client)\s*:\s*[A-Za-z_][A-Za-z0-9_]*(?:Contract|Client)\b/.test(source)) stop("CAPABILITIES", "禁止旧第三参数 capability/client");
 for (const db of source.matchAll(/\bdatabase\s+([A-Za-z_][A-Za-z0-9_]*)\s+/g)) {
+  if (!source.includes('database_operations!')) stop('DATABASE_DECLARATION', 'DB route 必须使用公开 database_operations!');
   if (!new Set(["query_optional", "write", "transaction_commit", "transaction_rollback"]).has(db[1])) {
     stop("DATABASE", `禁止非静态或未批准数据库模式 ${db[1]}`);
   }
@@ -226,6 +227,7 @@ for (const certainty of ["NotExecuted","Executed","MayHaveExecuted"]) {
   if (!source.includes(certainty)) stop("EXECUTION_CERTAINTY", `缺少显式分支 ${certainty}`);
 }
 const forbidden = [
+  ["HIDDEN_DATABASE", /saddle::__private|\bStaticQueryOptionalOperation\b|\bStaticWriteOperation\b/],
   ["WILDCARD", /_\s*=>/], ["LISTENER", /\b(TcpListener|axum|hyper|actix_web|warp)\b/],
   ["RUNTIME", /\b(tokio::runtime|Runtime::new|spawn\s*\()/], ["RAW_RPC", /\b(tonic|Channel|ProfuseContractBoundary|raw_invoke|invoke_raw)\b/],
   ["DYNAMIC_FUNCTION", /\b(dynamic_function|call_dynamic|DynamicExternalFunction)\b/],
@@ -250,4 +252,4 @@ try {
   fs.rmSync(target, {recursive: true, force: true});
 }
 if (process.exitCode) process.exit(process.exitCode);
-process.stdout.write("SADDLE_03_GATE PASS; SKILL=0.3.9; RUST=0.3.9; ADMISSION_DERIVED; W0; CLOSED_RESPONSE; CLOSED_CODES; FAILURE_MESSAGE_256; FAILURE_8X3; LOCKED_OFFLINE\n");
+process.stdout.write("SADDLE_03_GATE PASS; SKILL=0.3.11; RUST=0.3.11; ADMISSION_DERIVED; W0; CLOSED_RESPONSE; CLOSED_CODES; FAILURE_MESSAGE_256; FAILURE_8X3; LOCKED_OFFLINE\n");