@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/test/test_run_batch_post_build_recovery.py

@@ -0,0 +1,65 @@
+from pathlib import Path
+import sys
+
+SCRIPTS = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SCRIPTS))
+
+import cosmic_api
+
+
+def test_post_phase_failure_keeps_successfully_saved_root_and_exact_repair_input(tmp_path):
+    artifact = tmp_path / "check_in.json"
+    payload = {"status": True, "data": {"entityResults": [{
+        "success": True, "formId": "SAVED-FORM", "formNumber": "uhyl_check_in",
+        "formName": "入住单",
+    }]}}
+    summary = {"ok": True, "formNumbers": [{"number": "uhyl_check_in", "name": "入住单"}]}
+    pending = {"command": "modifyMeta", "input": {"formId": "SAVED-FORM", "ops": [{"op": "add"}]}}
+    cosmic_api._attach_post_build_phase_failure(
+        summary, payload, phase="addRefBill", app_root=str(tmp_path),
+        artifact_path=str(artifact), pending_write=pending,
+    )
+    public = cosmic_api._apply_build_failure_contract(payload, summary)
+    assert public["status"] is False
+    assert public["metadataRetained"] is True
+    assert public["doNotRetryBuildMeta"] is True
+    assert public["data"]["entityResults"][0]["success"] is True
+    assert public["retainedTargets"][0]["formId"] == "SAVED-FORM"
+    assert public["reconciliation"][0]["input"]["formNumber"] == "uhyl_check_in"
+    assert public["repairPlans"][0]["pendingWrites"] == [pending]
+    assert public["retryAdvice"] == "inspect_retained_form"
+    assert public["retryable"] is False
+
+
+def test_unknown_root_does_not_fabricate_a_retained_identity(tmp_path):
+    summary = {"ok": False}
+    actual = cosmic_api._attach_post_build_phase_failure(
+        summary, {"status": False}, phase="verify", app_root=str(tmp_path),
+        artifact_path=str(tmp_path / "form.json"),
+    )
+    assert actual == {"ok": False}
+
+
+def test_batch_keeps_post_failure_separate_from_verified_and_unwritten_targets(tmp_path):
+    saved = {"ok": True, "formNumbers": [{"number": "uhyl_check_in"}]}
+    cosmic_api._attach_post_build_phase_failure(
+        saved, {"data": {"entityResults": [{
+            "success": True, "formId": "SAVED", "formNumber": "uhyl_check_in",
+        }]}}, phase="addRefBill", app_root=str(tmp_path),
+        artifact_path=str(tmp_path / "check_in.json"),
+    )
+    report = {"total": 3, "success": 1, "failed": 2, "results": [
+        {"ok": True, "summary": {"ok": True, "formNumbers": [{"number": "uhyl_room"}]}},
+        {"ok": False, "phase": "addRefBill", "summary": saved, "errors": ["REF_BILL_ADD_FAILED"]},
+        {"ok": False, "phase": "dependency", "writeAttempted": False,
+         "artifactPath": str(tmp_path / "bill.json"), "errors": ["DEPENDENCY_FAILED"]},
+    ]}
+    summary = cosmic_api._summarize_run_batch(report)
+    cosmic_api._apply_build_failure_contract(report, summary)
+    assert report["status"] is False
+    assert report["metadataRetained"] is True
+    assert report["notStartedArtifacts"] == [str(tmp_path / "bill.json")]
+    assert report["retainedTargets"][0]["formNumber"] == "uhyl_check_in"
+    assert summary["formNumbers"] == [{"name": "", "number": "uhyl_room"}]
+    assert "REF_BILL_ADD_FAILED" in summary["errors"]
+    assert len(report["repairPlans"]) == 1

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/test/test_run_batch_verification_evidence.py

@@ -29,3 +29,20 @@ def test_compact_verified_targets_exposes_only_successful_exact_assertions():
         {"type": "entity_exists", "target": "uhyl_bill"},
         {"type": "field_exists", "target": "uhyl_detail.uhyl_amount"},
     ]
+
+
+def test_batch_receipt_persists_raw_verified_results_and_artifact_paths(tmp_path):
+    import json
+    from _core.formatters import save_run_batch_result
+    artifact = tmp_path / "emit" / "artifact.json"
+    raw = {"results": [{"artifact": str(artifact), "ok": True, "verification": {"status": "pass"},
+                       "result": {"data": {"entityResults": [{"formNumber": "sample", "formName": "样例"}]}}}]}
+    result = save_run_batch_result(raw, str(tmp_path / "app"), [str(artifact)])
+    saved = json.loads(Path(result["resultPath"]).read_text())
+    assert saved == result
+    assert saved["results"] == raw["results"]
+    assert saved["artifactPaths"] == [str(artifact.resolve())]
+    assert saved["appRoot"] == str((tmp_path / "app").resolve())
+    second = save_run_batch_result(raw, str(tmp_path / "app"), [str(artifact)])
+    assert second["resultPath"] != result["resultPath"]
+    assert Path(result["resultPath"]).is_file()

package/skills/cosmic-build/skills/cosmic-meta-knowledge/generation/api-param-checklist.md

@@ -48,7 +48,7 @@
 | R11 | ActionType 为平台注册子类名 | 不能用基类名，如 `LockFieldAction` 而非 `Action` | ActionType 不存在导致 ADD_RULE_FAIL |
 | R12 | Fields 格式 | `[{"_Type_": "FieldId", "Id": "fieldKey"}]` | 缺少 `_Type_` 字段或 Id 值错误 |
 | R13 | formRule 动作 `RET` 必填 | 每个 formRule 动作必须显式包含 `RET` 字段（常用 251 = 与设计器勾选"加载+值更新"一致） | RET 缺失导致触发时机"加载"和"值更新"未勾选 |
-| R14 | bizRule 动作默认值按类型决定 | 优先传语义化 lower-camel 输入；CLI 只为已发布动作补 `Seq` 与已验证 `RET`。`CallFieldChangeAction` 已确认运行态失败并阻断 | 复用通用 RET 或发布仅设计态动作会产生惰性规则 |
+| R14 | bizRule 动作默认值按类型决定 | 优先传语义化 lower-camel 输入；CLI 按动作补 `Seq` 和 `RET`（CallFieldChangeAction 为 773）。设计态回读不证明运行态分发 | 复用通用 RET 或把保存成功当运行成功会产生惰性规则 |
 | R15 | description 已填写 | 规则整体描述，便于 listRules 时快速识别规则用途 | 缺失不影响功能但降低可维护性 |
 
 ---

package/skills/cosmic-build/skills/cosmic-meta-knowledge/generation/rule-modeling-guide.md

@@ -419,7 +419,7 @@
 | `ClearValueAction`      | 清空字段值    | `field1:field2`             |
 | `TakeBaseProAction`     | 携带基础资料属性 | `[{TargetField, SrcField}]` |
 | `SetEqutionAction`      | 携带字段值    | `[{TargetField, SrcField}]` |
-| `CallFieldChangeAction` | 已阻断 | 仅设计态可写；运行态不会触发目标事件链 |
+| `CallFieldChangeAction` | 调用单个字段的值更新服务 | 一个目标字段 key；设计态可验证，运行效果需在目标环境检查 |
 
 
 ---
@@ -459,7 +459,9 @@
 }
 ```
 
-**CallFieldChangeAction** 已阻断。禁止生成：隔离运行态正对照证明目标字段事件链不会被调用。
+**CallFieldChangeAction** 的 `Expression` 指向单个目标字段，`RET` 为 773。
+元数据回读只能验证配置；既有隔离测试未观察到后续规则链分发，因此必须在目标环境
+验证实际效果，不能将保存成功等同于运行成功。
 
 **TakeBaseProAction（携带基础资料属性）**：
 
@@ -478,7 +480,8 @@
 }
 ```
 
-每条动作只编译一组映射。被引用属性还必须存在于基础资料字段的 `RefProps`，否则规则虽能
+同一服务的多组映射应逐行写入一条动作的 Expression 和 FieldName 列表。
+被引用属性还必须存在于基础资料字段的 `RefProps`，否则规则虽能
 落库，运行态仍会失败。
 
 ### 8.2 formRule 动作载荷格式
@@ -513,7 +516,7 @@
 | preCondition           | `billstatus = 'C'`                                                | `billstatus = 'C'`（**单等号**）                                                                                                 | 原样保留                                |
 | FormulaAction          | `{actionType: "FormulaAction", expression: "a = b * c"}`          | `{ActionType: "FormulaAction", Expression: "a = b * c", RET: 253, Seq: 1}`                                                 | 大小写 + 补 RET/Seq                     |
 | ClearValueAction       | `{actionType: "ClearValueAction", expression: "f1:f2"}`           | `{ActionType: "ClearValueAction", Expression: "f1_key:f2_key", RET: 253, Seq: 1}`                                          | 大小写 + 补 RET/Seq + bizWord→fieldKey  |
-| CallFieldChangeAction  | 已阻断 | 已阻断 | 运行态不会调用目标事件链 |
+| CallFieldChangeAction  | `{actionType: "CallFieldChangeAction", expression: "field"}` | `{ActionType: "CallFieldChangeAction", Expression: "field_key", RET: 773, Seq: 1}` | 解析单个目标；运行效果另验 |
 | LockFieldAction fields | `{actionType: "LockFieldAction", fields: ["f1", "f2"], RET: 251}` | `{ActionType: "LockFieldAction", Fields: [{_Type_: "FieldId", Id: "f1_key"}, {_Type_: "FieldId", Id: "f2_key"}], RET: 251}` | 大小写 + 字符串数组→对象数组 + bizWord→fieldKey |
 | HideFieldAction fields | 同 LockFieldAction                                                 | 同 LockFieldAction                                                                                                           | 同上                                  |
 

package/skills/cosmic-build/skills/cosmic-meta-modeling/SKILL.md

@@ -5,7 +5,7 @@ description: app-build 内部目标：创建实体表单、类型明确的页面
 
 # 苍穹元数据建模
 
-`ROOT_DIR` 与 `ROOT_DIR` 都指已加载的 app-build 包目录。
+`ROOT_DIR` 与 `{ROOT_DIR}` 都指已加载的 app-build 包目录。
 使用已发布命令及其返回的已验证身份。
 
 ## 路由锁定
@@ -26,9 +26,14 @@ appMapping.tsv、目录内容、archive、最近使用记录或本地仅有一
 视觉结构，不决定 model 类型。实体截图按观察到的布局编写受支持的 `uiComposition`；
 当前显示值不能证明完整候选值或默认值。
 
-复用所选应用已验证的 `appRoot` 与 `appCode`。应用已选但未绑定时，按
-[application-context.md](../../references/application-context.md) 完成绑定，再调用需要这些参数的
-创建命令。应用选择由用户决定，绑定由 CLI 执行。报告真实 CLI 错误，不自行生成上下文缺失
+复用所选应用已验证的 `appRoot` 与 `appCode`。应用编码已确认且没有给出绑定时，在本任务工作区直接执行：
+
+```text
+{python} {ROOT_DIR}/scripts/bootstrap_cosmic_context.py --project-root "<当前任务工作区>" --app-code "<已选应用编码>" --resolve-existing-app
+```
+
+复用返回的路径，无需先列本地目录判断是否绑定。只有应用名称、目标歧义或归属冲突才读取
+[application-context.md](../../references/application-context.md)，再用已验证身份调用创建命令。应用选择由用户决定，绑定由 CLI 执行。报告真实 CLI 错误，不自行生成上下文缺失
 回执。创建调用持续使用已验证身份；身份和 ISV 命名校验归脚本所有。
 只读模板查询使用自身声明的范围，不要求准备创建上下文。
 
@@ -49,13 +54,42 @@ appMapping.tsv、目录内容、archive、最近使用记录或本地仅有一
 
 ## ENTITY_CREATE
 
+用户未指定单据/基础资料模板时，省略 `templateKey`，由 emitter 补齐标准模板。
+列表中的 `blankPage` 是虚拟空白选项，不能用它修复模板查询失败。
+
 用于一个依赖完整的 Bill/Base 请求。本地引用需要同批创建时，可一次 author 多个根实体与分录。
 
+缺失的业务字段或候选值仍是未决需求，编译器的最小要求不授权添加占位字段或替换字段类型。
+保留已确认要求，在该对象创建前解决缺失定义；其他定义完整的独立对象可继续创建。
+
+### 业务输入与编译器职责
+
+依据当前需求和已委托的字段设计，一次编写业务字段。显示名与类型属于业务选择；持久化前缀、
+存储键与模板合并由编译器处理。bizWord 表达并区分业务角色，不手算实际字段键；用户明确指定
+的标识通过已发布的覆盖参数保留，生成标识的命名约束交编译器处理。
+
+编译器动态读取所选模板的表头、分录预置字段，按准确键复用重叠项；仅中文名相同不证明身份相同。
+普通新建无需单独查询模板字段。只有业务行为需要引用准确预置字段时，才对所选模板查询一次并复用结果：
+
+```text
+{python} {ROOT_DIR}/skills/cosmic-meta-api/scripts/cosmic_api.py --stdout getEntityFields --app-root "<appRoot>" --formNumber "<templateKey>"
+```
+
+返回位置是 `data.headerFields.fields` 和 `data.entryFields.fields`。省略 templateKey 时使用
+`--describe` 发布的默认模板；模板显示名或猜测的别名不是模板编码。
+不为普通输入搜索编译器/装饰器源码，也不猜造系统字段。真实冲突按返回的字段级校验错误定点修正。
+
 ### 只加载命中的 authoring 知识
 
-始终读取：
+输入形状未知时，查询现有编译器一次：
+
+```text
+{python} {ROOT_DIR}/skills/cosmic-meta-modeling/scripts/data_model_emit.py --describe
+```
 
-`{ROOT_DIR}/skills/cosmic-meta-modeling/references/parse-core.md`
+它离线返回当前 Schema、业务/编译器职责边界、默认模板、准确模板字段查询命令、解析器参数和执行路径。契约已知就直接使用；只有仍有业务语义不明确时，
+再读 parse-core.md 或相应专题，不为同一输入形状重复读取。除非用户要求复制、恢复或续建，
+不拿历史 authoring、compiler state、archive 或 DYM 代替本轮业务输入。
 
 再按明确语义只追加命中的专题：
 
@@ -71,6 +105,8 @@ appMapping.tsv、目录内容、archive、最近使用记录或本地仅有一
 | 列表列/搜索/过滤/排序 | `references/authoring-list-configuration.md` |
 | 实体分区、页签或截图布局 | `references/authoring-ui-composition.md` |
 
+模板预置的 `billstatus` 不触发候选值专题；`IntegerField` 加文本单位不触发 `QtyField` 配套专题；普通表头加分录不触发 UI 分区专题。字段类型和结构已由契约确定时，直接编写输入，不为确认熟悉的形状加载无关参考。
+
 `OrgField`、`UserField`、`CustomerField`、`CityField`、`AdminDivisionField` 已编码
 内置目标，无需查询目标或填写 `prdRef`。受支持内置类型的带出映射省略 reference 时，emitter
 按已声明映射补齐平台引用；显式 reference 保持原样并校验。通用 `BasedataField`/`MulBasedataField` 必须声明目标，使用顶层
@@ -81,14 +117,16 @@ appMapping.tsv、目录内容、archive、最近使用记录或本地仅有一
 未请求的可选默认值与提示信息省略。选择字段使用专题中完整的 `comboOptions` 契约，
 该已发布 authoring 形状无需额外读取实时 Schema。
 
-已从发布契约确定所需 `FieldDataType` 及伴随参数时，不再执行字段类型目录。读取
-`parse-core.md` 和命中专题；类型或伴随参数未知时查询目录：
+已从发布契约确定所需 `FieldDataType` 及伴随参数时，不再执行字段类型目录。
+布尔复选框的 authoring 类型是 `CheckBoxField`；`CheckBox` 只是界面简称，
+不能作为元数据 `dataType`。
+类型或伴随参数未知时查询目录：
 
 ```text
-{python} {ROOT_DIR}/skills/cosmic-meta-modeling/scripts/field_type_registry.py --catalog
+{python} {ROOT_DIR}/skills/cosmic-meta-modeling/scripts/field_type_registry.py --catalog --compact
 ```
 
-模型根据返回 JSON 做语义选择；命令不负责分类自然语言。
+已选类型用 `--catalog --types <准确类型> ...` 返回完整约束。模型做语义选择；命令不按关键词替换类型。
 
 ### 编译与执行
 
@@ -101,14 +139,22 @@ appMapping.tsv、目录内容、archive、最近使用记录或本地仅有一
 只有用户明确给出根表单编码且 authoring 仅含一个根实体时才传 `--root-form-number`，模型生成的
 `bizName` 不使用该参数。多个用户给定编码的根实体应一起 author，各自写入 `logicalName` 并
 省略该参数；一个 manifest 和一次 `runBatch` 会处理全部根实体。
-明确功能分组必须在初始 batch 完成，不得之后用 `moveForm` 修补。
+明确功能分组必须在初始 batch 完成，不得之后用 `moveForm` 修补。首次 `runBatch` 前，
+按需求中的准确名称通过[功能分组入口](../cosmic-meta-modifier/modules/unit/SKILL.md)解析；
+不存在且已授权创建时，使用准确名称/编码及已绑定 `appRoot` 调用 `addUnit`。省略 `--seq`
+时，CLI 从已验证的现有分组序号选择下一位。分组回读通过后才执行初始批次；重名或查询
+不明时阻塞目标选择，不用失败的批次来发现分组缺失。
 
-使用 stdout 返回的 `manifest:` 路径执行批次：
+直接执行 stdout 返回的 `NEXT_COMMAND` argv；旧版 emitter 才按 `manifest:` 路径组装批次：
 
 ```text
-{python} {ROOT_DIR}/skills/cosmic-meta-api/scripts/cosmic_api.py --stdout runBatch --app-root "{appRoot}" --app-code "{appCode}" --emit-manifest "{manifestPath}" --verify
+{python} {ROOT_DIR}/skills/cosmic-meta-api/scripts/cosmic_api.py runBatch --app-root "{appRoot}" --app-code "{appCode}" --emit-manifest "{manifestPath}" --verify
 ```
 
+保留返回的结果文件供 Java 准备使用，其中包含 `resultPath`、完整 `artifactPaths` 和原始验证回执；
+直接作为 `--run-result` 传入，不重读完整结果或手抄字段。
+
+
 `runBatch` 自己完成依赖波次、身份漂移保护，以及实体/字段、属性、规则、列表和
 `uiComposition` 的准确回读。`verification.verifiedTargets` 与
 `[runBatch] FORMS=[...]` 提供已验证目标的证据与身份。已完成事项复用该证据；剩余请求属性
@@ -160,3 +206,5 @@ UI、属性/默认值、规则/操作和列表配置。剩余事项把已验证
 创建已经满足整个请求时，在当前回合继续交付，不能用创建总结结束。成功的 `runBatch` 结果包含
 `delivery.command` 时直接使用；否则遵循 `{ROOT_DIR}/references/delivery.md`，
 由该文档统一负责卡片收口和输出。
+
+消费 `RESULT_SUMMARY` 中的本次目标、验证结论、结果路径和已有交付命令；只有缺少细节或发生失败时才读取完整回执，不为收尾重复读同一结果。

package/skills/cosmic-build/skills/cosmic-meta-modeling/modules/app-menu/SKILL.md

@@ -27,6 +27,7 @@ description: app-build 内部执行技能，用于查询和管理已经验证的
 | 上移/下移菜单 | `moveMenu` |
 | 删除菜单及其后代 | `deleteMenu` |
 | 解析菜单要求的权限项 | `listPermItems` |
+| 完成明确要求的菜单发布 | 对同一应用先 `getApp`，再 `publishApp --action enable` |
 
 直接使用以下形态，不调用 help：
 
@@ -68,6 +69,13 @@ listPermItems
 一次交付多个菜单后，只额外调用一次 `queryMenuTree`，验证需求要求的父级、目录和页面完整路径。
 单条菜单的 `verified=true` 只证明记录已保存；整棵树没有出现全部目标路径时不得报告菜单交付完成。
 
+明确要求新增、修改或移动菜单时，最终菜单树验证通过后，还要确保所属应用已启用。使用 archive
+中的准确 `appId` 调用 `getApp --bizAppId "<appId>"` 核对身份，再调用一次
+`publishApp --bizAppId "<appId>" --action enable`。平台明确回复“应用已处于启用状态”时，
+在准确 `getApp` 身份已核对的前提下视为已满足，不重试。成功启用后再调用 `getApp`，
+核对同一应用及启用状态；回读不明属于 `unknown_after_write`，不能据此宣称用户已能看到菜单。
+仅查询或删除菜单不隐含启用应用。
+
 遵守最多三级、禁止循环父级和帮助中心菜单删除保护。面向用户只返回菜单、动作、已
 验证结果，以及阻塞时唯一的下一步。本模块不输出产物卡片；app-build 在该最终结果后只输出
 一次。

package/skills/cosmic-build/skills/cosmic-meta-modeling/modules/formtemplate/SKILL.md

@@ -80,6 +80,7 @@
 - `isDialog` 继承自 `templateNumber`（`bos_dialogtpl` → `true`）。
 - `bos_dialogtpl` 和 `bos_dialogtpl_middle` 已自带确定/取消按钮，保留模板按钮；
   仅在用户明确要求额外行为时声明新增按钮与操作。
+  编写对应操作 key 时使用 `confirm/donothing`、`cancel/donothing`。
 - DynamicFormModel 没有原生记录持久化。在线操作目录支持 `close/close`，
   但不支持单据/基础资料的 `save/save`、`saveandnew/saveandnew`。保留保存按钮
   key 时使用 `save/donothing`、`saveandnew/donothing`，真实持久化由已注册插件
@@ -102,6 +103,10 @@
 
 `run` 返回 `writeAttempted=false` 且 `retryAdvice=fix_input` 时，修正点名输入后重试。
 已经保留元数据或写后未知时，只按回执执行检查/续写，不重新创建。
+`run` 保存该创建请求的保留写入回执；修改同一 Artifact 后再执行会返回
+`DYNAMIC_FORM_RECOVERY_REQUIRED`，不会重新写入。直接执行 `reconciliation[].arguments`
+给出的 `getFormSchema --formId`，随后使用既有表单修复入口。按编码查询未找到，
+不能推翻已返回的 formId 或证明写入已回滚。
 若返回 `retryAdvice=user_input_required`，禁止进入修复循环或缩短 `logicalName`；
 只向用户询问一次新的表单编码。
 用户回答后，只用一条命令更新同一文件并完成校验：

package/skills/cosmic-build/skills/cosmic-meta-modeling/modules/formtemplate/dynamic-form-artifact-schema.md

@@ -52,6 +52,11 @@
 
 禁止写平台装饰后的 `entityKey`、`fieldKey`、`tableName`、`columnName`；装饰由 `run` 负责。
 
+`BasedataField` / `MulBasedataField` 用
+`reference: {"mode":"platform","formNumber":"<准确目标编码>"}`，或在 `prdRef` 中声明
+明确名称/编码。`run` 复用实体建模的解析器，在创建前验证并补齐 `basedataNumber`。
+目标未解析时在写入前失败；保留引用字段，不通过改字段类型或删字段让创建通过。
+
 用户给出准确表单编码时，将其原样写入 `entities[0].logicalName`。`bizName` 仍是生成
 标识时使用的业务语义；`logicalName` 是最终持久化的准确表单身份。格式与长度只由
 `dynamic_form_validator.py` 判定，禁止在 CLI 返回类型化证据前重复校验或缩短。

package/skills/cosmic-build/skills/cosmic-meta-modeling/modules/report/SKILL.md

@@ -26,6 +26,16 @@
 各区段载荷形状以
 `{ROOT_DIR}/skills/cosmic-meta-api/contracts/schema/report-write.schema.json` 为准。
 
+编写列、过滤或排序前，一次取得这两份契约：
+
+```text
+{python} {ROOT_DIR}/skills/cosmic-meta-modeling/scripts/report_validator.py --schema
+```
+
+返回的 Schema 已包含本地引用定义。按实际必填键编写：列使用 `kind: "column"`、
+`caption`、`dateIndex`；排序使用 `direction: "asc" | "desc"`。只有需要额外展示
+或插件行为时才读下方对应示例。
+
 使用真实公共模板编号：
 
 - `bos_rpttpl`：默认报表；
@@ -163,6 +173,10 @@ id 和显示名由平台解析：调用方给的 id 无法证明存在，而存
 
 ## 能力边界
 
+报表过滤使用 `{ROOT_DIR}/references/report-filter-contract.md`。保留源字段类型、引用和枚举语义，
+Java 交接消费 filterValueContracts。优先已发布 CLI 和独立回读；候选 key 或 filterFieldConfig
+写入成功均不证明控件类型或实际提交的运行 key。
+
 类型化 CLI 未发布数据源编排和报表插件删除能力。不要在 Artifact 中写入 `dataSources` 或
 `reportBehavior`，也不要用 `setComplexProperty` 模拟这些操作。
 
@@ -170,16 +184,14 @@ id 和显示名由平台解析：调用方给的 id 无法证明存在，而存
 行背景色、初始字段以及单列的展现，都可以在下文的 `reportProperties` 段里声明；同样这些属性，修改期
 的 `setReportProperties` 也能在创建之后按宿主逐个写入。
 
-另有两条限制属于契约级事实，不是可以绕过的缺陷：
+剩余边界需明确：
 
-- `reportColumns[].fieldType` 只限于写入/读回对称性已验证的类型，所以金额、数量和基础资料的
-  展现无法作为元数据写入。请声明存储形态的类型（金额/数量用 `decimal`，基础资料引用用 `text`
-  或 `bigint`），再在该列的 `presentation` 对象里声明真正的展现。
-- `reportFilters[].compare` 是必填输入，但被测部署把每种比较都存成同一个普通过滤控件：写完之后
-  `=`、`in`、`between` 无法区分，`between` 日期条件也不会变成日期区间控件。所以比较语义是对
-  `query()` 的要求，不是过滤面板会替你执行的事。
-  `mustInput` 与 `visible` 确实会落地，读回可由设计态导出证明；`defaultValue` 没有任何可观测证据，
-  读回报为不可判定。不可判定的属性永远不会被报成 mismatch，因此声明它不会让写入失败。
+- 报表列展现仍通过插件契约和已核验的 ReportColumnFactory 完成。
+- `reportFilters[].source = {formNumber, fieldKey}` 使用 `ReportFilters.typed` 从准确来源字段创建原生控件。
+  CLI 读取来源类型、引用、枚举及数字/日期配置，保存后独立回读报表配置，并与重新读取的来源比较。
+  日期 `between` 使用 DateRangeField。此能力需要 `assets/platform-report-filters/` 中的平台扩展；
+  旧平台在类型化写入前拒绝，不静默回退成 TextField。未支持的专用类型、组织和条件引用依赖明确失败。
+  未声明 source 时，旧比较符驱动的控件行为仍按部署版本核验。控件类型不证明过滤生效，`compare` 仍是查询要求。
 
 这两类需求都不会被丢弃：它们会被编译进一份插件契约
 `{appRoot}/_runtime/<formNumber>.report-plugin-contract.json`，由 `prepare_plugin_handoff` 以

package/skills/cosmic-build/skills/cosmic-meta-modeling/references/authoring-entity-graphs.md

@@ -28,7 +28,7 @@
 
 模型生成的子实体 `bizName` 只是语义输入，不是可跨表单复用的物理身份。emitter 在应用
 长度预算前将其绑定到父实体身份，避免不同表单复用已删除表单留下的子表。明确提供的子实体
-`logicalName` 保持原值。
+`logicalName` 统一追加一次开发商前缀。
 
 ## 正例
 

package/skills/cosmic-build/skills/cosmic-meta-modeling/references/authoring-storage-constraints.md

@@ -4,14 +4,16 @@
 
 - 精确页面/实体编码原样写入实体的 `logicalName`。
 - 精确字段编码原样写入字段的 `logicalName`。
+- 编译器统一为逻辑标识追加一次开发商前缀，显式编码也遵循此规则；已有前缀不重复追加。
+  长度限制包含前缀。物理名称、已有外部对象的引用不追加前缀，新模型内引用统一使用最终标识映射。
 - `{isv}_materialgroup1` 这类值是命名模板，不是精确编码。只将
   `materialgroup1` 写入 `bizName`/`bizWord`，省略 `logicalName`；emitter 通过
   `getDevInfo` 解析 `isvNumber` 和 `standard`。禁止用 appCode 或应用目录展开 `{isv}`。
 - 精确表名原样写入实体的 `physicalName`。
 - 精确数据库列名原样写入字段的 `physicalName`。
 - 需求未给出时省略这些键。模型不得自行派生、修复、补前缀、缩短或协调这些值。
-- 语义 `bizName`/`bizWord` 与 `physicalName` 相互独立。emitter 校验精确约束：合法则
-  原样应用，不合法则只返回一个终止性约束错误。明确文本长度或 `varchar(N)` 不属于
+- 语义 `bizName`/`bizWord` 与 `physicalName` 相互独立。emitter 在开发商前缀规范化后校验最终标识：
+  合法则应用，不合法则返回约束错误。明确文本长度或 `varchar(N)` 不属于
   authoring 键；app-build 在建模成功后通过属性命令设置。
 
 ```json
@@ -34,7 +36,7 @@
 }
 ```
 
-实体 `logicalName` 保留明确编码的原始大小写，最长 25。字段逻辑编码和
+实体 `logicalName` 在前缀规范化后保留编码大小写，含前缀最长 25。字段逻辑编码和
 物理列名最长 24，表名最长 25。明确编码永不截断；自动生成的语义名在引用、
 规则、属性和分录编译前一次投影为最终持久化 key。无效的明确约束不得
 静默放宽或替换为自动生成值。

package/skills/cosmic-build/skills/cosmic-meta-modeling/references/authoring-ui-composition.md

@@ -10,10 +10,13 @@
   `uiComposition`。字段名称与截图 authoring 使用同一显示名。section 的 rows 进入一个原生
   Fieldset；每个非空 TabPage 下创建一个隐藏标题的原生 Fieldset，字段直接放入。通过
   `sections:[{"key":"fs_basic_info","caption":"...","rows":[{"fields":[...]}]}]` 表达，`tabs` 下也使用同一
-  `caption`/`rows` 结构；section 行不得包含 null。单字段行不隐含整行，只有显式
-  `{\"field\":\"<字段>\",\"fullLine\":true}` 才将该字段扩展为整行。所有直接字段的
+  `caption`/`rows` 结构；section 行不得包含 null。每个 row 只能有 `fields` 属性；
+  `fullLine` 必须放在 `fields` 数组中的字段对象上，不能放在 row 上。有效整行示例是
+  `{"fields":[{"field":"描述","fullLine":true}]}`；
+  `{"fields":["描述"],"fullLine":true}` 和 `{"field":"描述","fullLine":true}` 都是无效 row。
+  单字段行不隐含整行。所有直接字段的
   `Width` 保持平台原生空值以保留 Fieldset 栏间距，绝不以 `Width=100%` 表达一行。图片中明确整行或横排的选项控件可使用
-  `{"field":"职能类型","fullLine":true,"optionLayout":"horizontal","maxColumnWidth":"25%"}`；
+  `{"fields":[{"field":"职能类型","fullLine":true,"optionLayout":"horizontal","maxColumnWidth":"25%"}]}`；
   顶层可用 `gap:"10px"` 保持统一面板间距。emitter 在 buildMeta 前校验全部字段，`runBatch`
   负责组合布局的结构、属性写入与验证。这些阶段不是一个可整体回滚的事务；失败可能保留
   前序写入，应保留回执并按继续执行或对账指引处理。不得延后拆成

package/skills/cosmic-build/skills/cosmic-meta-modeling/references/creation-recovery.md

@@ -1,5 +1,15 @@
 # 创建失败与恢复
 
+`POST_BUILD_PHASE_FAILED` 表示主体表单已保存，后续阶段或回读失败。先按 `reconciliation`
+读取返回的准确表单 ID、编码和应用绑定。批次单项状态使用 `ok`、`phase`、`errors`；嵌套的
+`entityResults.success=true` 只证明主体保存，不能代表后续写入全部完成。
+
+`repairPlans` 保留失败阶段、原 artifact 路径和可用的待修复输入。先对照当前元数据：
+相同字段直接复用，只执行已证实缺失的写入；身份不一致或写入结果未知时停止。
+待修复输入不是盲目重复 add 的许可。保留原错误和成功回执，完成该主体剩余属性、规则及验证后，
+只提交 `notStartedArtifacts` 中明确 `writeAttempted=false` 的文件，不把已保存或已验证对象
+再次加入创建批次，也不重新生成原 artifact。
+
 返回 `retryAdvice=continue_with_retained_form` 时保留已建实体，只按返回的
 `continuations[]`，用其中 command、`appRoot`、`formNumber`、`input` 各执行一次。禁止重构
 载荷或重跑 emit、`runBatch`、`buildMeta`。
@@ -15,3 +25,6 @@
 `fix_input` 且确认零写入时，可修正报告的输入后重新提交；
 重复相同失败应诊断原因，不盲目重试。保留或未知写入按返回的对账、继续执行指引处理，
 不得重新开始创建。
+
+已确认未写入的工作使用持久化批次回执的 `resume`；来源绑定与只读核对见
+[执行契约](../../../references/execution-contract.md)。

package/skills/cosmic-build/skills/cosmic-meta-modeling/references/parse-core.md

@@ -5,6 +5,9 @@ authoring，不是路由或匹配阶段。
 
 ## 规则
 
+- `templateKey` 可填实时模板编码或唯一显示名；emitter 在实体模型类型内解析名称，
+  然后读取模板预置字段。名称歧义时返回候选，不替换成其他模板。
+
 - 必须有对象类型/名称，以及用户字段或明确的字段选择授权。
 - `BillEntity` 默认 `templateKey="bos_billtpl"`；`BaseEntity` 默认
   `"bos_basetpl"`。省略时由 emitter 在内存中补齐；显式值保持原样并接受校验。

package/skills/cosmic-build/skills/cosmic-meta-modeling/scripts/data_model_contract.py

@@ -356,7 +356,8 @@ def validate_authoring_contract(
                     f"root entity type '{entity_type}' must not declare parentEntityRef",
                 )
         if entity_type in {"BillEntity", "BaseEntity"}:
-            _required_string(entity, "templateKey", path, issues)
+            if "templateKey" in entity:
+                _required_string(entity, "templateKey", path, issues)
             if biz_name:
                 main_names.add(biz_name)
         elif entity_type == "MainEntity":
@@ -611,6 +612,10 @@ def validate_authoring_contract(
                     f"{reference_hint} is a built-in single-select reference; use {expected_wrapper}",
                 )
             if data_type in REF_BILL_TYPES:
+                if entity_type == "BaseEntity":
+                    _issue(issues, "REF_BILL_OWNER_UNSUPPORTED", f"{field_path}.dataType",
+                           "The current RefBillField writer supports bill forms, not BaseEntity. "
+                           "Resolve the intended model/reference semantics before creation; do not substitute a field type automatically.")
                 if "reference" not in field:
                     _issue(
                         issues,