@antprofuse/saddle-skill 0.3.9 → 0.3.11

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: saddle-service-0-3
-description: 使用 Saddle 0.3.9 Skill 开发或审查带 profusegw 固定入口和 profusecontract 强类型外部函数调用的 Rust 业务应用。用于定义 protobuf 契约、声明强类型业务配置、编写固定 ProfuseGwContext 四参数 handler、以框架响应映射业务拒绝和技术失败，或运行正式业务门禁。
+description: 使用 Saddle 0.3.11 Skill 开发或审查带 profusegw 固定入口和 profusecontract 强类型外部函数调用的 Rust 业务应用。用于定义 protobuf 契约、声明强类型业务配置、编写固定 ProfuseGwContext 四参数 handler、以框架响应映射业务拒绝和技术失败，或运行正式业务门禁。
 ---
 
-# Saddle 0.3.9 业务研发契约
+# Saddle 0.3.11 业务研发契约
 
 业务 Agent 的直接输入只有业务 spec 与本 Skill。不要要求用户阅读 Saddle 仓库、审计报告、组件提交或内部实现。
 
@@ -27,11 +27,13 @@ description: 使用 Saddle 0.3.9 Skill 开发或审查带 profusegw 固定入口
 
 ## 正式版本身份
 
+本包交付时 0.3.11 尚为候选。候选验证只消费发布方提供的同版隔离 registry/依赖缓存；不能把本地验证称为公网已发布，也不能退回旧版。发布可用后才使用公开 registry 安装同一 exact 版本。
+
 业务 crate 必须精确依赖：
 
 ```toml
 [dependencies]
-saddle-framework = "=0.3.9"
+saddle-framework = "=0.3.11"
 ```
 
 `saddle-framework` 是唯一业务 facade。业务不得直接依赖 `saddle-core`、`saddle-admission`、`saddle-boundary`、`saddle-db`、`saddle-macros`、`saddle-observability`、`saddle-runtime` 或 `saddle-service`。
@@ -39,6 +41,8 @@ saddle-framework = "=0.3.9"
 ## 固定边界
 
 - Saddle 编译进业务应用，不是独立服务、进程或控制面。
+- DB 声明只用公开 `database_operations!`，正常 Cargo build 生成 typed operation 与具名 Params/Row；完整可启动工程见 [打包业务示例](references/business-example.md)。不手写 SQL 或隐藏 trait。DB 调用用 `(result, c) = c.read(...).await`，剩余 c 仅能外呼，不能二次 DB。
+- query_optional 固定 LIMIT 1；bytes<N> 返回完整合法值，超界明确失败。数值支持集合见 [DB 合同](references/database-name-mapping.md)。已知 DB 内存贡献从现有 memory 配置推导并发，不新增预算参数；这不承诺全进程 RSS、driver/TLS 或任意业务分配的绝对硬界。
 - profusegw 唯一入口是 `POST /saddle/v1/ingress/profusegw/invoke`；不得手写 listener、HTTP handler 或第二路由。
 - 应用声明唯一字面量 `deployment_app`；请求 `target.app` 必须逐字匹配。每个字面量 `target.interfaceId` 只由静态 `operation_type` 分派，业务 handler 不读取或自行路由它。
 - profusegw body 固定且只含 `target`、`profuseGwContext`、`requestData`；`profuseGwContext.userInfo.userId` 仅在 backend 入站由框架形成只读 `ProfuseGwContext::user_id()`，业务 payload 不得覆盖。通用 ProfuseContract 技术 context 与wire 绝无 `user_id`；下游业务需要时，必须在具体 protobuf request 声明字段并由 handler 显式赋值。框架自动传播的只有 trace/rpc、LDC 和 deadline。
@@ -64,14 +68,17 @@ saddle-framework = "=0.3.9"
 - 配置在 listener 建立前一次解析、校验、解析 secret 环境引用并冻结。普通配置不接受环境变量覆盖；secret 只能通过 `[secrets]` 明确声明的环境变量名注入。未知字段、缺失必填字段、类型错误、secret 缺失、数据库 secret/mapping 配置不成对或相对路径非法均须 fail-fast。
 - `[framework.admission]` 必须声明正整数 `cpuCores` 与 `memoryMb`；`requestTimeoutMs` 可省略，省略时固定为 5000ms。`[framework.admission.dependencies]` 必须声明正整数 `databaseConcurrency` 与 `profusecontractConcurrency`。不存在 `maxActiveRequests`，也不得由业务代码直接指定 active/wait 容量。
 - 框架以 `min(CPU、封闭单请求内存预算、Database concurrency、ProfuseContract concurrency)` 冻结 active capacity，wait capacity 固定为 `W=0`。任一资源耗尽时在 handler 前立即拒绝，不排队、不后台重试。
-- ingress body、外部请求和外部响应各自受 1 MiB 静态边界约束；请求结束、断连或绝对 timeout 都必须归还同一准入资源。当前 `saddle-application/2` 没有 DB uses 时由框架完成受控 `NotUsed` 终态，业务不得增加伪 DB 调用；未来真实 DB operation 只能以 `Returned` 或 `Discarded` 终结物理资源。
-- 文件日志只由 `[framework.observability.logging]` 配置；默认目录 `./logs`、默认 `daily`。活动文件固定为 `saddle.log`；daily 归档为 `saddle.log.YYYY-MM-DD`，hourly 归档为 `saddle.log.YYYY-MM-DD-HH`。应用不得安装第二 subscriber，也不得把 stdout/stderr 混入该文件。大小轮转、压缩和清理策略不属于 Saddle 0.3.9，由运维侧管理归档目录容量与采集。
+- ingress 已携带绝对 deadline 时，该 deadline 贯穿 body、handler、数据库连接、ProfuseContract unary 调用和 terminal；只有 ingress 未提供时才使用 `requestTimeoutMs`（省略为 5000ms）。业务不得重置、延长或按阶段另建 timeout。
+- ingress body、外部请求和外部响应各自受 1 MiB 静态边界约束；请求结束、断连或绝对 timeout 都必须归还同一准入资源。当前 `saddle-application/2` 没有 DB uses 时由框架完成受控 `NotUsed` 终态；真实 DB timeout 会污染并 `Discarded` 当前连接，框架须恢复池容量，transaction 成功 commit，失败、timeout 或 cancel rollback，rollback 失败则 discard。业务不得增加伪 DB 调用或直接控制 commit/rollback。
+- 四维任一容量超限时，`W=0` 且同步返回 HTTP 503；已 accept 的 socket 即使响应侧背压或客户端慢读，也只能得到有界 HTTP 503 或正常终态，不能以 0-byte EOF 代替拒绝。terminal 后 CPU、memory、Database、ProfuseContract 和 aggregate used metrics 均须归零。
+- 文件日志只由 `[framework.observability.logging]` 配置；默认目录 `./logs`、默认 `daily`。活动文件固定为 `saddle.log`；daily 归档为 `saddle.log.YYYY-MM-DD`，hourly 归档为 `saddle.log.YYYY-MM-DD-HH`。应用不得安装第二 subscriber，也不得把 stdout/stderr 混入该文件。大小轮转、压缩和清理策略不属于 Saddle 0.3.11，由运维侧管理归档目录容量与采集。
 - `[framework.management].bind` 是独立于业务 `listen` 的必填管理监听地址。管理面只接受固定 `GET /live` 与 `GET /ready`：进程处于 Starting、Ready 或 Draining 时 `/live` 返回 200；只有 Ready 时 `/ready` 返回 200，其余阶段返回 503。业务代码不得注册、覆盖或写入健康状态。
 - 同一独立 management listener 还固定提供 `GET /metrics`，只读导出进程内有界快照。标签集合封闭且低基数，不得携带 request/trace/rpc/user/payload/authority/error text 或任意业务值；业务不得注册第二 metrics 端点。
 - `[framework.lifecycle]` 只接受正整数 `startTimeoutMs` 与 `shutdownTimeoutMs`，两者省略时均为 `30000`。shutdown 值是从 SIGTERM 起覆盖停止接收、drain、逆序 shutdown、post-driver 与资源 ZERO 的唯一绝对总预算，不能分段重置。
+- 日志队列满时只允许丢弃日志并递增有界 dropped 计数；不得阻塞请求、改变业务响应或资源终态。
 - SIGTERM 必须先使 `/ready` 变为 503 并停止新业务流量，再 drain 已准入请求；drain 期间 `/live` 保持 200，业务入口先停止，管理入口最后停止。探针只投影本进程受管生命周期，不探测数据库、profusecontract 或其他下游；下游策略由部署环境另行负责。
 - 框架结构化日志必须能以同一 `trace_id` 还原 ingress → admission → handler → DB/NotUsed → ProfuseContract → response → resource finalization，并包含容量 limit/used/bottleneck/reject reason、child `rpc_id`/zone/安全 authority、生命周期/健康和 logger dropped/output failure。完整字段与查询方式见 [生产日志还原](references/operations-observability.md)。
-- 日志不得包含 body、Header、secret、token、Database URL、SQL/参数或物理表列；业务和运维不得依赖这些内容。0.3.9 不引入 Metrics、Prometheus 或 OTLP。
+- 日志不得包含 body、Header、secret、token、Database URL、SQL/参数或物理表列；业务和运维不得依赖这些内容。长期背压/恢复专项属于框架回归入口，不要求业务部署运行；Skill 不引入第二 metrics 端点、Prometheus 或 OTLP。
 
 ## 立即停止
 
@@ -84,7 +91,7 @@ saddle-framework = "=0.3.9"
 - handler 返回 Rust `Result`/`Err`、空成功、任意 JSON，或业务自建第二响应结构；
 - 业务拒绝或任一技术失败组合没有显式映射，机器码不稳定，或 `FailureMessage` 超过 256 bytes；
 - 出现旧响应字段、顶层 code/message 或任何旧协议兼容叙述；
-- Cargo 不是精确 `=0.3.9` Rust facade、缺 lock，或正式 Gate 不通过。
+- Cargo 不是精确 `=0.3.11` Rust facade、缺 lock，或正式 Gate 不通过。
 - 出现旧扁平 authority 长键或旧配置类型模块路径。
 - 缺少独立 management bind、把探针挂到业务入口、添加动态管理路由，或把下游连通性等同 readiness/liveness。
 - admission 预算缺失、为零/负数/溢出，出现 `maxActiveRequests`、业务自定 active/wait 容量、等待队列或资源归还旁路。

package/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Saddle 0.3 业务应用"
   short_description: "使用 Saddle 0.3 开发受控边界的 Rust 业务应用"
-  default_prompt: "请安装 Saddle 0.3.9 Skill（npm install --save-exact --ignore-scripts --no-audit --no-fund @antprofuse/saddle-skill@0.3.9），结合业务 spec 开始研发。"
+  default_prompt: "请安装 Saddle 0.3.11 Skill（npm install --save-exact --ignore-scripts --no-audit --no-fund @antprofuse/saddle-skill@0.3.11），结合业务 spec 开始研发。"