@antprofuse/saddle-islands-design 0.1.24 → 0.1.28

package/SKILL.md

@@ -1,60 +1,50 @@
 ---
 name: saddle-islands-design
-description: 消费 Islands Spec 与自洽 adapt，设计后端契约、逻辑数据库表及 Saddle与profusecontract的external-contract-proto，可独立或联合设计并审查边界一致性。不猜填适配逻辑，不实现业务代码或部署。
+description: 消费Islands Spec、视觉、正式physical绑定和上游生成协议，设计客户端与后端契约与必要数据库结构，审查字段来源、身份和跨层一致性。不设计替代的外部协议，不实现产品或部署。
 ---
 
-# Saddle Islands 设计
+# Saddle–Islands 工程设计
 
-先完整阅读本轮冻结的 saddle-workflow 及本 Skill 原始包。按 workflow 的传播规则消费已提交并推送的 Git 包，核仓库、完整 commit、版本和逐文件摘要；同批保持一致，运行中不静默替换。npm 仅作发布备份，不要求安装 latest 或等待 registry。缺失正文或引用文件须修复交接，不能凭版本号相同认定内容一致。
+## 阶段职责
 
-当项目明确由上游Spec工具生成既有gRPC协议时，该协议是只读输入；本Skill只设计前后端契约与DB，不另建业务proto、不添加Saddle专有option。协议缺口回报上游，Java实现与部署不纳入范围。下述external-contract-proto模块仅适用于用户明确委托本阶段设计外部协议的项目。
+输入是本轮指定并冻结的Spec、视觉、正式physical绑定、相关Islands指南与上游生成协议。输出是有来源依据的客户端与后端契约、必要逻辑表结构和具体交接边界。普通实现代码未完成不阻塞设计；输入语义缺失不能由设计者猜填。
 
-Spec定义抽象业务；适配输入可以是项目指定的独立adapt，也可以是当前Islands正式physical绑定。本Skill按实际输入模式消费自洽的业务与适配语义，产出后端契约、DB和external-contract-proto，不要求迁回旧目录形状。不能让业务Spec为工具格式增加技术字段。后端聚合契约与外部能力契约不是一一对应；适配语义须先确定，但profusecontract实现代码不是设计前置。
+执行前读取本轮冻结的workflow和本Skill，核对版本、来源及引用文件。单Agent兼任多个阶段也遵守同一交接规则；测试建设和产品实现分别消费设计，不在此阶段生成覆盖率或宣称验收通过。
 
-## 选择模块
+## 模块与工具
 
-按用户范围执行，不捆绑未要求的设计或实现。所有模式先完整阅读[adapt输入与身份规则](references/adapt.md)，再读所选模块：
+完整阅读[正式输入与身份边界](<references/formal-inputs.md>)，再按实际范围选择模块，不捆绑无关设计：
 
-| 任务 | 执行前完整阅读 | 交付 |
-| --- | --- | --- |
-| 后端契约 | [设计流程](modules/backend-contract/design.md)、[格式](modules/backend-contract/references/backend-contract.md) | `*.backend-contract.yaml` |
-| DB | [设计流程](modules/db/design.md)、[表格式](modules/db/references/db-table-v1.md) | `*.table.yaml` |
-| external-contract-proto | [外部协议设计](modules/external-contract-proto/design.md)、[运行时边界](modules/external-contract-proto/references/runtime.md) | 共同消费的业务 `.proto` |
-| 联合设计 | 所选模块的完整参考 | 独立交付，做跨层复核 |
+| 工作 | 完整阅读 | 交付 |
+|---|---|---|
+| 客户端与后端契约 | [设计流程](<modules/backend-contract/design.md>)、[格式](<modules/backend-contract/references/backend-contract.md>) | *.backend-contract.yaml |
+| 逻辑数据库 | [设计流程](<modules/db/design.md>)、[表格式](<modules/db/references/db-table-v1.md>) | *.table.yaml |
 
-有来源问题时读对应模块findings参考；模板在模块assets。一个Skill、一个版本，模块不是另一个安装包。
+语义身份使用独立工具集的公开`identity generate/register/check`入口及随附说明，生成和登记而不手写摘要。当前没有完整设计自动校验器；人工来源审查不能冒充工具验证。模板由模块链接，独立Skill分发包含引用闭包，不包含工具实现。
 
-## 输入与协作
+## 输入到设计
 
-- 明确Spec仓库与目录、adapt位置、交付仓库与目录，仓库和目录分别记录；上下文已明确的不重复询问。adapt通常与spec、code同级，但必须检查实际存在，不猜内容。Spec、adapt都属于输入；缺失声明不能由设计Agent默认生成。
-- 后端契约另需完整业务前缀；DB不需要。默认交付code/backend-contract、code/db、code/external-contract-proto，与backend并列，以用户指定为准。外部协议还需目标Saddle协议版本及业务单元实际值，已有输入足够时不重复询问，不从MobileGW前缀猜业务单元。不要求先提供生成代码或SOFA物理合同替代adapt。
-- 项目Spec、adapt及契约关联一律解析当前仓库当前分支，不切换到远程默认分支或历史提交，不生成仓库地址、分支或提交号的来源元数据。Islands理念参考仍可读取其官方指南；这不是项目契约跨仓库关联。
-- 通读所选范围的Spec、adapt及相关Islands指南，检查Prototype与测试责任。元数据不可用时可做来源有据的推演，不能虚报编译、覆盖或测试通过。
-- 所选范围的adapt语义自洽后进入正式设计。缺失身份、取数能力、字段形状或业务结果语义时退回讨论，不由本Skill补齐。普通代码尚未实现不是阻塞；用户另行授权的局部草稿不宣称整体交付完成。
-- 普通消费Agent发现规范缺口应反馈维护者，不私造规则；获得Skill维护授权的设计者先给出合理设计供确认，再修通用规则，不把旧Skill能力当业务限制。
-- Findings只记录Spec业务缺失或矛盾；adapt待定项、规范缺口、消费者迁移问题分别说明，不倒逼Spec改成物理流程。
-- 交付目录仅放有效契约，不放过程记录、检查脚本或findings。用户授权替换时清掉本范围旧设计文件，不并存冲突真源；不越权删除实现代码，也不宣称消费者自动兼容。
-- 提交、推送、发布按用户各仓库授权执行；Spec默认先展示diff tree确认。维护权不等于每次任务自动有发布权，不向其他workspace自行派单。
-- 使用的包名和版本要明确；起手消息模板不自动改写。
+这是可重入的设计迭代：从指定分支当前设计出发，核对正式输入，保留有效设计并补齐、修订或清理失效设计；没有现成设计时再创建，不因重入默认重建。仓内契约、逻辑表和身份登记按本Skill读取与交付，无需任务逐项标注“已有”。
 
-## 联合复核
+明确本轮仓库、输入根、源版本和交付目录；已有明确上下文不重复询问。来源path按输入仓库根解析，同一设计使用同一冻结来源，不偷偷改用远端最新分支。版本快照保存在项目交接中，不向业务身份增添Git字段。
 
-后端契约以Prototype+测试要求确定范围，实体与adapt用于解释字段和边界；DB以adapt明确承载责任确定表集合，不从响应反向建表。
+后端契约从正式页面动作与结果消费确定边界，按业务连续性聚合；不按实体或外部接口数量拆分。DB从正式来源与持久化责任确定表集合，不从页面响应反向建表。
 
-共同核对完整实体属性（Spec+adapt扩展）、实例归属、身份方式、金额单位和可空性。业务字段长度缺失须记录，不能把DB列长或运行时容量当作补齐了业务规则；类型和语义已明确时，技术容量在实现阶段统一确定，不前置为全部契约设计的阻塞条件。关联跟随目标身份，不能统一假设uid。DB宽松存储约束不能放宽后端契约成功结果；后端结果投影不要求复制全部数据库列。
+核对Spec属性与physical扩展、实例归属、真实身份、金额单位、可空性和错误语义。缺少业务长度不能用DB容量伪装成业务规则；类型语义明确时，技术容量按已批准规范处理，不阻断全部设计。来源中TODO仍决定字段、取数依据、结果或存储结构时，反馈影响范围，授权局部草稿也不称整体完成。
 
-external-contract-proto覆盖adapt明确交给profusecontract的Dependency及external-contract，字段类型引用应解析为具体传输字段；不能因为类型相同就猜某个实例的值。正常调用与组装由backend研发依据业务和绑定完成，不要求额外编排配置。跨层核对空值、精度、单位和失败语义，不把前端JSON信封复制到外部函数result。
+上游生成的gRPC协议是只读输入。核原始Service/Method、请求结果及调用边界，不设计另一份proto、不添加框架专有option，不承担Java/SOFA实现。真实协议缺口反馈上游；普通调用组装属于后端研发，不要求额外编排设计。
 
-三类设计完成不等于实现、测试或生产链路完成。不从TODO发明加载、同步或对外调用；不修改profusecontract后面不可控的SOFA协议。
+## 交付与反馈
 
-## 交给测试与实现
+向测试和产品交付完整调用点、字段/错误合同、来源责任、必要存储以及上游协议引用。客户端与后端可分别接入测试、研发和交付；真实下游未部署不自动阻止按确定协议做Mock验收。
 
-设计交接应让下游独立得到：当前调用点和物理输入、完整结果/错误合同、来源责任、外部能力协议、持久化结构，以及尚未完成事项所影响的具体边界。真实 SOFA 或 Java 实现尚未完成不自动阻塞前端契约 Mock、后端 Invoke Mock 测试；只有影响当前协议或预期的未定语义才阻塞对应场景。
+后端测试另建设隔离数据库、DDL、物理名映射、seed和启动接入，这些不进入逻辑表设计。客户端测试按当前正式责任树覆盖页面行为，不按设计文件数推导覆盖。
 
-前端测试消费 Spec/Prototype、adapt、backend-contract；后端测试还消费 DB 与 external-contract-proto。两者根据当前 Islands 正式责任清单分别落实可观察义务，不按设计文件数量反推覆盖。数据库实例、DDL、测试物理名映射、seed 和启动接入由测试建设承担，不塞入 `code/db/`，也不留给产品研发补测试 adapter。
+交付目录只存有效契约；findings和过程诊断留项目指定位置。仅真实源语义缺失/矛盾归源问题，工具/规范/消费问题各归责任方。更新授权范围内清理失效设计，不能自动改所有消费者。提交推送按各仓库授权执行，本库master规则不扩展到业务仓。
 
-共享协议是唯一真源，但“一致性审查”不授权修改所有消费者。只迁移本次获授权的设计或实现目录，其他消费者差异单独报告；Mock 验收与真实下游兼容验收分别记录。删除 backend 内旧协议副本，不等于需要同步编写 Java 适配实现。
+本Skill只维护上述两个设计模块；不恢复独立adapt或人工外部适配研发阶段。规范缺口反馈体系维护者，不私造规则，也不把旧工具限制当业务限制。
 
-## 维护边界
 
-当前三个模块为后端契约、DB、external-contract-proto；独立adapt设计由并列的saddle-islands-adapt负责；已在当前Islands physical中表达的输入按其正式语义消费，不再制造第二套adapt。版本只递增最末位0.1.x的patch，未经明确要求不升前两位。保持已批准约定，不把单个案例固化成通用设计；保留包外未批准草稿。
+## 统一交付门禁
+
+交付前必须使用本轮指定的公开工具入口执行交付门禁；门禁未通过，不得作成功交付。保留实际结果到本地任务信息目录，失败按责任修复后重新执行。具体检查项及参数由冻结工具版本提供，见 `tools/docs/iteration.md`，任务不重复列举或自行裁剪检查项。

package/modules/backend-contract/design.md

@@ -1,23 +1,23 @@
 # 后端契约设计
 
-消费Spec+adapt，产出后端向前端提供的独立契约。先读共用adapt规则，再完整阅读[格式](references/backend-contract.md)。来源有问题时读[findings](references/findings.md)。
+消费Spec与正式physical输入，产出后端向客户端提供的独立契约。先读共用正式输入规则，再完整阅读[格式](<references/backend-contract.md>)。来源有问题时读[findings](<references/findings.md>)。
 
 ## 推演顺序
 
 1. 核对指定 Spec/Prototype 的交互、展示与结果需求。覆盖分母和链路算法由后续测试阶段产出，不在契约设计阶段提前生成。Spec其他内容用于解释实体与业务，不据此扩展接口范围；不要求Spec预先声明物理服务接口。
-2. 先读取 本轮冻结的 saddle-workflow 原始包 的语义身份规范，用公共工具生成并登记 identity/id，证明唯一页面语义起点；不同起点独立契约，同起点内聚合。找到实际页面动作，沿业务逻辑走到下次用户参与或交付结果的边界。中间无需用户补充输入的关联读取可以归并一次调用；不按实体数、Logic数或Dependency数机械拆接口，也不强制所有业务只有一个查询。
-3. 输入逐字段追溯实体属性（含adapt扩展）、正式外部入口字段或正式命名事务入口参数（transactionInput）。后端不能从系统取得才向前端索要；系统当前用户不出现在input或context。入口字段可直接向后传递，不强制归属实体属性。
-4. 输出是具体线上字段的实体投影，不是让前后端各自解释的抽象Row。说明本次实体实例根和关联路径，不能仅凭字段同名认定来源正确。不为仅传递对象制造uid、token或身份映射。
+2. 先读取 本轮冻结工具集的语义身份规范，用公共工具生成并登记 identity/id，证明唯一页面语义起点；不同起点独立契约，同起点内聚合。找到实际页面动作，沿业务逻辑走到下次用户参与或交付结果的边界。中间无需用户补充输入的关联读取可以归并一次调用；不按实体数、Logic数或Dependency数机械拆接口，也不强制所有业务只有一个查询。
+3. 输入逐字段追溯实体属性（含physical扩展）、正式外部入口字段或正式命名事务入口参数（transactionInput）。后端不能从系统取得才向客户端索要；系统当前用户不出现在input或context。入口字段可直接向后传递，不强制归属实体属性。
+4. 输出是具体线上字段的实体投影，不是让客户端与后端各自解释的抽象Row。说明本次实体实例根和关联路径，不能仅凭字段同名认定来源正确。不为仅传递对象制造uid、token或身份映射。
 5. 选择最小充分的结果结构：对象+可空成员已完整表达时无需case；存在真实互斥形状时用联合。完整枚举来自声明，不来自样例。确认的跨字段、实例归属及空值语义写入invariants，不以过程说明代替正式约束。
 6. 对照测试逐项验证输入形成、输出展示、关系和副作用；不把“链接了测试”当作满足测试。需要后端保证的事实仍应验证，不能因删除传输冗余就删除业务条件。
 7. 只交付当前输入对应的有效设计。用户授权更新范围内移除过时契约；实现迁移另列，不为旧代码保留另一套相冲突的真源。
 
 ## 边界
 
-- 字段集合、类型、可空性、合法枚举、单位、时刻格式及错误码含义由契约完整定义，不交给前后端各自约定。使用[模板](assets/backend-contract.template.yaml)，清除示例占位。
+- 字段集合、类型、可空性、合法枚举、单位、时刻格式及错误码含义由契约完整定义，不交给客户端与后端各自约定。使用[模板](<../../resources/templates/design/backend-contract.template.yaml>)，清除示例占位。
 - 后端契约不包含SQL、代码组织、代码生成配置、外部RPC调用顺序或profusecontract实现。id与文件名按格式规范一致，不把实现目录约定混入业务字段。
-- 后端若明确保证同一响应中对象归属一致，前端可以消费该保证而不重复身份字段。必须有来源依据及明确结果约束，不能取消源业务条件；若要求独立身份比较或跨请求回传，另核对真实身份需求。
-- 字段省略不等于null，零金额不等于空结果，查询失败不等于无业务数据。展示文案、时间格式化和页面组织归前端。
+- 后端若明确保证同一响应中对象归属一致，客户端可以消费该保证而不重复身份字段。必须有来源依据及明确结果约束，不能取消源业务条件；若要求独立身份比较或跨请求回传，另核对真实身份需求。
+- 字段省略不等于null，零金额不等于空结果，查询失败不等于无业务数据。展示文案、时间格式化和页面组织归客户端。
 - 一般按Prototype+测试所需字段投影；用户确认简单实体字段扩展保留倾向时可保留，但注明来源与扩展理由，不声称页面已消费，不据此暴露敏感或内部路由事实。
 - 技术错误与非技术失败边界必须互斥。未定义业务结果可按用户确认隔离并记录问题，不借错误码硬补已要求的业务语义。
-- 正式设计要求本范围adapt语义自洽；未写代码不阻塞，TODO仍决定数据来源或结果含义则先反馈。局部草稿不等于正式交付。能力已经明确时，正常调用组装属于backend研发，不要求另交编排程序。
+- 正式设计要求本范围正式绑定语义自洽；未写代码不阻塞，TODO仍决定数据来源或结果含义则先反馈。局部草稿不等于正式交付。能力已经明确时，正常调用组装属于backend研发，不要求另交编排程序。

package/modules/backend-contract/references/backend-contract.md

@@ -13,19 +13,19 @@
 以下示例中的业务、域、页面、接口ID和来源名称仅展示格式，必须按当前项目正式输入与身份工具生成结果替换；不是默认配置或对特定业务的限制。后续来源示例同样如此。
 
 ```yaml
-id: api_91d5e0b55164bb5b60240fa030519c23
+id: api_c6267626643566cd7945122e2bd54b73
 identity:
   kind: backend_contract
-  business: bill-deploy
-  domain: 生活缴费
-  page: 查账结果
+  business: example-app
+  domain: 示例领域
+  page: 示例页面
   trigger: /页面/页面初始化事务
 binding:
   type: mobilegw
   operationType: profuse.mgw.invoke
   target:
     app: saddle
-    interfaceId: api_91d5e0b55164bb5b60240fa030519c23
+    interfaceId: api_c6267626643566cd7945122e2bd54b73
 callSites: []
 input: {type: object, nullable: false, fields: {}}
 output: {type: object, nullable: false, fields: {}}
@@ -37,17 +37,17 @@ types: {}
 
 ## 契约身份与唯一页面起点
 
-使用 `本轮冻结的 saddle-workflow 原始包` 的 包内 `references/semantic-identity.md`及 scripts/semantic_identity.py，设计阶段生成，研发直接消费。不自行重写摘要。
+使用本轮冻结的独立工具集公开identity入口及随附语义身份说明，设计阶段生成和登记，研发直接消费。不自行重写摘要。
 
 identity 必须且仅有 kind/business/domain/page/trigger 五个字符串，kind 固定 backend_contract。归一化及校验由公共工具执行；id 为 `api_` 加32位小写十六进制摘要。页面和触发标识必须有真实 Spec 依据，不通过文案重新翻译。
 
 文件名 `<id>.backend-contract.yaml`、后端 `operations/<id>/`、Rust 模块及静态注册 operation_type 原样使用 id；后端静态 operation_type 及 binding.target.interfaceId 必须等于 id。MobileGW 外层 binding.operationType 为 profuse.mgw.invoke，binding.target.app 消费项目已确定的 deployment_app，不从 business 猜。不得把内部接口身份直接当成外层网关 operationType。
 
-callSites 非空，每项必需 triggerSource（按 workflow 身份规范的 explicit 或 languageDefault 封闭形状）及 trigger 且等于 identity.trigger，每项 page 必须等于 identity.page。调用位置定位相同语义事件的不同载体；不同页面或不同语义起点必须独立契约。一个起点内按业务连续性聚合读取，不按实体机械拆分；中断后的后续请求使用源头正式续接位置作为新的触发起点，不增加自由命名职责。
+callSites 非空，每项必需 triggerSource（按工具集语义身份规范的 explicit 或 languageDefault 封闭形状）及 trigger 且等于 identity.trigger，每项 page 必须等于 identity.page。调用位置定位相同语义事件的不同载体；不同页面或不同语义起点必须独立契约。一个起点内按业务连续性聚合读取，不按实体机械拆分；中断后的后续请求使用源头正式续接位置作为新的触发起点，不增加自由命名职责。
 
 业务根 code/identity-registry.json 是只追加的 ID→归一化身份登记表。文件删除不删除登记。使用公共工具对可信 Git 基线检查不可删改，对全量当前契约检查重复、摘要及登记一致性。源文件的仓库路径、显示文案不进入摘要或登记；identity.trigger 的源声明语义定位属于身份原文，必须保存。
 
-现有业务交付迁移必须同步前端调用、后端静态路由、日志、测试以及 DB 与测试覆盖引用，不能只重命名契约文件。工具只支持当前规则，不在一个发布内部并行接受历史格式；历史源码由 Git 和发布包保留。本次 Skill 更新不自动迁移业务仓库。
+现有业务交付迁移必须同步客户端调用、后端静态路由、日志、测试以及 DB 与测试覆盖引用，不能只重命名契约文件。工具只支持当前规则，不在一个发布内部并行接受历史格式；历史源码由 Git 和发布包保留。本次 Skill 更新不自动迁移业务仓库。
 
 ## 调用点
 
@@ -114,7 +114,7 @@ Visual Form 的宽泛类型不自动构成业务类型冲突：应追溯真实
 
 - 普通字符串未特殊指定时最大500 UTF-8字节，编码、户号、户名、地址一视同仁。已有明确特殊类型/输入约束优先；字符串值不按中文/英文计数，不截断。类型定义中的十进制编码、日期格式与实体身份遵守各自规则，不能用普通字符串上限替代合法值验证。
 - 人民币金额以元精确十进制JSON字符串传输、分整数存储，转换必须精确，不用浮点舍入；是否允许零/负数由业务规则决定。Spec未重复精度不等于允许自主切换单位；发现输入明确要求不同币种或不足一分的精度时报告真实冲突。
-- 数组的存储序列化只在存储适配层发生，接口与业务层保留数组；不能把TEXT/JSON文本直接交前端解析。金额数组沿用同一金额类型规则。
+- 数组的存储序列化只在存储适配层发生，接口与业务层保留数组；不能把TEXT/JSON文本直接交客户端解析。金额数组沿用同一金额类型规则。
 
 ## Schema 节点
 
@@ -128,7 +128,7 @@ Visual Form 的宽泛类型不自动构成业务类型冲突：应追溯真实
 - `decimal`：使用精确的十进制 JSON 字符串，绝不使用二进制浮点数。业务正确性依赖精度和舍入时，来源语义必须定义二者。
 - `string`：不隐含格式。业务编码、月份等应有 Spec 业务依据；后端契约自有传输编码由契约规范定义，不要求业务 Spec 表达技术细节。
 
-实体身份不能靠一个抽象entityReference让两端各自决定编码。本版请求优先采用真实实体属性或ingress字段，输出为具体字段投影。需要跨请求身份回传时，必须先按adapt确认真实身份及其传输字段；不为仅对象传递实体生成uid、token或映射。旧entityReference节点不用于新交付；它的删除不授权修改业务要求。
+实体身份不能靠一个抽象entityReference让两端各自决定编码。本版请求优先采用真实实体属性或ingress字段，输出为具体字段投影。需要跨请求身份回传时，必须先按正式输入确认真实身份及其传输字段；不为仅对象传递实体生成uid、token或映射。旧entityReference节点不用于新交付；它的删除不授权修改业务要求。
 
 枚举：
 
@@ -200,7 +200,7 @@ cases:
 - case key 互不重复，并属于来源枚举的合法值；
 - case 只是契约和代码生成使用的结构分支，不出现在 JSON 中；
 - 不允许另加无 Structure 来源的“结果类型”字段充当判别器；
-- 若只有部分枚举值能够形成当前后端契约的成功结果，其余值必须由 Spec 已定义的错误或明确的 fail-closed error 承接，不能静默遗漏。
+- 若只有部分枚举值能够形成当客户端与后端契约的成功结果，其余值必须由 Spec 已定义的错误或明确的 fail-closed error 承接，不能静默遗漏。
 
 `ref` 只能解析到当前文件的 `types`；后端契约之间绝不共享业务模型。
 
@@ -228,11 +228,11 @@ cases:
 
 线上为 `{case: "机构维护", data: {维护说明: "…"}}`。`case` 与 `data` 必填且无额外字段；不直接输出 source、payload 或 invariants 这些 schema 元数据。case key 是唯一且封闭的后端契约标签，不是 Structure 字段；不要求它有单个枚举字段来源。payload 是非 nullable 对象或指向该对象的文件内 ref；静态业务结果可为 `{}`。联合内每个对象仍禁止省略字段，nullable 不等于可省略。
 
-每个 case 必须有可解析的 `source: {board, node, page}` 与非空 `invariants`，说明该结果的业务条件。来源不能只引用节点名称而忽略到达它的业务含义。payload 的业务叶字段仍逐一遵守来源规则。节点/页面不是线上跳转指令；前端拥有展示组织权。
+每个 case 必须有可解析的 `source: {board, node, page}` 与非空 `invariants`，说明该结果的业务条件。来源不能只引用节点名称而忽略到达它的业务含义。payload 的业务叶字段仍逐一遵守来源规则。节点/页面不是线上跳转指令；客户端拥有展示组织权。
 
 若 Spec 明确由终止 Logic 向调用方公开交付事实，可改用 `source: {board, node}`：不得填写虚构 page；节点必须无后继且有明确的公开结果说明及真实产出。单纯无后继不自动构成后端契约结果。原有 Visual 来源保留 page。这样可表达交回上游，而不新增错误页或把所有内部 Logic 都暴露成结果。
 
-从真实调用点追踪到下一次需要用户参与或展示的业务边界，核对所有可达结果及后续纯前端动作消费。不是每个节点都产生一个后端契约，也不规定每个 Visual 必须机械对应一种结果。归并必须保留业务差异并说明依据。
+从真实调用点追踪到下一次需要用户参与或展示的业务边界，核对所有可达结果及后续纯客户端动作消费。不是每个节点都产生一个后端契约，也不规定每个 Visual 必须机械对应一种结果。归并必须保留业务差异并说明依据。
 
 仅查询命中分支需要的数据，不为其他 case 填字段而继续调用外部系统。不得把尚未查询、部分响应或 null 当作零/无欠费。Spec 遗留问题留在过程记录，不以新增 case、禁用操作或错误码暗中补业务规则。
 
@@ -240,7 +240,7 @@ cases:
 
 `input` 是完整、显式的对象。名称必须携带完整业务含义，例如 `当前户号绑定ID`，绝不使用依赖周边语义才能理解的缩写。
 
-每个input业务叶字段必须声明直接source：真实实体属性（含adapt扩展）、正式外部入口字段，或下文 transactionInput 正式事务入口参数。不通过派生表达或内部实现参数凭空增加请求来源。source定义含义，inputBindings定义本次取值，两者都要核对：
+每个input业务叶字段必须声明直接source：真实实体属性（含physical扩展）、正式外部入口字段，或下文 transactionInput 正式事务入口参数。不通过派生表达或内部实现参数凭空增加请求来源。source定义含义，inputBindings定义本次取值，两者都要核对：
 
 ```yaml
 费种:
@@ -250,13 +250,13 @@ cases:
   source: {entity: 户号, field: 费种}
 ```
 
-取值来源定义在每个调用点的 `inputBindings` 中，须核对作用域和类型兼容性；这是设计校验要求，不宣称现有Compiler已实现adapt检查。不能仅因为Logic、数据库或外部RPC需要某值就增加客户端字段；系统内置提供的值不进入input或inputBindings。
+取值来源定义在每个调用点的 `inputBindings` 中，须核对作用域和类型兼容性；这是设计校验要求，不宣称现有Compiler已实现完整设计检查。不能仅因为Logic、数据库或外部RPC需要某值就增加客户端字段；系统内置提供的值不进入input或inputBindings。
 
 入口字段保持来源类型；明确固定值可表达为单值enum。普通字符串的几个示例不构成封闭枚举，不自行增加长度、trim、空串拒绝或默认值。实体必填、请求nullable与DB可空列是不同合同。
 
-## adapt字段来源
+## 实体扩展来源与历史格式兼容
 
-以下为source的新增封闭形状：
+以下保留既有source封闭形状。ingressField仅用于识别历史契约，当前设计不新建旧ingress文件；当前入口来源见本文physical章节。
 
 ```yaml
 # 输入专用；仅source多一个kind，inputBindings.ingressField不带kind。
@@ -271,7 +271,7 @@ source:
 # 实体扩展字段，可用于请求或结果，地位与Spec属性相同。
 source:
   kind: adaptEntityField
-  path: example/adapt/entities/机构代理.binding.yaml
+  path: example/spec/domains/示例域/physical/entities/机构代理.binding.yaml
   domain: 示例域
   entity: 机构代理
   field: 机构代理编码
@@ -283,7 +283,7 @@ ingressField只允许kind/path/domain/board/entry/field；adaptEntityField只允
 
 如果对象+nullable已充分表达所有结果，不添加冗余case标签。需要互斥形状时仍按下述联合规则设计，不把一个业务的“单张或空”固化为所有业务规则。
 
-例如来源明确订单与所查账户一致，经确认由后端保证时，在output.invariants明确“返回订单属于同一响应的账户”。前端可消费该保证，不再重复身份字段；后端测试仍验证不串户。若前端必须独立比较身份，不能省略其必要字段。缺失字段不是null，零值不是无结果，相关可空字段的成对性必须写明。
+例如来源明确订单与所查账户一致，经确认由后端保证时，在output.invariants明确“返回订单属于同一响应的账户”。客户端可消费该保证，不再重复身份字段；后端测试仍验证不串户。若客户端必须独立比较身份，不能省略其必要字段。缺失字段不是null，零值不是无结果，相关可空字段的成对性必须写明。
 
 ## Output 来源
 
@@ -328,7 +328,7 @@ source:
 # 精确关联正式 Rule 返回合同；对象返回值可用 field 指定真实字段路径。
 source:
   kind: ruleResult
-  rule: 生活缴费·查账准入结论
+  rule: 示例领域·查账准入结论
 ```
 
 `flowForm` 必需且仅允许 `kind/board/node/direction/port/field`。direction 为 `input` 或 `output`，分别解析节点的入参或产出；port 是正式名称，field 是 Form 内逐段存在的字段路径。输出端口若存在多个分支声明，须全部兼容且追踪其生产分支，不能任选一个样例。不存在公开端口的内部过程值不能用本形状冒充公开输出。
@@ -341,7 +341,7 @@ source:
 
 同一个 Visual 可以对应多个 flowResult case。覆盖检查按可达业务结果及后续组件条件核对，不能要求 case 数等于 Visual 节点数；也不能仅检查节点名称存在就认为契约正确。每个 case 的 invariants 必须表达互斥条件以及跨字段约束，例如特定原因下时间对必非空、其它原因下均为 null。仅标 nullable 不代表允许所有字段组合。
 
-投影可以用已经证明的 case 代替临时答复的整体传输。必须证明页面及后续纯前端动作所需事实都能从结果取得，不能机械照搬所有页面内部入参，也不能用实体引用代替未提供的展示属性。重试调用点与写入后实际绑定同样属于契约完备性检查。
+投影可以用已经证明的 case 代替临时答复的整体传输。必须证明页面及后续纯客户端动作所需事实都能从结果取得，不能机械照搬所有页面内部入参，也不能用实体引用代替未提供的展示属性。重试调用点与写入后实际绑定同样属于契约完备性检查。
 
 以上为来源能力，输出的实体、Form与Rule来源仍有效；Form/Rule不扩大请求来源范围，消费方需支持新来源元数据。规范升级不代表现有生成器、运行时或校验器已经兼容。
 
@@ -400,7 +400,7 @@ source:
   field: accountNumber
 ```
 
-仅允许kind/path/helper/field。path定位当前helper声明，helper逐字等于name；field是入口绑定实际读取的返回对象键。类型及约束必须由helper正式返回合同或绑定读取→execute参数的实际赋值链证明，不能从Mock样例猜类型。还须证明该值来自前端可取得的页面输入，而非用户身份、请求时间或其他系统可信值。动态键或无法证明的转换先反馈。
+仅允许kind/path/helper/field。path定位当前helper声明，helper逐字等于name；field是入口绑定实际读取的返回对象键。类型及约束必须由helper正式返回合同或绑定读取→execute参数的实际赋值链证明，不能从Mock样例猜类型。还须证明该值来自客户端可取得的页面输入，而非用户身份、请求时间或其他系统可信值。动态键或无法证明的转换先反馈。
 
 页面调用点仍使用visualPageLoad。inputBindings同形输入位置用`physicalInput: {path, helper, field}`（无kind）。位置和取值与input逐项对应，并核对入口绑定确实引用此helper。该来源只供请求使用，不为响应凭空增加实体无关字段。Spec实体及扩展来源规则不变。
 
@@ -410,9 +410,9 @@ source:
 
 当当前输入由请求入参绑定的bind读取RequestContext，再传入execute时，可用`source: {kind: physicalExecuteParameter, path: <真实绑定文件>, parameter: <execute参数名>}`。仅这三个键；path必须定位唯一请求入参绑定，parameter必须是该文件唯一execute的正式参数，类型由其声明取得。此标记不能用于绕过实体来源限制的任意后端函数参数。
 
-设计者必须完整追踪bind中query/queryAll/cookie/body到该参数的赋值、别名优先与转换、空值及校验，不从Mock样例猜取值。来源位于前端实际可取得的请求数据时才可作为前后端请求字段；getLoginUser/getRequestInfo等可信内置不进入客户端输入。调用点对应使用`physicalParameter: {path, parameter}`。具体别名优先、转换和非空约束写入input.invariants，不能仅靠参数名让两端分别推导。
+设计者必须完整追踪bind中query/queryAll/cookie/body到该参数的赋值、别名优先与转换、空值及校验，不从Mock样例猜取值。来源位于客户端实际可取得的请求数据时才可作为客户端与后端请求字段；getLoginUser/getRequestInfo等可信内置不进入客户端输入。调用点对应使用`physicalParameter: {path, parameter}`。具体别名优先、转换和非空约束写入input.invariants，不能仅靠参数名让两端分别推导。
 
-RequestContext不是线上DTO：不要求前端上传完整URL、Cookie或请求体，也不把后端execute的物理工作搬给前端。若输入没有完整解析链或真实可用数据，明确反馈而不造来源。旧helper仍实际存在时可用前节physicalInput；已删除时不得继续引用旧helper。
+RequestContext不是线上DTO：不要求客户端上传完整URL、Cookie或请求体，也不把后端execute的物理工作搬给客户端。若输入没有完整解析链或真实可用数据，明确反馈而不造来源。旧helper仍实际存在时可用前节physicalInput；已删除时不得继续引用旧helper。
 
 ## 正式事务入口参数来源
 
@@ -428,7 +428,7 @@ source:
 
 仅允许 kind/path/transaction/parameter 四字段。path 定位当前事务源文件；transaction 逐字等于 `事务图.名称`；parameter 必须唯一匹配该事务入口入参中的正式 `名称`。入口不唯一或同名参数跨入口有歧义时反馈，不默认首项，不自行添加下标字段。引用实例行不冒充命名标量参数，仍追溯真实实体字段。
 
-校验必须同时证明：当前 callSites 的页面触发确实调用该事务；该参数存在且类型来自正式声明；Visual 的 `传入` 实际绑定该参数并可由前端取得；业务边界以内的参数传递无未经定义的转换。inputBindings 继续使用真实 actionInput/pageRead 等表达，不能只给 source 不检查当前值。类型映射沿统一规则（金额精确元字符串），不按样例或物理 execute 的 Java 类型反推业务类型。
+校验必须同时证明：当前 callSites 的页面触发确实调用该事务；该参数存在且类型来自正式声明；Visual 的 `传入` 实际绑定该参数并可由客户端取得；业务边界以内的参数传递无未经定义的转换。inputBindings 继续使用真实 actionInput/pageRead 等表达，不能只给 source 不检查当前值。类型映射沿统一规则（金额精确元字符串），不按样例或物理 execute 的 Java 类型反推业务类型。
 
 这不允许向客户端索要可信用户身份/服务端时间，不允许将任意局部变量、内部函数参数、物理实现参数声明为业务来源；也不要求 Spec 新增实体去承载本来合法的事务参数。physicalExecuteParameter 的 RequestContext 入口限定保持不变。
 
@@ -442,6 +442,6 @@ source:
 - `physicalExecuteResult`：`{kind, path, execute, field, protocol}`，field逐段对应正式返回DTO；protocol为`{path, service, method, field}`，精确关联官方生成proto的真实Service/Method/结果字段，数组项按实际DTO元素类型核对。不得猜命名映射、使用旧协议伪证新字段，或把未返回的数据作为投影。该来源只适用于此项目已经确定的物理执行结果交付方式；业务实体投影仍可使用原来源形状。
 - 请求业务字段仍须追溯实体、正式事务或入口参数。不能因为存在一个execute参数就从客户端索要可信用户或系统时刻，也不向客户端暴露任意execute调用能力。仅适用RequestContext入口的physicalExecuteParameter限制保持不变。
 
-前端JSON外层网关、后端契约信封、官方gRPC结果是三层不同结构，必须逐字段核对。原物理字符串单位以源声明和实际赋值链为准：不能把分字符串因名称含Amount就标为元；业务金额按统一精确元字符串规则，两者的转换位置不得重复或遗漏。
+客户端JSON外层网关、后端契约信封、官方gRPC结果是三层不同结构，必须逐字段核对。原物理字符串单位以源声明和实际赋值链为准：不能把分字符串因名称含Amount就标为元；业务金额按统一精确元字符串规则，两者的转换位置不得重复或遗漏。
 
 维护这些规范时，先核已确认的项目约定和实际消费者。只有新增来源形状或迁移范围已明确，才修改校验与生成器；文档支持不冒充现有工具已自动实现。开工前用项目当前契约做兼容核对，不把Skill滞后当作源业务问题，也不静默收紧已有请求可空或网关包装行为。

package/modules/backend-contract/references/findings.md

@@ -2,18 +2,18 @@
 
 当 Spec 无法支持完整契约时记录 finding。Finding 是诊断，不是后端契约字段，也不构成自行增加业务 fallback 的授权。Skill 或 v1 格式自身的表达能力问题应修复 Skill，不登记成项目 Spec finding。
 
-adapt输入缺失、身份约定待定及消费者迁移问题单独反馈，不归为Spec业务缺陷。已授权维护Skill时先推导合理设计并确认规则，再补规范，不能让旧格式反向限制业务。仅缺具体适配实现、不影响输入输出时继续设计明确部分。
+正式绑定输入缺失、身份约定待定及消费者迁移问题单独反馈，不归为Spec业务缺陷。已授权维护Skill时先推导合理设计并确认规则，再补规范，不能让旧格式反向限制业务。仅缺具体适配实现、不影响输入输出时继续设计明确部分。
 
 Finding 写入调用方指定的过程记录位置；未指定时只在交付说明中报告。不得在正式 `code/backend-contract` 目录创建 findings 文件。
 
 ```yaml
 findingsVersion: backend-contract-findings/v1
 findings:
-  - id: BILL-VISUAL-001
+  - id: EXAMPLE-VISUAL-001
     severity: blocker
     category: missing-call-site
     affected:
-      contractCandidate: query_bill_input_model
+      contractCandidate: example_input_model
       path: callSites
     evidence:
       - {kind: logic, board: 查询欠费单, node: 查询欠费单}

package/modules/db/design.md

@@ -1,17 +1,17 @@
 # DB设计
 
-消费Spec+adapt，产出逻辑表结构。先读共用adapt规则，再完整阅读[表格式](references/db-table-v1.md)。后端契约用于一致性复核，不是建表前提；数据库也不能由响应模型反向生成。
+消费Spec与正式physical输入，产出逻辑表结构。先读共用正式输入规则，再完整阅读[表格式](<references/db-table-v1.md>)。后端契约用于一致性复核，不是建表前提；数据库也不能由响应模型反向生成。
 
 ## 推演顺序
 
-1. 按共用输入规则核对所有相关实体承载：独立adapt看显式声明，当前Islands physical看正式实体来源与绑定及其自有库表规则。本地持久化实体建表，外部对象和代码静态实体不建实体表。来源冲突先反馈；不以未见写操作推翻明确承载，不要求新physical补旧adapt标记。
-2. 合并Spec原始属性与adapt扩展属性。二者在物理设计上都是实体属性，只是来源不同；持久化实体全部正常落列。
+1. 按共用输入规则核对所有相关实体承载：按当前Islands正式实体来源与绑定及其自有库表规则。本地持久化实体建表，外部对象和代码静态实体不建实体表。来源冲突先反馈；不以未见写操作推翻明确承载，不要求新physical补旧adapt标记。
+2. 合并Spec原始属性与physical扩展属性。二者在物理设计上都是实体属性，只是来源不同；持久化实体全部正常落列。
 3. 逐个关联核对目标身份：本地uid、静态固定主键、原生标识或已确认身份映射。不能一律存uid，不能存展示名称代替身份，不能自行给仅对象传递实体增加映射。
 4. 按已确认规则定义系统列、基础类型、长度档位、可空性。DB宽松约束与业务必填分开，不自行增加唯一性、外键或索引。
 5. 记录输入已明确的Logic、Visual或physical绑定持久访问责任，不将内存字段消费或传入Dependency推导成独立DB查询，不补同步、建档和外部CRUD。未完成适配影响访问计划不等于表结构不成立。
 6. 复核表集合、完整属性、关联方向和身份、后端契约非空结果与DB可空列的区别。后端契约不需要展示的本地属性仍可落列；非持久化返回对象不建表。
 
-使用[模板](assets/table.template.yaml)。每表一份实体名.table.yaml，交付目录只放表契约，不放findings、DDL、物理名称映射、迁移或测试工具。局部问题直接报告或进入用户指定过程位置；见[findings](references/findings.md)。
+使用[模板](<../../resources/templates/design/table.template.yaml>)。每表一份实体名.table.yaml，交付目录只放表契约，不放findings、DDL、物理名称映射、迁移或测试工具。局部问题直接报告或进入用户指定过程位置；见[findings](<references/findings.md>)。
 
 ## 固定边界
 

package/modules/db/references/db-table-v1.md

@@ -10,22 +10,22 @@
 entity:
   source: {entity: 机构代理}
   persistenceBinding:
-    path: example/adapt/entities/机构代理.binding.yaml
+    path: example/spec/domains/示例域/physical/entities/机构代理.binding.yaml
     domain: 示例域
     entity: 机构代理
-  persistenceReason: adapt明确声明本地持久化实体，身份为Saddle标准uid。
+  persistenceReason: 已核正式实体来源与当前Islands自有库表规则；本例承担本地持久化，身份为Saddle标准uid。
 table:
   name: 机构代理
   comment: 机构代理实体的本地持久化
 ```
 
-entity必需source/persistenceBinding/persistenceReason。persistenceBinding与身份来源必须解析到实际适配输入。独立adapt定位承载声明；当前Islands physical定位实体扩展（无扩展时定位逻辑实体），reason同时说明已核对外部实体来源与自有库表规则的依据，不编造旧adapt标记。table必需name/comment。完整系统列见[模板](../assets/table.template.yaml)。
+entity必需source/persistenceBinding/persistenceReason。persistenceBinding与身份来源必须解析到实际适配输入。当前Islands physical定位实体扩展（无扩展时定位逻辑实体），reason同时说明已核对外部实体来源与自有库表规则的依据，不编造旧adapt标记。table必需name/comment。完整系统列见[模板](<../../../resources/templates/design/table.template.yaml>)。
 
 ## 建表与字段集合
 
-按共用输入模式规则确认本地承载后建表；独立adapt须明确持久化声明，当前Islands physical依据正式实体来源/绑定与自有库表规则。不持久化实体和代码静态实体不建表。不检查Spec旧external标记，不强制先有本地写入流程。已明确同步到本地的实体可以持久化，但同步实现不能由表结构反向推导。
+按共用输入模式规则确认本地承载后建表；依据当前Islands正式实体来源/绑定与自有库表规则。不持久化实体和代码静态实体不建表。不检查Spec旧external标记，不强制先有本地写入流程。已明确同步到本地的实体可以持久化，但同步实现不能由表结构反向推导。
 
-columns完整覆盖该实体的Spec属性与adapt扩展属性。二者同等落列；不因未被后端契约输出而省略，也不因前端显示需要而给非持久化实体建表。
+columns完整覆盖该实体的Spec属性与physical扩展属性。二者同等落列；不因未被后端契约输出而省略，也不因客户端显示需要而给非持久化实体建表。
 
 若输入使用继承，按来源明确的继承属性展开，source指向实际声明；所有实体承载仍以选定输入模式的正式规则为准。抽象父实体、拆表或继承结构未明确时反馈，不从未声明生命周期猜表。
 
@@ -53,12 +53,12 @@ Saddle 数据访问层必须对所有普通读取强制施加 `is_deleted = fals
 source: {entity: 机构, field: 机构名称}
 ```
 
-adapt扩展属性：
+physical扩展属性：
 
 ```yaml
 source:
   kind: adaptEntityField
-  path: example/adapt/entities/机构代理.binding.yaml
+  path: example/spec/domains/示例域/physical/entities/机构代理.binding.yaml
   domain: 示例域
   entity: 机构代理
   field: 机构代理编码
@@ -78,24 +78,24 @@ source:
   storesEntityIdentity:
     entity: 机构
     strategy: saddle_uid
-    source: {path: example/adapt/entities/机构.binding.yaml, domain: 示例域, entity: 机构}
+    source: {path: example/spec/domains/示例域/physical/entities/机构.binding.yaml, domain: 示例域, entity: 机构}
 
 费种:
-  type: {kind: varchar, length: 64}
+  type: {kind: varchar, length: 500}
   nullable: true
   source: {entity: 机构, field: 费种}
   storesEntityIdentity:
     entity: 费种
     strategy: fixed_primary_key
-    source: {path: example/adapt/entities/费种.binding.yaml, domain: 示例域, entity: 费种}
+    source: {path: example/spec/domains/示例域/physical/entities/费种.binding.yaml, domain: 示例域, entity: 费种}
 ```
 
-strategy只允许如下值，并与adapt身份一一核对：
+strategy只允许如下值，并与正式身份声明一一核对：
 
-| strategy | adapt身份 | 存储 |
+| strategy | 正式身份 | 存储 |
 | --- | --- | --- |
 | saddle_uid | Saddle标准uid | varchar(32)，目标本地实体uid |
-| fixed_primary_key | 固定主键 | 目标静态实例主键，按明确值类型与长度选基本类型；当前字符串编码按64档 |
+| fixed_primary_key | 固定主键 | 目标静态实例主键，按明确值类型与长度选基本类型；未声明特殊长度的字符串按本规范统一默认容量，不按业务名称选择档位 |
 | external_native_id | 外部原生标识 | 已声明稳定原生标识，不能猜成内部uid |
 | external_mapped_uid | 外部身份映射 | 已确认映射的本地标准uid，varchar(32)；要求映射定义已充分 |
 
@@ -120,7 +120,7 @@ v1 只允许以下封闭类型：
 - 普通字符串未特殊指定时统一最大500 UTF-8字节；`varchar.length`默认500，编码、户号、户名、名称、地址、枚举不再按业务名分档。MySQL VARCHAR长度按字符解释，不能据此声称数据库已保证字节上限，应用边界须核验UTF-8字节且不得静默截断。明确输入约束或已确认特殊类型优先；内部uid固定32，TEXT采用自身容量规则，不把JSON序列化整列误限为500。业务身份的特殊编码必须有依据，不能借默认长度猜造身份。
 - `bigint` 固定生成 MySQL 64 位有符号整数。
 - `text` 对应 MySQL `TEXT`，类型节点仅为 `{kind: text}`，不允许 length、precision 或 scale。适用于文章正文等有明确业务含义的长文本，不强制按 varchar 的长度分档。最大容量为 65,535 字节而非字符数，可容纳字符数取决于数据库字符集；环境字符集仍由运维负责，不新增实例配置。业务长度与内容格式由业务逻辑处理，不生成数据库约束，不静默截断。明确超过 TEXT 容量时反馈讨论，不自动升级 MEDIUMTEXT/LONGTEXT。依据：[MySQL 字符串类型](https://dev.mysql.com/doc/refman/8.4/en/string-type-syntax.html)。
-- TEXT 字段继续使用 `nullable: true`、无数据库默认值和Spec或adapt实体属性来源。仅选择存储类型，不擅自规定正文是纯文本、HTML 或 Markdown，也不因正文可能很长而另拆表、增加索引或生成 DDL。不能用 TEXT 序列化未知对象来绕过未支持的结构或关联。
+- TEXT 字段继续使用 `nullable: true`、无数据库默认值和Spec或physical实体属性来源。仅选择存储类型，不擅自规定正文是纯文本、HTML 或 Markdown，也不因正文可能很长而另拆表、增加索引或生成 DDL。不能用 TEXT 序列化未知对象来绕过未支持的结构或关联。
 - `decimal` 必须明确 precision、scale 和单位；精度与小数位来自 Structure/Rule。
 - 人民币金额使用有符号 `bigint` 保存分，附加 `money: {currency: CNY, unit: minor, minorUnitsPerMajor: 100}`；与后端契约的元精确十进制字符串在应用边界准确换算，不使用二进制浮点数。非负等业务值域仍由业务逻辑负责。其他币种或需要不足一分的精度时先讨论，不套用人民币比例。没有本地金额字段时不为使用此规则新增字段或表。
 - `boolean` 固定生成 MySQL `TINYINT(1)`，但契约保留布尔业务语义。
@@ -143,7 +143,7 @@ v1 只允许以下封闭类型：
 
 实体上结构明确的数组属性，经设计确认可使用varchar或TEXT字符串列序列化保存；不强制拆成关联实体。具体方案必须在列comment中完整定义元素编码、空值/空列表、顺序、单位与无损转换，类型本身仍只使用基础字符串类型，不增加数据库JSON依赖。已知金额数组可以按确认的金额单位采用JSON整数数组，但不能把某项目的币种/编码自动套给所有数组。
 
-存储适配层负责双向转换，读取后业务逻辑拿到数组，后端契约也按数组表达；不得让业务或前端解析数据库序列化字符串。损坏编码不能静默降为空列表，不截断元素、不经浮点舍入；存储容量与业务数组数量约束分开。此规则不允许把未知对象或实体关联打包成字符串来逃避建模。
+存储适配层负责双向转换，读取后业务逻辑拿到数组，后端契约也按数组表达；不得让业务或客户端解析数据库序列化字符串。损坏编码不能静默降为空列表，不截断元素、不经浮点舍入；存储容量与业务数组数量约束分开。此规则不允许把未知对象或实体关联打包成字符串来逃避建模。
 
 ## 数据库约束边界
 
@@ -183,7 +183,7 @@ operation必需kind/columns/predicateColumns；kind仅read/insert/update/delete
 ## 完成检查
 
 - 表集合严格对应所选输入模式的承载规则；身份、实体和扩展来源可解析，不凭历史输出推导。
-- Spec+adapt全部属性正常落列，关联目标与身份策略一致，无误加身份映射。
+- Spec与正式physical输入全部属性正常落列，关联目标与身份策略一致，无误加身份映射。
 - 四个系统列完整且固定；类型参数明确，业务列可空无默认，不加业务约束或索引。
 - 已知访问责任来源与字段可核对，空列表不伪装完整执行计划。
 - 表文件没有TODO、占位符、诊断、DDL或运行时物理名映射。

package/modules/db/references/findings.md

@@ -1,6 +1,6 @@
 # DB问题反馈
 
-仅当Spec自身的业务表达缺失或矛盾时记录Spec finding。adapt缺失承载、身份冲突、扩展属性不明单独向用户反馈，不能要求Spec补external、外部编码或写入剧情来迁就表设计。规范能力不足由维护者处理，消费者适配问题另列。
+仅当Spec自身的业务表达缺失或矛盾时记录Spec finding。正式输入缺失承载、身份冲突、扩展属性不明单独向用户反馈，不能要求Spec补external、外部编码或写入剧情来迁就表设计。规范能力不足由维护者处理，消费者适配问题另列。
 
 反馈必须有实际实体、属性、节点及来源证据，说明影响哪张表、是否影响结构、能否继续其余设计。仅缺具体访问实现时不能把已确认表结构判为失败。缺失身份映射结构时不发明映射表。
 

package/package.json

@@ -1,16 +1,21 @@
 {
   "name": "@antprofuse/saddle-islands-design",
-  "version": "0.1.24",
-  "description": "消费自洽 adapt 与 Islands Spec，设计后端契约、数据库表和 external-contract-proto。",
+  "version": "0.1.28",
+  "description": "消费Islands正式输入和上游生成协议，设计客户端与后端契约与必要数据库结构。",
   "license": "MIT OR Apache-2.0",
   "files": [
     "SKILL.md",
-    "agents",
     "modules",
-    "references"
+    "references",
+    "resources"
   ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@code.alipay.com/profuse/saddle-islands.git",
+    "directory": "skills/design"
   }
 }

package/references/formal-inputs.md

@@ -0,0 +1,35 @@
+# 正式输入与身份边界
+
+以指定项目入口、当前Islands正式指南及编译清单确定来源。顺着逻辑与Visual锚点消费physical绑定及实际引用的entities、endpoints、helpers和current-user；核参数、DTO、prepare/set、结果和错误。不能把同目录未引用声明自动作为需求，也不要求额外建设历史adapt目录。
+
+## 实体与持久化
+
+完整实体属性由Spec与physical扩展共同形成。同名冲突不能覆盖。扩展文件本身不等于实体获取来源；核完整来源关系与当前Islands自有库表规则后确定本地持久化责任，不能凭缺少一个文件推断，也不能发明同步、回填或CRUD。
+
+本地实体采用已批准Saddle uid；实体引用键可能是业务字段，不能把引用键自动变成数据库主键或唯一约束。按绑定解析关联后消费属性，不能把$ref当完整实体。
+
+| 正式输入确定的实体身份 | 设计责任 |
+|---|---|
+| 本地持久化实体 | 建表，使用Saddle标准uid |
+| 代码静态实体 | 不建实体表，关联使用真实固定主键 |
+| 外部原生标识 | 不镜像实体表，按声明使用稳定原生ID |
+| 仅对象传递 | 不为传输制造uid、token或映射 |
+| 明确的外部身份映射 | 仅依据已确定生命周期和结构设计必要映射 |
+
+类型引用不是实例取值路径。关联按目标身份，不存展示名称代替标识。来源要求持久引用但对象没有身份时反馈冲突，不能暗中改变承载。事务创建或状态变化不自动声明数据库、回传接口或同步任务。
+
+## 请求与执行边界
+
+请求来源可以是正式实体属性、physical入口读取的字段或正式事务参数；需要证明客户端可取得该值。系统用户和请求时间由可信宿主提供，不转成客户端参数。非null不隐含trim、空串拒绝或默认值，值域不得从Mock样例猜测。
+
+按transport和正式执行边界接入：SOFA能力由ProfuseContract承载；已有alipay-rpc MobileGW调用保持真实operation，不改成新SOFA或套业务前缀。其他协议依据明确平台合同。后端提供页面实际消费的投影，不等于复制下游协议。
+
+上游生成gRPC只读消费Service/Method和请求结果。bind是逻辑转换依据，execute属于上游实现。端点相同不意味着共享一次调用结果；保留声明的独立调用、副作用、空结果与错误。Mock验收、编译和真实联调分别举证。
+
+## 来源格式兼容
+
+path是指定输入仓库根相对路径，语义目标与文件必须同时匹配。实体扩展来源保留既有`adaptEntityField`格式名，path直接定位真实physical实体扩展；这不是要求生成旧adapt文件。DB的persistenceBinding及身份source定位实际physical实体声明，无扩展时定位逻辑实体，reason记录真实来源规则依据。
+
+契约格式保留旧`ingressField`的兼容说明，供识别已有契约；当前设计使用实际physicalInput、physicalExecuteParameter或transactionInput等正式来源，不创建旧ingress文件。来源已退役应按当前正式输入迁移，不靠兼容格式制造另一套业务语义。
+
+只有输入语义确定的部分可正式设计。缺口须说明位置、影响与责任方；代码尚未实现不等于缺失语义。工具或消费者不能解析合法输入时归体系维护，不要求业务源配合错误工具。

package/{modules/backend-contract/assets → resources/templates/design}/backend-contract.template.yaml

@@ -1,24 +1,24 @@
-# 示例身份及摘要必须一起通过 workflow 工具替换；不得手改 id。
+# 示例身份及摘要必须一起通过独立身份工具替换；不得手改 id。
 identity:
   kind: backend_contract
-  business: bill-deploy
-  domain: 生活缴费
-  page: 查账结果
+  business: example-app
+  domain: 示例领域
+  page: 示例页面
   trigger: /页面/页面初始化事务
-id: api_91d5e0b55164bb5b60240fa030519c23
+id: api_c6267626643566cd7945122e2bd54b73
 binding:
   type: mobilegw
   operationType: profuse.mgw.invoke
   target:
-    app: saddle # 必须核项目实际deployment_app，不从business猜
-    interfaceId: api_91d5e0b55164bb5b60240fa030519c23
+    app: 替换为实际deployment_app # 必须核项目实际deployment_app，不从business猜
+    interfaceId: api_c6267626643566cd7945122e2bd54b73
 callSites:
   - kind: visualPageLoad
-    page: 查账结果
+    page: 示例页面
     trigger: /页面/页面初始化事务
-    triggerSource: {kind: explicit, path: bill-deploy/spec/domains/生活缴费/visual/查账结果.yaml, pointer: /页面/页面初始化事务}
+    triggerSource: {kind: explicit, path: example-app/spec/domains/示例领域/visual/示例页面.yaml, pointer: /页面/页面初始化事务}
     inputBindings:
-      示例输入: {pageInput: $示例输入}
+      示例输入: {physicalInput: {path: 替换为helper文件仓库相对路径, helper: 替换为helper名称, field: 替换为外部字段}}
 input:
   type: object
   nullable: false
@@ -27,11 +27,9 @@ input:
       type: string
       nullable: false
       source:
-        kind: ingressField
-        path: 替换为ingress文件仓库相对路径
-        domain: 替换为业务域
-        board: 替换为板块
-        entry: 替换为入口
+        kind: physicalInput
+        path: 替换为helper文件仓库相对路径
+        helper: 替换为helper名称
         field: 替换为外部字段
 # output 只定义成功响应的 data；失败固定为 success:false + failure.code/message。
 # 来源也支持正式 Flow Form / Rule 返回合同，见参考；不可从样例猜测枚举。

package/{modules/db/assets → resources/templates/design}/table.template.yaml

@@ -2,10 +2,10 @@ schemaVersion: saddle-db-table/v1
 entity:
   source: {entity: 替换为内部持久化实体}
   persistenceBinding:
-    path: 替换为adapt实体文件仓库相对路径
+    path: 替换为正式physical实体声明或逻辑实体文件仓库相对路径
     domain: 替换为业务域
     entity: 替换为内部持久化实体
-  persistenceReason: 替换为明确的adapt本地持久化声明依据。
+  persistenceReason: 替换为当前正式来源与自有库表规则的核对依据。
 table:
   name: 替换为同一个Structure实体名
   comment: 替换为表的业务语义。
@@ -32,11 +32,11 @@ systemColumns:
     default: false
     maintainedBy: saddle
     readPolicy: exclude_deleted_by_default
-# columns包含Spec与adapt扩展的全部属性；来源不同不改变列规则。
-# 实体关联须添加storesEntityIdentity及目标adapt来源，参见格式规范。
+# columns包含Spec与physical扩展的全部属性；来源不同不改变列规则。
+# 实体关联须添加storesEntityIdentity及目标正式身份来源，参见格式规范。
 columns:
   替换为Structure字段名:
-    type: {kind: varchar, length: 64}
+    type: {kind: varchar, length: 500}
     nullable: true
     comment: 替换为字段业务语义。
     source: {entity: 替换为字段声明实体, field: 替换为Structure字段名}

package/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Saddle Islands Design"
-  short_description: "消费自洽 adapt 与 Spec，设计后端契约、数据库及外部协议"

package/modules/external-contract-proto/design.md

@@ -1,34 +0,0 @@
-# External Contract Proto 设计
-
-先完整阅读[运行时边界](references/runtime.md)。本模块将自洽adapt的外部能力转成Saddle与profusecontract共同遵守的业务protobuf契约，不定义SOFA协议，也不把前端综合查询原样复制为出口函数。
-
-## 输入与范围
-
-- 消费Spec、实体承载/扩展/身份、Dependency及external-contract绑定。绑定来源不同，适配协议定义要求相同；不额外包装一层转发RPC。
-- 确认目标Saddle版本及权威proto，明确业务单元实际值。默认交付code/external-contract-proto，与backend并列。旧目录迁移须获项目授权，不保留两份真源；核对双方消费路径，实际修改限于本次授权范围，其他消费者迁移单列交接，不为 Mock 验收扩大到真实下游实现。Skill升级不自动迁移项目。
-- 用户未提供生成语言不是阻塞。业务方法身份与语言标识符分开，不要求backend先写代码再设计出口协议。
-- 读取已发布的共享协议，不从旧生成代码推导新规范；版本不一致先报告。不能因为仓库里同时存在puc和business_unit就兼容两套身份。
-
-## 设计过程
-
-1. 列出本范围明确由profusecontract承载的能力及其真实绑定目标。核对实体外部承载的名称唯一性，避免重复生成同一函数。
-2. 逐输入、输出解析实体字段类型，包括adapt扩展和身份。记录绑定文件、业务域、能力、字段路径及对应proto字段，采用proto注释保存设计关联，不增加线上来源字段或自造protobuf extension。
-3. 用具体具名request/result及必要嵌套message表达已确定的输入输出。proto需要合法标识符，中文业务名称与实体字段通过注释保留关联；同类型不是同实例，不扩展成整实体快照。
-4. 核对字段presence、空串/零、空集合、无对象、业务失败和技术异常。proto3默认值不是业务默认，不能让缺失悄悄成为0或空字符串。按目标runtime支持的presence能力表达；输入没有决定的对象整体可空或联合结构先退回讨论。
-5. 保留金额精度、日期与时刻语义、枚举及合法范围。不得默认double、按DB分存储反推外部金额单位、按前端JSON格式推断外部编码。协议编码存在多个可行选择而影响跨端正确性时，提供具体候选让用户确认再固化。
-6. 按实际选定版本的method option绑定身份，核对puc+function规则，puc值由业务确定。deadline、trace/LDC及技术异常走框架边界，下游所需用户ID是明确的业务request字段，不是通用context。字段由adapt确定，不照搬SOFA模型、类名、重试或容量默认值。
-7. 编译同一份proto及权威imports，检查descriptor中函数身份、request/result、字段号和presence。对已有契约比较descriptor及bytes hash；不得复用已删字段号、改变既有字段含义或让两端各自演化。
-
-## 交付门槛
-
-- 每个生成字段可解析到adapt字段及有效实体定义，不丢字段，不凭SOFA响应增字段。
-- 每个绑定要求的结果形状都可表达；资料缺失与调用失败不合并。部分成功策略来自adapt，不由proto设计决定。
-- request/result具名且结构封闭。契约固定类型、presence、业务语义及来源明确的值域；无业务依据的字符串长度、集合条数等技术容量由backend与profusecontract实现阶段按Saddle要求统一确定并校验，不作为契约交付的前置门槛。不得任填常量，不能用实现容量替代业务长度规则，也不能因此宣称运行时无须容量预算。
-- 缺少业务字段长度设计应记为独立Spec遗留问题，标明尚未明确的字段和影响；在类型、编码、空值及业务结果已明确且不妨碍当前协议表达时不阻塞设计。若确实影响字段语义或无损编码，应说明具体冲突再讨论。
-- 输出唯一契约树：原样固定根模板及业务proto。模板由目标Saddle提供，不修改为业务私有版本。生成代码、部署、SOFA实现、conformance脚本不属于本模块交付。
-- 交接记录proto相对路径、原始bytes SHA-256、package/service/rpc及业务身份，记录输入和runtime版本；过程检查放协作记录，不为了日志在交付目录建第二套协议清单。
-- proto编译成功、两端生成成功、conformance通过和真实联调分别举证；没执行的不要宣称通过。语义或目标runtime未明确只能给候选草稿，不能发布可直接研发的正式协议。
-
-## 与其他设计复核
-
-后端综合契约可以汇总多个外部函数；DB只有明确本地承载实体的表。非持久化返回值不建表，外部函数不要求前端额外传内部身份。各边界允许不同编码，但转换必须可准确实现且语义有依据。backend负责按需求调用与组装，不由本模块生成调用顺序或隐式加载计划。

package/modules/external-contract-proto/references/runtime.md

@@ -1,38 +0,0 @@
-# 运行时协议依据
-
-框架Skill使用用户指定或当前项目锁对应的官方精确版本，完整记录发布方来源、版本和摘要；不查询latest来隐式升级既有项目。完整阅读该版实际提供的协议与消费、验证参考文件和模板，不能假定各版本路径相同。官方包与旧资料冲突以已选定实包为准；协议变化单独反馈。包不可取得时不手写替代。工程Skill传播遵循workflow的Git原始包规则，不能把官方框架私改后冒充官方版本。
-
-## 固定模板和共享目录
-
-包内 assets/saddle_external_function.proto 与 assets/saddle_call_context.proto 由Saddle拥有定义权。design将其原样写入唯一contract_dir根部，不改名、不改bytes、不另造extension。本Skill不维护第二份模板。
-
-默认目录为 code/external-contract-proto，与backend、backend-contract、db并列。目录树是双方共同输入，包含固定根模板和业务proto；不建聚合proto、手工proto清单、protocol子目录或版本副本。只有带正式method option的RPC进入外部函数索引。
-
-对支持同级目录的Saddle版本，backend可声明 `contract_dir "../external-contract-proto";`，相对应用Cargo.toml所在目录而非shell。构建与CI消费当前分支同次检出的完整契约树，执行记录可以保留实际提交和摘要用于复现，但不在业务契约中增加 revision 定位字段或另锁历史来源。根目录定位允许上行不代表proto import允许逃逸，目录不得经symlink。具体限制核对选定版本。目录外引用支持与研发Skill停止生成proto是两项独立检查，不能因前者成立就宣称后者完成。
-
-业务proto精确 import "saddle_external_function.proto";，使用 (saddle.profusecontract.external_function)，字段为 puc 与 function。
-
-- puc是固定字段名，其值是项目确认的业务单元，不固定为字符串puc；例如bill可以按确认填bill。
-- backend DSL business_unit与option的puc值逐字一致，不把option字段改名business_unit。
-- function保留adapt契约原名，可中文；package/service/rpc合法技术名字不替代业务身份。
-- 不支持alias、fallback、动态函数或多版本路由。
-
-网络仍走固定ProfuseContractBoundary/Invoke unary，业务service/rpc不要求新增同名网络端点。
-
-## 上下文和数据
-
-技术context只自动传播trace/rpc、LDC和deadline，绝无通用user_id。下游需要用户ID时，adapt明确具体业务输入，proto显式声明，backend从可信入站上下文赋值；不向小程序索要，不默认复制，也不一律禁止下游业务身份字段。
-
-技术异常由框架TechnicalFailure承载，不进入业务result，不复制前端响应信封。前端信封与backend错误策略是另一层；发现不一致先报告，不在接管proto时静默修改其他模块。
-
-request/result具名、结构封闭；禁止Any、开放map、任意JSON和裸bytes业务对象。契约保留有依据的业务值域，技术容量不由设计者猜填。字符串、bytes、集合及嵌套的静态预算，由backend与profusecontract在实现接入阶段按Saddle要求统一确定并校验；该预算尚未选定不阻塞语义完备的契约交接，但运行验证前仍须落实。框架payload bytes不授权业务绕过schema。
-
-业务长度、存储容量和运行时预算是不同约束。业务长度缺失单独记录为Spec遗留问题；不能把DB列长或实现选定的字节预算反推为业务规则。超限不得静默截断、舍入或把部分结果冒充完整成功。
-
-## 职责迁移与验收
-
-design负责定义并冻结完整契约树。Saddle消费它，负责编译期递归扫描/import闭合、option-only索引、强类型生成、functions/uses及正式Gate。用户另安排Saddle团队移除重复定义职责并支持backend外引用；本Skill升级不表示旧Gate和项目配置自动兼容，须由该团队版本和验收证明。
-
-核对presence区分缺失与空串/0、空对象与空集合、枚举未知值、整数范围及金额精度。复杂adapt形状未定先退回讨论，不靠proto创造语义。金额/日期无权威编码时先给具体候选确认。
-
-protoc编译、两端conformance和真实联调分别举证，不把可解析冒充可实现。固定模板须逐字一致。不要混入本地旧资料的business_unit option、不同import路径或下游通用用户context。

package/references/adapt.md

@@ -1,117 +0,0 @@
-# adapt输入与身份规则
-
-三模块共用。adapt是Spec到code之间的明确设计输入，不是Islands运行时语法，也不是Saddle表列名映射。读取它不表示已实现转换或编译器已支持。设计模块消费已经自洽的adapt，不接管适配事实的发明。
-
-## 当前Islands physical输入
-
-先按当前项目入口、编译清单与本轮Islands指南确认输入模式。项目使用正式`spec/domains/<domain>/physical/`时，本节优先于下文独立adapt文件格式要求；不要扫描历史输出、复制旧绑定或要求用户重建旧adapt目录。同范围存在两份冲突来源时报告，不按文件新旧猜优先级。
-
-- 顺着正式逻辑/Visual锚点读取其绑定、引用的entities/endpoints/helpers及current-user，核对结构化目标、参数、局部DTO、prepare/set与结果语义。只消费实际引用的能力，不把同目录未引用文件自动当作需求。
-- 原实体属性与physical/entities扩展共同组成落地模型。扩展文件本身不是获取来源；按当前指南核对外部实体来源及其绑定，未声明此类来源的实体按自有库表理解。先检查当前范围的完整来源关系，不凭缺少某个文件直接推断；不另造洗数据、同步或CRUD流程。
-- 本地表沿已确认的Saddle uid标准；实体引用键可能是业务字段，引用键与数据库主键不是同一概念。按绑定要求解析关联后才消费实体属性，不能把`$ref`当成完整实体，也不能静默把业务引用键变成数据库唯一键。
-- 入口外部DTO及实体字段都可以成为后端请求依据，系统身份由可信宿主供给；不能把所有外部输入都强改为实体属性。按当前绑定实际声明取值，不从样例用户或World中猜身份。
-- 按transport判定执行端。在本体系中SOFA能力由ProfuseContract承载；alipay-rpc既有MobileGW端点由前端调用，使用其真实operation作为operationType，不能改成新SOFA能力或套用新业务前缀。后端仍需供给前端绑定实际消费的实体投影。其他协议按项目明确的边界处理。
-- 上游已生成并交付gRPC协议时，只读消费原始Service/Method及请求结果类型；bind仍是逻辑实体转换依据，execute属于上游实现，不重设计业务proto或要求专有信封。只有用户委托本阶段设计协议时，才依据自洽绑定职责设计外部协议。共享端点声明不代表共享一次调用结果。尊重明确的独立调用、副作用、错误及空结果语义。Mock、编译与真实接入分别举证。
-
-实体扩展来源沿用`adaptEntityField`形状，但path定位实际physical实体声明，domain/entity/field必须一致。DB的persistenceBinding和身份source也定位真实physical实体扩展（无扩展文件时定位逻辑实体），persistenceReason写明本轮指南及当前来源核对依据，不能编造承载标记。绑定原文、来源规则及编译能力不是由本Skill修改或重新定义。
-
-## 独立adapt输入结构与职责
-
-常见结构为同级spec、adapt、code；adapt含ingress/<入口名>.binding.yaml、entities/实体名.binding.yaml、dependencies/依赖名.binding.yaml、external-contract/名称.binding.yaml。位置以调用方指定为准，每项独立文件；ingress以业务域、目标板块和入口定位独立文件。不把Islands旧physical.yaml与adapt自动合并，也不由同名猜优先级。发现同范围冲突先反馈。
-
-采用独立adapt模式时，所有实体都应有显式承载及身份声明。承载与身份属于adapt，不要求Spec理想实体写external、技术主键或外部编码。没有实际写操作不代表不建表；一次对象属性读取也不代表DB或RPC调用。声明缺失先问，不允许消费者隐含推导。
-
-## 实体承载与身份
-
-```yaml
-业务域: 示例域
-实体: 机构代理
-承载: 本地持久化实体
-身份:
-  方式: Saddle标准uid
-扩展属性:
-  机构代理编码:
-    类型: string
-    说明: 外部体系中的机构代理编码。
-```
-
-完整落地实体属性=Spec属性+adapt扩展属性。两者同等进入字段设计，只区分追溯来源；不在属性定义写“对应入口某字段”。同名冲突不得静默覆盖，类型和语义需确认。
-
-| 承载 | 身份方式 | 设计含义 |
-| --- | --- | --- |
-| 本地持久化实体 | Saddle标准uid | 建实体表，标准UUIDv7身份 |
-| 代码静态实体 | 固定主键 | 实例固定于代码，不建表；引用保存固定主键 |
-| 不持久化实体 | 外部原生标识 | 不建实体表；原生稳定ID可直接作为引用 |
-| 不持久化实体 | 仅对象传递 | 不建表，不为传递制造身份或映射 |
-| 不持久化实体 | 外部身份映射 | 仅在已明确需要持久引用时使用已确认的本地身份映射；不是业务实体镜像表 |
-
-这里规定身份语义，不默认生成外部身份映射的具体表。稳定外部识别条件、映射生命周期和映射结构尚未明确时，反馈对应待定项，不能自行设计组合键、hash或token。映射不能解决外部身份本身不稳定的问题。有合适原生ID时不重复映射。
-
-原生标识声明例：
-
-```yaml
-身份:
-  方式: 外部原生标识
-  标识:
-    字段: 用户ID
-    来源: 平台用户ID
-```
-
-静态实例声明例（示例列表不是任何项目的默认值域）：
-
-```yaml
-身份:
-  方式: 固定主键
-实例:
-  - 主键: WATER
-    属性:
-      费种名称: 水费
-```
-
-固定主键是adapt身份，不是新增业务编码属性。合法值和属性来自实际实例声明，不能仅凭几个示例认定枚举穷尽。静态实体引用不保存名称，不另建uid映射。
-
-持久化关联以目标身份为准；若目标仅对象传递而来源要求持久引用，必须反馈冲突，不能暗中升级承载模式或创建映射。
-
-## 入口适配
-
-```yaml
-业务域: 示例域
-目标: {板块: 查询账单, 入口: 开始查询}
-外部入参:
-  subBizType:
-    类型: string
-    可空: false
-实体映射:
-  缴费账户: {实体: 缴费账户}
-适配: |
-  subBizType 可映射 @费种(主键=$subBizType)
-  TODO：由用户填写其余适配逻辑。
-```
-
-入口描述外部字段到内部实体体系的关系，不是函数返回值。实体映射必须与Spec目标入口类型一致；集合等基数必须有输入声明，不能猜测。适配允许自然语言与上述轻量记号混合，不宣称有可执行表达式解释器。
-
-后端契约请求字段只能来自实体属性（含扩展）或ingress外部入参。字段允许向后传递而不归属实体属性；必须保留来源含义和类型，不因为后端需要就新增客户端参数。非null不隐含trim、空串拒绝、缺省值或其他校验政策。系统可信身份不进入业务请求或context段。
-
-进入正式设计前区分：普通代码未写不影响语义自洽；TODO仍决定字段、取数依据、身份、合法结果或持久化结构则输入未闭合，须反馈。用户授权局部草稿时可做已确定部分，不当作正式完整交付。
-
-## Dependency边界
-
-Dependency与external-contract只在逻辑锚点上不同：前者目标指向Spec依赖，后者可由实体的外部承载名称引用。两者使用字段级输入、输出及长文本逻辑，不沿用整实体输入/返回的旧接口形状，也不要求前者必须再调用后者。
-
-字段的`类型: 实体名.字段名`是数据类型引用，不是来源或取值路径；解析Spec属性、adapt扩展及已声明的`实体名.主键`，不能重复一个可能冲突的基础类型，也不能从该引用推导实例关联。复杂结构必须由输入契约自身明确；缺失时退回adapt确认，不由design发明组合语义。
-
-实体可声明`外部承载: [{名称: 查询资料}]`，精确引用同业务域external-contract；不重复输出映射，缺失或重名应报告。它声明能力，不触发自动加载。非持久化对象仅作为实参不代表存在外部CRUD。后端代码根据Spec消费需要和契约使用能力，外部取数资料不足才是盲区，尚未写组装代码不是。
-
-后端契约可以聚合多个结果；profusecontract能力按职责划分，不机械一一对应。逻辑或实体绑定明确需要的外部能力进入external-contract-proto，具体SOFA调用逻辑不混入后端契约、表或proto。
-
-## 来源定位
-
-本版本的path均为已指定输入仓库根目录相对路径，不是shell工作目录或URL。实体类型在业务域内解析；歧义不能按同名猜。项目关联只解析当前仓库当前分支，不承载跨仓库或跨分支定位。
-
-实体绑定位置用 `{path, domain, entity}`，入口位置用 `{path, domain, board, entry}`，入口字段再加field。路径与语义目标必须同时匹配，不使用数组下标。关联随当前分支的Spec+adapt内容重新核对。
-
-入口按每个绑定一个文件交付，顶层为业务域、目标、外部入参、实体映射、适配，不使用入口数组。文件名优先为入口名.binding.yaml；同名入口冲突时以板块名限定文件名，身份仍由业务域和目标确定。仅接受新形状，迁移时同步所有path引用，不保留旧聚合文件或双读规则；保持既有适配逻辑原文。
-
-## 当前输入的状态与存储边界
-
-事务创建、状态迁移或中断表达逻辑行为，不自动声明本地持久化表、支付回传接口或同步任务。先核对实体来源及后续真实消费者；外部构造实体不能因拥有状态而复制为本地表。前端平台中断结果用于本次页面分支时，按输入衔接同一实例，不替输入增加业务留存需求。