@antprofuse/saddle-db-design 0.1.0 → 0.1.1

package/SKILL.md

@@ -1,46 +1,45 @@
 ---
 name: saddle-db-design
-description: 在 Saddle 后端研发前，从 Islands Spec 与已确认的前后端 API 契约设计可追溯的数据库表结构 YAML。适用于判定内部持久化实体、定义字段类型与约束、设计索引和关联，并报告局部输入缺口。不用于 API 设计、外部 RPC 设计、生成 SQL 或编写数据库访问代码。
+description: 在 Saddle 后端研发前，从已编译 Islands Spec 设计可追溯的逻辑数据库表契约。适用于判定 Saddle 持久化实体、定义字段与基础 MySQL 类型、关联 Logic 事务访问责任，并报告局部输入缺口。不用于 API、External RPC、物理表名映射、索引优化、DDL 或数据库访问代码设计。
 ---
 
 # Saddle DB 设计
 
-为 Saddle 后端需要持久化的内部业务实体产出完整、自包含、可追溯的表结构 YAML。数据库是 API 后端实现与持久化之间的边界，不能反向决定前后端 API。
+从 Islands Spec 确定性产出 Saddle 拥有的逻辑表契约。数据库设计覆盖 API、系统事务、定时任务、消息和回调等全部 Saddle 持久化责任；前端 API 只是可选入口，不是建表前提。
 
-执行前必须阅读 [references/db-table-v1.md](references/db-table-v1.md)。遇到实体归属、生命周期、字段来源、唯一性、类型、关联或索引无法唯一确定时，阅读 [references/findings.md](references/findings.md)。
+执行前必须阅读 [references/db-table-v1.md](references/db-table-v1.md)。遇到实体归属、生命周期、字段来源、类型或事务责任无法唯一确定时，阅读 [references/findings.md](references/findings.md)。
 
 ## 输入
 
 - 用户明确提供的交付目录；不得自行改用固定仓库路径。
-- 已编译 Islands Spec 中相关 Structure、Logic、Rule、Visual 与 Test Responsibility。
-- 已确认的前后端 API 契约，尤其是字段来源、派生依赖和调用责任。
-- 当前 Saddle 数据库平台已经确认的物理能力；不得从旧 Harness 规范继承未经确认的策略。
+- 已编译 Islands Spec 中相关 Structure、Logic、Rule 与 Test Responsibility。
+- 已确认的 API 契约可作为事务入口证据，但不是必需输入。
 
 ## 工作流程
 
-1. 先按 API 后端责任识别需要持久化的业务事实，再回到 Structure 判断实体归属与生命周期。不能看到实体就机械建表。
-2. 将实体分类为内部持久化、外部事实或瞬时/派生事实。只有内部持久化实体进入表设计。
-3. 每个内部持久化实体产出一个 v1 表结构 YAML；逐字段关联 Structure，并明确物理类型、nullable、主键、唯一约束、关联和索引。
-4. 使用 API access pattern 证明表和索引服务于哪些读写责任。不能用“以后可能查询”增加字段或索引。
-5. 跨文件检查表名、列名、约束名全局唯一，引用目标存在且类型兼容。
-6. 只交付完整表文件。局部不确定项写入 findings，并继续设计不受影响的实体。
+1. 从 Logic 生命周期识别必须跨事务保留并在后续读取、更新或判定的事实。
+2. 回到 Structure 确认实体所有权。只有未声明 `external: true` 的实体才可能建表；本地所有权不自动等于需要持久化。
+3. 每个需要持久化的具体实体产出一个完整表契约。表与业务列原样复用 Structure 实体和字段身份，并包含全部 Structure 字段。
+4. 子实体表展开全部继承字段。父实体只有存在独立持久化生命周期时才单独建表。
+5. 精确关联每个访问该表的 Logic 事务及其读写字段。事务由 API 承载时可附加 `apiId`，但不得用 API 身份替代 Logic 事务身份。
+6. 跨文件检查逻辑表身份唯一、字段来源可解析、关联目标存在、类型完整。
+7. 只交付完整表文件。局部不确定项按 findings 规则报告，不用临时字段、宽泛类型或冗余表绕过。
 
 ## 产出
 
-在用户提供的交付目录中写入：
-
-- 每个内部持久化实体一个 `<table_name>.table.yaml`；
-- 存在问题时写一个 `db-design-findings.yaml`。
+- 在用户指定的 DB 交付目录中，每个持久化实体产出一个 `<Structure实体名>.table.yaml`。
+- DB 交付目录只放正式表契约。Findings 写入用户指定的过程协作位置；未指定时直接反馈给用户，不在交付目录落盘。
 
 使用 [assets/table.template.yaml](assets/table.template.yaml) 作为起始结构。交付文件不得包含 TODO、占位符、阻塞标记或诊断节点。
 
-不生成、拼接、维护或要求 `structure.sql`。DDL 与迁移脚本属于后续确定性生成和部署工作，不是本 Skill 的设计产物。
+不生成物理表名/列名映射、索引、外键、唯一约束、CHECK、DDL、迁移脚本或数据库访问代码。Saddle 的必填映射能力只负责逻辑表名/列名到物理标识符的映射，不拥有其他表结构设计权。
 
-## 边界
+## 固定边界
 
-- API 先于 DB；表结构必须链接其支持的 API 后端责任，但 API 字段不必机械等同于数据库列。
-- 标记为外部、外部共享、外部只读或由 external 能力维护的实体不建本地表。
-- 查询响应、页面模型、统计值、当次外部快照和可重新计算派生值默认不建表；只有 Spec 明确要求跨请求持久保存且生命周期闭合时才可进入表。
-- 不默认增加代理主键、审计时间、软删除、版本号、租户字段或状态列。每个字段都必须有明确来源或已确认的工程必要性。
-- 不默认禁用或启用外键、CHECK、JSON、生成列、触发器等能力；v1 中未定义的物理能力产出 `unsupported-shape` finding，等待后续版本扩展。
+- 表契约使用 MySQL 基础类型，但逻辑表名和业务列名保持 Islands 原始业务概念。
+- 每张表固定使用 `uid`、`gmt_create`、`gmt_modified`、`is_deleted` 四个系统列；业务 Agent 不增删或改写其语义。
+- 所有业务字段允许 `NULL`，且不设置数据库默认值。必填、枚举、值域、业务唯一性和关联完整性由 Saddle 业务逻辑负责。
+- 不设计业务唯一约束、普通索引或数据库外键。索引属于运行后的观测与运维优化。
+- 实体关联字段保留 Structure 的关联业务语义，值存储目标实体 `uid`。同一目标的多重关联依靠原始角色语义区分，例如卖家与买家。
+- 删除统一为软删除。Saddle 数据访问层必须对普通读取强制过滤 `is_deleted = false`；业务查询不得各自实现这条规则。
 - 一个不完整实体只阻塞对应表，不阻塞其他完整表的交付。

package/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
   display_name: "Saddle DB 设计"
-  short_description: "从 Islands Spec 与 API 契约设计可追溯的表结构"
+  short_description: "从 Islands Spec 设计可追溯的逻辑表契约"

package/assets/table.template.yaml

@@ -1,19 +1,45 @@
 schemaVersion: saddle-db-table/v1
 entity:
   source: {entity: 替换为内部持久化实体}
-  persistenceReason: 替换为可追溯的持久化原因。
+  persistenceReason: 替换为可追溯的跨事务持久化原因。
 table:
-  name: replace_with_table_name
+  name: 替换为同一个Structure实体名
   comment: 替换为表的业务语义。
+systemColumns:
+  uid:
+    type: {kind: varchar, length: 32}
+    nullable: false
+    primaryKey: true
+    generation: {owner: saddle, algorithm: uuid_v7, format: lowercase_hex_without_hyphens}
+  gmt_create:
+    type: {kind: datetime, precision: 3}
+    nullable: false
+    default: current_timestamp
+    maintainedBy: database
+  gmt_modified:
+    type: {kind: datetime, precision: 3}
+    nullable: false
+    default: current_timestamp
+    onUpdate: current_timestamp
+    maintainedBy: database
+  is_deleted:
+    type: {kind: boolean}
+    nullable: false
+    default: false
+    maintainedBy: saddle
+    readPolicy: exclude_deleted_by_default
 columns:
-  replace_with_identity_column:
+  替换为Structure字段名:
     type: {kind: varchar, length: 64}
-    nullable: false
-    comment: 替换为字段语义。
-    source: {entity: 替换为内部持久化实体, field: 替换为稳定身份字段}
-primaryKey:
-  columns: [replace_with_identity_column]
-uniqueConstraints: []
-indexes: []
-references: []
-apiResponsibilities: []
+    nullable: true
+    comment: 替换为字段业务语义。
+    source: {entity: 替换为字段声明实体, field: 替换为Structure字段名}
+accessResponsibilities:
+  - transaction:
+      paragraph: 替换为段落
+      branch: 替换为分支
+      transactionId: 替换为事务ID
+    operations:
+      - kind: read
+        columns: [替换为Structure字段名]
+        predicateColumns: []

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antprofuse/saddle-db-design",
-  "version": "0.1.0",
-  "description": "从 Islands Spec 与 API 契约设计可追溯的 Saddle 数据库表结构。",
+  "version": "0.1.1",
+  "description": "从 Islands Spec 设计可追溯的 Saddle 逻辑数据库表契约。",
   "license": "MIT OR Apache-2.0",
   "files": ["SKILL.md", "agents", "assets", "references"],
   "publishConfig": {"access": "public", "registry": "https://registry.npmjs.org/"}

package/references/db-table-v1.md

@@ -1,10 +1,12 @@
-# Saddle DB 表结构 v1
+# Saddle DB 逻辑表契约 v1
 
-## 设计单位与文件身份
+## 设计单位与身份
 
-一个 `*.table.yaml` 只定义一个内部持久化实体的一张表。v1 不支持一个实体拆多表或多实体合表；遇到该场景产出 `unsupported-shape` finding。
+一个 `*.table.yaml` 只定义一个 Saddle 内部持久化实体的一张逻辑表。v1 不支持一个实体拆多表或多实体合表；遇到该场景产出 `unsupported-shape` finding。
 
-文件固定命名为 `<table_name>.table.yaml`。`table.name` 必须是全局唯一的 snake_case 标识符，并与文件名去掉 `.table.yaml` 后原样一致。
+逻辑表身份直接复用 Islands Structure 实体名。文件固定命名为 `<Structure实体名>.table.yaml`，`table.name`、`entity.source.entity` 和文件名 stem 必须原样一致。中文业务身份合法，不翻译为物理标识符。
+
+Saddle 的必填物理映射配置负责逻辑表名/列名到 MySQL 表名/列名的映射。映射层只改名字，不得改变字段集合、类型、nullable、默认值、主键或系统语义；物理映射不属于本 Skill 产物。
 
 ## 完整结构
 
@@ -12,185 +14,194 @@
 schemaVersion: saddle-db-table/v1
 entity:
   source: {entity: 用户账单}
-  persistenceReason: 用户账单由本系统创建并跨请求保留，供查询与状态更新使用。
+  persistenceReason: 用户账单由本系统创建并跨事务保留，供后续查询和状态更新。
 table:
-  name: user_bill
+  name: 用户账单
   comment: 用户账单持久化事实
-columns:
-  bill_id:
-    type: {kind: varchar, length: 64}
+systemColumns:
+  uid:
+    type: {kind: varchar, length: 32}
     nullable: false
-    comment: 用户账单稳定标识
-    source: {entity: 用户账单, field: 账单ID}
-  user_id:
-    type: {kind: varchar, length: 64}
+    primaryKey: true
+    generation: {owner: saddle, algorithm: uuid_v7, format: lowercase_hex_without_hyphens}
+  gmt_create:
+    type: {kind: datetime, precision: 3}
     nullable: false
-    comment: 账单所属用户标识
-    source: {entity: 用户账单, field: 用户ID}
-  amount:
-    type: {kind: decimal, precision: 18, scale: 2}
+    default: current_timestamp
+    maintainedBy: database
+  gmt_modified:
+    type: {kind: datetime, precision: 3}
     nullable: false
-    comment: 应缴金额，单位为人民币元，按业务金额规则舍入。
-    source: {entity: 用户账单, field: 应缴金额}
-  bill_status:
-    type: {kind: varchar, length: 32}
+    default: current_timestamp
+    onUpdate: current_timestamp
+    maintainedBy: database
+  is_deleted:
+    type: {kind: boolean}
     nullable: false
-    comment: 账单状态
-    source: {entity: 用户账单, field: 账单状态}
-primaryKey:
-  columns: [bill_id]
-uniqueConstraints: []
-indexes:
-  - name: idx_user_bill_user_status
-    columns:
-      - {column: user_id, order: asc}
-      - {column: bill_status, order: asc}
-    purpose: 支持按当前用户和账单状态查询账单。
-    supports:
-      - {apiId: query_user_bill, accessPattern: 按用户与状态过滤}
-references: []
-apiResponsibilities:
-  - apiId: query_user_bill
+    default: false
+    maintainedBy: saddle
+    readPolicy: exclude_deleted_by_default
+columns:
+  账单标识:
+    type: {kind: varchar, length: 64}
+    nullable: true
+    comment: 用户账单的业务标识
+    source: {entity: 用户账单, field: 账单标识}
+  所属用户:
+    type: {kind: varchar, length: 32}
+    nullable: true
+    comment: 关联用户的 uid
+    source: {entity: 用户账单, field: 所属用户}
+    storesEntityUid: {entity: 用户}
+  应缴金额:
+    type: {kind: decimal, precision: 18, scale: 2}
+    nullable: true
+    comment: 应缴金额，单位为人民币元
+    source: {entity: 用户账单, field: 应缴金额}
+accessResponsibilities:
+  - transaction:
+      paragraph: 账单域·账单维护
+      branch: 主分支
+      transactionId: 创建用户账单
+    apiId: create_user_bill
     operations:
-      - kind: read
-        columns: [bill_id, user_id, amount, bill_status]
-        predicateColumns: [user_id, bill_status]
-  - apiId: update_user_bill_status
+      - kind: insert
+        columns: [账单标识, 所属用户, 应缴金额]
+        predicateColumns: []
+  - transaction:
+      paragraph: 账单域·账单维护
+      branch: 主分支
+      transactionId: 查询用户账单
     operations:
-      - kind: update
-        columns: [bill_status]
-        predicateColumns: [bill_id]
+      - kind: read
+        columns: [账单标识, 所属用户, 应缴金额]
+        predicateColumns: [所属用户]
 ```
 
-顶层字段 `schemaVersion / entity / table / columns / primaryKey / uniqueConstraints / indexes / references / apiResponsibilities` 全部必填。没有内容的集合显式写 `[]`，禁止未知顶层字段。
+顶层字段 `schemaVersion / entity / table / systemColumns / columns / accessResponsibilities` 全部必填，禁止未知顶层字段。示例中的 `apiId` 可省略；其他示例身份和内容必须替换为真实编译来源。
+
+## 持久化判定
+
+DB 设计覆盖 Saddle 拥有的全部持久化事实，不以是否存在前端 API 为边界。只有同时满足以下条件的实体才产出表：
 
-## Entity 与持久化判定
+1. 实体未声明 `external: true`；
+2. Logic 明确要求该事实跨事务保留；
+3. 后续 Logic 会读取、更新、删除或据此判定；
+4. 实体生命周期和所有权可以唯一确定。
 
-`entity.source` 使用 Islands Structure 的稳定实体身份。`persistenceReason` 说明为什么该业务事实必须由 Saddle 跨请求保存，并必须能从 Logic 生命周期和 API 后端责任得到证明。
+以下内容不建表：`external: true` 的实体；只由外部 SOFA RPC 维护的事实；页面状态、API response model 或请求内临时对象；一次 External 调用的临时快照；没有独立持久化生命周期的可重算结果。
 
-以下内容不得产出表文件：
+“页面需要展示”“API 需要返回”或“Structure 中存在实体”本身都不构成持久化理由。
 
-- Spec 标记为 external、外部共享或外部只读的实体；
-- 由真实外部 SOFA RPC 负责维护的业务事实；
-- 页面状态、API response model、统计结果与可重新计算派生字段；
-- 只在一次请求或一次外部查询中成立的快照；
-- 生命周期、唯一身份或所有权尚未闭合的候选实体。
+## 实体与继承
 
-“页面需要展示”或“API 需要返回”本身不构成持久化理由。
+一个需要持久化的具体实体对应一张逻辑表，并包含其全部 Structure 字段。子实体表直接展开父实体继承的全部字段；继承字段的 `source` 指向其原始声明实体和字段。父实体只有存在独立持久化生命周期时才单独建表。v1 不设计父子表连接或其他数据库继承策略。
 
-## 表与列命名
+## 系统列
 
-表名、列名、约束名和索引名均使用完整、无歧义的英文 snake_case，不使用缩写。表名和列名分别在其作用域内唯一。
+每张表的 `systemColumns` 必须与固定结构完全一致：
 
-表名、列名及命名对象格式为 `^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$`。名称必须稳定，实现层不得再次重命名。
+- `uid`：唯一主键。Saddle 应用侧生成标准 UUIDv7，去掉中横线后保存为 32 位小写十六进制字符串；不增加严格单调等自定义扩展。
+- `gmt_create`：`DATETIME(3)`，数据库使用 `DEFAULT CURRENT_TIMESTAMP(3)` 维护。
+- `gmt_modified`：`DATETIME(3)`，数据库使用 `DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3)` 维护。
+- `is_deleted`：布尔值，数据库默认 `false`；Logic 删除由 Saddle 更新为 `true`，数据库随之更新 `gmt_modified`。
 
-## 列来源
+表契约不规定数据库实例或会话时区；`DATETIME` 的环境时间语义属于运维配置。
 
-每个业务列必须具有且仅具有一个直接 Structure 来源：
+Saddle 数据访问层必须对所有普通读取强制施加 `is_deleted = false`。只有明确的恢复、审计或运维能力可以读取已删除记录。普通业务查询不得自行重复实现或绕过默认过滤。关联到已软删除记录时，业务上视为目标不存在。
+
+## 业务列与来源
+
+`columns` 必须包含实体的全部 Structure 字段。每个业务列名原样复用 Structure 字段名，并具有且仅具有一个直接来源：
 
 ```yaml
 source: {entity: 用户账单, field: 账单状态}
 ```
 
-v1 不把派生值作为持久化列。若业务明确要求保存派生结果，但其刷新时机、一致性和来源依赖已经闭合，产出 `unsupported-shape` finding 以驱动后续格式扩展，不能先用自然语言列绕过。
+所有业务列固定 `nullable: true`，不允许 `default` 或 `onUpdate`。Structure 的必填、枚举和值域仍是业务规则，由 Saddle 逻辑校验，不下沉为数据库约束。
+
+关联字段保留原始业务角色名，并存储目标实体的 `uid`：
 
-不得默认增加 `id`、`created_at`、`updated_at`、`deleted`、`version`、`tenant_id` 等工程字段。只有它们已是 Structure 字段或存在已确认、可追溯的系统级持久化规范时才能加入；v1 暂不定义自由 `systemField`。
+```yaml
+卖家:
+  type: {kind: varchar, length: 32}
+  nullable: true
+  source: {entity: 订单, field: 卖家}
+  storesEntityUid: {entity: 用户}
+买家:
+  type: {kind: varchar, length: 32}
+  nullable: true
+  source: {entity: 订单, field: 买家}
+  storesEntityUid: {entity: 用户}
+```
 
-## 物理类型
+同一目标实体被多次关联时，以 Structure 中不同的关联角色区分。不得改成含义不清的统一“用户”列，也不建立数据库外键。
 
-v1 面向 Saddle 当前 MySQL/MariaDB 数据源，允许以下封闭类型：
+## 基础 MySQL 类型
+
+v1 只允许以下封闭类型：
 
 ```yaml
 {kind: varchar, length: 64}
-{kind: text}
-{kind: signed_integer, bits: 32}
-{kind: signed_integer, bits: 64}
-{kind: unsigned_integer, bits: 32}
-{kind: unsigned_integer, bits: 64}
+{kind: bigint}
 {kind: decimal, precision: 18, scale: 2}
 {kind: boolean}
 {kind: date}
-{kind: datetime, precision: 6}
-{kind: binary, length: 32}
+{kind: datetime, precision: 3}
 ```
 
-规则：
-
-- `varchar.length` 与 `binary.length` 必须是正整数，来自业务最大长度或已确认编码上界，不能随意统一为 255。
-- integer 的 signed 与 bits 必须由值域证明。
-- decimal 必须明确 precision、scale、单位及舍入语义；单位写入 comment，舍入语义来自 Structure/Rule。
-- `date` 表示 `YYYY-MM-DD` 业务日期；`datetime` 表示精确时刻，必须有统一时区语义。
-- 枚举在 v1 中映射为具有充分 length 的 `varchar`，合法值仍由 Structure 枚举定义；DB CHECK 策略尚未纳入 v1。
-- JSON、浮点数、数据库 enum、blob、timestamp、生成列及其他类型不在 v1 中，遇到时产出 `unsupported-shape` finding。
+- `varchar.length` 必须是正整数，并有 Structure 值域、编码上界或已确认业务约束；不得任意统一为 255。
+- `bigint` 固定生成 MySQL 64 位有符号整数。
+- `decimal` 必须明确 precision、scale 和单位；精度与小数位来自 Structure/Rule。
+- `boolean` 固定生成 MySQL `TINYINT(1)`，但契约保留布尔业务语义。
+- `date` 表示业务日期。
+- `datetime` 必须明确 precision；系统时间列固定为 3。
+- 枚举使用能够容纳全部合法值的 `varchar`；合法值由业务逻辑校验，不生成数据库 ENUM 或 CHECK。
+- JSON、TEXT、BLOB、浮点数、TIMESTAMP、数据库 ENUM、生成列等不在 v1 中；确定需要时产出 `unsupported-shape` finding。
 
-API 类型不能单独决定 DB 类型；必须结合 Structure 值域、持久化语义和查询需求。
+## 数据库约束边界
 
-## Nullable
+除 `uid` 主键及四个系统列的固定规则外，v1 不设计其他数据库约束：
 
-`nullable` 表示持久化事实是否允许缺失，不表示页面暂时不展示、API 字段可选或 external 偶发未返回。
+- 不使用复合主键或自增主键；
+- 不建立业务唯一约束；
+- 不建立数据库外键；
+- 不建立普通索引；
+- 不生成 CHECK、触发器或业务默认值。
 
-必须从实体生命周期证明 nullable。若字段仅在某状态后产生，需要确认是允许 NULL、拆分实体，还是业务模型缺少状态事实；DB Skill 不自行选择。
+业务唯一性、关联一致性、必填和值域校验由 Saddle 业务逻辑实现。索引属于系统运行后的性能观测和运维优化，不在初始表结构设计阶段预判。
 
-## 主键与唯一约束
+## Logic 事务访问责任
 
-`primaryKey.columns` 是非空列数组。主键优先使用 Structure 已定义的稳定实体身份，不能默认制造代理主键。
-
-复合业务身份使用 `uniqueConstraints`：
+`accessResponsibilities` 穷举当前表支持的 Logic 事务读写责任。事务身份必须通过 Islands Compiler 元数据唯一解析：
 
 ```yaml
-uniqueConstraints:
-  - name: uq_user_bill_user_period
-    columns: [user_id, bill_period]
-    reason: 同一用户同一账期最多存在一张本系统账单。
-    evidence:
-      - {entity: 用户账单, fields: [用户ID, 账期]}
+transaction:
+  paragraph: 查缴域·查账
+  branch: 主分支
+  transactionId: 查询并形成欠费单
 ```
 
-唯一性必须由 Structure/Logic 明确证明；案例数据不构成唯一性证据。
-
-## References
-
-跨内部表关联显式写入：
-
-```yaml
-references:
-  - name: ref_user_bill_user
-    columns: [user_id]
-    target:
-      entity: 用户
-      table: user
-      columns: [user_id]
-    enforcement: logical
-    reason: 当前平台尚未确认使用数据库外键约束，由后端保持引用一致性。
-```
-
-`enforcement` v1 只允许 `logical`。是否启用数据库 FOREIGN KEY 尚未形成平台统一规范，不由业务 Agent 自行打开。
-
-引用 external 实体时不能建立目标表或 reference；只在本实体确有业务需要时保存 external 的稳定标识字段。
-
-## Indexes 与 API responsibility
-
-索引必须由已确认 API 的实际访问模式证明。每个索引包含稳定 name、有序 columns、purpose 和至少一个 supports。
+事务可以来自人工 API、系统事务、定时任务、消息或回调。`apiId` 仅在该事务由已确认前端 API 承载时出现，并必须解析到对应 API 契约。
 
-`apiResponsibilities` 穷举当前表支持的 API 读写责任：
+每个 operation：
 
 - `kind` 只允许 `read / insert / update / delete`；
-- `columns` 是读取、插入或变更的列；
-- `predicateColumns` 是定位或过滤使用的列；
-- `apiId` 必须解析到已确认 API 契约。
+- `columns` 精确列出读取、插入或变更的逻辑业务列；
+- `predicateColumns` 精确列出定位、关联或筛选使用的逻辑业务列；
+- 不记录 SQL、索引或物理列名；
+- `delete` 表达 Logic 删除语义，运行时固定执行软删除，不执行物理 `DELETE`。
 
-不要求每个 predicate 都单独建立索引；应按组合过滤、排序、唯一性和预期访问方式形成最小充分索引。没有 API 或 Logic 证据的预防性索引禁止加入。
+系统列生成、时间维护和默认软删除过滤是 Saddle 固定责任，不在每个 operation 中重复列出。
 
 ## 完成门禁
 
-表文件可交付必须满足：
-
-1. 实体已证明为内部持久化实体；
-2. 文件名与 `table.name` 原样一致且全局唯一；
-3. 每个业务列都能解析到唯一 Structure 字段；
-4. 类型参数、nullable、主键与唯一性均有依据；
-5. reference 目标存在、列数和类型一致；
-6. 每个索引都有 API/Logic 访问证据；
-7. 每个 `apiId` 都能解析到已确认 API；
-8. 不存在 external 多建表、瞬时数据落库、TODO、占位符或诊断标记；
-9. 交付目录中不存在本 Skill 生成的 `structure.sql`。
+1. 实体已证明为 Saddle 内部持久化实体，且不是 `external: true`；
+2. 文件名、`table.name` 和 Structure 实体身份原样一致；
+3. 表包含固定且完整的四个系统列；
+4. 全部 Structure 字段均出现，且每个业务列解析到唯一 Structure 字段；
+5. 关联字段明确存储目标实体 `uid`，多重关联角色无歧义；
+6. 类型参数完整，全部业务字段 nullable 且无默认值；
+7. 每个 Logic 事务身份可解析，字段访问责任完整；
+8. 不存在业务唯一约束、普通索引、外键、物理映射、TODO、占位符或诊断节点；
+9. 交付目录中不存在本 Skill 生成的 findings、DDL、迁移脚本或 `structure.sql`。

package/references/findings.md

@@ -1,6 +1,8 @@
 # DB 设计 Findings v1
 
-当输入不足或 v1 格式不支持某个确定需求时，在用户指定的交付目录写入 `db-design-findings.yaml`：
+当 Islands Spec 或 v1 格式无法支持完整表契约时，报告 DB finding。Finding 是过程诊断，不是正式 DB 交付物，也不授权 Agent 创建临时字段、宽泛类型、冗余表或物理约束绕过问题。
+
+DB 交付目录只放完整的 `*.table.yaml`。用户指定过程协作位置时，可在那里写入 `db-design-findings.yaml`；未指定时直接向用户反馈，不自行在交付目录或其他仓库落盘。
 
 ```yaml
 findingsVersion: saddle-db-findings/v1
@@ -13,15 +15,23 @@ findings:
       path: entity.persistenceReason
     evidence:
       - {kind: structureEntity, entity: 欠费单}
-      - {kind: apiContract, apiId: query_bill}
-    message: 欠费单被标记为外部共享的当次查询事实，当前没有本系统持久化生命周期证据。
-    requiredUpstreamChange: 明确该事实由外部实时提供，或补齐由 Saddle 创建、更新和失效的生命周期。
+      - {kind: logicTransaction, paragraph: 查缴域·查账, branch: 主分支, transactionId: 查询并形成欠费单}
+    message: 当前只能确认欠费单来自一次外部查询，不能证明 Saddle 需要跨事务持久保存。
+    requiredUpstreamChange: 明确该事实只在请求内使用，或补齐由 Saddle 创建、读取、更新或删除的跨事务生命周期。
 ```
 
 必填字段为 `id / severity / category / affected / evidence / message / requiredUpstreamChange`。
 
 严重程度为 `blocker / warning`。
 
-v1 分类：`persistence-ownership-unknown / external-entity-local-table-conflict / missing-entity-identity / missing-field-source / missing-type-bound / nullable-ambiguous / unique-constraint-ambiguous / reference-target-missing / api-responsibility-missing / unsupported-shape`。
+v1 分类：
+
+- `persistence-ownership-unknown`
+- `external-entity-local-table-conflict`
+- `missing-field-source`
+- `missing-type-bound`
+- `association-target-ambiguous`
+- `logic-responsibility-missing`
+- `unsupported-shape`
 
-Finding 必须精确到实体、表或字段。一个实体的问题不能阻塞其他完整表文件。Finding 不进入 `*.table.yaml`，也不授权 Agent 创建临时字段、宽泛类型或冗余表来绕过问题。
+Finding 必须精确到实体、字段或 Logic 事务。一个实体的问题不能阻塞其他完整表文件。Evidence 优先使用 Islands Compiler 的稳定身份，不得只使用源码行号。