@antprofuse/saddle-islands-design 0.1.19 → 0.1.20

package/SKILL.md

@@ -7,7 +7,9 @@ description: 消费 Islands Spec 与自洽 adapt，设计后端契约、逻辑
 
 开始先安装并完整阅读 `@antprofuse/saddle-workflow@latest` 的共同规则。所有 Skill 间引用统一从 npm 官方 registry 使用 `@latest`，不写死版本；记录本轮实际解析版本及摘要，同一协作批次保持一致，不在执行途中漂移。引用未发布或无法取得时明确反馈，不能静默使用本地草稿。自身 package 版本和格式版本不受此规则影响。
 
-Spec定义抽象业务，saddle-islands-adapt完成落地语义自洽，本Skill消费两层输入产出后端契约、DB和external-contract-proto。不能让业务Spec为工具格式增加技术字段。后端聚合契约与外部能力契约不是一一对应；适配语义须先确定，但profusecontract实现代码不是设计前置。
+当项目明确由上游Spec工具生成既有gRPC协议时，该协议是只读输入；本Skill只设计前后端契约与DB，不另建业务proto、不添加Saddle专有option。协议缺口回报上游，Java实现与部署不纳入范围。下述external-contract-proto模块仅适用于用户明确委托本阶段设计外部协议的项目。
+
+Spec定义抽象业务；适配输入可以是项目指定的独立adapt，也可以是当前Islands正式physical绑定。本Skill按实际输入模式消费自洽的业务与适配语义，产出后端契约、DB和external-contract-proto，不要求迁回旧目录形状。不能让业务Spec为工具格式增加技术字段。后端聚合契约与外部能力契约不是一一对应；适配语义须先确定，但profusecontract实现代码不是设计前置。
 
 ## 选择模块
 
@@ -15,7 +17,7 @@ Spec定义抽象业务，saddle-islands-adapt完成落地语义自洽，本Skill
 
 | 任务 | 执行前完整阅读 | 交付 |
 | --- | --- | --- |
-| 后端契约 | [设计流程](modules/backend-contract/design.md)、[格式](modules/backend-contract/references/backend-contract-v1.md)、[覆盖规则](modules/backend-contract/references/coverage.md) | `*.backend-contract.yaml` |
+| 后端契约 | [设计流程](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` |
 | 联合设计 | 所选模块的完整参考 | 独立交付，做跨层复核 |
@@ -39,7 +41,7 @@ Spec定义抽象业务，saddle-islands-adapt完成落地语义自洽，本Skill
 
 后端契约以Prototype+测试要求确定范围，实体与adapt用于解释字段和边界；DB以adapt明确承载责任确定表集合，不从响应反向建表。
 
-共同核对完整实体属性（Spec+adapt扩展）、实例归属、身份方式、金额单位和可空性。关联跟随目标身份，不能统一假设uid。DB宽松存储约束不能放宽后端契约成功结果；后端结果投影不要求复制全部数据库列。
+共同核对完整实体属性（Spec+adapt扩展）、实例归属、身份方式、金额单位和可空性。业务字段长度缺失须记录，不能把DB列长或运行时容量当作补齐了业务规则；类型和语义已明确时，技术容量在实现阶段统一确定，不前置为全部契约设计的阻塞条件。关联跟随目标身份，不能统一假设uid。DB宽松存储约束不能放宽后端契约成功结果；后端结果投影不要求复制全部数据库列。
 
 external-contract-proto覆盖adapt明确交给profusecontract的Dependency及external-contract，字段类型引用应解析为具体传输字段；不能因为类型相同就猜某个实例的值。正常调用与组装由backend研发依据业务和绑定完成，不要求额外编排配置。跨层核对空值、精度、单位和失败语义，不把前端JSON信封复制到外部函数result。
 
@@ -55,4 +57,4 @@ external-contract-proto覆盖adapt明确交给profusecontract的Dependency及ext
 
 ## 维护边界
 
-当前三个模块为后端契约、DB、external-contract-proto；adapt设计由并列的saddle-islands-adapt负责。版本只递增最末位0.1.x的patch，未经明确要求不升前两位。保持已批准约定，不把单个案例固化成通用设计；保留包外未批准草稿。
+当前三个模块为后端契约、DB、external-contract-proto；独立adapt设计由并列的saddle-islands-adapt负责；已在当前Islands physical中表达的输入按其正式语义消费，不再制造第二套adapt。版本只递增最末位0.1.x的patch，未经明确要求不升前两位。保持已批准约定，不把单个案例固化成通用设计；保留包外未批准草稿。

package/modules/backend-contract/assets/backend-contract.template.yaml

@@ -1,24 +1,21 @@
-contractVersion: backend-contract/v1
-id: replace_with_contract_id
+# 示例身份及摘要必须一起通过 workflow 工具替换；不得手改 id。
+identity:
+  kind: backend_contract
+  business: bill-deploy
+  domain: 生活缴费
+  page: 查账结果
+  trigger: /页面/页面初始化事务
+id: api_91d5e0b55164bb5b60240fa030519c23
 binding:
   type: mobilegw
-  operationType: alipay.profuse.industry.replace.replaceOperation
+  operationType: api_91d5e0b55164bb5b60240fa030519c23
 callSites:
-  - kind: flowEntry
-    flow: {board: 替换为板块, entry: 替换为入口}
-    ingress:
-      path: 替换为ingress文件仓库相对路径
-      domain: 替换为业务域
-      board: 替换为板块
-      entry: 替换为入口
+  - kind: visualPageLoad
+    page: 查账结果
+    trigger: /页面/页面初始化事务
+    triggerSource: {kind: explicit, path: bill-deploy/spec/domains/生活缴费/visual/查账结果.yaml, pointer: /页面/页面初始化事务}
     inputBindings:
-      示例输入:
-        ingressField:
-          path: 替换为ingress文件仓库相对路径
-          domain: 替换为业务域
-          board: 替换为板块
-          entry: 替换为入口
-          field: 替换为外部字段
+      示例输入: {pageInput: $示例输入}
 input:
   type: object
   nullable: false
@@ -49,5 +46,3 @@ errors:
   - code: EXAMPLE_ERROR
     description: 替换为封闭的可观察错误语义。
 types: {}
-# 必须逐项替换为真实 Prototype/测试关联，禁止空数组交付；见 references/coverage.md。
-coverage: []

package/modules/backend-contract/design.md

@@ -1,14 +1,14 @@
 # 后端契约设计
 
-消费Spec+adapt，产出后端向前端提供的独立契约。先读共用adapt规则，再完整阅读[格式](references/backend-contract-v1.md)与[覆盖](references/coverage.md)。来源有问题时读[findings](references/findings.md)。
+消费Spec+adapt，产出后端向前端提供的独立契约。先读共用adapt规则，再完整阅读[格式](references/backend-contract.md)。来源有问题时读[findings](references/findings.md)。
 
 ## 推演顺序
 
-1. 列出指定Prototype交互、展示及测试责任的完整分母。Spec其他内容用于解释实体与业务，不据此扩展接口范围；不要求Spec预先声明物理服务接口。
-2. 找到实际入口或页面动作，沿业务逻辑走到下次用户参与或交付结果的边界。中间无需用户补充输入的关联读取可以归并一次调用；不按实体数、Logic数或Dependency数机械拆接口，也不强制所有业务只有一个查询。
-3. 输入逐字段追溯实体属性（含adapt扩展）或ingress。后端不能从系统取得才向前端索要；系统当前用户不出现在input或context。入口字段可直接向后传递，不强制归属实体属性。
+1. 核对指定 Spec/Prototype 的交互、展示与结果需求。覆盖分母和链路算法由后续测试阶段产出，不在契约设计阶段提前生成。Spec其他内容用于解释实体与业务，不据此扩展接口范围；不要求Spec预先声明物理服务接口。
+2. 先读取 @antprofuse/saddle-workflow@latest 的语义身份规范，用公共工具生成并登记 identity/id，证明唯一页面语义起点；不同起点独立契约，同起点内聚合。找到实际页面动作，沿业务逻辑走到下次用户参与或交付结果的边界。中间无需用户补充输入的关联读取可以归并一次调用；不按实体数、Logic数或Dependency数机械拆接口，也不强制所有业务只有一个查询。
+3. 输入逐字段追溯实体属性（含adapt扩展）、正式外部入口字段或正式命名事务入口参数（transactionInput）。后端不能从系统取得才向前端索要；系统当前用户不出现在input或context。入口字段可直接向后传递，不强制归属实体属性。
 4. 输出是具体线上字段的实体投影，不是让前后端各自解释的抽象Row。说明本次实体实例根和关联路径，不能仅凭字段同名认定来源正确。不为仅传递对象制造uid、token或身份映射。
-5. 选择最小充分的结果结构：对象+可空成员已完整表达时无需case；存在真实互斥形状时用联合。完整枚举来自声明，不来自样例。确认的跨字段、实例归属及空值语义写入invariants，不只藏在coverage。
+5. 选择最小充分的结果结构：对象+可空成员已完整表达时无需case；存在真实互斥形状时用联合。完整枚举来自声明，不来自样例。确认的跨字段、实例归属及空值语义写入invariants，不以过程说明代替正式约束。
 6. 对照测试逐项验证输入形成、输出展示、关系和副作用；不把“链接了测试”当作满足测试。需要后端保证的事实仍应验证，不能因删除传输冗余就删除业务条件。
 7. 只交付当前输入对应的有效设计。用户授权更新范围内移除过时契约；实现迁移另列，不为旧代码保留另一套相冲突的真源。
 

package/modules/backend-contract/references/{backend-contract-v1.md → backend-contract.md}

@@ -1,4 +1,4 @@
-# Saddle 后端契约 v1
+# Saddle 后端契约
 
 ## 契约边界
 
@@ -11,59 +11,38 @@
 ## 必需的顶层结构
 
 ```yaml
-contractVersion: backend-contract/v1
-id: query_bill
+id: api_91d5e0b55164bb5b60240fa030519c23
+identity:
+  kind: backend_contract
+  business: bill-deploy
+  domain: 生活缴费
+  page: 查账结果
+  trigger: /页面/页面初始化事务
 binding:
   type: mobilegw
-  operationType: alipay.profuse.industry.bill.queryBill
+  operationType: api_91d5e0b55164bb5b60240fa030519c23
 callSites: []
 input: {type: object, nullable: false, fields: {}}
 output: {type: object, nullable: false, fields: {}}
 errors: []
 types: {}
-coverage: []
 ```
 
-九个顶层字段全部必填，禁止未知顶层字段。`operationType` 全局唯一，使用完整、无歧义的命名。`coverage` 的形状与全量审查规则见 [coverage.md](coverage.md)，正式交付不得为空。
+八个顶层字段 id/identity/binding/callSites/input/output/errors/types 全部必填，禁止未知顶层字段。不再携带 contractVersion：格式由当前工具与 Skill 发布统一定义。不包含 coverage；测试覆盖分母、链路身份和覆盖记录由测试阶段基于 Spec 与契约独立产出。
 
-coverage 是必填设计元数据；旧八字段契约不能宣称符合新版设计门禁。严格只接受八字段的消费者需适配；现有项目应单独 review 后补关联，不捏造旧测试证据。
+## 契约身份与唯一页面起点
 
-0.1.12 统一更名：格式标识为 `backend-contract/v1`，文件后缀为 `.backend-contract.yaml`。线上请求、响应、operationType 和契约 id 的语义不变，但文件发现规则与格式标识校验必须同步迁移；不得宣称旧消费者自动兼容。旧发布版本及历史交付不自动重写，项目迁移须单独获得授权。0.1.14使用Spec入口+adapt来源，不再接受callSites.api或旧逻辑API声明。
+使用 `@antprofuse/saddle-workflow@latest` 的 包内 `references/semantic-identity.md`及 scripts/semantic_identity.py，设计阶段生成，研发直接消费。不自行重写摘要。
 
-## 后端契约 ID
+identity 必须且仅有 kind/business/domain/page/trigger 五个字符串，kind 固定 backend_contract。归一化及校验由公共工具执行；id 为 `api_` 加32位小写十六进制摘要。页面和触发标识必须有真实 Spec 依据，不通过文案重新翻译。
 
-后端契约 ID 是实现切片稳定、全局唯一、可直接落盘的机器身份。它必须原样用于：
+文件名 `<id>.backend-contract.yaml`、后端 `operations/<id>/`、Rust 模块及静态注册 operation_type 原样使用 id；binding.operationType 必须等于 id。它是内部目标接口，不能替代外层 profuse.mgw.invoke 转发通道，也不从 business 猜 deployment_app。
 
-```text
-契约 id                query_bill
-后端契约文件名             query_bill.backend-contract.yaml
-Backend operation 目录 query_bill/
-Rust module 名         query_bill
-```
-
-任何消费方都不得再建立 kebab-case、camelCase、缩写或别名映射，也不得把后端契约 ID 重新翻译为实现名称。文件名去掉固定后缀 `.backend-contract.yaml` 后必须严格等于 `id`；operation 目录 basename 与 Rust module 标识符也必须严格等于 `id`。
-
-后端契约 ID 必须同时满足：
+callSites 非空，每项必需 triggerSource（按 workflow 身份规范的 explicit 或 languageDefault 封闭形状）及 trigger 且等于 identity.trigger，每项 page 必须等于 identity.page。调用位置定位相同语义事件的不同载体；不同页面或不同语义起点必须独立契约。一个起点内按业务连续性聚合读取，不按实体机械拆分；中断后的后续请求使用源头正式续接位置作为新的触发起点，不增加自由命名职责。
 
-- 格式为 `^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$`；
-- 使用完整、无歧义的英文业务动作名称，禁止缩写；
-- 在全部后端契约中全局唯一；
-- 不是 Rust 当前关键字或保留关键字；
-- 不使用 `r#` 原始标识符逃逸；
-- 一经发布即保持稳定，业务含义变化时不能复用旧 ID 承载另一能力。
+业务根 code/identity-registry.json 是只追加的 ID→归一化身份登记表。文件删除不删除登记。使用公共工具对可信 Git 基线检查不可删改，对全量当前契约检查重复、摘要及登记一致性。源文件的仓库路径、显示文案不进入摘要或登记；identity.trigger 的源声明语义定位属于身份原文，必须保存。
 
-禁止使用的 Rust 关键字及保留字至少包括：
-
-```text
-as async await break const continue crate dyn else enum extern false fn for
-if impl in let loop match mod move mut pub ref return self Self static struct
-super trait true try type union unsafe use where while abstract become box do
-final macro override priv typeof unsized virtual yield
-```
-
-设计门禁必须同时检查契约 `id` 唯一性、文件名一致性和 Rust 标识符合法性。Backend 生成阶段只消费该 ID，不拥有命名权。
-
-`binding` 只声明当前后端契约采用系统已有的 MobileGW 协议，并分配唯一 `operationType`，不允许增加其他字段。
+现有业务交付迁移必须同步前端调用、后端静态路由、日志、测试以及 DB 与测试覆盖引用，不能只重命名契约文件。工具只支持当前规则，不在一个发布内部并行接受历史格式；历史源码由 Git 和发布包保留。本次 Skill 更新不自动迁移业务仓库。
 
 ## 调用点
 
@@ -71,6 +50,8 @@ Visual 读取：
 
 ```yaml
 - kind: visualRead
+  trigger: /页面/页面初始化事务
+  triggerSource: {kind: explicit, path: 示例业务/spec/domains/示例域/visual/收款概览.yaml, pointer: /页面/页面初始化事务}
   page: 收款概览
   read: $工作台数据
   inputBindings:
@@ -81,6 +62,8 @@ Visual 读取：
 
 ```yaml
 - kind: visualPageLoad
+  trigger: /页面/页面初始化事务
+  triggerSource: {kind: explicit, path: 示例业务/spec/domains/示例域/visual/欠费单.yaml, pointer: /页面/页面初始化事务}
   page: 欠费单
   inputBindings:
     机构名称: {pageInput: $机构名称}
@@ -95,12 +78,14 @@ Visual 读取：
 - 输出仍须逐字段遵守下述来源规则，并由 Visual 的实际消费证明必要性；
 - 页面中彼此独立、刷新周期不同或业务语义不同的读取不得强行聚合。
 
-所有调用点都绑定全部定义输入，嵌套结构与input一致。位置使用真实稳定语义身份，不使用源码数组下标或旧Paragraph身份。
+所有调用点都绑定全部定义输入，嵌套结构与input一致。各调用点还必需 trigger，逐字等于 identity.trigger。位置使用真实稳定语义身份，不使用源码数组下标或旧Paragraph身份。
 
 新版 Business Flow 动作使用 `visualFlow`：
 
 ```yaml
 - kind: visualFlow
+  trigger: /页面/组件树/页面主体/子组件/户号区/子组件/户号卡列表/子组件/户号卡/交互
+  triggerSource: {kind: explicit, path: 示例业务/spec/domains/示例域/visual/查询户号.yaml, pointer: /页面/组件树/页面主体/子组件/户号区/子组件/户号卡列表/子组件/户号卡/交互}
   page: 查询户号
   component: 页面主体/户号区/户号卡列表/户号卡
   flow: {board: 查询欠费单, node: 输入查询信息}
@@ -114,33 +99,21 @@ Visual 读取：
 
 Visual Form 的宽泛类型不自动构成业务类型冲突：应追溯真实赋值来源。若完整赋值链均来自同一 Structure 封闭枚举且无转换，可以在后端契约保留该枚举；不能仅依据同名字段猜测值域。
 
-公开入口以Spec板块/入口与adapt ingress共同定位，不要求逻辑API声明：
+本格式要求页面归属；无页面公开入口不伪造 page/trigger，需另行定义其身份类型。旧 flowEntry 不作为当前页面契约调用点。
 
-```yaml
-- kind: flowEntry
-  flow: {board: 查询账单, entry: 开始查询}
-  ingress:
-    path: example/adapt/ingress/开始查询.binding.yaml
-    domain: 示例域
-    board: 查询账单
-    entry: 开始查询
-  inputBindings:
-    账户编号:
-      ingressField:
-        path: example/adapt/ingress/开始查询.binding.yaml
-        domain: 示例域
-        board: 查询账单
-        entry: 开始查询
-        field: accountNumber
-```
+页面调用点仍使用pageInput/pageRead/actionInput/collectionItem绑定，位置必须真实存在；请求的业务含义还须遵守下述实体或ingress来源限制。旧Paragraph事务来源不用于当前Graph，按真实visualFlow或visualTransaction定位。
+
+## 统一类型规则
 
-flowEntry必需kind/flow/ingress/inputBindings；ingress四键必须同时定位唯一条目，flow必须与目标一致。ingressField五键表达本次输入值来源；每个定义的输入（含nullable）均须绑定。不得使用旧api/eventInput，不能把任意后台事件自动暴露成MobileGW调用。无本域页面的真实公开入口不虚构页面。
+类型规则先于项目字段设计，不因Spec没有重复技术细节重新猜测或让业务逐字段决定：
 
-页面调用点仍使用pageInput/pageRead/actionInput/collectionItem绑定，位置必须真实存在；请求的业务含义还须遵守下述实体或ingress来源限制。旧Paragraph事务来源不用于当前Graph，按真实visualFlow或flowEntry定位。
+- 普通字符串未特殊指定时最大500 UTF-8字节，编码、户号、户名、地址一视同仁。已有明确特殊类型/输入约束优先；字符串值不按中文/英文计数，不截断。类型定义中的十进制编码、日期格式与实体身份遵守各自规则，不能用普通字符串上限替代合法值验证。
+- 人民币金额以元精确十进制JSON字符串传输、分整数存储，转换必须精确，不用浮点舍入；是否允许零/负数由业务规则决定。Spec未重复精度不等于允许自主切换单位；发现输入明确要求不同币种或不足一分的精度时报告真实冲突。
+- 数组的存储序列化只在存储适配层发生，接口与业务层保留数组；不能把TEXT/JSON文本直接交前端解析。金额数组沿用同一金额类型规则。
 
 ## Schema 节点
 
-每个节点都必须包含 `type` 和 `nullable`。object可附 `invariants`：非空字符串数组，表达该对象的实例来源、归属、字段关联、单位及组合约束。它是正式契约语义，不进入线上数据；每项须有Spec或已确认设计依据。应由coverage关联这些约束，不把约束只写在coverage解释里。
+每个节点都必须包含 `type` 和 `nullable`。object可附 `invariants`：非空字符串数组，表达该对象的实例来源、归属、字段关联、单位及组合约束。它是正式契约语义，不进入线上数据；每项须有Spec或已确认设计依据。约束必须直接写入正式 schema，不由后续测试覆盖说明替代。
 
 标量类型为 `string / integer / decimal / boolean / date / datetime`：
 
@@ -262,7 +235,7 @@ cases:
 
 `input` 是完整、显式的对象。名称必须携带完整业务含义，例如 `当前户号绑定ID`，绝不使用依赖周边语义才能理解的缩写。
 
-每个input业务叶字段必须声明直接source，限定为真实实体属性（含adapt扩展）或ingress外部字段，不通过派生表达制造第三类请求来源。source定义含义，inputBindings定义本次取值，两者都要核对：
+每个input业务叶字段必须声明直接source：真实实体属性（含adapt扩展）、正式外部入口字段，或下文 transactionInput 正式事务入口参数。不通过派生表达或内部实现参数凭空增加请求来源。source定义含义，inputBindings定义本次取值，两者都要核对：
 
 ```yaml
 费种:
@@ -299,7 +272,7 @@ source:
   field: 机构代理编码
 ```
 
-ingressField只允许kind/path/domain/board/entry/field；adaptEntityField只允许kind/path/domain/entity/field。必须解析到真实字段，不能用入口field来源为响应添无实体根的透传字段。扩展字段的来源可用于下述派生dependencies。
+ingressField只允许kind/path/domain/board/entry/field；adaptEntityField只允许kind/path/domain/entity/field。必须解析到真实字段，不能用入口field来源为响应添无实体根的透传字段。扩展字段的来源可用于下述派生dependencies。当前Islands physical/entities中的字段沿用adaptEntityField形状，path直接定位该实体扩展文件，不制造旧adapt副本；必须核对实体、业务域和真实字段声明。
 
 ## 结果结构与约束
 
@@ -365,7 +338,7 @@ source:
 
 投影可以用已经证明的 case 代替临时答复的整体传输。必须证明页面及后续纯前端动作所需事实都能从结果取得，不能机械照搬所有页面内部入参，也不能用实体引用代替未提供的展示属性。重试调用点与写入后实际绑定同样属于契约完备性检查。
 
-以上为 v1 来源能力的增量扩展，输出的实体、Form与Rule来源仍有效；Form/Rule不扩大请求来源范围，消费方需支持新来源元数据。规范升级不代表现有生成器、运行时或校验器已经兼容。
+以上为来源能力，输出的实体、Form与Rule来源仍有效；Form/Rule不扩大请求来源范围，消费方需支持新来源元数据。规范升级不代表现有生成器、运行时或校验器已经兼容。
 
 ## Errors 与响应信封（线上结构）
 
@@ -406,6 +379,50 @@ source:
 
 ## 完成门禁
 
-首先必须完整支撑指定范围的 Prototype 与测试用例，且按 coverage 参考逐项关联、无漏项或伪造覆盖；其他 Spec 的未关联内容不能用于扩展接口范围。覆盖记录与后端契约同版本维护，不包含测试执行状态或运行日志。测试缺口或双方冲突应报告，不能宣布整体设计完备。
+设计审查必须确认指定 Spec/Prototype 的调用输入、结果消费及业务约束得到支持；不按现有用例数量反推接口，不生成测试覆盖分母或覆盖率。测试阶段独立建立完整链路覆盖，并可反馈设计缺口。不能把设计核对称为测试已覆盖或运行通过。
+
+只有满足以下条件，契约才可交付：后端契约 ID 在完整业务登记范围内唯一、符合 Rust module 标识符规则且与文件名原样一致；全部位置可解析；每个调用点绑定全部必填输入；类型、枚举、nullable、日期时间和 decimal 语义封闭；每个输入与输出叶字段均有来源；判别联合的 case 完整且互斥；ref 可解析且无环；output 与 errors 不矛盾；不存在 TODO、占位符、空枚举、未解析 ref 或诊断标记。
+
+## 当前 physical 入口来源
+
+当前Islands以入口绑定调用helper取得外部字段时，source可使用以下封闭形状，不伪造历史ingress文件：
+
+```yaml
+source:
+  kind: physicalInput
+  path: example/spec/domains/示例域/physical/helpers/getPageParams.yaml
+  helper: getPageParams
+  field: accountNumber
+```
+
+仅允许kind/path/helper/field。path定位当前helper声明，helper逐字等于name；field是入口绑定实际读取的返回对象键。类型及约束必须由helper正式返回合同或绑定读取→execute参数的实际赋值链证明，不能从Mock样例猜类型。还须证明该值来自前端可取得的页面输入，而非用户身份、请求时间或其他系统可信值。动态键或无法证明的转换先反馈。
+
+页面调用点仍使用visualPageLoad。inputBindings同形输入位置用`physicalInput: {path, helper, field}`（无kind）。位置和取值与input逐项对应，并核对入口绑定确实引用此helper。该来源只供请求使用，不为响应凭空增加实体无关字段。Spec实体及扩展来源规则不变。
+
+当前事务调用使用`visualTransaction`：必需kind/page/trigger/triggerSource/component/transaction/inputBindings。transaction为真实事务图名称；component定位当前页面实际绑定该事务的组件（含分支完整语义路径）。inputBindings使用实际actionInput/pageRead/collectionItem等取值表达，字段结构与input一致，不伪造旧board/node入口。按本次调用的入参、响应、中断及终点完整检查；中断本身不强制生成后端接口。
+
+## RequestContext入口适配后的物理参数
+
+当当前输入由请求入参绑定的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，不能仅靠参数名让两端分别推导。
+
+RequestContext不是线上DTO：不要求前端上传完整URL、Cookie或请求体，也不把后端execute的物理工作搬给前端。若输入没有完整解析链或真实可用数据，明确反馈而不造来源。旧helper仍实际存在时可用前节physicalInput；已删除时不得继续引用旧helper。
+
+## 正式事务入口参数来源
+
+当前 Visual 通过交互调用事务，并传入事务正式声明的命名标量参数时，请求字段可使用：
+
+```yaml
+source:
+  kind: transactionInput
+  path: 示例业务/spec/domains/示例域/logic/transactions/缴费.yaml
+  transaction: 缴费
+  parameter: 缴费金额
+```
+
+仅允许 kind/path/transaction/parameter 四字段。path 定位当前事务源文件；transaction 逐字等于 `事务图.名称`；parameter 必须唯一匹配该事务入口入参中的正式 `名称`。入口不唯一或同名参数跨入口有歧义时反馈，不默认首项，不自行添加下标字段。引用实例行不冒充命名标量参数，仍追溯真实实体字段。
+
+校验必须同时证明：当前 callSites 的页面触发确实调用该事务；该参数存在且类型来自正式声明；Visual 的 `传入` 实际绑定该参数并可由前端取得；业务边界以内的参数传递无未经定义的转换。inputBindings 继续使用真实 actionInput/pageRead 等表达，不能只给 source 不检查当前值。类型映射沿统一规则（金额精确元字符串），不按样例或物理 execute 的 Java 类型反推业务类型。
 
-只有满足以下条件，契约才可交付：后端契约 ID 全局唯一、符合 Rust module 标识符规则且与文件名原样一致；全部位置可解析；每个调用点绑定全部必填输入；类型、枚举、nullable、日期时间和 decimal 语义封闭；每个输入与输出叶字段均有来源；判别联合的 case 完整且互斥；ref 可解析且无环；output 与 errors 不矛盾；不存在 TODO、占位符、空枚举、未解析 ref 或诊断标记。
+这不允许向客户端索要可信用户身份/服务端时间，不允许将任意局部变量、内部函数参数、物理实现参数声明为业务来源；也不要求 Spec 新增实体去承载本来合法的事务参数。physicalExecuteParameter 的 RequestContext 入口限定保持不变。

package/modules/db/design.md

@@ -4,11 +4,11 @@
 
 ## 推演顺序
 
-1. 核对所有相关实体的adapt承载声明：本地持久化实体建表，不持久化和代码静态实体不建实体表。声明缺失或矛盾先反馈；不以未见写操作推翻明确承载，也不由Spec旧external标记推导。
+1. 按共用输入规则核对所有相关实体承载：独立adapt看显式声明，当前Islands physical看正式实体来源与绑定及其自有库表规则。本地持久化实体建表，外部对象和代码静态实体不建实体表。来源冲突先反馈；不以未见写操作推翻明确承载，不要求新physical补旧adapt标记。
 2. 合并Spec原始属性与adapt扩展属性。二者在物理设计上都是实体属性，只是来源不同；持久化实体全部正常落列。
 3. 逐个关联核对目标身份：本地uid、静态固定主键、原生标识或已确认身份映射。不能一律存uid，不能存展示名称代替身份，不能自行给仅对象传递实体增加映射。
 4. 按已确认规则定义系统列、基础类型、长度档位、可空性。DB宽松约束与业务必填分开，不自行增加唯一性、外键或索引。
-5. 记录输入已明确的Logic持久访问责任，不将内存字段消费或传入Dependency推导成独立DB查询，不补同步、建档和外部CRUD。未完成适配影响访问计划不等于表结构不成立。
+5. 记录输入已明确的Logic、Visual或physical绑定持久访问责任，不将内存字段消费或传入Dependency推导成独立DB查询，不补同步、建档和外部CRUD。未完成适配影响访问计划不等于表结构不成立。
 6. 复核表集合、完整属性、关联方向和身份、后端契约非空结果与DB可空列的区别。后端契约不需要展示的本地属性仍可落列；非持久化返回对象不建表。
 
 使用[模板](assets/table.template.yaml)。每表一份实体名.table.yaml，交付目录只放表契约，不放findings、DDL、物理名称映射、迁移或测试工具。局部问题直接报告或进入用户指定过程位置；见[findings](references/findings.md)。
@@ -19,4 +19,6 @@
 
 Saddle物理映射只改表名列名，不改变列集合、类型、默认值、主键和系统语义。数据库实例时区、字符集及运行期索引优化不属于此设计。人民币金额采用BIGINT分存储，长文本支持TEXT；没有本地金额或长文本字段就不凭空新增。
 
+明确结构的数组属性如经确认用字符串列存储，序列化/反序列化只属于存储适配层，进入业务逻辑及后端契约前恢复数组；具体编码、空值、顺序和精度必须定义，不能用字符串掩盖未知结构。
+
 外部身份映射仅在用户明确配置且结构依据充分时设计；当前只有语义没有映射结构的输入，应反馈其缺失，不自动发明额外表。

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

@@ -19,15 +19,15 @@ table:
   comment: 机构代理实体的本地持久化
 ```
 
-entity必需source/persistenceBinding/persistenceReason。persistenceBinding与身份来源必须解析到对应adapt条目；reason说明依据，不替代声明。table必需name/comment。完整系统列见[模板](../assets/table.template.yaml)。
+entity必需source/persistenceBinding/persistenceReason。persistenceBinding与身份来源必须解析到实际适配输入。独立adapt定位承载声明；当前Islands physical定位实体扩展（无扩展时定位逻辑实体），reason同时说明已核对外部实体来源与自有库表规则的依据，不编造旧adapt标记。table必需name/comment。完整系统列见[模板](../assets/table.template.yaml)。
 
 ## 建表与字段集合
 
-adapt明确本地持久化才建实体表；不持久化实体和代码静态实体不建表。不检查Spec旧external标记，不强制先有本地写入流程。已明确同步到本地的实体可以持久化，但同步实现不能由表结构反向推导。
+按共用输入模式规则确认本地承载后建表；独立adapt须明确持久化声明，当前Islands physical依据正式实体来源/绑定与自有库表规则。不持久化实体和代码静态实体不建表。不检查Spec旧external标记，不强制先有本地写入流程。已明确同步到本地的实体可以持久化，但同步实现不能由表结构反向推导。
 
 columns完整覆盖该实体的Spec属性与adapt扩展属性。二者同等落列；不因未被后端契约输出而省略，也不因前端显示需要而给非持久化实体建表。
 
-若输入使用继承，按来源明确的继承属性展开，source指向实际声明；所有实体承载仍以adapt为准。抽象父实体、拆表或继承结构未明确时反馈，不从未声明生命周期猜表。
+若输入使用继承，按来源明确的继承属性展开，source指向实际声明；所有实体承载仍以选定输入模式的正式规则为准。抽象父实体、拆表或继承结构未明确时反馈，不从未声明生命周期猜表。
 
 ## 系统列
 
@@ -64,11 +64,11 @@ source:
   field: 机构代理编码
 ```
 
-扩展来源kind/path/domain/entity/field五键必须同时定位真实声明。来源不同不是另一种列类型。系统列单独定义，不伪造其Spec来源。
+扩展来源kind/path/domain/entity/field五键必须同时定位真实声明；path允许当前Islands physical/entities实体扩展文件，不要求同一份字段另存adapt副本。来源不同不是另一种列类型。系统列单独定义，不伪造其Spec来源。
 
 ## 关联身份
 
-每个实体关联列必需storesEntityIdentity，非关联列不使用。包含且仅包含entity/strategy/source；source为目标实体的adapt位置{path,domain,entity}，必须与关联目标一致。
+每个实体关联列必需storesEntityIdentity，非关联列不使用。包含且仅包含entity/strategy/source；source为目标实体的实际适配输入位置{path,domain,entity}，必须与关联目标一致。
 
 ```yaml
 机构:
@@ -117,7 +117,7 @@ v1 只允许以下封闭类型：
 - {kind: datetime, precision: 3}
 ```
 
-- `varchar.length` 默认采用已确认的64/256/1024档：标识符、编码、户号文本、枚举64；名称256；地址1024。明确的项目约定优先。外部复合身份引用不是裸户号文本，应按已确认编码预算选档；不得把历史项目外部引用长度当作新项目身份编码。内部 uid 固定32。不要求 Spec 精确给出数据库长度；超出已选上界或需要新类型时讨论，不静默截断。
+- 普通字符串未特殊指定时统一最大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 序列化未知对象来绕过未支持的结构或关联。
@@ -139,6 +139,12 @@ v1 只允许以下封闭类型：
   source: {entity: 文章, field: 文章内容}
 ```
 
+## 已确认的数组存储适配
+
+实体上结构明确的数组属性，经设计确认可使用varchar或TEXT字符串列序列化保存；不强制拆成关联实体。具体方案必须在列comment中完整定义元素编码、空值/空列表、顺序、单位与无损转换，类型本身仍只使用基础字符串类型，不增加数据库JSON依赖。已知金额数组可以按确认的金额单位采用JSON整数数组，但不能把某项目的币种/编码自动套给所有数组。
+
+存储适配层负责双向转换，读取后业务逻辑拿到数组，后端契约也按数组表达；不得让业务或前端解析数据库序列化字符串。损坏编码不能静默降为空列表，不截断元素、不经浮点舍入；存储容量与业务数组数量约束分开。此规则不允许把未知对象或实体关联打包成字符串来逃避建模。
+
 ## 数据库约束边界
 
 除 `uid` 主键及四个系统列的固定规则外，v1 不设计其他数据库约束：
@@ -156,7 +162,7 @@ v1 只允许以下封闭类型：
 
 accessResponsibilities记录当前输入明确的直接持久操作，不是完整后端执行计划。没有可定位的直接操作可为[]；不代表表不会被访问、没有价值或禁止实现加载。不能因此省略明确的本地持久化表。已知操作不能遗漏，不凭未填写的适配内容发明查询或同步任务；入口已明确将字段映射为本地实体属性时，等值定位已有依据，不再要求额外 SQL 或查询步骤声明。唯一性、查无与多命中仍按已有合同核对，不任取首项。
 
-每项必需source/operations，可选backendContractId/atomic。source只采用当前Graph/Visual稳定身份：
+每项必需source/operations，可选backendContractId/atomic。source采用当前Graph/Visual稳定身份或真实physical绑定中的明确读取责任：
 
 ```yaml
 accessResponsibilities:
@@ -168,17 +174,31 @@ accessResponsibilities:
         predicateColumns: [机构]
 ```
 
-source支持{kind:logic,board,node}、{kind:branch,board,node}、{kind:visualRead,page,read}，类型需与来源一致，不使用旧Paragraph事务。backendContractId指真实契约id，不替代节点身份。
+source支持{kind:logic,board,node}、{kind:branch,board,node}、{kind:visualRead,page,read}及{kind:physicalBinding,path,pointer}。physicalBinding的path为当前输入仓库根相对路径，pointer是解码YAML文档上的JSON Pointer，须定位明确要求读取的说明或声明，例如/说明；读取正文与目标实体/字段要共同核对，不能仅验证文件存在。绑定重命名或结构变化时同步更新。不伪造Visual读名，也不从任意属性访问推断新DB操作。backendContractId指真实契约id，不替代节点身份。
 
-operation必需kind/columns/predicateColumns；kind仅read/insert/update/delete，字段必须在当前业务列中。读取或变更列与筛选列分别说明，不写SQL、索引或物理列名。显式按入参身份更新可有targetInput，必须定位真实Row输入；空predicateColumns不表示全表操作。atomic:true仅当来源已确认原子要求，不声称跨RPC原子性。
+operation必需kind/columns/predicateColumns；kind仅read/insert/update/delete，columns必须在当前业务列中；predicateColumns可引用业务列或已声明的uid系统身份列，用于准确表达按内部关联身份解析。读取或变更列与筛选列分别说明，不写SQL、索引或物理列名。显式按入参身份更新可有targetInput，必须定位真实Row输入；空predicateColumns不表示全表操作。atomic:true仅当来源已确认原子要求，不声称跨RPC原子性。
 
 关联对象已在内存时字段消费不另列DB查询；不能为每个页面值生成独立事务。适配实现尚未确定的访问计划单独反馈，不在正式表文件写TODO或阻塞节点。所有明确写入与delete仍必须记录，delete统一软删除；状态字段赋值“已删除”仍为update，不自行联动is_deleted。
 
 ## 完成检查
 
-- 表集合严格对应adapt承载；身份、实体和扩展来源可解析，无默认推导。
+- 表集合严格对应所选输入模式的承载规则；身份、实体和扩展来源可解析，不凭历史输出推导。
 - Spec+adapt全部属性正常落列，关联目标与身份策略一致，无误加身份映射。
 - 四个系统列完整且固定；类型参数明确，业务列可空无默认，不加业务约束或索引。
 - 已知访问责任来源与字段可核对，空列表不伪装完整执行计划。
 - 表文件没有TODO、占位符、诊断、DDL或运行时物理名映射。
 - DB结构设计检查、Skill格式检查和真实数据库/业务测试是不同结论；未执行的测试不宣称通过。
+
+## 页面实体来源脚本
+
+当前Visual通过页面实体来源脚本读取本地实体时，accessResponsibilities.source使用以下封闭形状：
+
+```yaml
+kind: visualEntitySource
+page: 查询页
+entity: 机构配置
+path: example/spec/domains/示例域/visual/查询页.yaml
+pointer: /页面/实体来源/机构配置
+```
+
+五键必需且不接受其他键。path是当前仓库相对路径，page须与视觉稿正式名称一致，entity须是该来源声明的实体，pointer解析该实体来源完整声明。检查来源脚本的入参与关系查询、基数和实际目标表；不能把普通展示字段读取伪装成新查询。该形状不声明调用顺序或新取数逻辑。

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

@@ -23,7 +23,8 @@
 
 - 每个生成字段可解析到adapt字段及有效实体定义，不丢字段，不凭SOFA响应增字段。
 - 每个绑定要求的结果形状都可表达；资料缺失与调用失败不合并。部分成功策略来自adapt，不由proto设计决定。
-- request/result封闭可有界，静态上限须明确，不填任意常量，也不靠“以后实现决定”声称已可交接。未决定的边界条件报告，不声称已通过运行期验证。
+- request/result具名且结构封闭。契约固定类型、presence、业务语义及来源明确的值域；无业务依据的字符串长度、集合条数等技术容量由backend与profusecontract实现阶段按Saddle要求统一确定并校验，不作为契约交付的前置门槛。不得任填常量，不能用实现容量替代业务长度规则，也不能因此宣称运行时无须容量预算。
+- 缺少业务字段长度设计应记为独立Spec遗留问题，标明尚未明确的字段和影响；在类型、编码、空值及业务结果已明确且不妨碍当前协议表达时不阻塞设计。若确实影响字段语义或无损编码，应说明具体冲突再讨论。
 - 输出唯一契约树：原样固定根模板及业务proto。模板由目标Saddle提供，不修改为业务私有版本。生成代码、部署、SOFA实现、conformance脚本不属于本模块交付。
 - 交接记录proto相对路径、原始bytes SHA-256、package/service/rpc及业务身份，记录输入和runtime版本；过程检查放协作记录，不为了日志在交付目录建第二套协议清单。
 - proto编译成功、两端生成成功、conformance通过和真实联调分别举证；没执行的不要宣称通过。语义或目标runtime未明确只能给候选草稿，不能发布可直接研发的正式协议。

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

@@ -25,7 +25,9 @@
 
 技术异常由框架TechnicalFailure承载，不进入业务result，不复制前端响应信封。前端信封与backend错误策略是另一层；发现不一致先报告，不在接管proto时静默修改其他模块。
 
-request/result具名、封闭且可有界；禁止Any、开放map、任意JSON和裸bytes业务对象。字符串、bytes、集合、嵌套须有明确静态上限；不填任意容量默认值，未明确不能宣称已可供Saddle实现。框架payload bytes不授权业务绕过schema。
+request/result具名、结构封闭；禁止Any、开放map、任意JSON和裸bytes业务对象。契约保留有依据的业务值域，技术容量不由设计者猜填。字符串、bytes、集合及嵌套的静态预算，由backend与profusecontract在实现接入阶段按Saddle要求统一确定并校验；该预算尚未选定不阻塞语义完备的契约交接，但运行验证前仍须落实。框架payload bytes不授权业务绕过schema。
+
+业务长度、存储容量和运行时预算是不同约束。业务长度缺失单独记录为Spec遗留问题；不能把DB列长或实现选定的字节预算反推为业务规则。超限不得静默截断、舍入或把部分结果冒充完整成功。
 
 ## 职责迁移与验收
 

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@antprofuse/saddle-islands-design",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "消费自洽 adapt 与 Islands Spec，设计后端契约、数据库表和 external-contract-proto。",
   "license": "MIT OR Apache-2.0",
-  "files": ["SKILL.md", "agents", "modules", "references"],
+  "files": [
+    "SKILL.md",
+    "agents",
+    "modules",
+    "references"
+  ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/references/adapt.md

@@ -2,11 +2,24 @@
 
 三模块共用。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，不要求Spec理想实体写external、技术主键或外部编码。没有实际写操作不代表不建表；一次对象属性读取也不代表DB或RPC调用。声明缺失先问，不允许消费者隐含推导。
+采用独立adapt模式时，所有实体都应有显式承载及身份声明。承载与身份属于adapt，不要求Spec理想实体写external、技术主键或外部编码。没有实际写操作不代表不建表；一次对象属性读取也不代表DB或RPC调用。声明缺失先问，不允许消费者隐含推导。
 
 ## 实体承载与身份
 
@@ -98,3 +111,7 @@ Dependency与external-contract只在逻辑锚点上不同：前者目标指向Sp
 实体绑定位置用 `{path, domain, entity}`，入口位置用 `{path, domain, board, entry}`，入口字段再加field。路径与语义目标必须同时匹配，不使用数组下标。关联随当前分支的Spec+adapt内容重新核对。
 
 入口按每个绑定一个文件交付，顶层为业务域、目标、外部入参、实体映射、适配，不使用入口数组。文件名优先为入口名.binding.yaml；同名入口冲突时以板块名限定文件名，身份仍由业务域和目标确定。仅接受新形状，迁移时同步所有path引用，不保留旧聚合文件或双读规则；保持既有适配逻辑原文。
+
+## 当前输入的状态与存储边界
+
+事务创建、状态迁移或中断表达逻辑行为，不自动声明本地持久化表、支付回传接口或同步任务。先核对实体来源及后续真实消费者；外部构造实体不能因拥有状态而复制为本地表。前端平台中断结果用于本次页面分支时，按输入衔接同一实例，不替输入增加业务留存需求。

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

@@ -1,59 +0,0 @@
-# Prototype 与测试覆盖关联
-
-覆盖元数据与后端契约同生命周期，放在每份后端契约文件顶层 `coverage`，不进入线上请求/响应，也不是运行测试日志。实体 source 表达字段业务来源，callSites 表达调用位置，coverage 表达为何足以支撑输入要求；三者不能互相替代。
-
-针对当前Islands，先读取test list及相关test show的正式责任与操作断言。逻辑测试的Row身份、世界数据库、Mock不能直接要求生产生成对应表或身份token：根据adapt承载重述其业务义务，保留正确对象、依赖实参、本次答复及不写入等保证。无法对应时报告，不把责任编号存在当作全覆盖。Prototype组件通过Visual稳定语义定位，并检查实际原型消费，不只挂页面总链接。
-
-跨字段、归属和空值条件应先进入output或所属object的invariants，coverage约束项可指向该数组。页面显示事实、后端保障和纯前端动作分别核对；不为已确认由后端保证的关系重复身份字段，也不以此删除对应测试义务。扩展字段保留倾向须用户确认，不将未消费字段虚构为Prototype责任。
-
-## 形状
-
-`coverage` 为非空数组，每项必填且只允许 `id / prototypes / tests / obligations`。id 是文件内唯一的稳定语义标识，不使用数组序号。
-
-- prototypes：Prototype 来源数组，每项必填且只允许 `path / selector`。
-- tests：测试来源数组，同样两个必填键。selector 为真实测试责任/case ID；脚本没有独立 ID 时用文件内唯一的完整测试名称，不自创 ID。
-- path：当前仓库根目录相对文件路径；selector：当前分支内可唯一解析的页面/组件/动作/状态或测试身份。所有关联只解析当前仓库当前分支，禁止跨仓库、跨分支或固定历史版本定位；不接受仓库地址、分支名或提交号等额外键。禁止仅用行号、数组下标或样例别名。
-- 每项 prototypes/tests 至少一个非空；每份后端契约两类来源都必须非空。原型独有显示责任可无 tests，测试独有边界责任可无 prototypes，但必须参与全量核对，不能人为删空掩盖已有对应来源。
-- obligations：非空数组。每项必填且只允许 `aspect / requirement / targets / explanation`。
-- aspect：封闭枚举 `input / output / constraint / frontend`。requirement 是来源中具体操作、展示或断言的准确含义；不是另造需求。explanation 说明目标如何完整支撑该责任，含必要前置事实和适用条件。
-- targets：指向**当前后端契约 YAML 文档**的非空 JSON Pointer 数组，如 `/input/fields/当前绑定`、`/output/cases/查询暂不可用/payload/fields/原因`。转义按 JSON Pointer：`~` 为 `~0`，`/` 为 `~1`。目标必须存在，不是线上 JSON 路径；不得指向 coverage 自身。不得使用样例行号或不稳定数组下标；约束可指向所属 invariants 数组整体，并在 explanation 精确引用其语义，错误码可指向 errors 整体并写明具体 code。空 targets 只允许 frontend 且确实完全不消费后端契约数据的行为，必须说明无需后端契约的依据。
-
-结构示意（以下来源字符串需替换为实际输入，不能原样作为交付）：
-
-```yaml
-coverage:
-  - id: non_service_hours
-    prototypes:
-      - path: <原型文件>
-        selector: <非服务时段分支的真实身份>
-    tests:
-      - path: <测试文件>
-        selector: <非服务时段测试的真实case ID>
-    obligations:
-      - aspect: output
-        requirement: 展示非服务时段原因及服务起止时间。
-        targets:
-          - /output/cases/查询暂不可用/payload/fields/原因
-          - /output/cases/查询暂不可用/payload/fields/每日服务开始时间
-          - /output/cases/查询暂不可用/payload/fields/每日服务结束时间
-        explanation: 该场景返回原因非服务时段，两时间非空且与来源预期一致，足以支持原型展示和测试断言。
-      - aspect: constraint
-        requirement: 被服务时段拦截时不执行账单查询。
-        targets: [/output/cases/查询暂不可用/invariants]
-        explanation: 对应本分支在读取账单前返回的约束，不能只靠返回错误页面而忽略禁止查账的责任。
-      - aspect: frontend
-        requirement: 返回来源页。
-        targets: []
-        explanation: 来源中的返回行为不提交业务变更也不消费新增数据，无需额外后端契约。
-```
-
-## 如何证明完整
-
-1. 从实际 Prototype 和测试责任清单取得指定范围的完整分母，不能从已经写出的后端契约反推分母。逐项辨认前置事实、动作、预期显示、断言、禁止副作用和后续交互。纯样式/导航等纯前端责任明确分类，不为覆盖它们造后端契约。
-2. 每个后端契约的 coverage 只声明本接口承担的部分。同一用例涉及多个后端契约时，各自映射其负责的操作/断言，按相同来源身份汇总后证明整条用例被支撑；不共享业务 schema，也不要求一用例一接口。
-3. 对每条关联实际推演：动作值能否形成合法 input；系统身份是否仍由系统提供；预期结果是否落到正确输出分支；字段、枚举、nullable、顺序和关联是否足够；写入/不写入及后续页面行为是否符合预期。仅验证 path/selector/target 存在不算语义覆盖。
-4. 反向检查各调用点、业务结果、叶字段及约束可追溯到两类基准的需求或为满足它们所必需的实体投影。系统通用信封遵守既有规范，不为其伪造业务测试。Form/Rule 来源规则保持，但不能借机自造实体、展示包装或技术字段。有限样例不定义完整枚举。
-5. 汇总所有后端契约的关联，检查输入分母的所有项。完全独立且无需后端契约的纯前端项在交付 review 中逐项说明，无需为其创建空后端契约文件；消费当前后端契约输出的后续前端项留在该文件 coverage 内。未覆盖责任和冲突在过程反馈中列明，不能把缺口写成“已覆盖”或以 fail-closed 错误替代已要求的业务结果。
-6. Prototype 或测试更新时，在当前分支重新核对path/selector与obligations；后端契约schema变化时重核targets和覆盖语义。关联随当前分支内容共同演进，不通过固定历史快照规避输入变化。
-
-设计完备表示当前指定 Prototype 与测试用例全部得到支撑，并且字段业务来源、协议类型等契约检查成立。不是已完成生产实现、测试已运行或所有业务理论情况被穷举。来源缺失、冲突或无法定位时，不自行扩充所有 Spec 需求或补写测试来制造完备；报告并继续不受影响部分。