@antprofuse/saddle-skill 0.3.9 → 0.3.11

package/assets/business-example/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "saddle-0311-consumer"
+version = "0.0.0"
+edition = "2024"
+rust-version = "1.95"
+publish = false
+
+[dependencies]
+saddle-framework = "=0.3.11"
+
+[workspace]

package/assets/business-example/contracts/api.proto

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package puc;
+
+import "saddle_external_function.proto";
+
+service ExternalFunctions {
+  rpc Lookup(LookupRequest) returns (LookupResult) {
+    option (saddle.profusecontract.external_function) = {
+      puc: "puc"
+      function: "查询用户绑定户号"
+    };
+  }
+}
+
+message LookupRequest { string user_id = 1; uint64 value = 2; }
+message LookupResult { uint64 count = 1; }

package/assets/business-example/contracts/saddle_external_function.proto

@@ -0,0 +1,13 @@
+syntax = "proto3";
+package saddle.profusecontract;
+
+import "google/protobuf/descriptor.proto";
+
+message ExternalFunction {
+  string puc = 1;
+  string function = 2;
+}
+
+extend google.protobuf.MethodOptions {
+  ExternalFunction external_function = 50001;
+}

package/assets/business-example/mappings/users.json

@@ -0,0 +1 @@
+{"table":{"from":"users","to":"app_users"},"columns":[{"from":"id","to":"user_id"},{"from":"value","to":"user_value"}]}

package/assets/business-example/saddle.toml

@@ -0,0 +1,31 @@
+[framework]
+listen = "127.0.0.1:39101"
+
+[framework.management]
+bind = "127.0.0.1:39103"
+
+[framework.lifecycle]
+startTimeoutMs = 30000
+shutdownTimeoutMs = 30000
+
+[framework.admission]
+cpuCores = 2
+memoryMb = 512
+requestTimeoutMs = 5000
+
+[framework.admission.dependencies]
+databaseConcurrency = 4
+profusecontractConcurrency = 8
+
+[framework.profusecontract]
+authority = "http://127.0.0.1:39102"
+
+[framework.observability.logging]
+directory = "./logs"
+rotation = "daily"
+
+[secrets]
+databaseUrlEnv = "SADDLE_DATABASE_URL"
+
+[database]
+mappingDir = "mappings"

package/assets/business-example/src/main.rs

@@ -0,0 +1,389 @@
+use saddle::{
+    BusinessConfig, application, business_types,
+    ingress::{
+        FailureMessage, ProfuseGwCode, ProfuseGwContext, ProfuseGwFailure,
+        ProfuseGwResponse as Response,
+    },
+    profusecontract::ExternalFunctionResult,
+    testing::{
+        FakeExecutionCertainty, FakeProfuseContractBoundary, FakeStep, FakeTechnicalCode,
+        PROFUSEGW_MEDIA_TYPE, PROFUSEGW_METHOD, PROFUSEGW_PATH, ProfuseGwTestRequest,
+        TestIngressIdentity,
+    },
+};
+
+business_types! {
+    #[derive(Clone, PartialEq, Message, Deserialize)]
+    #[serde(crate = "serde")]
+    struct IngressRequest {
+        #[prost(uint64, tag = "1")]
+        id: u64,
+    }
+    #[derive(Clone, PartialEq, Message, Serialize)]
+    #[serde(crate = "serde")]
+    struct IngressResponse {
+        #[prost(uint64, tag = "1")]
+        count: u64,
+    }
+    #[derive(Clone, PartialEq, Message)]
+    struct LookupRequest {
+        #[prost(string, tag = "1")]
+        user_id: String,
+        #[prost(uint64, tag = "2")]
+        value: u64,
+    }
+    #[derive(Clone, PartialEq, Message)]
+    struct LookupResult {
+        #[prost(uint64, tag = "1")]
+        count: u64,
+    }
+}
+
+saddle::database_operations! {
+    pub mod generated {
+        table users { id: u64, value: u64 }
+        query_optional FindUser {
+            table users;
+            parameters FindUserParams { id => id }
+            result FindUserRow { value => value }
+        }
+        upsert SaveUser {
+            table users;
+            parameters SaveUserParams { id => id, value => value }
+            key id;
+        }
+    }
+}
+
+enum Code {
+    Dependency,
+}
+impl ProfuseGwCode for Code {
+    const REGISTERED_CODES: &'static [&'static str] = &["TECHNICAL_DEPENDENCY"];
+    fn stable_code(&self) -> &'static str {
+        "TECHNICAL_DEPENDENCY"
+    }
+}
+
+async fn handler(
+    _request: IngressRequest,
+    context: ProfuseGwContext,
+    capabilities: Capabilities,
+    _business: BusinessConfig<()>,
+) -> Response<IngressResponse, Code> {
+    assert_eq!(context.trace_info().trace_id(), "trace-1");
+    assert_eq!(context.trace_info().rpc_id(), "0");
+    assert_eq!(context.ldc_info().zone(), "z1");
+    assert_eq!(context.ldc_info().idc(), "i1");
+    assert_eq!(context.ldc_info().env(), "test");
+    match capabilities
+        .lookup(LookupRequest {
+            user_id: context.user_id().into(),
+            value: 0,
+        })
+        .await
+    {
+        ExternalFunctionResult::Completed(result) => Response::success(IngressResponse {
+            count: result.count,
+        }),
+        ExternalFunctionResult::TechnicalFailure(failure) => {
+            technical_failure(failure.code(), failure.certainty())
+        }
+    }
+}
+
+fn technical_failure(
+    code: saddle::profusecontract::TechnicalFailureCode,
+    certainty: saddle::profusecontract::ExecutionCertainty,
+) -> Response<IngressResponse, Code> {
+    use saddle::profusecontract::{ExecutionCertainty::*, TechnicalFailureCode::*};
+    let message = match (code, certainty) {
+        (FunctionNotFound, NotExecuted) => "FunctionNotFound: NotExecuted",
+        (FunctionNotFound, Executed) => "FunctionNotFound: Executed",
+        (FunctionNotFound, MayHaveExecuted) => "FunctionNotFound: MayHaveExecuted",
+        (FunctionRequestInvalid, NotExecuted) => "FunctionRequestInvalid: NotExecuted",
+        (FunctionRequestInvalid, Executed) => "FunctionRequestInvalid: Executed",
+        (FunctionRequestInvalid, MayHaveExecuted) => "FunctionRequestInvalid: MayHaveExecuted",
+        (CapacityRejected, NotExecuted) => "CapacityRejected: NotExecuted",
+        (CapacityRejected, Executed) => "CapacityRejected: Executed",
+        (CapacityRejected, MayHaveExecuted) => "CapacityRejected: MayHaveExecuted",
+        (DeadlineExceeded, NotExecuted) => "DeadlineExceeded: NotExecuted",
+        (DeadlineExceeded, Executed) => "DeadlineExceeded: Executed",
+        (DeadlineExceeded, MayHaveExecuted) => "DeadlineExceeded: MayHaveExecuted",
+        (DependencyUnavailable, NotExecuted) => "DependencyUnavailable: NotExecuted",
+        (DependencyUnavailable, Executed) => "DependencyUnavailable: Executed",
+        (DependencyUnavailable, MayHaveExecuted) => "DependencyUnavailable: MayHaveExecuted",
+        (ContractResultInvalid, NotExecuted) => "ContractResultInvalid: NotExecuted",
+        (ContractResultInvalid, Executed) => "ContractResultInvalid: Executed",
+        (ContractResultInvalid, MayHaveExecuted) => "ContractResultInvalid: MayHaveExecuted",
+        (InternalFailure, NotExecuted) => "InternalFailure: NotExecuted",
+        (InternalFailure, Executed) => "InternalFailure: Executed",
+        (InternalFailure, MayHaveExecuted) => "InternalFailure: MayHaveExecuted",
+        (TransportFailure, NotExecuted) => "TransportFailure: NotExecuted",
+        (TransportFailure, Executed) => "TransportFailure: Executed",
+        (TransportFailure, MayHaveExecuted) => "TransportFailure: MayHaveExecuted",
+    };
+    Response::failure(ProfuseGwFailure::new(
+        Code::Dependency,
+        FailureMessage::new(message).unwrap(),
+    ))
+}
+
+fn database_failure() -> Response<IngressResponse, Code> {
+    Response::failure(ProfuseGwFailure::new(
+        Code::Dependency,
+        FailureMessage::new("Database unavailable").unwrap(),
+    ))
+}
+
+async fn query_handler(
+    request: IngressRequest,
+    context: ProfuseGwContext,
+    capabilities: Capabilities<QueryRoute>,
+    _: BusinessConfig<()>,
+) -> Response<IngressResponse, Code> {
+    let (result, capabilities) = capabilities
+        .query((generated::FindUserParams { id: request.id }).into_parameters())
+        .await;
+    match result {
+        Ok(row) => match generated::FindUserRow::from_database(row) {
+            Some(row) => match capabilities
+                .lookup(LookupRequest {
+                    user_id: context.user_id().into(),
+                    value: row.value,
+                })
+                .await
+            {
+                ExternalFunctionResult::Completed(output) => Response::success(IngressResponse {
+                    count: output.count,
+                }),
+                ExternalFunctionResult::TechnicalFailure(failure) => {
+                    technical_failure(failure.code(), failure.certainty())
+                }
+            },
+            None => database_failure(),
+        },
+        Err(_) => database_failure(),
+    }
+}
+
+async fn write_handler(
+    request: IngressRequest,
+    _: ProfuseGwContext,
+    capabilities: Capabilities<WriteRoute>,
+    _: BusinessConfig<()>,
+) -> Response<IngressResponse, Code> {
+    let (result, capabilities) = capabilities
+        .write(
+            (generated::SaveUserParams {
+                id: request.id,
+                value: 7,
+            })
+            .into_parameters(),
+        )
+        .await;
+    match result {
+        Ok(value) => Response::success(IngressResponse {
+            count: value.rows_affected(),
+        }),
+        Err(_) => database_failure(),
+    }
+}
+
+async fn transaction_handler(
+    request: IngressRequest,
+    _: ProfuseGwContext,
+    capabilities: Capabilities<TransactionRoute>,
+    _: BusinessConfig<()>,
+) -> Response<IngressResponse, Code> {
+    let (result, capabilities) = capabilities
+        .transaction(
+            (generated::SaveUserParams {
+                id: request.id,
+                value: 9,
+            })
+            .into_parameters(),
+        )
+        .await;
+    match result {
+        Ok(value) => Response::success(IngressResponse {
+            count: value.rows_affected(),
+        }),
+        Err(_) => database_failure(),
+    }
+}
+
+async fn rollback_handler(
+    request: IngressRequest,
+    _: ProfuseGwContext,
+    capabilities: Capabilities<RollbackRoute>,
+    _: BusinessConfig<()>,
+) -> Response<IngressResponse, Code> {
+    let (result, capabilities) = capabilities
+        .rollback(
+            (generated::SaveUserParams {
+                id: request.id,
+                value: 11,
+            })
+            .into_parameters(),
+        )
+        .await;
+    match result {
+        Ok(value) => Response::success(IngressResponse {
+            count: value.rows_affected(),
+        }),
+        Err(_) => database_failure(),
+    }
+}
+
+application! {
+    schema "saddle-application/2";
+    application BusinessApp;
+    deployment_app "business-app";
+    business_config ();
+    profusecontract {
+        contract_dir "contracts";
+        capability Capabilities;
+        response_code Code;
+        functions {
+            Lookup => lookup {
+                business_unit "puc";
+                function "查询用户绑定户号";
+            } (LookupRequest) -> LookupResult;
+        }
+    }
+    service LookupIngress {
+        ingress profusegw;
+        operation_type "business.lookup";
+        request IngressRequest;
+        response IngressResponse;
+        handler handler;
+        uses Lookup;
+    }
+    service QueryRoute { ingress profusegw; operation_type "business.query"; request IngressRequest; response IngressResponse; handler query_handler; uses Lookup; database query_optional query (generated::FindUser); }
+    service WriteRoute { ingress profusegw; operation_type "business.write"; request IngressRequest; response IngressResponse; handler write_handler; uses Lookup; database write write (generated::SaveUser); }
+    service TransactionRoute { ingress profusegw; operation_type "business.transaction"; request IngressRequest; response IngressResponse; handler transaction_handler; uses Lookup; database transaction_commit transaction (generated::SaveUser); }
+    service RollbackRoute { ingress profusegw; operation_type "business.rollback"; request IngressRequest; response IngressResponse; handler rollback_handler; uses Lookup; database transaction_rollback rollback (generated::SaveUser); }
+}
+
+fn identity(name: &str) -> TestIngressIdentity {
+    TestIngressIdentity::new(name, "incoming", 1_800_000_000_000).unwrap()
+}
+
+fn request(method: &str, path: &str, media_type: &str) -> ProfuseGwTestRequest {
+    ProfuseGwTestRequest::new(
+        method,
+        path,
+        media_type,
+        identity("request-1"),
+        r#"{
+          "target":{"app":"business-app","interfaceId":"business.lookup"},
+          "profuseGwContext":{"userInfo":{"userId":"2088-user"},"traceInfo":{"traceId":"trace-1","rpcId":"0"},"ldcInfo":{"zone":"z1","idc":"i1","env":"test"}},
+          "requestData":{"id":1}
+        }"#,
+    )
+}
+
+fn smoke() {
+    let execution = BusinessApp::profusegw_test_harness(
+        FakeProfuseContractBoundary::completed(LookupResult { count: 7 }),
+        BusinessConfig::unit(),
+    )
+    .run(request(
+        PROFUSEGW_METHOD,
+        PROFUSEGW_PATH,
+        PROFUSEGW_MEDIA_TYPE,
+    ))
+    .unwrap();
+    assert_eq!(
+        execution.response_json().unwrap(),
+        r#"{"success":true,"data":{"count":7}}"#
+    );
+    let attempt = &execution.attempts()[0];
+    assert_eq!(attempt.request_id(), "request-1");
+    assert_eq!(attempt.call_id(), "incoming-1");
+    assert_eq!(attempt.trace_id(), "trace-1");
+    assert_eq!(attempt.rpc_id(), "0.1");
+    assert_eq!(attempt.zone(), "z1");
+    assert_eq!(attempt.idc(), "i1");
+    assert_eq!(attempt.env(), "test");
+    assert_eq!(attempt.function(), "查询用户绑定户号");
+
+    for (method, path, media_type, expected) in [
+        (
+            "GET",
+            PROFUSEGW_PATH,
+            PROFUSEGW_MEDIA_TYPE,
+            "METHOD_NOT_ALLOWED",
+        ),
+        (
+            PROFUSEGW_METHOD,
+            "/wrong",
+            PROFUSEGW_MEDIA_TYPE,
+            "PATH_NOT_FOUND",
+        ),
+        (
+            PROFUSEGW_METHOD,
+            PROFUSEGW_PATH,
+            "text/plain",
+            "MEDIA_TYPE_NOT_SUPPORTED",
+        ),
+    ] {
+        let result = BusinessApp::profusegw_test_harness(
+            FakeProfuseContractBoundary::completed(LookupResult { count: 0 }),
+            BusinessConfig::unit(),
+        )
+        .run(request(method, path, media_type));
+        let error = match result {
+            Err(error) => error,
+            Ok(_) => panic!("invalid framing must be rejected"),
+        };
+        assert_eq!(error.code(), expected);
+    }
+
+    let technical_codes = [
+        FakeTechnicalCode::FunctionNotFound,
+        FakeTechnicalCode::FunctionRequestInvalid,
+        FakeTechnicalCode::CapacityRejected,
+        FakeTechnicalCode::DeadlineExceeded,
+        FakeTechnicalCode::DependencyUnavailable,
+        FakeTechnicalCode::ContractResultInvalid,
+        FakeTechnicalCode::InternalFailure,
+        FakeTechnicalCode::TransportFailure,
+    ];
+    let certainties = [
+        FakeExecutionCertainty::NotExecuted,
+        FakeExecutionCertainty::Executed,
+        FakeExecutionCertainty::MayHaveExecuted,
+    ];
+    for code in technical_codes {
+        for certainty in certainties {
+            let technical = BusinessApp::profusegw_test_harness(
+                FakeProfuseContractBoundary::scripted([FakeStep::technical_failure(
+                    code, certainty,
+                )]),
+                BusinessConfig::unit(),
+            )
+            .run(request(
+                PROFUSEGW_METHOD,
+                PROFUSEGW_PATH,
+                PROFUSEGW_MEDIA_TYPE,
+            ))
+            .unwrap();
+            assert!(
+                matches!(technical.response(), ProfuseGwResponse::LookupIngress(response) if response.failure_value().is_some())
+            );
+        }
+    }
+}
+
+fn main() {
+    if std::env::args().nth(1).as_deref() == Some("--smoke") {
+        smoke();
+        return;
+    }
+    if let Err(error) = BusinessApp::run() {
+        eprintln!("{}", error.code());
+        std::process::exit(1);
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antprofuse/saddle-skill",
-  "version": "0.3.9",
-  "description": "Saddle 0.3.9 中文 AI Coding 研发契约与业务门禁。",
+  "version": "0.3.11",
+  "description": "Saddle 0.3.11 中文 AI Coding 研发契约与业务门禁。",
   "license": "MIT OR Apache-2.0",
   "files": ["SKILL.md", "agents", "references", "scripts", "assets"],
   "bin": {"saddle-03-gate": "scripts/saddle-03-gate.js"},

package/references/business-example.md

@@ -0,0 +1,40 @@
+# 从已安装 Skill 启动完整业务示例
+
+本包包含 `assets/business-example` 完整工程：Cargo.toml、lock、Rust业务源码、固定协议与业务proto、saddle.toml、表映射。业务唯一直接依赖是 `saddle-framework = "=0.3.11"`；不添加内部crate或patch。
+
+0.3.11 未发布时只能使用发布方提供的同版本候选 registry 和依赖缓存。候选烟测不证明公网可安装；版本未就绪应停止，不能回退旧版或把本地源码当registry。发布后再执行公网 exact 安装。示例的候选 lock 需在获批 registry 准备阶段由正常 Cargo 解析形成对应checksum lock，随后必须 locked/offline。
+
+```bash
+# 候选阶段：SKILL_TGZ 指向发布方提供的精确tgz，先核对其SHA256。
+npm install --save-exact --ignore-scripts --no-audit --no-fund "$SKILL_TGZ"
+cp -R node_modules/@antprofuse/saddle-skill/assets/business-example ./business-app
+cd business-app
+# 仅依赖准备阶段允许解析；候选registry由发布方提供，勿手写patch。
+cargo +1.95.0 generate-lockfile --offline
+../node_modules/.bin/saddle-03-gate --manifest-path Cargo.toml
+cargo +1.95.0 run --locked --offline -- --smoke
+cargo +1.95.0 build --release --locked --offline
+target/release/saddle-0311-consumer --config /absolute/path/business-app/saddle.toml
+```
+
+`--smoke` 是该示例的受控无DB外呼测试；默认启动路径调用真正的 BusinessApp::run。完整 DB→网络外呼需要以下部署输入，不会由 smoke 伪造：
+
+- 预先存在的 MariaDB app_users 表，user_id/user_value 为规范非空整数，user_id 为唯一键；DDL由业务运维负责。
+- 显式 `SADDLE_DATABASE_URL` secret 环境变量；不要把值写入配置、命令记录或日志。
+- ProfuseContract 实现本目录 api.proto 的“查询用户绑定户号”，接收 handler 显式传入的user_id和数据库value，返回count。将 `[framework.profusecontract].authority` 改成真实plaintext地址。
+- 根据环境选择业务listen、独立management bind及日志目录。其余配置规则见 [启动配置](local-integration.md)。本示例 `business_config ();` 不需要[business]。
+
+同一固定入口的调用示例（先write，再query）：
+
+```bash
+curl -i -X POST http://127.0.0.1:39101/saddle/v1/ingress/profusegw/invoke \
+  -H 'Content-Type: application/json' \
+  --data '{"target":{"app":"business-app","interfaceId":"business.write"},"profuseGwContext":{"userInfo":{"userId":"2088-user"},"traceInfo":{"traceId":"trace-1","rpcId":"0"},"ldcInfo":{"zone":"z1","idc":"i1","env":"test"}},"requestData":{"id":1}}'
+curl -i -X POST http://127.0.0.1:39101/saddle/v1/ingress/profusegw/invoke \
+  -H 'Content-Type: application/json' \
+  --data '{"target":{"app":"business-app","interfaceId":"business.query"},"profuseGwContext":{"userInfo":{"userId":"2088-user"},"traceInfo":{"traceId":"trace-1","rpcId":"0"},"ldcInfo":{"zone":"z1","idc":"i1","env":"test"}},"requestData":{"id":1}}'
+curl -i http://127.0.0.1:39103/ready
+curl -i http://127.0.0.1:39103/metrics
+```
+
+business.query 的query结果进入同请求真实外呼，再形成框架响应。business.transaction 与 business.rollback 分别是静态commit/rollback route；不能把它们外推成handler控制的动态事务。超大响应受现有1MiB编码与framing边界约束，超界是技术失败，不截断成功。已知DB贡献使用现有memory配置推导并发；不承诺RSS/driver/TLS/任意业务分配绝对硬界。

package/references/consumer-start.md

@@ -46,7 +46,7 @@ Saddle 在编译期从 `contract_dir` 确定性递归收集 `.proto`，闭合 im
 
 ## 阶段 3：Rust 实现
 
-业务 crate 精确使用 `saddle-framework = "=0.3.9"`，然后按 [最小编程模型](programming-model.md) 编写固定 `deployment_app`、显式 `business_config`、静态 operation 声明和四参数 handler。不得直接依赖任何 Saddle 中间件 crate。
+业务 crate 精确使用 `saddle-framework = "=0.3.11"`，然后按 [最小编程模型](programming-model.md) 编写固定 `deployment_app`、显式 `business_config`、静态 operation 声明和四参数 handler。不得直接依赖任何 Saddle 中间件 crate。
 
 实现通过 Gate 后，按 [本地联调](local-integration.md) 由外部 harness 注入唯一 plaintext profusecontract authority，并以固定 profusegw body 验证真实 typed call。endpoint、request/call identity 和 deadline 都是框架或部署输入，不写入业务 spec。
 
@@ -63,6 +63,6 @@ Saddle 在编译期从 `contract_dir` 确定性递归收集 `.proto`，闭合 im
 - 缺少固定 `deployment_app`，或 app/interfaceId/endpoint 被做成动态业务输入；
 - 技术失败码或执行确定性存在 catch-all/default；
 - 需要裸 gRPC/channel/bytes、第二入口、动态 descriptor 或未声明外部 I/O；
-- `saddle-framework` 不是精确 `=0.3.9`，或 [正式 Gate](validation.md) 失败。
+- `saddle-framework` 不是精确 `=0.3.11`，或 [正式 Gate](validation.md) 失败。
 
 停止产物只包含最小复现、缺失身份和期望业务表达，不包含中间件替代实现。

package/references/database-name-mapping.md

@@ -1,8 +1,8 @@
 # 数据库名称映射
 
-业务源码只声明稳定的逻辑表、逻辑字段和静态 query/write/transaction 操作，不写部署环境中的物理库表名。生成的启动接线必须在唯一 `SaddleConfig` 上完成三件事：
+业务源码用公开 `saddle::database_operations!` 声明逻辑表、逻辑字段和静态 operation。正常 Cargo build 生成 typed operation、具名 Params/Row 及启动注册，不需要独立生成器、build.rs、SQL 或隐藏 trait。框架自动完成：
 
-1. 以 `database_name_mapping_directory(...)` 指向部署提供的映射目录；
+1. 从 saddle.toml 的 `[database].mappingDir` 读取部署映射目录；
 2. 注册应用实际使用的全部逻辑表；
 3. 注册应用实际使用的全部 query 与 write/transaction 操作。
 
@@ -11,3 +11,48 @@
 业务 Agent 不直接调用隐藏的注册 API；应由 Saddle 生成代码为声明过的静态表和操作生成接线。数据库关闭时不得声明映射目录或数据库操作。映射只改变部署名称，不改变业务类型、SQL 语义、事务边界或响应模型。
 
 本地和正式 Gate 至少覆盖：映射 query、映射 write、transaction commit、业务失败 rollback，以及缺失/漂移映射 fail-closed。任何路径不得把物理库表名暴露为业务配置或请求字段。
+
+## 最小公开声明
+
+```rust
+saddle::database_operations! {
+    pub mod ops {
+        table users { id: u64, value: u64 }
+        query_optional Read {
+            table users;
+            parameters ReadParams { id => id }
+            result ReadRow { value => value }
+        }
+        upsert Save {
+            table users;
+            parameters SaveParams { id => id, value => value }
+            key id;
+        }
+    }
+}
+```
+
+route 使用 `database query_optional read (ops::Read);` 或 `database write write (ops::Save);`。多个 route 可共享同一个 operation。静态 `transaction_commit` / `transaction_rollback` 也可引用 Save，不提供动态多步事务、嵌套或业务 commit/rollback。
+
+调用 `let (result, c) = c.read(ops::ReadParams { id }.into_parameters()).await;`。成功时 `ops::ReadRow::from_database(row)` 得到 `Option<ops::ReadRow>`；Some 字段直接读取，None 仅表示没有匹配行。剩余 c 可 typed 外呼但没有第二次 DB 方法，同请求 context/deadline 保持。完整工程见 [业务示例](business-example.md)。
+
+query_optional 固定 LIMIT 1，无 ORDER BY，不承诺多匹配行的选取顺序，不检测唯一性，也不限制服务器扫描工作。多行、nullable、String/Vec、浮点不是本版声明类型。
+
+| 声明 | 合法物理表示与值 | 拒绝 |
+| --- | --- | --- |
+| u64 | MariaDB整数或 DECIMAL(p,0)，0..18446744073709551615 | 负数、溢出、NULL、数字文本、BIT、浮点、小数编码 |
+| i64 | 整数或 DECIMAL(p,0)，-9223372036854775808..9223372036854775807 | 溢出、NULL、数字文本、BIT、浮点、小数编码 |
+| bool | 整数或 DECIMAL(p,0) 中的0/1，包括 BOOLEAN/TINYINT 的0/1 | 其他整数、NULL、BIT、文本 |
+| bytes<N> | 二进制/字符列查询值完整原字节，长度不超过N，具名字段为 FixedDbBytes<N>，用 as_slice() 读取 | 超长或NULL明确 db.invalid_column，不截断、不伪装None |
+
+CHAR 的服务器尾空格规则仍由数据库决定。非法结果须映射技术失败；不能伪造空成功。
+
+映射每表一个JSON。例如 users.json：
+
+```json
+{"table":{"from":"users","to":"app_users"},"columns":[{"from":"id","to":"user_id"},{"from":"value","to":"user_value"}]}
+```
+
+物理表由部署环境预先准备，Saddle 不执行 DDL/迁移。连接只通过 `[secrets].databaseUrlEnv` 引用环境变量，普通配置不由环境变量覆盖。
+
+已知 DB 参数、行、转换贡献从声明推导，以现有 memoryMb 计算可准入并发；不新增 DB memory、fieldBytes 或并发预算参数。不承诺全进程 RSS、driver/TLS、任意业务分配的绝对硬界。

package/references/external-function-contracts.md

@@ -15,7 +15,7 @@
 - `puc` 是业务单元，例如 `puc`。
 - `function` 是契约原始函数名，允许中文，例如 `查询用户绑定户号`。
 - protobuf method、Rust 方法和 Java 方法使用各语言合法的本地标识符；它们不是跨系统身份。
-- 0.3.9 不定义 contract version、多版本路由、翻译表、alias 或 fallback。
+- 0.3.11 不定义 contract version、多版本路由、翻译表、alias 或 fallback。
 
 ## 定义步骤
 
@@ -84,4 +84,4 @@ message BoundAccount {
 
 ## 变更规则
 
-先修改共同契约目录并重新通过双方 conformance，再修改两侧实现。禁止两侧各自维护近似定义后人工对齐；0.3.9 遇到不兼容变化时停止并共同升级，不在运行时并存或猜测版本。
+先修改共同契约目录并重新通过双方 conformance，再修改两侧实现。禁止两侧各自维护近似定义后人工对齐；0.3.11 遇到不兼容变化时停止并共同升级，不在运行时并存或猜测版本。