@antprofuse/saddle-skill 0.3.0-alpha.1 → 0.3.0-alpha.3

package/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: saddle-service-0-3
-description: 使用正式 Saddle 0.3.0-alpha.1 开发或审查带 profusegw 固定入口和 profusecontract 强类型外部函数调用的 Rust 业务应用。用于根据纯业务 spec 定义共同 protobuf 契约、编写固定 ProfuseGwContext handler、穷举技术失败，或运行正式业务门禁。
+description: 使用正式 Saddle 0.3.0-alpha.3 开发或审查带 profusegw 固定入口和 profusecontract 强类型外部函数调用的 Rust 业务应用。用于根据纯业务 spec 定义共同 protobuf 契约、编写固定 ProfuseGwContext handler、穷举技术失败，或运行正式业务门禁。
 ---
 
-# Saddle 0.3.0-alpha.1 业务研发契约
+# Saddle 0.3.0-alpha.3 业务研发契约
 
 业务 Agent 的直接输入只有业务 spec 与本 Skill。不要要求用户阅读 Saddle 仓库、审计报告、组件提交或内部实现。
 
 ## 必须按顺序执行
 
 1. 阅读 [消费者起手式](references/consumer-start.md)，只从业务 spec 提取接口、业务类型、业务规则、业务结果和外部业务能力。
-2. 每个外部能力先按 [外部函数协议](references/external-function-contracts.md) 定义双方共同的 `.proto`。冻结文件原始 bytes 与 SHA-256 后，才并行交给 Saddle 后端和 profusecontract 实现。
+2. 先按 [外部函数协议](references/external-function-contracts.md) 在唯一 `contract_dir` 根部生成固定 `saddle_external_function.proto`，再只把具体外部函数写入业务 `.proto`。冻结目录内容后，才并行交给 Saddle 后端和 profusecontract 实现。
 3. 按 [编程模型](references/programming-model.md) 声明应用、固定 profusegw operation、应用级强类型外部函数能力和唯一 handler。
 4. 对八类技术失败与三种执行确定性逐项给出业务 spec 明确允许的处理。禁止 wildcard/default、自动重试、默认业务成功或空结果。
 5. 按 [正式 Gate](references/validation.md) 生成 lock，并在交付前运行：
@@ -27,7 +27,7 @@ description: 使用正式 Saddle 0.3.0-alpha.1 开发或审查带 profusegw 固
 
 ```toml
 [dependencies]
-saddle-framework = "=0.3.0-alpha.1"
+saddle-framework = "=0.3.0-alpha.3"
 ```
 
 `saddle-framework` 是唯一业务 facade。业务不得直接依赖 `saddle-core`、`saddle-admission`、`saddle-boundary`、`saddle-db`、`saddle-macros`、`saddle-observability`、`saddle-runtime` 或 `saddle-service`。
@@ -36,19 +36,24 @@ saddle-framework = "=0.3.0-alpha.1"
 
 - Saddle 编译进业务应用，不是独立服务、进程或控制面。
 - profusegw 唯一入口是 `POST /saddle/v1/ingress/profusegw/invoke`；不得手写 listener、HTTP handler 或第二路由。
-- 所有 handler 使用 `saddle::ingress::ProfuseGwContext`；alpha.1 只读取只读、有界的 `user_id`，不得读取 Header、Cookie、原始 JSON 或任意上下文 Map。
-- 外部函数由共同 `.proto` 的 `(business_unit, function)` 精确定位。中文 `function` 逐字保留，不翻译、不 alias、不 fallback、不动态选择。
+- 所有 handler 使用 `saddle::ingress::ProfuseGwContext`；只读取正式 API 提供的只读、有界字段，不得读取 Header、Cookie、原始 JSON 或任意上下文 Map。
+- 应用只配置一个 `contract_dir`。Saddle 在编译期确定性递归扫描其中的 `.proto`、闭合 import，并按 canonical 相对路径形成身份；不得列 proto 文件清单、维护聚合 proto，或在运行时扫描目录。
+- 将 [固定协议模板](assets/saddle_external_function.proto) 原样写为 `${contract_dir}/saddle_external_function.proto`。不得改名、改内容、增加版本副本或另建 protocol 目录。
+- 具体外部函数只写在业务 proto，并使用 `import "saddle_external_function.proto";`。profusecontract 直接消费整个 `contract_dir`，无需安装 Saddle。
+- 只有带正式 `external_function` method option 的 RPC 进入外部函数索引；普通 RPC 与纯消息 proto 可以存在于同一目录，不得被误判为外部函数。
+- 外部函数由共同 `.proto` option 的 `(puc, function)` 精确定位；应用 DSL 的 `business_unit` 必须逐字等于 option 的 `puc`。中文 `function` 逐字保留，不翻译、不 alias、不 fallback、不动态选择。
+- `functions` 只声明应用实际调用的外部函数，每项必须被至少一个 service 的 `uses` 引用；不得登记未使用能力。
 - 业务只使用生成的应用级强类型 capability，不接触 channel、stub、裸 protobuf bytes、动态函数名或通用依赖容器。
 - 不支持 contract 多版本路由、`Any`、开放 Map、任意 JSON、streaming、cancel 或框架自动业务重试。
 - 不创建线程、第二 Runtime、后台 task、裸 DB/网络 I/O、日志 subscriber 或第二执行面。
 
 ## 立即停止
 
-- 双方没有同一份已冻结 `.proto`，或 descriptor 摘要不同；
-- method option 缺少逐字 `business_unit + function`；
+- 双方没有同一份已冻结契约目录，或 descriptor 摘要不同；
+- method option 缺少逐字 `puc + function`，或 DSL `business_unit` 与 `puc` 不同；
 - 请求、结果、字符串、bytes、集合或嵌套对象没有业务静态上限；
 - 需要动态 function/descriptor、raw invoke、裸 gRPC、原始网络上下文或未声明外部 I/O；
 - 八类技术失败或三种执行确定性未显式处理；
-- Cargo 不是精确 alpha.1 facade、缺 lock，或正式 Gate 不通过。
+- Cargo 不是精确 alpha.3 facade、缺 lock，或正式 Gate 不通过。
 
 停止时只交最小复现和期望业务表达，由 Saddle 修复公共能力缺口。

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.0-alpha.1 Skill（npm install --save-exact --ignore-scripts --no-audit --no-fund @antprofuse/saddle-skill@0.3.0-alpha.1），结合业务 spec 开始研发。"
+  default_prompt: "请安装 Saddle 0.3.0-alpha.3 Skill（npm install --save-exact --ignore-scripts --no-audit --no-fund @antprofuse/saddle-skill@0.3.0-alpha.3），结合业务 spec 开始研发。"

package/assets/example-contracts/puc_external_functions.proto

@@ -0,0 +1,26 @@
+syntax = "proto3";
+
+package puc;
+
+import "saddle_external_function.proto";
+
+service PucExternalFunctions {
+  rpc QueryBoundAccounts(QueryBoundAccountsRequest) returns (QueryBoundAccountsResult) {
+    option (saddle.profusecontract.external_function) = {
+      puc: "puc"
+      function: "查询用户绑定户号"
+    };
+  }
+}
+
+message QueryBoundAccountsRequest {
+  string user_id = 1;
+}
+
+message QueryBoundAccountsResult {
+  repeated BoundAccount accounts = 1;
+}
+
+message BoundAccount {
+  string account_id = 1;
+}

package/assets/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/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@antprofuse/saddle-skill",
-  "version": "0.3.0-alpha.1",
-  "description": "Saddle 0.3.0-alpha.1 中文 AI Coding 研发契约与业务门禁。",
+  "version": "0.3.0-alpha.3",
+  "description": "Saddle 0.3.0-alpha.3 中文 AI Coding 研发契约与业务门禁。",
   "license": "MIT OR Apache-2.0",
-  "files": ["SKILL.md", "agents", "references", "scripts"],
+  "files": ["SKILL.md", "agents", "references", "scripts", "assets"],
   "bin": {"saddle-03-gate": "scripts/saddle-03-gate.js"},
   "publishConfig": {"access": "public", "registry": "https://registry.npmjs.org/"}
 }

package/references/consumer-start.md

@@ -2,7 +2,7 @@
 
 ## 目标
 
-从纯业务 spec 形成可供 Saddle 后端与 profusecontract 并行消费的同一份外部函数契约和可编译业务 consumer。
+从纯业务 spec 形成可供 Saddle 后端与 profusecontract 并行消费的同一棵外部函数契约目录和可编译业务 consumer。
 
 ## 阶段 0：核对输入
 
@@ -18,43 +18,48 @@
 
 任一项缺失时停止，不进入实现。
 
-## 阶段 1：先冻结共同 `.proto`
+## 阶段 1：先冻结共同契约目录
 
-按 [外部函数契约](external-function-contracts.md) 为每个能力定义 rpc 与 method option。`function` 必须保留业务契约中的中文原名，例如：
+建立唯一 `contract_dir`。先把 Skill 的固定模板 `../assets/saddle_external_function.proto` 原样写到目录根部，目标路径必须是 `${contract_dir}/saddle_external_function.proto`；再按 [外部函数契约](external-function-contracts.md) 为每个能力定义业务 rpc 与 method option。`function` 必须保留业务契约中的中文原名，例如：
 
 ```protobuf
 option (saddle.profusecontract.external_function) = {
-  business_unit: "puc"
+  puc: "puc"
   function: "查询用户绑定户号"
 };
 ```
 
-冻结一个 canonical 文件，记录其原始 bytes SHA-256。Saddle 后端与 profusecontract 必须消费同一路径或同摘要副本；不得维护两份“等价”定义。
+冻结同一目录树。Saddle 后端与 profusecontract 必须消费同源目录或同摘要副本；不得维护两份“等价”定义，也不得另建 proto 聚合文件或手工文件清单。
 
-必须 import `saddle/profusecontract/external_function.proto` 并使用其 `external_function` method option；不得自建同名 extension。
+Saddle 在编译期从 `contract_dir` 确定性递归收集 `.proto`，闭合 import，并按 canonical 相对路径排序。目录扫描不是运行时发现机制，业务不得据此动态选择函数。
+
+每个使用外部函数 option 的业务 proto 必须 `import "saddle_external_function.proto";` 并使用其中的 `external_function` method option；不得自建同名 extension。可直接参考 `../assets/example-contracts/puc_external_functions.proto`。
 
 ## 阶段 2：同源并行交接
 
 共同 `.proto` 冻结后才创建两个互不改写契约的工作项：
 
-1. **Saddle 后端**：准备 operation、contract、允许函数、固定 `ProfuseGwContext` handler 和技术失败决策；只有阶段 3 身份门禁通过后才写真实 Rust 实现。
-2. **profusecontract**：按同一 `(business_unit, function)` 实现 Java/SOFA 防腐与同 descriptor conformance。
+1. **Saddle 后端**：准备 operation、唯一 `contract_dir`、实际使用的函数、固定 `ProfuseGwContext` handler 和技术失败决策；只有阶段 3 身份门禁通过后才写真实 Rust 实现。
+2. **profusecontract**：直接消费整个 `contract_dir`，按同一 `(puc, function)` 实现 Java/SOFA 防腐与同 descriptor conformance；不要求安装 Saddle。
 
-两项交接必须携带相同的 proto bytes SHA-256。任何契约变化先合回 canonical `.proto`，重新冻结后同时通知两侧。
+两项交接必须携带相同的契约树身份。任何契约变化先合回共同目录，重新冻结后同时通知两侧。
 
 ## 阶段 3：Rust 实现
 
-业务 crate 精确使用 `saddle-framework = "=0.3.0-alpha.1"`，然后按 [最小编程模型](programming-model.md) 编写声明和 handler。不得直接依赖任何 Saddle 中间件 crate。
+业务 crate 精确使用 `saddle-framework = "=0.3.0-alpha.3"`，然后按 [最小编程模型](programming-model.md) 编写声明和 handler。不得直接依赖任何 Saddle 中间件 crate。
 
 ## 阶段 4：闭合前停止条件
 
 以下任一情况立即 STOP：
 
-- 两侧 proto bytes 或 `(business_unit, function)` 不同；
+- 两侧契约树或 `(puc, function)` 不同；
+- 应用声明单个 proto 路径、proto 文件清单、聚合 proto，或把递归扫描当成运行时发现；
+- 目录根缺少固定 `saddle_external_function.proto`，模板 bytes 被修改，业务 proto 未按固定文件名 import，或出现第二份协议定义；
+- `functions` 声明了没有被 service `uses` 的能力；
 - 中文 `function` 被翻译、alias、fallback 或动态选择；
 - handler 不使用唯一固定 `ProfuseGwContext`，或读取原始网络上下文；
 - 技术失败码或执行确定性存在 catch-all/default；
 - 需要裸 gRPC/channel/bytes、第二入口、动态 descriptor 或未声明外部 I/O；
-- `saddle-framework` 不是精确 `=0.3.0-alpha.1`，或 [正式 Gate](validation.md) 失败。
+- `saddle-framework` 不是精确 `=0.3.0-alpha.3`，或 [正式 Gate](validation.md) 失败。
 
 停止产物只包含最小复现、缺失身份和期望业务表达，不包含中间件替代实现。

package/references/external-function-contracts.md

@@ -9,24 +9,27 @@
 外部函数只由以下二元组定位：
 
 ```text
-(businessUnit, function)
+(puc, function)
 ```
 
-- `businessUnit` 是业务单元，例如 `puc`。
+- `puc` 是业务单元，例如 `puc`。
 - `function` 是契约原始函数名，允许中文，例如 `查询用户绑定户号`。
 - protobuf method、Rust 方法和 Java 方法使用各语言合法的本地标识符；它们不是跨系统身份。
 - 0.3.0 不定义 contract version、多版本路由、翻译表、alias 或 fallback。
 
 ## 定义步骤
 
-1. 从业务 spec 识别外部业务能力，不复制 SOFA service、method 或传输模型。
-2. 为每个能力定义具名 protobuf request 和 result。
-3. 使用 Saddle 提供的 `google.protobuf.MethodOptions` extension，把 rpc 方法绑定到 `businessUnit + function`。
-4. 把同一份 `.proto` 交给 Saddle 业务 Agent 和 profusecontract Agent。
-5. Saddle 侧显式引用契约并登记允许调用的函数；profusecontract 侧实现对应函数和防腐映射。
-6. 双方以同一 descriptor 运行 conformance fixture 后再联调。
+1. 在 `contract_dir` 根部原样生成 Skill 资产 `../assets/saddle_external_function.proto`，文件名绝对固定。
+2. 从业务 spec 识别外部业务能力，不复制 SOFA service、method 或传输模型。
+3. 为每个能力在业务 proto 中定义具名 protobuf request 和 result，并 import 根部的 `saddle_external_function.proto`。
+4. 使用固定文件提供的 `google.protobuf.MethodOptions` extension，把 rpc 方法绑定到 `puc + function`。
+5. 把同一棵 `contract_dir` 契约树交给 Saddle 业务 Agent 和 profusecontract Agent。
+6. Saddle 侧配置契约根目录，并只登记业务实际调用的函数；profusecontract 直接消费整个目录，实现对应函数和防腐映射，无需安装 Saddle。
+7. 双方以同一 descriptor 运行 conformance fixture 后再联调。
 
-第 4 步是并行研发的起点，不是第 1 步。交接时至少记录 `.proto` 相对路径、原始 bytes SHA-256、package、service、rpc、`business_unit` 和中文 `function`。任一方改动契约都必须回到共同冻结步骤，不能在各自分支继续演化。
+第 5 步是并行研发的起点，不是第 1 步。契约目录本身是唯一真源：不另写 proto 文件清单或聚合文件。固定协议文件不是第二真源，而是同一目录必须包含的根文件；不得创建独立 protocol 目录、版本副本或 manifest。任一方改动业务契约都必须回到共同冻结步骤，不能在各自分支继续演化。
+
+Saddle 编译期递归扫描目录、闭合 import 并按 canonical 相对路径排序。只有带本页正式 method option 的 RPC 进入索引；普通 RPC 与纯消息文件只参与 descriptor/import 闭包，不成为可调用外部函数。
 
 ## 模板
 
@@ -35,7 +38,7 @@ syntax = "proto3";
 
 package puc;
 
-import "saddle/profusecontract/external_function.proto";
+import "saddle_external_function.proto";
 
 service PucExternalFunctions {
   rpc QueryBoundAccounts(
@@ -44,7 +47,7 @@ service PucExternalFunctions {
     QueryBoundAccountsResult
   ) {
     option (saddle.profusecontract.external_function) = {
-      business_unit: "puc"
+      puc: "puc"
       function: "查询用户绑定户号"
     };
   }
@@ -65,7 +68,7 @@ message BoundAccount {
 
 这里的跨系统正式身份是 `("puc", "查询用户绑定户号")`。`QueryBoundAccounts`、未来生成的 Rust 方法名和 Java 方法名都只是本地代码标识符，不能替换、翻译或推导中文 `function`。
 
-该 import 与 method option 属于 Saddle `0.3.0-alpha.1` 固定协议。不得自行创建同名 extension，也不得复制为另一份协议。
+该 import 必须精确指向同目录根部的 `saddle_external_function.proto`。其 bytes 来自 Saddle `0.3.0-alpha.3` 的权威模板并由 Skill 固定携带；不得自行创建同名 extension，也不得复制为另一份协议。
 
 实际线上网络仍只调用 Saddle 固定 `ProfuseContractBoundary/Invoke` unary。契约中的 service/rpc 用于绑定身份、request 和 result，不要求 profusecontract 暴露同名网络方法。
 
@@ -79,4 +82,4 @@ message BoundAccount {
 
 ## 变更规则
 
-先修改共同 `.proto` 并重新通过双方 conformance，再修改两侧实现。禁止两侧各自维护近似定义后人工对齐；0.3.0 遇到不兼容变化时停止并共同升级，不在运行时并存或猜测版本。
+先修改共同契约目录并重新通过双方 conformance，再修改两侧实现。禁止两侧各自维护近似定义后人工对齐；0.3.0 遇到不兼容变化时停止并共同升级，不在运行时并存或猜测版本。

package/references/programming-model.md

@@ -2,7 +2,7 @@
 
 ## 应用显式声明
 
-业务应用使用 `saddle-framework = "=0.3.0-alpha.1"` 的公开编程面：
+业务应用使用 `saddle-framework = "=0.3.0-alpha.3"` 的公开编程面：
 
 ```rust
 saddle::application! {
@@ -10,7 +10,7 @@ saddle::application! {
     application PucBackend;
 
     profusecontract {
-        contract "contracts/puc-external-functions.proto";
+        contract_dir "contracts";
         capability PucProfuseContract;
         functions {
             QueryBoundAccounts => query_bound_accounts {
@@ -33,7 +33,11 @@ saddle::application! {
 }
 ```
 
-这是业务实现显式写出的静态事实。Saddle 不从 spec 自动选择 contract、function 或调用边，也不允许运行时动态修改。
+这是业务实现显式写出的静态事实。`contract_dir` 是唯一 proto 真源；不要再列文件清单或维护聚合 proto。Saddle 只在编译期确定性递归扫描、闭合 import 并建立 option-only 索引，不在运行时发现函数。
+
+`functions` 只写当前应用实际使用的外部函数。每项必须由至少一个 service 的 `uses` 引用；普通 RPC、纯消息 proto 和未带正式 method option 的 RPC 不写入 `functions`。
+
+业务 proto option 使用字段 `puc`；应用 DSL 使用 `business_unit`。两者必须逐字相等，均不允许翻译、alias 或 fallback。
 
 ## Handler
 

package/references/validation.md

@@ -1,4 +1,4 @@
-# Saddle 0.3.0-alpha.1 正式业务 Gate
+# Saddle 0.3.0-alpha.3 正式业务 Gate
 
 ## 依赖与锁
 
@@ -9,10 +9,10 @@
 name = "my-saddle-app"
 version = "0.1.0"
 edition = "2024"
-rust-version = "1.85"
+rust-version = "1.95"
 
 [dependencies]
-saddle-framework = "=0.3.0-alpha.1"
+saddle-framework = "=0.3.0-alpha.3"
 ```
 
 在允许访问正式 registry 的依赖准备阶段生成并提交 `Cargo.lock`。禁止 `path`、`git`、`[patch]`、source replacement 或宽松 Saddle 版本。
@@ -25,12 +25,15 @@ saddle-framework = "=0.3.0-alpha.1"
 npx --no-install saddle-03-gate --manifest-path Cargo.toml
 ```
 
-命令由已安装的 `@antprofuse/saddle-skill@0.3.0-alpha.1` 提供，不需要 Saddle 源码仓库。它会检查：
+命令由已安装的 `@antprofuse/saddle-skill@0.3.0-alpha.3` 提供，不需要 Saddle 源码仓库。它会检查：
 
 - facade 精确版本、禁止直接中间件依赖和 Cargo source 旁路；
 - `Cargo.lock` 同版映射；
+- 唯一 `contract_dir`、目录存在、禁止旧单文件 contract 声明；
+- 目录根部 `saddle_external_function.proto` 与 Skill 权威模板逐字一致且仅出现一次，使用 option 的业务 proto 必须 direct import 根文件；
+- 编译期递归扫描/import 闭包、option-only 索引、身份唯一、请求结果类型匹配，以及所有 function 均有实际 `uses`；
 - 固定 `ProfuseGwContext`、应用声明、八类技术失败与三种 certainty 均被显式引用；
 - 无 wildcard/default、第二 listener/Runtime、裸 gRPC/HTTP、动态函数或 raw invoke；
-- Rust 1.85 下 `cargo check --locked --offline`。
+- Rust 1.95 下 `cargo check --locked --offline`。
 
 Gate 使用临时 target 并在成功、失败和信号退出时清理。任何失败均为 STOP；不得加跳过参数或改 Gate 脚本。

package/scripts/saddle-03-gate.js

@@ -5,6 +5,7 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const cp = require("child_process");
+const canonicalSchema = fs.readFileSync(path.resolve(__dirname, "../assets/saddle_external_function.proto"));
 
 function stop(rule, detail) {
   process.stderr.write(`SADDLE_03_GATE ${rule} ${detail}\n`);
@@ -29,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\.0-alpha\.1"\s*(?:#.*)?$/.test(facade[1].trim())) {
-  stop("SADDLE_VERSION", '必须直接且精确依赖 saddle-framework = "=0.3.0-alpha.1"');
+if (!facade || !/^"=0\.3\.0-alpha\.3"\s*(?:#.*)?$/.test(facade[1].trim())) {
+  stop("SADDLE_VERSION", '必须直接且精确依赖 saddle-framework = "=0.3.0-alpha.3"');
 }
 const internals = ["saddle-core","saddle-admission","saddle-boundary","saddle-db","saddle-macros","saddle-observability","saddle-runtime","saddle-service"];
 for (const name of internals) {
@@ -40,8 +41,8 @@ if (!fs.existsSync(lockPath)) {
   stop("LOCK", "缺少 Cargo.lock");
 } else {
   const lock = fs.readFileSync(lockPath, "utf8");
-  if (!/name = "saddle-framework"\nversion = "0\.3\.0-alpha\.1"/.test(lock)) {
-    stop("LOCK", "Cargo.lock 未绑定 saddle-framework 0.3.0-alpha.1");
+  if (!/name = "saddle-framework"\nversion = "0\.3\.0-alpha\.3"/.test(lock)) {
+    stop("LOCK", "Cargo.lock 未绑定 saddle-framework 0.3.0-alpha.3");
   }
 }
 
@@ -58,6 +59,45 @@ visit(sourceRoot);
 const source = files.map(p => fs.readFileSync(p, "utf8")).join("\n");
 if (!source.includes("application!")) stop("APPLICATION", "缺少 Saddle application! 声明");
 if (!source.includes("ProfuseGwContext")) stop("CONTEXT", "handler 必须使用固定 ProfuseGwContext");
+const contractDirs = [...source.matchAll(/\bcontract_dir\s+"([^"]+)"\s*;/g)];
+if (contractDirs.length !== 1) stop("CONTRACT_DIR", "必须且只能声明一个 contract_dir");
+if (/\bcontract\s+"[^"]+"\s*;/.test(source)) stop("CONTRACT_DIR", "禁止旧单 proto contract 声明");
+if (contractDirs.length === 1) {
+  const value = contractDirs[0][1];
+  if (path.isAbsolute(value) || value.split(/[\\/]+/).includes("..")) {
+    stop("CONTRACT_DIR", "contract_dir 必须是 crate 内无逃逸的相对路径");
+  } else {
+    const dir = path.resolve(root, value);
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+      stop("CONTRACT_DIR", `目录不存在: ${value}`);
+    } else {
+      const rootSchema = path.join(dir, "saddle_external_function.proto");
+      if (!fs.existsSync(rootSchema) || !fs.readFileSync(rootSchema).equals(canonicalSchema)) {
+        stop("CONTRACT_SCHEMA", "contract_dir 根部固定协议缺失或与 Skill 权威模板不一致");
+      }
+      const protos = [];
+      function visitContracts(current) {
+        for (const ent of fs.readdirSync(current, {withFileTypes: true})) {
+          const p = path.join(current, ent.name);
+          if (ent.isDirectory()) visitContracts(p);
+          else if (ent.isFile() && p.endsWith(".proto")) protos.push(p);
+        }
+      }
+      visitContracts(dir);
+      if (protos.filter(p => path.basename(p) === "saddle_external_function.proto").length !== 1) {
+        stop("CONTRACT_SCHEMA", "固定协议必须且只能位于 contract_dir 根部");
+      }
+      for (const proto of protos) {
+        if (proto === rootSchema) continue;
+        const body = fs.readFileSync(proto, "utf8");
+        if (body.includes("saddle.profusecontract.external_function") &&
+            !/^\s*import\s+"saddle_external_function\.proto"\s*;/m.test(body)) {
+          stop("CONTRACT_IMPORT", `${path.relative(dir, proto)} 必须 direct import 根部固定协议`);
+        }
+      }
+    }
+  }
+}
 for (const code of ["FunctionNotFound","FunctionRequestInvalid","CapacityRejected","DeadlineExceeded","DependencyUnavailable","ContractResultInvalid","InternalFailure","TransportFailure"]) {
   if (!source.includes(code)) stop("TECHNICAL_FAILURE", `缺少显式分支 ${code}`);
 }
@@ -75,10 +115,10 @@ if (process.exitCode) process.exit(process.exitCode);
 const target = fs.mkdtempSync(path.join(os.tmpdir(), "saddle-03-gate-"));
 try {
   const env = {...process.env, CARGO_TARGET_DIR: target, CARGO_NET_OFFLINE: "true"};
-  const result = cp.spawnSync("cargo", ["+1.85.0", "check", "--manifest-path", manifest, "--locked", "--offline"], {env, stdio: "inherit"});
-  if (result.error || result.status !== 0) stop("COMPILER", "Rust 1.85 locked/offline 编译失败");
+  const result = cp.spawnSync("cargo", ["+1.95.0", "check", "--manifest-path", manifest, "--locked", "--offline"], {env, stdio: "inherit"});
+  if (result.error || result.status !== 0) stop("COMPILER", "Rust 1.95 locked/offline 编译失败");
 } finally {
   fs.rmSync(target, {recursive: true, force: true});
 }
 if (process.exitCode) process.exit(process.exitCode);
-process.stdout.write("SADDLE_03_GATE PASS; VERSION=0.3.0-alpha.1; LOCKED_OFFLINE; BUSINESS_BOUNDARIES=CLOSED\n");
+process.stdout.write("SADDLE_03_GATE PASS; VERSION=0.3.0-alpha.3; LOCKED_OFFLINE; BUSINESS_BOUNDARIES=CLOSED\n");