@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/cosmic_api.py

@@ -51,6 +51,8 @@ import json
 import argparse
 import builtins
 import hashlib
+import shlex
+import subprocess
 from datetime import datetime, timezone
 
 # Windows default stdout is GBK, cannot output ⚠️ and other Unicode chars, force UTF-8
@@ -95,6 +97,7 @@ from _core.validators import (           # noqa: F401
 )
 
 from field_decorator import (  # noqa: F401
+  make_entity_key_for,
   decorate_artifact,
   decorate_ops,
   validate_dynamic_form_number,
@@ -307,6 +310,14 @@ def _append_meta_event(phase, **payload):
 
 
 def _summarize_build_meta_result(result, artifact=None):
+  if isinstance(result, dict) and result.get("status") is False and result.get("writeAttempted") is False:
+    summary = {"ok": False, "successCount": 0, "failedCount": 1, "formNumbers": [],
+               "errors": [_extract_error_message(result) or result.get("errorCode")],
+               "errorCode": result.get("errorCode"), "writeAttempted": False}
+    if result.get("errorCode") == "TARGET_ALREADY_EXISTS":
+      _attach_target_exists_contract(summary, (result.get("data") or {}).get("conflicts", []))
+      summary["writeAttempted"] = False
+    return summary
   data = result.get("data") if isinstance(result, dict) else {}
   data = data if isinstance(data, dict) else {}
   entity_results = data.get("entityResults") or []
@@ -673,6 +684,79 @@ def _dynamic_form_identity_preflight(artifact):
   }
 
 
+def _resolve_dynamic_reference_fields(artifact, *, app_root=None, isv="", query_forms=None, entity_exists=None):
+  """Use the entity-authoring resolver for dynamic-form reference fields."""
+  entities = artifact.get("entities") or []
+  if not entities or entities[0].get("type") != "MainEntity":
+    return None
+  modeling = os.path.abspath(os.path.join(SCRIPT_DIR, "../../cosmic-meta-modeling/scripts"))
+  if modeling not in sys.path:
+    sys.path.insert(0, modeling)
+  from basedata_resolver import BasedataResolver
+  resolver = BasedataResolver(app_root=app_root, isv=isv, query_forms=query_forms, entity_exists=entity_exists)
+  resolved = {}
+  pending = []
+  for entity in entities:
+    for field in entity.get("fields") or []:
+      if field.get("dataType") not in {"BasedataField", "MulBasedataField"}:
+        continue
+      reference = field.get("reference") or {}
+      selector = str(reference.get("formNumber") or field.get("prdRef") or field.get("basedataNumber") or "").strip()
+      if reference and reference.get("mode") != "platform":
+        pending.append({"field": field.get("bizWord"), "reason": "dynamic_reference_requires_platform_target"})
+        continue
+      if not selector:
+        pending.append({"field": field.get("bizWord"), "reason": "reference_target_missing"})
+        continue
+      if selector not in resolved:
+        resolved[selector] = resolver.resolve(prd_ref=selector)
+      target = resolved[selector]
+      if target.is_ok:
+        field["basedataNumber"] = target.number
+        continue
+      pending.append({"field": field.get("bizWord"), "selector": selector, "reason": target.reason,
+                      "status": target.status, "candidates": [item.to_dict() for item in target.candidates]})
+  if not pending:
+    return None
+  return {
+    "status": False, "errorCode": "DYNAMIC_REFERENCE_TARGET_UNRESOLVED",
+    "message": "Resolve declared reference targets before creation; preserve the requested reference field types.",
+    "writeAttempted": False, "metadataChanged": False, "retryAdvice": "resolve_reference_target",
+    "data": {"unresolvedReferences": pending},
+  }
+
+
+def _dynamic_creation_receipt(app_root, artifact_path, result=None):
+  """Retain a partial creation receipt for the same request across input changes."""
+  if not app_root:
+    return None
+  identity = os.path.normcase(os.path.abspath(artifact_path))
+  key = hashlib.sha256(identity.encode("utf-8")).hexdigest()[:24]
+  receipt = os.path.join(app_root, "_runtime", "cosmic-metadata", "output", "retained-run-" + key + ".json")
+  if result is not None:
+    if result.get("metadataRetained") is not True or result.get("writeAttempted") is not True:
+      return None
+    retained = dict(result)
+    retained.update(status=False, errorCode="DYNAMIC_FORM_RECOVERY_REQUIRED", doNotRetryRun=True,
+                    terminal=True, retryable=False, retryAdvice="inspect_retained_form", artifactPath=identity,
+                    allowedNextActions=["inspect_retained_form"])
+    rows = (result.get("data") or {}).get("entityResults") or []
+    retained["reconciliation"] = [{
+      "command": "getFormSchema", "formId": row["formId"],
+      "arguments": ["--stdout", "getFormSchema", "--app-root", os.path.abspath(app_root), "--formId", row["formId"]],
+    } for row in rows if isinstance(row, dict) and row.get("formId")]
+    retained["modelInstruction"] = "This creation request already wrote metadata. Inspect the returned formId and repair the existing form; changing its artifact does not authorize another creation."
+    os.makedirs(os.path.dirname(receipt), exist_ok=True)
+    with open(receipt, "w", encoding="utf-8") as stream:
+      json.dump(retained, stream, ensure_ascii=False, indent=2)
+    return retained
+  if not os.path.isfile(receipt):
+    return None
+  with open(receipt, "r", encoding="utf-8") as stream:
+    retained = json.load(stream)
+  return {**retained, "writeAttempted": False, "metadataChanged": False}
+
+
 def _dynamic_form_artifact_preflight(artifact):
   """The public run command enforces the same dynamic contract as the authoring validator."""
   roots = artifact.get("entities") or []
@@ -765,6 +849,7 @@ def _apply_build_failure_contract(payload, summary):
   if summary.get("errorCode") not in (
     "TARGET_ALREADY_EXISTS", "FUNCTIONAL_GROUP_MOUNT_INCOMPLETE",
     "DYNAMIC_FORM_IDENTITY_DRIFT", "POST_BUILD_CONTINUATION_REQUIRED",
+    "POST_BUILD_PHASE_FAILED",
   ):
     return payload
   payload["status"] = False
@@ -776,12 +861,58 @@ def _apply_build_failure_contract(payload, summary):
     "doNotRetryBuildMeta", "targetConflicts", "unitMountFailures",
     "requestedFormNumber", "actualFormNumbers",
     "allowedNextActions", "continuation", "continuations", "modelInstruction",
+    "retainedTargets", "reconciliation", "repairPlans", "failedPhase",
+    "notStartedArtifacts",
   ):
     if key in summary:
       payload[key] = summary[key]
   return payload
 
 
+class _PostBuildWriteError(ValueError):
+  def __init__(self, message, result, pending_write):
+    super().__init__(message)
+    self.result = result
+    self.pending_write = pending_write
+
+
+def _attach_post_build_phase_failure(summary, payload, *, phase, app_root,
+                                    artifact_path, pending_write=None):
+  """A successful root save survives a later write or verification failure."""
+  targets = [
+    {"formId": row["formId"],
+     "formNumber": row.get("formNumber") or row.get("entityKey"),
+     "formName": row.get("formName") or row.get("displayName"),
+     "failedPhase": phase}
+    for row in ((payload or {}).get("data") or {}).get("entityResults", [])
+    if isinstance(row, dict) and row.get("formId")
+    and (row.get("formNumber") or row.get("entityKey"))
+  ]
+  if not targets:
+    return summary
+  summary.update({
+    "ok": False, "errorCode": "POST_BUILD_PHASE_FAILED",
+    "message": f"The form exists; phase {phase} requires reconciliation before repair",
+    "failedPhase": phase, "terminal": True, "retryable": False,
+    "writeAttempted": True, "metadataChanged": True, "metadataRetained": True,
+    "doNotRetryBuildMeta": True, "retryAdvice": "inspect_retained_form",
+    "retainedTargets": targets,
+    "reconciliation": [{"command": "getFormSchema", "appRoot": app_root,
+                        "input": {"formId": target["formId"],
+                                  "formNumber": target["formNumber"]}}
+                       for target in targets],
+    "repairPlans": [{
+      "failedPhase": phase, "appRoot": app_root,
+      "artifactPath": os.path.abspath(artifact_path),
+      "pendingWrites": [pending_write] if pending_write else [],
+      "precondition": "Read the retained form first. Reuse matching elements; execute only writes proven absent. Stop on mismatched identities or unknown write outcomes.",
+    }],
+    "allowedNextActions": ["getFormSchema", "getProperties", "listElements"],
+    "modelInstruction": "Preserve the saved form and the original artifact. Inspect the exact retained target before a narrow existing-form repair; never rerun emit, runBatch or buildMeta for this artifact. Reconcile every failed or unknown post-write before retrying. The batch results use ok and phase, not success.",
+  })
+  return summary
+
+
 def _apply_dynamic_ui_failure_contract(payload, summary, error):
   """Expose a retained post-build UI failure on the public command envelope."""
   if not isinstance(payload, dict) or not isinstance(summary, dict):
@@ -995,6 +1126,7 @@ def _summarize_run_batch(summary):
   target_conflicts = []
   unit_mount_failures = []
   continuations = []
+  post_build_failures = []
   for item in results:
     if not isinstance(item, dict):
       continue
@@ -1013,6 +1145,8 @@ def _summarize_run_batch(summary):
     continuation = one.get("continuation")
     if isinstance(continuation, dict):
       continuations.append(continuation)
+    if one.get("errorCode") == "POST_BUILD_PHASE_FAILED":
+      post_build_failures.append(one)
     if not item.get("ok"):
       errors.extend(str(e) for e in (item.get("errors") or [])[:3 - len(errors)])
       if continuation is None:
@@ -1053,8 +1187,23 @@ def _summarize_run_batch(summary):
   }
   result = _attach_functional_group_mount_contract(result, unit_mount_failures)
   result = _attach_target_exists_contract(result, target_conflicts)
-  if continuations and result.get("errorCode") not in {
+  if post_build_failures and result.get("errorCode") not in {
     "TARGET_ALREADY_EXISTS", "FUNCTIONAL_GROUP_MOUNT_INCOMPLETE",
+  }:
+    result.update({key: value for key, value in post_build_failures[0].items()
+                   if key in {"errorCode", "message", "terminal", "retryable",
+                              "retryAdvice", "writeAttempted", "metadataChanged",
+                              "metadataRetained", "doNotRetryBuildMeta",
+                              "allowedNextActions", "modelInstruction"}})
+    for key in ("retainedTargets", "reconciliation", "repairPlans"):
+      result[key] = [value for failure in post_build_failures for value in failure.get(key, [])]
+    result["notStartedArtifacts"] = [item["artifactPath"] for item in results
+                                     if item.get("writeAttempted") is False
+                                     and item.get("artifactPath")]
+  if continuations:
+    result["continuations"] = continuations
+  if continuations and result.get("errorCode") not in {
+    "TARGET_ALREADY_EXISTS", "FUNCTIONAL_GROUP_MOUNT_INCOMPLETE", "POST_BUILD_PHASE_FAILED",
   }:
     result.update({
       "ok": False,
@@ -1079,6 +1228,11 @@ def _summarize_run_batch(summary):
         "once against its retained form, then continue the remaining metadata scope."
       ),
     })
+  attempts = [item.get("writeAttempted", (item.get("summary") or {}).get("writeAttempted",
+              (item.get("result") or {}).get("writeAttempted"))) for item in results if isinstance(item, dict)]
+  if attempts:
+    result["writeAttempted"] = (True if any(value is True for value in attempts)
+                                else False if all(value is False for value in attempts) else None)
   return result
 
 
@@ -1242,6 +1396,108 @@ def _resolve_app_root_arg(args):
   return os.path.abspath(raw)
 
 
+def _normalize_key_property(args, properties):
+  result = dict(properties)
+  selector = "Key" if "Key" in result else "key" if "key" in result else None
+  if not selector:
+    return result
+  workspace = _load_workspace_at(_resolve_app_root_arg(args)) or {}
+  standard = workspace.get("standard")
+  if isinstance(standard, str):
+    standard = standard.strip().lower() == "true"
+  result[selector] = make_entity_key_for(
+    str(result[selector] or "").strip(), str(workspace.get("isv") or ""),
+    standard=standard)
+  return result
+
+
+def _rename_element_key(cfg, token, args):
+  """Rename one metadata key and migrate observable rule string references."""
+  old_key = resolve_element_selector(cfg, token, args.formNumber, args.element)
+  normalized = _normalize_key_property(args, {"Key": args.new_key})
+  new_key = str(normalized["Key"] or "").strip()
+  if not new_key or new_key == old_key:
+    return {
+      "status": True, "errorCode": "0", "writeAttempted": False,
+      "data": {"alreadySatisfied": True, "changed": False, "formNumber": args.formNumber,
+               "oldKey": old_key, "newKey": new_key},
+      "verification": {"verified": True, "preservationVerified": True},
+    }
+  before_elements = do_list_elements(cfg, token, args.formNumber)
+  before_rows = before_elements.get("data") if _is_api_success(before_elements) else []
+  before = next((row for row in before_rows if isinstance(row, dict)
+                 and str(row.get("key") or "") == old_key), None)
+  if before is None:
+    return {"status": False, "errorCode": "RENAME_TARGET_NOT_FOUND",
+            "message": "The exact current element is absent; nothing was written",
+            "writeAttempted": False}
+  rules_result = do_list_rules(cfg, token, args.formNumber)
+  if not _is_api_success(rules_result):
+    return {"status": False, "errorCode": "RENAME_REFERENCE_READ_FAILED",
+            "message": "Cannot inspect rule references before renaming; nothing was written",
+            "writeAttempted": False, "data": {"cause": rules_result}}
+  pattern = re.compile(rf"(?<![A-Za-z0-9_]){re.escape(old_key)}(?![A-Za-z0-9_])")
+  patches = []
+  for rule in (rules_result.get("data") or {}).get("rules") or []:
+    if not isinstance(rule, dict):
+      continue
+    patch = {
+      "ruleType": rule.get("ruleType"), "ruleId": rule.get("ruleId"),
+    }
+    for source in ("preCondition", "triggerField"):
+      value = rule.get(source)
+      if isinstance(value, str) and pattern.search(value):
+        patch[source] = pattern.sub(new_key, value)
+    if len(patch) > 2:
+      patches.append(patch)
+  written = do_set_properties_verified(
+    cfg, token, args.formNumber, old_key, {"Key": new_key})
+  if not _is_api_success(written) or not (written.get("verification") or {}).get("verified"):
+    return written
+  migrated = []
+  for patch in patches:
+    updated = do_update_rule_verified(cfg, token, args.formNumber, patch)
+    if not _is_api_success(updated) or not (updated.get("verification") or {}).get("verified"):
+      rollback = do_set_properties_verified(
+        cfg, token, args.formNumber, new_key, {"Key": old_key})
+      return {
+        "status": False, "errorCode": "RENAME_REFERENCE_MIGRATION_FAILED",
+        "message": "Key changed but a rule reference migration failed; rollback was attempted",
+        "writeAttempted": True, "metadataRetained": not (
+          _is_api_success(rollback) and (rollback.get("verification") or {}).get("verified")),
+        "data": {"failedRule": patch, "ruleResult": updated, "rollback": rollback},
+      }
+    migrated.append(str(patch.get("ruleId") or ""))
+  after_elements = do_list_elements(cfg, token, args.formNumber)
+  after_rows = after_elements.get("data") if _is_api_success(after_elements) else []
+  after = next((row for row in after_rows if isinstance(row, dict)
+                and str(row.get("key") or "") == new_key), None)
+  preserved = bool(after) and all(
+    before.get(key) == after.get(key) for key in ("name", "type", "parentKey", "index")
+  )
+  final_rules = do_list_rules(cfg, token, args.formNumber)
+  stale = [
+    str(rule.get("ruleId") or "") for rule in ((final_rules.get("data") or {}).get("rules") or [])
+    if isinstance(rule, dict) and any(
+      isinstance(rule.get(key), str) and pattern.search(rule[key])
+      for key in ("preCondition", "triggerField")
+    )
+  ] if _is_api_success(final_rules) else ["<read-failed>"]
+  verified = after is not None and preserved and not stale
+  return {
+    "status": verified, "errorCode": "0" if verified else "RENAME_READBACK_MISMATCH",
+    "message": None if verified else "Renamed key did not preserve the requested observable state",
+    "writeAttempted": True, "metadataRetained": True,
+    "data": {"changed": True, "verified": verified, "formNumber": args.formNumber,
+             "oldKey": old_key, "newKey": new_key, "migratedRuleIds": migrated,
+             "staleRuleIds": stale},
+    "verification": {"verified": verified, "preservationVerified": preserved,
+                     "oldKeyAbsent": not any(isinstance(row, dict)
+                       and str(row.get("key") or "") == old_key for row in after_rows),
+                     "newKeyPresent": after is not None, "staleRuleIds": stale},
+  }
+
+
 def _assert_workspace_matches_archive(app_root, workspace):
   """Fail closed before a platform write if appRoot and workspace identities drift."""
   if not app_root:
@@ -1311,6 +1567,15 @@ def _assert_platform_target_matches_archive(
     )
 
 
+def _unit_app_target(app_root, biz_app_id=None, biz_app_number=None):
+  if not app_root:
+    return biz_app_id, biz_app_number
+  workspace = _load_workspace_at(app_root)
+  _assert_platform_target_matches_archive(app_root, workspace, biz_app_id=biz_app_id, biz_app_number=biz_app_number)
+  app_id = biz_app_id or workspace.get("bizAppId")
+  return app_id, biz_app_number or (None if app_id else workspace.get("appNumber"))
+
+
 def _retarget_runtime_dir(app_root):
   """Re-point global RUNTIME_DIR/WORKSPACE_JSON to `{app_root}/_runtime/cosmic-metadata`.
 
@@ -1323,6 +1588,9 @@ def _retarget_runtime_dir(app_root):
   if not app_root:
     return
   resolved = os.path.abspath(os.path.expanduser(app_root))
+  # kd_token_cache resolves its workspace independently from _core.config.
+  # Keep authentication state under the same explicit appRoot as metadata state.
+  os.environ["PROJECT_ROOT"] = resolved
   from _core import config as _cfg
   _cfg._init_paths(app_root=resolved)
   RUNTIME_DIR = _cfg.RUNTIME_DIR
@@ -1708,6 +1976,9 @@ def _resolve_owned_report_target(cfg, token, args, command):
 
 def _attach_report_readback(cfg, token, form_id, section, expected, result_data):
   schema = do_get_report_schema(cfg, token, form_id=form_id)
+  if section == "filters" and any(item.get("source") for item in expected):
+    from _core.report_ops import report_filter_source_expectations
+    schema["filterSourceExpectations"] = report_filter_source_expectations(cfg, token, expected)
   if not schema.get("readBackAvailable"):
     # No canonical read-back on this deployment; the write already returned platform
     # success, so report succeeded-but-unverified, not a mismatch.
@@ -2658,11 +2929,14 @@ from _core.formatters import (           # noqa: F401
   _print_forms, _print_schema, _print_templates,
   _print_form_layout_tree, _print_panels,
   _print_find_results, _print_biz_hierarchy,
-  pjson, _transform_build_meta_result,
+  pjson, _transform_build_meta_result, save_run_batch_result,
   set_output_file, set_stdout_mode, set_current_command, _is_en,
 )
 
 
+from execution_binding import execution_binding, validate_execution_binding
+from _core.execution_errors import attach_execution_error
+
 _FORMATTER_PJSON = pjson
 _CLI_MACHINE_MODE = False
 _CLI_RESULT_EMITTED = False
@@ -2675,6 +2949,27 @@ class _CliUsageError(ValueError):
     self.recovery = recovery
 
 
+def _load_mapping_request(args):
+  request = _load_json_arg(args.input_file)
+  if not isinstance(request, dict):
+    raise _CliUsageError("--input must contain a JSON object with mappings")
+  overrides = {
+    "entity": args.entity,
+    "conditionField": args.condition_field,
+    "operator": args.operator,
+    "value": args.value,
+    "events": args.events,
+    "addEvents": args.add_events,
+  }
+  for key, value in overrides.items():
+    if value is None or value == "":
+      continue
+    if key in request and request[key] != value:
+      raise _CliUsageError(f"--input conflicts with --{key}: {request[key]!r} != {value!r}")
+    request[key] = value
+  return request
+
+
 class _CliResultFailure(Exception):
   def __init__(self, exit_code=1):
     super().__init__("structured command failure")
@@ -2707,6 +3002,14 @@ class _CliArgumentParser(argparse.ArgumentParser):
   def error(self, message):
     if "--stdout" in sys.argv[1:]:
       command = self.prog.rsplit(" ", 1)[-1]
+      selected_parser = self
+      for action in self._actions:
+        if isinstance(action, argparse._SubParsersAction):
+          selected = next((arg for arg in sys.argv[1:] if arg in action.choices), None)
+          if selected:
+            command = selected
+            selected_parser = action.choices[selected]
+      message = re.sub(r"\s*\(choose from .+\)\s*$", "", str(message))
       if _shell_split_inline_json(message):
         # Prefixed so `_exception_error_code` publishes the transport code: the caller
         # must change how the payload is passed, not what the payload says.
@@ -2718,8 +3021,8 @@ class _CliArgumentParser(argparse.ArgumentParser):
           " that path as the same argument. argparse reported: " + str(message or "")
         )
       raise _CliUsageError(message, {
-        "usage": self.format_usage().strip() if command in _CATALOG_COMMAND_POLICIES else f"{self.prog} <command> [arguments]",
-        "describeCommand": f"describeCommand {command}" if command in _CATALOG_COMMAND_POLICIES else "catalog",
+        "usage": selected_parser.format_usage().strip() if command in _CATALOG_COMMAND_POLICIES else f"{self.prog} <command> [arguments]",
+        "describeCommand": f"describeCommand {command}" if command in _CATALOG_COMMAND_POLICIES else "describeCommand <selected-command>",
       })
     super().error(message)
 
@@ -2731,7 +3034,7 @@ def _is_machine_failure(result):
 def pjson(obj, force_stdout=False):
   """Emit one structured result and make semantic failure affect the exit code."""
   global _CLI_RESULT_EMITTED
-  obj = _attach_verified_form_delivery(obj, _CLI_DELIVERY_ARGS)
+  obj = attach_execution_error(_attach_verified_form_delivery(obj, _CLI_DELIVERY_ARGS))
   _FORMATTER_PJSON(obj, force_stdout=force_stdout)
   _CLI_RESULT_EMITTED = True
   if _CLI_MACHINE_MODE and _is_machine_failure(obj):
@@ -2739,14 +3042,16 @@ def pjson(obj, force_stdout=False):
 
 
 def _persist_domain_model(result, output_file, model_type):
-  if _is_machine_failure(result): return result
+  if _is_machine_failure(result):
+    return result
   raw = (result or {}).get("data")
   if not isinstance(raw, str) or not raw.strip():
-    raise ValueError("DOMAIN_MODEL_DATA_INVALID: 平台未返回元模型 JSON 文本")
+    raise ValueError("DOMAIN_MODEL_DATA_INVALID: platform returned no JSON text")
   path = os.path.abspath(output_file)
   os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
   with open(path, "w", encoding="utf-8", newline="\n") as stream:
-    stream.write(raw); stream.write("\n")
+    stream.write(raw)
+    stream.write("\n")
   return {"status": True, "errorCode": "0", "message": None, "data": {
     "modelType": model_type, "path": path, "bytes": os.path.getsize(path),
     "sha256": hashlib.sha256(raw.encode("utf-8")).hexdigest(),
@@ -2760,6 +3065,10 @@ def _exception_error_code(exc):
     return match.group(1), match.group(2) or text
   if isinstance(exc, _CliUsageError):
     return "CLI_ARGUMENT_ERROR", text
+  if isinstance(exc, ImportError):
+    return "SKILL_INSTALLATION_ERROR", text
+  if isinstance(exc, (TimeoutError, ConnectionError)):
+    return "ENVIRONMENT_RUNTIME_ERROR", text
   return "CLI_EXECUTION_ERROR", text or exc.__class__.__name__
 
 
@@ -2771,6 +3080,13 @@ def _emit_machine_error(error_code, message, recovery=None):
       "errorCode": str(error_code or "CLI_EXECUTION_ERROR"),
       "message": str(message or "Command failed"),
       "data": None,
+      "errorCategory": attach_execution_error({"status": False, "errorCode": error_code})["errorCategory"],
+      "capabilityLimitConfirmed": error_code == "FULL_METADATA_API_UNAVAILABLE",
+      "executionBinding": execution_binding(),
+      **({"writeAttempted": False} if error_code in {
+        "SKILL_SOURCE_MISMATCH", "SKILL_REVISION_MISMATCH", "ENVIRONMENT_BINDING_MISMATCH",
+        "CONDITIONAL_CARRY_SOURCE_PROPERTY_UNAVAILABLE",
+      } else {}),
       **({"recovery": recovery} if recovery else {}),
     },
     force_stdout=True,
@@ -2886,12 +3202,16 @@ from _core.commands import (            # noqa: F401
   do_ensure_conditional_entry_style,
   do_ensure_conditional_control_state,
   do_ensure_conditional_clear_fields,
+  do_ensure_conditional_field_change,
   do_ensure_conditional_copy_field_value,
+  do_ensure_copy_field_mappings,
   do_ensure_conditional_carry_reference_property,
+  do_ensure_carry_reference_mappings,
   do_ensure_conditional_calculation,
   do_ensure_quantity_conversion,
   do_ensure_conditional_field_state,
   do_ensure_field_calculation,
+  do_ensure_time_difference_calculation,
   do_ensure_rule_function_formula,
   do_ensure_rule_set,
   do_update_rule, do_update_rule_verified,
@@ -2906,7 +3226,7 @@ from _core.commands import (            # noqa: F401
   do_describe_property_input,
   do_set_properties, do_set_properties_verified,
   do_apply_property_policy, validate_property_policy_input,
-  control_catalog, validate_control_batch_input, do_add_controls,
+  control_catalog, control_input_schema, validate_control_batch_input, do_add_controls,
   do_set_summary_to_field_resolved,
   resolve_element_rows, resolve_element_selector, resolve_element_for_properties,
   compile_must_input_equality,
@@ -2917,7 +3237,7 @@ from _core.commands import (            # noqa: F401
   do_set_combo_items, do_set_ref_props, do_set_display_prop,
   read_ref_props, ref_props_names,
   do_set_permission_control, do_set_business_control,
-  do_set_complex_property, do_set_custom_style, do_set_collapse_summary, do_list_parameter_forms,
+  do_set_complex_property, do_configure_dropdown_menu, do_set_custom_style, do_set_collapse_summary, do_list_parameter_forms,
   do_ensure_tab_page_operations,
   do_search_basedata, do_get_basedata_entity_id,
   # List/filter/toolbar shortcut commands (ported from bos-designer copy)
@@ -3021,7 +3341,7 @@ def _dispatch_serve(cfg, token, cmd, cmd_args):
   """
   if not isinstance(cmd_args, dict):
     raise ValueError("serve args must be an object")
-  if cmd in {"modifyMeta", "batchModify", "deleteForm", "enableDisableForm", "inheritForm", "layoutForm"}:
+  if cmd in {"modifyMeta", "batchModify", "deleteForm", "enableDisableForm", "inheritForm", "layoutForm", "registerPlugin"}:
     app_root = str(cmd_args.get("appRoot") or "").strip()
     if not app_root:
       raise ValueError(
@@ -3186,9 +3506,13 @@ def _dispatch_serve(cfg, token, cmd, cmd_args):
     )
 
   elif cmd == "getDomainModel":
-    return do_get_domain_model(cfg, token, cmd_args["modelType"],
-      only_entity=cmd_args.get("onlyEntity"), ext=cmd_args.get("ext"),
-      bizext=cmd_args.get("bizext"), app_id=cmd_args.get("appId"))
+    return do_get_domain_model(
+      cfg, token, cmd_args["modelType"],
+      only_entity=cmd_args.get("onlyEntity"),
+      ext=cmd_args.get("ext"),
+      bizext=cmd_args.get("bizext"),
+      app_id=cmd_args.get("appId"),
+    )
 
   elif cmd == "queryPublicTemplates":
     return do_query_public_templates(
@@ -3312,7 +3636,8 @@ def _dispatch_serve(cfg, token, cmd, cmd_args):
     return do_register_plugin(
       cfg, token,
       form_number=cmd_args.get("formNumber"),
-      plugin_config=cmd_args.get("pluginConfig", {})
+      plugin_config=normalize_plugin_registration_input(cmd_args.get("pluginConfig", {})),
+      app_root=cmd_args.get("appRoot"),
     )
 
   elif cmd == "updatePlugin":
@@ -3370,6 +3695,16 @@ def _dispatch_serve(cfg, token, cmd, cmd_args):
       right=cmd_args.get("right"),
     )
 
+  elif cmd == "ensureTimeDifferenceCalculation":
+    return do_ensure_time_difference_calculation(
+      cfg, token,
+      form_number=cmd_args.get("formNumber"),
+      entity=cmd_args.get("entity"),
+      target=cmd_args.get("target"),
+      start=cmd_args.get("start"),
+      end=cmd_args.get("end"),
+    )
+
   elif cmd == "ensureRuleFunctionFormula":
     return do_ensure_rule_function_formula(
       cfg, token,
@@ -3389,6 +3724,8 @@ def _dispatch_serve(cfg, token, cmd, cmd_args):
       value=cmd_args.get("value"),
       target=cmd_args.get("target"),
       behavior=cmd_args.get("behavior"),
+      add_events=cmd_args.get("addEvents"),
+      events=cmd_args.get("events"),
     )
 
   elif cmd == "ensureConditionalEntryStyle":
@@ -3423,9 +3760,24 @@ def _dispatch_serve(cfg, token, cmd, cmd_args):
       form_number=cmd_args.get("formNumber"), entity=cmd_args.get("entity"),
       condition_field=cmd_args.get("conditionField"), operator=cmd_args.get("operator"),
       value=cmd_args.get("value"), targets=cmd_args.get("targets"),
+      add_events=cmd_args.get("addEvents"),
+    )
+
+  elif cmd == "ensureConditionalFieldChange":
+    return do_ensure_conditional_field_change(
+      cfg, token, form_number=cmd_args.get("formNumber"),
+      entity=cmd_args.get("entity"),
+      condition_field=cmd_args.get("conditionField"),
+      operator=cmd_args.get("operator"), value=cmd_args.get("value"),
+      target=cmd_args.get("target"), add_events=cmd_args.get("addEvents"),
+      events=cmd_args.get("events"),
     )
 
   elif cmd == "ensureConditionalCopyFieldValue":
+    if isinstance(cmd_args.get("input"), dict):
+      return do_ensure_copy_field_mappings(
+        cfg, token, cmd_args.get("formNumber"), cmd_args["input"],
+      )
     return do_ensure_conditional_copy_field_value(
       cfg, token,
       form_number=cmd_args.get("formNumber"), entity=cmd_args.get("entity"),
@@ -3435,6 +3787,10 @@ def _dispatch_serve(cfg, token, cmd, cmd_args):
     )
 
   elif cmd == "ensureConditionalCarryReferenceProperty":
+    if isinstance(cmd_args.get("input"), dict):
+      return do_ensure_carry_reference_mappings(
+        cfg, token, cmd_args.get("formNumber"), cmd_args["input"],
+      )
     return do_ensure_conditional_carry_reference_property(
       cfg, token,
       form_number=cmd_args.get("formNumber"), entity=cmd_args.get("entity"),
@@ -3903,9 +4259,10 @@ def _dispatch_serve(cfg, token, cmd, cmd_args):
   elif cmd == "getUnit":
     return do_get_unit(cfg, token, cmd_args.get("bizAppId"), cmd_args.get("unitId"))
   elif cmd == "addUnit":
+    unit_app_id, unit_app_number = _unit_app_target(cmd_args.get("appRoot"), cmd_args.get("bizAppId"), cmd_args.get("bizAppNumber"))
     return do_add_unit(cfg, token,
-              biz_app_id=cmd_args.get("bizAppId"),
-              biz_app_number=cmd_args.get("bizAppNumber"),
+              biz_app_id=unit_app_id,
+              biz_app_number=unit_app_number,
               name=cmd_args.get("name"),
               number=cmd_args.get("number"),
               description=cmd_args.get("description"),
@@ -4320,7 +4677,8 @@ def _form_delivery(app_root, numbers):
     "instruction": (
       "写入及回读完成，产物交付尚未完成。若当前请求没有其他明确修改，下一步执行 command，"
       "按 references/delivery.md 完成本轮交付；否则先完成剩余修改，再按应用汇总本轮目标收口。"
-      "宿主提供 output_check 时在取得卡片后调用，并将返回的卡片协议块原样放入最终答复。"
+      "这是 app-build 的领域交付，不代表业务验收完成。独立 app-build 在最终展示卡片时调用 output_check；"
+      "专家团委托实施时保留卡片与目标引用，继续负责人安排的 E2E，再由负责人统一最终交付。"
       "此前轮次已展示该表单不代表本轮修改已交付。"
       "不要重放已完成的写入，不在中间步骤同步 DYM。"
     ),
@@ -4592,7 +4950,7 @@ def _serve_loop(cfg):
   token = do_auth(cfg)
 
   # Ready signal
-  print("###SERVE_READY###", flush=True)
+  print("###SERVE_READY###", file=sys.stdout, flush=True)
 
   for line in sys.stdin:
     line = line.strip()
@@ -4601,7 +4959,7 @@ def _serve_loop(cfg):
     try:
       request = json.loads(line)
     except (json.JSONDecodeError, ValueError) as e:
-      print(json.dumps({"success": False, "error": "Invalid JSON: %s" % str(e)}, ensure_ascii=False), flush=True)
+      print(json.dumps({"success": False, "error": "Invalid JSON: %s" % str(e)}, ensure_ascii=False), file=sys.stdout, flush=True)
       continue
 
     cmd = request.get("cmd", "")
@@ -4610,14 +4968,14 @@ def _serve_loop(cfg):
     if cmd == "exit":
       break
     if cmd == "ping":
-      print(json.dumps({"success": True, "data": "pong"}, ensure_ascii=False), flush=True)
+      print(json.dumps({"success": True, "data": "pong"}, ensure_ascii=False), file=sys.stdout, flush=True)
       continue
 
     try:
       result = _dispatch_serve(cfg, token, cmd, cmd_args)
-      print(json.dumps({"success": _serve_result_success(result), "data": result}, ensure_ascii=False), flush=True)
+      print(json.dumps({"success": _serve_result_success(result), "data": result}, ensure_ascii=False), file=sys.stdout, flush=True)
     except Exception as e:
-      print(json.dumps({"success": False, "error": str(e)}, ensure_ascii=False), flush=True)
+      print(json.dumps({"success": False, "error": str(e)}, ensure_ascii=False), file=sys.stdout, flush=True)
 
 
 # ─── Report Pipeline ─────────────────────────────────────────────────────────
@@ -4933,6 +5291,9 @@ def _execute_report_pipeline(cfg, token, artifact, biz_app_id, biz_unit_id, app_
     if columns:
       checks.append(report_readback_verification("columns", columns, final_schema))
     if filters:
+      if any(item.get("source") for item in filters):
+        from _core.report_ops import report_filter_source_expectations
+        final_schema["filterSourceExpectations"] = report_filter_source_expectations(cfg, token, filters)
       checks.append(report_readback_verification("filters", filters, final_schema))
     if sorts and "reportSorts" not in unverifiable:
       checks.append(report_readback_verification("sorts", sorts, final_schema))
@@ -5022,7 +5383,8 @@ def _execute_report_pipeline(cfg, token, artifact, biz_app_id, biz_unit_id, app_
   _plugin_contract = (
     None if (query_data_source and not plugins)
     else compile_report_plugin_contract(
-      {"reportColumns": columns, "reportFilters": filters, "reportPlugins": plugins},
+      {"reportColumns": columns, "reportFilters": filters, "reportPlugins": plugins,
+       "reportProperties": artifact.get("reportProperties") or {}},
       form_number,
     )
   )
@@ -5081,12 +5443,14 @@ def _execute_report_pipeline(cfg, token, artifact, biz_app_id, biz_unit_id, app_
 
 _CATALOG_INTERNAL_COMMANDS = {"catalog", "describeCommand"}
 _CATALOG_PAYLOAD_SCHEMA_REFS = {
+  "addControls": "skills/cosmic-meta-api/contracts/cli/control-authoring.json#/inputSchema",
   "modifyMeta": "skills/cosmic-meta-api/contracts/schema/metaops-structural.schema.json",
   "batchModify": "skills/cosmic-meta-api/contracts/schema/batch-modify-manifest.schema.json",
   "applyContainerLayout": "skills/cosmic-meta-api/contracts/schema/container-layout.schema.json",
   "applyFormComposition": "skills/cosmic-meta-api/contracts/schema/form-composition.schema.json",
   "applyPanelOrder": "skills/cosmic-meta-api/contracts/schema/panel-order.schema.json",
   "configureEntryGrid": "skills/cosmic-meta-api/contracts/schema/entry-grid.schema.json",
+  "configureDropdownMenu": "skills/cosmic-meta-api/contracts/schema/dropdown-menu.schema.json",
   "applyFormUi": "skills/cosmic-meta-api/contracts/schema/existing-form-ui.schema.json",
   "applyFormGrid": "skills/cosmic-meta-api/contracts/schema/form-grid.schema.json",
   "ensureOperationValidation": "skills/cosmic-meta-api/contracts/schema/operation-validation.schema.json",
@@ -5135,6 +5499,7 @@ _CATALOG_COMMAND_CONTRACT_REFS = {
   "applyFormComposition": "skills/cosmic-meta-api/contracts/cli/layout-ui.json#commands/applyFormComposition",
   "applyPanelOrder": "skills/cosmic-meta-api/contracts/cli/layout-ui.json#commands/applyPanelOrder",
   "configureEntryGrid": "skills/cosmic-meta-api/contracts/cli/layout-ui.json#commands/configureEntryGrid",
+  "configureDropdownMenu": "skills/cosmic-meta-api/contracts/cli/layout-ui.json#commands/configureDropdownMenu",
   "applyFormUi": "skills/cosmic-meta-api/contracts/cli/layout-ui.json#commands/applyFormUi",
   "ensureTabPage": "skills/cosmic-meta-api/contracts/cli/layout-ui.json#commands/ensureTabPage",
   "moveFormElement": "skills/cosmic-meta-api/contracts/cli/layout-ui.json#commands/moveFormElement",
@@ -5156,6 +5521,7 @@ _CATALOG_COMMAND_CONTRACT_REFS = {
   "deleteRule": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/deleteRule",
   "listRuleFunctions": "skills/cosmic-meta-api/contracts/cli/rule-functions.json",
   "ensureFieldCalculation": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/ensureFieldCalculation",
+  "ensureTimeDifferenceCalculation": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/ensureTimeDifferenceCalculation",
   "ensureRuleFunctionFormula": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/ensureRuleFunctionFormula",
   "ensureRuleSet": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/ensureRuleSet",
   "ensureConditionalFieldState": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/ensureConditionalFieldState",
@@ -5163,6 +5529,7 @@ _CATALOG_COMMAND_CONTRACT_REFS = {
   "ensureConditionalEntryStyle": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/ensureConditionalEntryStyle",
   "ensureConditionalControlState": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/ensureConditionalControlState",
   "ensureConditionalClearFields": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/ensureConditionalClearFields",
+  "ensureConditionalFieldChange": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/ensureConditionalFieldChange",
   "ensureConditionalCopyFieldValue": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/ensureConditionalCopyFieldValue",
   "ensureConditionalCarryReferenceProperty": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/ensureConditionalCarryReferenceProperty",
   "ensureConditionalCalculation": "skills/cosmic-meta-api/contracts/cli/rule-domain.json#commands/ensureConditionalCalculation",
@@ -5178,6 +5545,7 @@ _CATALOG_COMMAND_CONTRACT_REFS = {
   "setReportRowBackColor": "skills/cosmic-meta-api/contracts/cli/report-write-contracts.json#commands/setReportRowBackColor",
   "setReportFilterFieldConfig": "skills/cosmic-meta-api/contracts/cli/report-write-contracts.json#commands/setReportFilterFieldConfig",
   "setReportDefaultHiddenFields": "skills/cosmic-meta-api/contracts/cli/report-write-contracts.json#commands/setReportDefaultHiddenFields",
+  "renameElementKey": "skills/cosmic-meta-api/contracts/cli/property-batch.json#commands/renameElementKey",
   "registerReportPluginExt": "skills/cosmic-meta-api/contracts/cli/report-write-contracts.json#commands/registerReportPluginExt",
   "setBasedataDefault": "skills/cosmic-meta-api/contracts/cli/property-value-encoding.json#defaultValueModel",
   "setCollapseSummary": "skills/cosmic-meta-api/contracts/cli/collapse-summary.json",
@@ -5223,10 +5591,10 @@ _CATALOG_COMMANDS_BY_EFFECT = {
     "resetEnv", "serve", "setConfig", "setInitialized", "setPdmConfig", "syncDym",
   }),
   "write": frozenset({
-    "addAdvancedContainer", "addButton", "addControls", "addEntryEntity", "addField", "addFieldPanel", "addFilterColumn", "addListColumn", "applyContainerLayout", "applyFormComposition", "applyPanelOrder", "applyFormUi", "applyFormGrid", "applyFormSplit", "applyFormTabs", "configureEntryGrid", "configureList", "configureSelectionFields", "ensureTabPage", "moveFormElement",
+    "addAdvancedContainer", "addButton", "addControls", "addEntryEntity", "addField", "addFieldPanel", "addFilterColumn", "addListColumn", "applyContainerLayout", "applyFormComposition", "applyPanelOrder", "applyFormUi", "applyFormGrid", "applyFormSplit", "applyFormTabs", "configureDropdownMenu", "configureEntryGrid", "configureList", "configureSelectionFields", "ensureTabPage", "moveFormElement",
     "addReportColumns", "addSimpleField",
     "addMenu", "addOperation", "addRule", "addUnit", "batchModify",
-    "ensureConditionalCalculation", "ensureConditionalCarryReferenceProperty", "ensureConditionalClearFields", "ensureConditionalCopyFieldValue", "ensureConditionalControlState", "ensureConditionalClientAppearance", "ensureConditionalEntryStyle", "ensureConditionalFieldState", "ensureFieldCalculation", "ensureQuantityConversion", "ensureRuleFunctionFormula", "ensureRuleSet", "ensureTabPageOperations",
+    "ensureConditionalCalculation", "ensureConditionalCarryReferenceProperty", "ensureConditionalClearFields", "ensureConditionalFieldChange", "ensureConditionalCopyFieldValue", "ensureConditionalControlState", "ensureConditionalClientAppearance", "ensureConditionalEntryStyle", "ensureConditionalFieldState", "ensureFieldCalculation", "ensureTimeDifferenceCalculation", "ensureQuantityConversion", "ensureRuleFunctionFormula", "ensureRuleSet", "ensureTabPageOperations",
     "bootstrapWorkspace", "buildMeta", "copyForm", "createPage", "createScript",
     "enableDisableForm", "extendApp", "extendForm", "extendFormFlow",
     "importForm", "inheritForm", "layoutForm", "modifyMeta", "moveForm",
@@ -5238,7 +5606,7 @@ _CATALOG_COMMANDS_BY_EFFECT = {
     "setDisplayProp", "setEditSearchProp", "setFeatures", "setFilter", "setFormBackground",
     "setFreezeList", "setInitField", "setMustInputCondition", "setNetworkControl",
     "setSplitTables", "setInstantSync",
-    "setOrgFuncs", "setOrgViewScheme", "setPermissionControl", "setProperties",
+    "setOrgFuncs", "setOrgViewScheme", "setPermissionControl", "setProperties", "renameElementKey",
     "setRefLayout", "setRefProps", "setReportColumns",
     "setReportDefaultHiddenFields", "setReportFilterFieldConfig", "setReportFilters",
     "setReportProperties", "setReportQueryDataSource", "setReportRowBackColor",
@@ -5664,7 +6032,7 @@ _CATALOG_ARGUMENT_CONSTRAINTS = {
   "addField": [
     {
       "kind": "batch_fields",
-      "message": "--fields accepts name,bizWord,fieldType,combo,comboJson,required,fullLine and per-item panel/before/after. combo accepts a comma-separated string or JSON string array; comboJson accepts option objects. --validate-only checks all specs without authentication; ordered per-field writes share target preparation and stop at the first failure",
+      "message": "--fields accepts name,bizWord,fieldType,combo,comboJson,required,fullLine,panel,before,after,basedata,mulTable,unitField,flexType,refBaseField,refDisplayProp,asstTypeId,asstType. BasedataField/MulBasedataField also accept reference:{mode:platform,formNumber:<exact number>} instead of basedata. comboJson uses stable value/label objects. --validate-only checks all specs without authentication; ordered writes share target preparation and stop at the first failure",
     },
     {
       "kind": "header_placement",
@@ -5750,7 +6118,7 @@ _CATALOG_ARGUMENT_CONSTRAINTS = {
 for _property_command in (
   "setProperties", "setMustInputCondition", "setDefValueDesign",
   "setBasedataDefault", "setRefProps", "setRefLayout", "setOrgFuncs",
-  "setOrgViewScheme", "setAsstTypeId", "setComplexProperty", "setCustomStyle", "setCollapseSummary", "ensureTabPageOperations",
+  "setOrgViewScheme", "setAsstTypeId", "setComplexProperty", "configureDropdownMenu", "setCustomStyle", "setCollapseSummary", "ensureTabPageOperations",
   "setFeatures", "setFilter", "setDisplayProp", "setEditSearchProp", "setFormBackground",
   "setFreezeList", "setInitField", "setCompareTypeConfig",
   "setNetworkControl", "setPermissionControl", "setBusinessControl",
@@ -5778,6 +6146,8 @@ for _lifecycle_command in (
     "message": "the command resolves and verifies one exact existing form in the same invocation",
   })
 _CATALOG_CONDITIONAL_EFFECTS = {
+  "runBatch": [{"when": {"reconcile_only": True}, "effect": "local", "risk": "low",
+                "summary": "Reads platform state and updates only local recovery receipts; never creates metadata."}],
   "getApp": [
     {
       "when": {"sync_identity": True},
@@ -6015,9 +6385,14 @@ def _command_descriptor(subparsers, command, *, detailed=False):
     result_contract = "JSONL stdio" if command == "serve" else "JSON stdout"
     descriptor["execution"] = {
       "entry": os.path.abspath(__file__),
+      "python": sys.executable,
+      "argvPrefix": [sys.executable, os.path.abspath(__file__), "--stdout", command],
+      "binding": execution_binding(),
       "template": (
-        f'{sys.executable} {os.path.abspath(__file__)} --stdout '
-        f'{command} ' + ('--app-root "<appRoot>" ' if requires_app_root else '') + '<arguments>'
+        (subprocess.list2cmdline([sys.executable, os.path.abspath(__file__), "--stdout", command])
+         if os.name == "nt" else shlex.join([sys.executable, os.path.abspath(__file__), "--stdout", command])) + " "
+        + ('--app-root "<appRoot>" ' if requires_app_root else '')
+        + '<arguments>'
       ),
       "result": result_contract,
     }
@@ -6067,7 +6442,10 @@ def _command_descriptor(subparsers, command, *, detailed=False):
         "humanGate": "use the token only after a later user message confirms the exact returned targets",
       }
     if payload_schema_ref:
-      descriptor["payloadSchema"] = _catalog_payload_schema(payload_schema_ref)
+      descriptor["payloadSchema"] = (
+        control_input_schema() if command == "addControls"
+        else _catalog_payload_schema(payload_schema_ref)
+      )
   return descriptor
 
 
@@ -6245,6 +6623,10 @@ def _main_impl():
            help="Exact existing application code; verifies and synchronizes a trusted appRoot identity before any build write")
   prb.add_argument("--emit-manifest", default=None, dest="emit_manifest",
            help="Exact _emit_manifest.json produced for this workNo; prevents cross-run artifact reuse")
+  prb.add_argument("--reconcile-only", action="store_true",
+           help="Read-only recovery of --resume-result: verify retained exact identities or confirm absence before a later resume")
+  prb.add_argument("--resume-result", default=None,
+           help="Original durable runBatch result; reuse verified objects and execute only confirmed unwritten inputs")
   prb.add_argument("--verify", action="store_true",
            help="After each successful buildMeta, exactly read back entities, fields and parent links")
   prb.add_argument("--bizAppId", required=False, default=None,
@@ -6276,13 +6658,13 @@ def _main_impl():
   pi.add_argument("--force", action="store_true",
           help="Force refresh, even if config.md is already initialized")
   pi.add_argument("--isv", default=None,
-          help="[Bootstrap mode] Temporarily override isv in config.json (for first-time initialization)")
+          help="[Bootstrap mode] Temporarily override isv from ~/.kd/config.json (for first-time initialization)")
   pi.add_argument("--app-number", default=None, dest="app_number_override",
-          help="[Bootstrap mode] Temporarily override app_number in config.json (for first-time initialization)")
+          help="[Bootstrap mode] Temporarily override app_number from ~/.kd/config.json (for first-time initialization)")
 
-  # setConfig (write selected values to config.json during AI-guided initialization)
+  # setConfig (write selected values to ~/.kd/config.json / workspace.json during AI-guided initialization)
   psc = sub.add_parser("setConfig",
-             help="Write fields to scripts/config.json (no auth needed); credential fields and business fields can be written in one go")
+             help="Write fields to ~/.kd/config.json default environment and workspace.json (no auth needed); credential fields and business fields can be written in one go")
   psc.add_argument("--app-number",   default=None, dest="app_number",
            help="App number (written to workspace.json), e.g., uhyl_aireqdecomp")
   psc.add_argument("--biz-cloud-name", default=None, dest="biz_cloud_name",
@@ -6364,7 +6746,7 @@ def _main_impl():
 
   # queryFormsByApp (query within specified app/cloud scope)
   pqfa = sub.add_parser("queryFormsByApp", help="Query explicit app/cloud scope or the selected app-root; ignores ambient defaults. ZERO rows means no matches in that scope, not global absence. Use queryForms for global discovery.")
-  pqfa.add_argument("--appNumber",  default=None,
+  pqfa.add_argument("--appNumber", "--appCode", dest="appNumber", default=None,
            help="App number exact filter (e.g., uhyl_aireqdecomp)")
   pqfa.add_argument("--cloudNumber", default=None,
            help="Business cloud number exact filter (e.g., uhyl_bfyTest1)")
@@ -6372,9 +6754,9 @@ def _main_impl():
     "--keyword", "--form-name", "--form", "--formNumber",
     dest="keyword", default=None,
     help=(
-      "可选过滤条件：按表单名称或编码缩小结果；不传即可列出所选范围内全部表单。"
-      "无过滤条件时不要传空值或自行构造占位文本；--form-name、--form 和 "
-      "--formNumber 是兼容的参数写法"
+      "Optional filter by form name or number; omit it to list all forms in the selected scope. "
+      "Do not pass an empty or invented placeholder when no filter is intended; --form-name, "
+      "--form and --formNumber are compatible selector spellings"
     ),
   )
   pqfa.add_argument("--json", action="store_true", dest="raw_json",
@@ -6399,15 +6781,25 @@ def _main_impl():
   pgs.add_argument("--json", action="store_true", dest="raw_json",
            help="Output raw JSON")
 
-  pgdm = sub.add_parser("getDomainModel", help="按准确模型类型读取平台元模型 JSON")
-  pgdm.add_argument("--modelType", required=True, help="准确的平台模型类型，例如 BillFormModel")
-  pgdm.add_argument("--onlyEntity", default=None, help="可选 onlyEntity 查询值，原样传递")
-  pgdm.add_argument("--ext", default=None, help="可选扩展设计器查询值，原样传递")
-  pgdm.add_argument("--bizext", default=None, help="可选业务对象扩展查询值，原样传递")
-  pgdm.add_argument("--appId", default=None, help="可选应用编码，按接口 appId 查询键原样传递")
+  pgdm = sub.add_parser(
+    "getDomainModel",
+    help="Read one platform domain-model JSON by exact model type",
+  )
+  pgdm.add_argument("--modelType", required=True,
+       help="Exact platform model type, for example BillFormModel")
+  pgdm.add_argument("--onlyEntity", default=None,
+       help="Optional platform onlyEntity query value, passed through unchanged")
+  pgdm.add_argument("--ext", default=None,
+       help="Optional platform extension-designer query value, passed through unchanged")
+  pgdm.add_argument("--bizext", default=None,
+       help="Optional platform business-object-extension query value, passed through unchanged")
+  pgdm.add_argument("--appId", default=None,
+       help="Optional platform application code carried in the appId query key")
   pgdm_output = pgdm.add_mutually_exclusive_group(required=True)
-  pgdm_output.add_argument("--output-file", dest="domain_output_file", help="将 data JSON 文本写入 UTF-8 文件，stdout 只返回紧凑回执")
-  pgdm_output.add_argument("--stdout-data", action="store_true", help="明确输出完整响应；BillFormModel 可能超过 1 MB")
+  pgdm_output.add_argument("--output-file", dest="domain_output_file",
+       help="Write data JSON text to this UTF-8 file and print only a compact receipt")
+  pgdm_output.add_argument("--stdout-data", action="store_true",
+       help="Explicitly print the complete response; BillFormModel can exceed 1 MB")
 
   # discover (zero cold-start one-click discovery: locate form/app + get main entity + existing bizWord styles)
   pdv = sub.add_parser(
@@ -6438,7 +6830,7 @@ def _main_impl():
   paf_selectors = paf.add_mutually_exclusive_group(required=True)
   paf_selectors.add_argument("--field-name", dest="field_name",
                    help="New field display name")
-  paf_selectors.add_argument("--fields", help="JSON array/file: name, bizWord, fieldType, optional combo/comboJson/required/fullLine/panel/before/after; one ordered batch")
+  paf_selectors.add_argument("--fields", help="JSON array/file: name,bizWord,fieldType; optional comboJson,required,fullLine,panel,before,after,basedata,reference,mulTable,unitField,flexType,refBaseField,refDisplayProp,asstTypeId,asstType; one ordered batch")
   paf.add_argument("--validate-only", action="store_true", help="Validate --fields completely without platform writes")
   paf.add_argument("--biz-word", dest="biz_word",
                    help="Concise semantic English business word without ISV prefix")
@@ -6707,15 +7099,15 @@ def _main_impl():
 
   # queryPublicTemplates
   ppt = sub.add_parser("queryPublicTemplates", help="Query public template list")
-  ppt.add_argument("--modelType", default="FormModel_Bill",
-           help="Model type: FormModel_Bill (Bill)/ FormModel_Base（Base Data）")
+  ppt.add_argument("--modelType", default="BillFormModel",
+           help="Model type: BillFormModel (Bill) / BaseFormModel (Base Data)")
   ppt.add_argument("--json", action="store_true", dest="raw_json",
            help="Output raw JSON")
 
   # queryBizTemplates
   pbt = sub.add_parser("queryBizTemplates", help="Query business template list (specified app scope)")
-  pbt.add_argument("--modelType", default="FormModel_Bill",
-           help="Model type: FormModel_Bill / FormModel_Base")
+  pbt.add_argument("--modelType", default="BillFormModel",
+           help="Model type: BillFormModel / BaseFormModel")
   pbt.add_argument("--bizAppId", default=None, help="App ID")
   pbt.add_argument("--bizAppNumber", default=None,
            help="App number (mutually exclusive with bizAppId)")
@@ -6935,6 +7327,17 @@ def _main_impl():
     help="Binary arithmetic operator")
   p_efc.add_argument("--right", required=True, help="Right numeric operand field")
 
+  p_etdc = sub.add_parser(
+    "ensureTimeDifferenceCalculation",
+    help="Idempotently calculate decimal hours between two same-entity TimeFields")
+  p_etdc_target = p_etdc.add_mutually_exclusive_group(required=True)
+  p_etdc_target.add_argument("--formNumber", help="Exact form number")
+  p_etdc_target.add_argument("--form-name", dest="form_name", help="Exact form name or number")
+  p_etdc.add_argument("--entity", help="Optional exact entity; inferred from fields when omitted")
+  p_etdc.add_argument("--target", required=True, help="Numeric target field key or caption")
+  p_etdc.add_argument("--start", required=True, help="Start TimeField key or caption")
+  p_etdc.add_argument("--end", required=True, help="End TimeField key or caption")
+
   p_erff = sub.add_parser(
     "ensureRuleFunctionFormula",
     help="Compile one released FX function call into a same-entity formula rule",
@@ -6948,6 +7351,11 @@ def _main_impl():
     "--input", required=True, dest="input_file",
     help="Inline JSON or file with {call:{functionId,args:[{field}|{literal}|{call}|{condition}]}}",
   )
+  p_erff_timing = p_erff.add_mutually_exclusive_group()
+  p_erff_timing.add_argument("--event", action="append", dest="events",
+                             help="Select exact trigger timings for a new rule")
+  p_erff_timing.add_argument("--add-event", action="append", dest="add_events",
+                             help="Append timing without clearing existing events")
 
   p_ecfs = sub.add_parser(
     "ensureConditionalFieldState",
@@ -6968,6 +7376,11 @@ def _main_impl():
             help="Target field key or caption; repeat to control multiple fields in one rule")
   p_ecfs.add_argument("--behavior", required=True, choices=["show", "hide", "lock", "unlock"],
             help="Field state while the condition is true")
+  p_ecfs_timing = p_ecfs.add_mutually_exclusive_group()
+  p_ecfs_timing.add_argument("--add-event", action="append", dest="add_events",
+            help="Append a named timing to both branches while preserving existing timings")
+  p_ecfs_timing.add_argument("--event", action="append", dest="events",
+            help="Select the exact trigger timings for a new rule; repeat per timing")
 
   p_eces = sub.add_parser(
     "ensureConditionalEntryStyle",
@@ -7026,7 +7439,32 @@ def _main_impl():
     choices=["equals", "not-equals", "greater-than", "greater-or-equal", "less-than", "less-or-equal"])
   p_eccf.add_argument("--value", required=True)
   p_eccf.add_argument("--target", required=True, dest="targets", nargs="+",
-            help="One or more target field keys/captions in the same entity")
+            action="extend",
+            help="One or more target field keys/captions; repeat --target or list them after one flag")
+  p_eccf_timing = p_eccf.add_mutually_exclusive_group()
+  p_eccf_timing.add_argument("--add-event", action="append", dest="add_events",
+            help="Append a named timing, e.g. AfterCopy, preserving existing event bits")
+  p_eccf_timing.add_argument("--event", action="append", dest="events",
+            help="Select exact timings for a new rule; repeat per timing")
+
+  p_ecfc = sub.add_parser(
+    "ensureConditionalFieldChange",
+    help="Ensure one conditional field value-update service with optional trigger timings")
+  p_ecfc_target = p_ecfc.add_mutually_exclusive_group(required=True)
+  p_ecfc_target.add_argument("--formNumber", help="Exact form number")
+  p_ecfc_target.add_argument("--form-name", dest="form_name", help="Exact form name or number")
+  p_ecfc.add_argument("--entity", help="Optional exact entity; inferred from the fields")
+  p_ecfc.add_argument("--condition-field", required=True, dest="condition_field")
+  p_ecfc.add_argument("--operator", required=True,
+            choices=["equals", "not-equals", "greater-than", "greater-or-equal",
+                     "less-than", "less-or-equal", "empty", "not-empty"])
+  p_ecfc.add_argument("--value", help="Omit for empty/not-empty")
+  p_ecfc.add_argument("--target", required=True, help="Field whose value-update service is called")
+  p_ecfc_timing = p_ecfc.add_mutually_exclusive_group()
+  p_ecfc_timing.add_argument("--add-event", action="append", dest="add_events",
+            help="Append a named timing, e.g. AfterCopy")
+  p_ecfc_timing.add_argument("--event", action="append", dest="events",
+            help="Select the exact trigger timings for a new rule; repeat per timing")
 
   p_eccv = sub.add_parser(
     "ensureConditionalCopyFieldValue",
@@ -7035,13 +7473,15 @@ def _main_impl():
   p_eccv_target.add_argument("--formNumber", help="Exact form number")
   p_eccv_target.add_argument("--form-name", dest="form_name", help="Exact form name or number")
   p_eccv.add_argument("--entity", help="Optional exact entity; inferred from fields when omitted")
-  p_eccv.add_argument("--condition-field", required=True, dest="condition_field")
+  p_eccv.add_argument("--condition-field", dest="condition_field")
   p_eccv.add_argument(
-    "--operator", required=True,
+    "--operator",
     choices=["equals", "not-equals", "greater-than", "greater-or-equal", "less-than", "less-or-equal"])
-  p_eccv.add_argument("--value", required=True)
-  p_eccv.add_argument("--source", required=True, help="Source field key or caption")
-  p_eccv.add_argument("--target", required=True, help="Target field key or caption")
+  p_eccv.add_argument("--value")
+  p_eccv.add_argument("--source", help="Source field key or caption")
+  p_eccv.add_argument("--target", help="Target field key or caption")
+  p_eccv.add_argument("--input", dest="input_file",
+                        help="JSON {mappings:[{source,target}], optional conditionField/operator/value/ruleId/branch}; branch defaults to true (condition met), false executes when not met")
   p_eccv.add_argument("--only-empty-target", action="store_true", dest="only_empty_target")
 
   p_ecca = sub.add_parser(
@@ -7076,10 +7516,12 @@ def _main_impl():
     "--operator",
     choices=["equals", "not-equals", "greater-than", "greater-or-equal", "less-than", "less-or-equal", "empty", "not-empty"])
   p_eccr.add_argument("--value")
-  p_eccr.add_argument("--source-reference", required=True, dest="source_reference")
-  p_eccr.add_argument("--source-property", required=True, dest="source_property",
+  p_eccr.add_argument("--source-reference", dest="source_reference")
+  p_eccr.add_argument("--source-property", dest="source_property",
             help="Exact property key already declared in the source field RefProps")
-  p_eccr.add_argument("--target", required=True, help="Same-entity target field")
+  p_eccr.add_argument("--target", help="Same-entity target field")
+  p_eccr.add_argument("--input", dest="input_file",
+                        help="JSON {mappings:[{sourceReference,sourceProperty,target}], optional conditionField/operator/value/ruleId/branch}; branch defaults to true (condition met), false executes when not met")
   p_eccr.add_argument("--only-empty-target", action="store_true", dest="only_empty_target")
 
   p_eqc = sub.add_parser(
@@ -7093,6 +7535,12 @@ def _main_impl():
             help="Source QtyField key or caption")
   p_eqc.add_argument("--target-qty", required=True, action="append", dest="target_qty",
             help="Target QtyField key or caption; repeat for multiple targets")
+  for service_parser in (p_eccs, p_eccv, p_ecca, p_eccr, p_eqc):
+    timing = service_parser.add_mutually_exclusive_group()
+    timing.add_argument("--event", action="append", dest="events",
+                        help="Select exact timings for a new rule; repeat per timing")
+    timing.add_argument("--add-event", action="append", dest="add_events",
+                        help="Append a timing while preserving existing timings")
 
   p_ur = sub.add_parser("updateRule", help="Modify rule")
   p_ur_target = p_ur.add_mutually_exclusive_group(required=True)
@@ -7231,6 +7679,19 @@ def _main_impl():
   p_sp_input.add_argument("--input", dest="input_file",
            help='Legacy one-element property map, e.g. {"MustInput":true}')
 
+  p_rename = sub.add_parser(
+    "renameElementKey",
+    help="Rename one existing field/control/entry key and migrate verified rule references",
+  )
+  p_rename_form = p_rename.add_mutually_exclusive_group(required=True)
+  p_rename_form.add_argument("--formNumber", help="Exact existing form number")
+  p_rename_form.add_argument("--form-name", dest="form_name", help="Exact form name or number")
+  p_rename.add_argument("--app-code", "--appCode", default=None, dest="app_code")
+  p_rename.add_argument("--app-name", "--appName", default=None, dest="app_name")
+  p_rename.add_argument("--element", required=True, help="Current exact key or unique display name")
+  p_rename.add_argument("--new-key", required=True, dest="new_key",
+                        help="Requested new logical key; developer prefix is applied once")
+
   p_sf = sub.add_parser("setFeatures", help="Set feature control (complex property)")
   p_sf_form = p_sf.add_mutually_exclusive_group(required=True)
   p_sf_form.add_argument("--formNumber", help="Exact existing form number")
@@ -7312,6 +7773,21 @@ def _main_impl():
   p_scp.add_argument("--input", required=True, dest="input_file",
             help="Property data JSON file path or inline JSON string")
 
+  p_cdm = sub.add_parser(
+    "configureDropdownMenu",
+    help="Edit one button dropdown menu, preserving existing identities in one save",
+  )
+  p_cdm_form = p_cdm.add_mutually_exclusive_group(required=True)
+  p_cdm_form.add_argument("--formNumber", help="Exact existing form number")
+  p_cdm_form.add_argument("--form-name", dest="form_name", help="Exact form name or number")
+  p_cdm_target = p_cdm.add_mutually_exclusive_group()
+  p_cdm_target.add_argument("--elementKey", help="Persisted button/toolbar-item key")
+  p_cdm_target.add_argument("--element", help="Exact key or unique display name")
+  p_cdm.add_argument("--input", required=True, dest="input_file",
+                     help="Dropdown-menu intent JSON or UTF-8 JSON file")
+  p_cdm.add_argument("--locale",
+                     help="Exact language key returned for an ambiguous multilingual menu title")
+
   p_scs = sub.add_parser(
     "setCustomStyle",
     help="Set one element's custom CSS; the CLI owns designer-compatible encoding",
@@ -7463,7 +7939,7 @@ def _main_impl():
     help=("Must-input condition JSON with RuleCondition and RuleDescription; "
           "the CLI supplies _Type_=PreCondition; RuleTransExpr and Id are optional"))
   p_smic_condition.add_argument(
-    "--when-element",
+    "--when-element", "--condition-field",
     help="Exact trigger-field key or business display name for a simple comparison")
   p_smic_condition.add_argument(
     "--clear", action="store_true",
@@ -7474,6 +7950,8 @@ def _main_impl():
           "typed from the trigger field, while selection labels resolve to persisted values"))
   p_smic.add_argument(
     "--operator", choices=["=", "<>", ">", ">=", "<", "<=", "empty", "not-empty"],
+    type=lambda value: {"equals": "=", "not-equals": "<>", "greater-than": ">",
+                        "less-than": "<", "greater-or-equal": ">=", "less-or-equal": "<="}.get(value, value),
     help="Comparison operator used with --when-element; empty/not-empty take no value")
   p_smic.add_argument(
     "--value", dest="when_value",
@@ -7792,12 +8270,12 @@ def _main_impl():
   p_au.add_argument("--bizAppId", default=None, help="App ID")
   p_au.add_argument("--bizAppNumber", default=None, help="应forNumber")
   p_au.add_argument("--name", required=True, help="Feature group名称")
-  p_au.add_argument("--number", default=None,
-                    help="Feature groupNumber（optional；default由后端生成 lingee_<lowercase unitId>）")
+  p_au.add_argument("--number", required=True,
+                    help="Feature group code (required by the platform; preserve the requested code)")
   p_au.add_argument("--description", default=None,
-                    help="Feature group描述（optional；defaultempty string）")
+                    help="Feature group description (defaults to the group name)")
   p_au.add_argument("--seq", type=int, default=None,
-                    help="序号 [0, 1000)（optional；default0）")
+                    help="序号 [1, 999]；省略时按现有分组的已验证序号追加")
   p_au.add_argument("--parentUnitId", default=None, help="上级Feature groupID（空=一级分组）")
   p_au.add_argument("--isLeaf", default=None, choices=["true", "false"], help="是否叶子节点（Defaulttrue）")
 
@@ -7973,7 +8451,7 @@ def _main_impl():
   p_lf.add_argument("--pageType", required=True, choices=["Empty", "Inherit"],
            help="页面类型：Empty（空白）/ Inherit（继承）")
 
-  # KSQL 导出/查询（预置数据/基础数据，管理员/子管理员）
+  # KSQL 导出/查询（预置数据/基础数据，管理员/子管理员）—— 本地补丁 #14
   p_ksql_r = sub.add_parser("ksqlListDbRoutes", help="KSQL 分库列表（sys/secd/scm...）")
   p_ksql_dt = sub.add_parser("ksqlListDbTypes", help="KSQL 支持的数据库类型列表")
   p_ksql_tr = sub.add_parser("ksqlTranslate", help="翻译 KSQL 语句")
@@ -8246,7 +8724,7 @@ def _main_impl():
   p_acs_target.add_argument("--form-name", dest="form_name", help="Exact form name or number")
   p_acs.add_argument(
     "--input", dest="input_file", required=True,
-    help="Inline JSON or JSON file with parent and compact controls array",
+    help="JSON object with controls [{type, name}]; optional parent defaults to the live form root",
   )
   p_acs.add_argument(
     "--app-root", default=None, dest="app_root",
@@ -8714,7 +9192,11 @@ def _main_impl():
         _load_ops(args.input_file)
       )
     except (OSError, ValueError, TypeError, json.JSONDecodeError) as exc:
-      raise _CliUsageError(str(exc)) from exc
+      raise _CliUsageError(str(exc), {
+        **(getattr(exc, "recovery", None) or {}),
+        "describeCommand": "describeCommand addControls",
+        "payloadSchemaRef": _CATALOG_PAYLOAD_SCHEMA_REFS["addControls"],
+      }) from exc
 
   if args.cmd == "setMustInputCondition":
     if args.when_element and args.when_equals is None and args.operator is None:
@@ -8739,6 +9221,7 @@ def _main_impl():
     _route_unstructured_prints_to_stderr()
   app_root = _resolve_app_root_arg(args)
   if app_root:
+    validate_execution_binding(app_root)
     _retarget_runtime_dir(app_root)
 
   # 设置全局输出文件（--output）
@@ -8782,7 +9265,7 @@ def _main_impl():
       raise _CliUsageError("--fields carries each field specification; do not combine single-field specifications")
     if args.field_type != "TextField" or args.required or any(getattr(args, name, None) for name in (
         "basedata", "ref_bill", "mul_table", "unit_field", "flex_type", "ref_base_field", "ref_display_prop", "asstTypeId", "asst_type", "extAppId")):
-      raise _CliUsageError("--fields supports per-item basic and selection specs; use the single-field entry for reference-specific or selected-extension options")
+      raise _CliUsageError("--fields carries reference/type options on each item; do not combine single-field or selected-extension flags")
     validate_add_fields_input(args.fields)
     if args.validate_only:
       pjson({"status": True, "data": {"validated": len(args.fields), "writeAttempted": False,
@@ -9001,11 +9484,23 @@ def _main_impl():
         pjson(_dynamic_identity_failure)
         sys.exit(8)
 
+      if (raw_artifact.get("entities") or [{}])[0].get("type") == "MainEntity":
+        _retained_creation = _dynamic_creation_receipt(app_root, artifact_file)
+        if _retained_creation:
+          pjson(_retained_creation)
+          return 3
+
       _dynamic_input_failure = _dynamic_form_artifact_preflight(raw_artifact)
       if _dynamic_input_failure:
         pjson(_dynamic_input_failure)
         return 1
 
+      _dynamic_reference_failure = _resolve_dynamic_reference_fields(
+        raw_artifact, app_root=app_root, isv=(_load_workspace_at(app_root) or {}).get("isv", ""))
+      if _dynamic_reference_failure:
+        pjson(_dynamic_reference_failure)
+        return 1
+
       # 2) workspace 回退：优先 --app-root 下 workspace；其次全局 RUNTIME_DIR。
       # 显式名称尚未解析时只允许身份自举，禁止自动创建默认分组。
       ws = _load_workspace_for_write(
@@ -9016,6 +9511,12 @@ def _main_impl():
       )
       _isv = ws.get("isv", "")
       _app = ws.get("appNumber", "")
+      if _explicit_dynamic_identity:
+        _standard = ws.get("standard")
+        if isinstance(_standard, str):
+          _standard = _standard.strip().lower() == "true"
+        _explicit_dynamic_identity = make_entity_key_for(
+          _explicit_dynamic_identity, _isv, standard=_standard)
 
       # 3) 模板resolve：CLI > artifact.templateNumber > manifest 对应项
       _tpl = _resolve_template_number(args.template, artifact_file, manifest)
@@ -9229,6 +9730,12 @@ def _main_impl():
             except Exception as exc:
               _apply_dynamic_ui_failure_contract(result, _summary_run, exc)
           _apply_build_failure_contract(result, _summary_run)
+          if ents0 and ents0[0].get("type") == "MainEntity":
+            _retained_creation = _dynamic_creation_receipt(app_root, artifact_file, result)
+            if _retained_creation:
+              result.update(doNotRetryRun=True, retryable=False, retryAdvice="inspect_retained_form",
+                            reconciliation=_retained_creation["reconciliation"],
+                            modelInstruction=_retained_creation["modelInstruction"])
           _append_meta_event(
             "buildMeta.finished",
             command="run",
@@ -9334,6 +9841,7 @@ def _main_impl():
         cfg,
         app_root,
         identity_only=bool(args.bizUnitId or requested_biz_unit_name),
+        app_code=args.app_code,
       )
       _isv = ws.get("isv", "")
       _app = ws.get("appNumber", "")
@@ -9370,14 +9878,19 @@ def _main_impl():
         BuildDependencyError,
         bind_ref_bill_ids,
         collect_ref_bill_targets,
-        dependency_blocked_results,
+        collect_build_dependencies,
+        partition_build_wave,
         describe_build_plan,
         plan_build_waves,
         split_deferred_ref_bill_writes,
         split_deferred_property_fields,
         validate_deferred_property_field_sources,
+        validate_ref_bill_owner,
       )
 
+      dependencies = collect_build_dependencies(artifact_files, manifest=manifest, isv=_isv)
+      if flat_parallel and any(dependencies.values()):
+        raise _CliUsageError("BATCH_INPUT_DEPENDENCIES_REQUIRE_WAVES: referenced objects must finish before dependent writes")
       if flat_parallel or len(artifact_files) <= 1:
         build_waves = [artifact_files]
       else:
@@ -9386,6 +9899,7 @@ def _main_impl():
             artifact_files,
             manifest=manifest,
             isv=_isv,
+            dependencies=dependencies,
           )
         except BuildDependencyError as exc:
           pjson(exc.to_dict())
@@ -9418,7 +9932,7 @@ def _main_impl():
             ]
             continue
           prepared = decorated
-        artifact_errors = validate_deferred_property_field_sources(prepared)
+        artifact_errors = validate_deferred_property_field_sources(prepared) + validate_ref_bill_owner(prepared)
         validation_copy = copy.deepcopy(prepared)
         validation_copy.pop("listConfiguration", None)
         validation_copy.pop("formComposition", None)
@@ -9463,6 +9977,20 @@ def _main_impl():
         })
         sys.exit(3)
 
+      from _core.build_receipts import BuildReceipts
+      from kd_env_loader import load_environment_identity
+      progress = BuildReceipts(
+        app_root, biz_app_id, load_environment_identity(), prepared_artifacts,
+        resume_result=args.resume_result, reconcile_only=args.reconcile_only,
+        options=["--bizAppId", str(biz_app_id)]
+                + (["--bizUnitId", str(biz_unit_id)] if biz_unit_id else [])
+                + (["--template", args.template] if args.template is not None else []),
+      ) if app_root else None
+      if args.reconcile_only and not args.resume_result:
+        raise _CliUsageError("BATCH_INPUT_RESUME_REQUIRED: --reconcile-only requires --resume-result")
+      if args.resume_result and progress is None:
+        raise _CliUsageError("BATCH_INPUT_APP_ROOT_REQUIRED: resume requires --app-root")
+
       from threading import Lock
       ref_bill_id_cache = {}
       ref_bill_id_lock = Lock()
@@ -9475,36 +10003,39 @@ def _main_impl():
           cached = ref_bill_id_cache.get(key)
           if cached:
             return cached
-          queried = do_query_forms(cfg, token, keyword=target_number)
-          rows = (queried or {}).get("data") or []
-          exact = [
-            row for row in rows
-            if isinstance(row, dict)
-            and str(row.get("formNumber") or "").strip().lower() == key
-          ]
-          unique_ids = {
-            str(row.get("formId") or "").strip()
-            for row in exact
-            if str(row.get("formId") or "").strip()
-          }
-          if len(unique_ids) != 1:
-            raise ValueError(
-              f"REF_BILL_TARGET_UNRESOLVED: formNumber={target_number!r} "
-              f"matched {len(unique_ids)} exact form IDs"
-            )
-          non_bill = [
-            str(row.get("modelType") or "").strip()
-            for row in exact
-            if str(row.get("modelType") or "").strip() != "BillFormModel"
-          ]
-          if non_bill:
-            raise ValueError(
-              f"REF_BILL_TARGET_TYPE_MISMATCH: formNumber={target_number!r} "
-              f"is not a BillFormModel"
-            )
-          form_id = next(iter(unique_ids))
+        queried = do_query_forms(cfg, token, keyword=target_number)
+        if not _is_api_success(queried):
+          raise RuntimeError("REF_BILL_LOOKUP_UNCONFIRMED: " + (_extract_error_message(queried) or "queryForms failed"))
+        rows = (queried or {}).get("data") or []
+        exact = [
+          row for row in rows
+          if isinstance(row, dict)
+          and str(row.get("formNumber") or "").strip().lower() == key
+        ]
+        unique_ids = {
+          str(row.get("formId") or "").strip()
+          for row in exact
+          if str(row.get("formId") or "").strip()
+        }
+        if len(unique_ids) != 1:
+          raise ValueError(
+            f"REF_BILL_TARGET_UNRESOLVED: formNumber={target_number!r} "
+            f"matched {len(unique_ids)} exact form IDs"
+          )
+        non_bill = [
+          str(row.get("modelType") or "").strip()
+          for row in exact
+          if str(row.get("modelType") or "").strip() != "BillFormModel"
+        ]
+        if non_bill:
+          raise ValueError(
+            f"REF_BILL_TARGET_TYPE_MISMATCH: formNumber={target_number!r} "
+            f"is not a BillFormModel"
+          )
+        form_id = next(iter(unique_ids))
+        with ref_bill_id_lock:
           ref_bill_id_cache[key] = form_id
-          return form_id
+        return form_id
 
       def _bind_ref_bill_targets(artifact):
         resolved = {}
@@ -9588,8 +10119,16 @@ def _main_impl():
           ops=decorated_ops,
         )
         if not _is_api_success(result):
-          raise ValueError(
-            "REF_BILL_ADD_FAILED: " + (_extract_error_message(result) or "modifyMeta failed")
+          raise _PostBuildWriteError(
+            "REF_BILL_ADD_FAILED: " + (_extract_error_message(result) or "modifyMeta failed"),
+            result,
+            {"command": "modifyMeta", "appRoot": app_root,
+             "input": {"formId": str(receipt.get("formId") or "").strip(),
+                       "formNumber": root_number, "ops": raw_ops},
+             "expectedFields": [{"fieldKey": item["field"]["fieldKey"],
+                                 "fieldType": "RefBillField",
+                                 "billEntityId": item["field"].get("billEntityId")}
+                                for item in deferred]},
           )
         verified = []
         for item in deferred:
@@ -9948,7 +10487,33 @@ def _main_impl():
       )
 
       def _one(afile):
+        reused = progress.reused(afile) if progress else None
+        if reused:
+          return reused
         t0 = _time.time()
+        if args.reconcile_only:
+          previous = progress.current(afile)
+          if previous.get("writeAttempted") is False:
+            return previous
+          receipt = previous.get("result") or {}
+          targets = (receipt.get("data") or {}).get("entityResults", [])
+          if targets and all(row.get("formId") for row in targets) and len(targets) == len(previous["targetNumbers"]):
+            verification = _verify_build_meta_readback(cfg, token, prepared_artifacts[afile], receipt)
+            return {**previous, "ok": False, "phase": "retainedRepairRequired",
+                    "reconciliationVerification": verification,
+                    "errorCode": "BATCH_WRITE_RECONCILIATION_REQUIRED",
+                    "errors": ["Retained identity read back; finish the original repair plan through existing-form writers. Creation remains blocked."]}
+          observed = [do_query_forms(cfg, token, keyword=number) for number in previous["targetNumbers"]]
+          absent = all(_is_api_success(result) and isinstance(result.get("data"), list)
+                       and not any(str(row.get("formNumber") or "").casefold() == number.casefold()
+                                   for row in result["data"] if isinstance(row, dict))
+                       for number, result in zip(previous["targetNumbers"], observed))
+          return {**previous, "ok": False, "phase": "reconciledAbsent" if absent else "writeUnknown",
+                  "writeAttempted": False if absent else previous.get("writeAttempted"),
+                  "absenceEvidence": observed if absent else None,
+                  "errorCode": "BATCH_INPUT_READY_TO_RESUME" if absent else "BATCH_WRITE_RECONCILIATION_REQUIRED",
+                  "errors": ["Absence confirmed; use the returned resume command" if absent
+                             else "Read did not prove absence; do not adopt a same-number object as this batch's success"]}
         raw = copy.deepcopy(prepared_artifacts[afile])
         tpl_one = tpl_per_artifact.get(afile, "bos_billtpl")
         dec = raw
@@ -9957,12 +10522,16 @@ def _main_impl():
         try:
           ref_bill_errors = _bind_ref_bill_targets(dec)
         except Exception as exc:
-          ref_bill_errors = [str(exc)]
+          return {"artifact": os.path.basename(afile), "ok": False, "phase": "resolveRefBill",
+                  "writeAttempted": False, "errorCode": _exception_error_code(exc)[0],
+                  "errors": [str(exc)], "elapsed_sec": round(_time.time() - t0, 2)}
         if ref_bill_errors:
           return {
             "artifact": os.path.basename(afile),
             "ok": False,
             "phase": "resolveRefBill",
+            "writeAttempted": False,
+            "errorCode": "REF_BILL_TARGET_UNRESOLVED",
             "errors": ref_bill_errors,
             "elapsed_sec": round(_time.time() - t0, 2),
           }
@@ -9976,19 +10545,39 @@ def _main_impl():
             "artifact": os.path.basename(afile),
             "ok": False,
             "phase": "preValidate",
+            "writeAttempted": False,
+            "errorCode": "ARTIFACT_INPUT_INVALID",
             "errors": errs,
             "elapsed_sec": round(_time.time() - t0, 2),
           }
+        if progress:
+          try:
+            progress.start(afile)
+          except ValueError as exc:
+            return {"artifact": os.path.basename(afile), "ok": False,
+                    "phase": "preflight", "writeAttempted": False,
+                    "errorCode": "BATCH_WRITE_RECONCILIATION_REQUIRED", "errors": [str(exc)],
+                    "elapsed_sec": round(_time.time() - t0, 2)}
         try:
           raw_result = do_build_meta(
             cfg, token, dec,
             biz_app_id=biz_app_id,
             biz_unit_id=biz_unit_id,
             template_number=tpl_one,
+            on_write_result=(lambda response: progress.finish(afile, {
+              "ok": False, "phase": "rootReceipt", "writeAttempted": True,
+              "result": _transform_build_meta_result(response),
+            })) if progress else None,
           )
           transformed = _transform_build_meta_result(raw_result)
           # Derive write success from entity counts, never transport status alone.
           summary_one = _summarize_build_meta_result(transformed, artifact=dec)
+          if progress:
+            progress.finish(afile, {"ok": False, "phase": "buildMeta",
+                                   "writeAttempted": raw_result.get("writeAttempted", True),
+                                   "result": transformed, "summary": summary_one,
+                                   "metadataRetained": any(row.get("formId") for row in
+                                       (transformed.get("data") or {}).get("entityResults", []))})
           verification = None
           final_ok = bool(summary_one.get("ok"))
           phase = "buildMeta"
@@ -10000,6 +10589,7 @@ def _main_impl():
           list_configuration_result = None
           dynamic_ui_result = None
           form_composition_result = None
+          pending_write = None
           property_partial_only = (
             not final_ok
             and int(summary_one.get("successCount") or 0) > 0
@@ -10039,6 +10629,9 @@ def _main_impl():
               final_ok = False
               phase = "addRefBill"
               errors.append(str(exc))
+              if isinstance(exc, _PostBuildWriteError):
+                ref_bill_result = {"modifyMeta": exc.result, "status": False}
+                pending_write = exc.pending_write
           if final_ok and deferred_ref_bill_phase["propertySettings"]:
             try:
               ref_bill_property_result = _apply_ref_bill_property_settings(
@@ -10148,11 +10741,20 @@ def _main_impl():
                   f"failed={verify_summary.get('failed', 0)} "
                   f"errors={verify_summary.get('errors', 0)}"
                 )
+          if not final_ok and phase != "buildMeta" and not summary_one.get("errorCode"):
+            _attach_post_build_phase_failure(
+              summary_one, transformed, phase=phase, app_root=app_root,
+              artifact_path=afile, pending_write=pending_write,
+            )
           _apply_build_failure_contract(transformed, summary_one)
           return {
             "artifact": os.path.basename(afile),
+            "artifactPath": os.path.abspath(afile),
             "ok": final_ok,
             "phase": phase,
+            "writeAttempted": raw_result.get("writeAttempted", True),
+            "errorCode": (transformed.get("errorCode") or "0") if phase == "buildMeta"
+                         else _exception_error_code(ValueError(errors[0]))[0] if errors else "0",
             "result": transformed,
             "summary": summary_one,
             "refBillResult": ref_bill_result,
@@ -10173,19 +10775,40 @@ def _main_impl():
           return {
             "artifact": os.path.basename(afile),
             "ok": False,
-            "phase": "buildMeta",
+            "phase": "writeUnknown",
+            "writeAttempted": None,
+            "errorCode": "BATCH_WRITE_RESULT_UNKNOWN",
             "errors": [str(e)],
             "elapsed_sec": round(_time.time() - t0, 2),
           }
 
+      def _cancelled(path):
+        row = {"artifact": os.path.basename(path), "artifactPath": path, "ok": False,
+               "phase": "cancelled", "writeAttempted": False,
+               "errors": ["Not started because --fail-fast was requested"], "elapsed_sec": 0.0}
+        return progress.finish(path, row) if progress else row
+
       results = []
       fail_fast = bool(getattr(args, "fail_fast", False))
       t_start = _time.time()
       aborted = False
       dependency_blocked = False
-      for wave_idx, wave_files in enumerate(build_waves, 1):
+      succeeded_paths = set()
+      if progress:
+        for source in artifact_files:
+          reused = progress.reused(source)
+          if reused:
+            _cache_build_receipts(reused)
+            succeeded_paths.add(os.path.normpath(os.path.abspath(source)))
+      for wave_idx, wave_files in enumerate([artifact_files] if args.reconcile_only else build_waves, 1):
         if aborted:
-          break
+          results.extend(_cancelled(path) for path in wave_files)
+          continue
+        wave_files, blocked = (wave_files, []) if args.reconcile_only else partition_build_wave(wave_files, dependencies, succeeded_paths)
+        results.extend(progress.finish(row["artifactPath"], row) if progress else row for row in blocked)
+        dependency_blocked = dependency_blocked or bool(blocked)
+        if not wave_files:
+          continue
         if len(build_waves) > 1:
           print(
             f"[runBatch] —— wave {wave_idx}/{len(build_waves)} "
@@ -10194,14 +10817,19 @@ def _main_impl():
             flush=True,
           )
         with ThreadPoolExecutor(max_workers=concurrency) as pool:
-          wave_result_start = len(results)
           futures = {pool.submit(_one, f): f for f in wave_files}
           try:
             for fut in as_completed(futures):
+              if fut.cancelled():
+                results.append(_cancelled(futures[fut]))
+                continue
               r = fut.result()
+              if progress:
+                r = progress.finish(futures[fut], r)
               results.append(r)
               if r.get("ok"):
                 _cache_build_receipts(r)
+                succeeded_paths.add(os.path.normpath(os.path.abspath(futures[fut])))
               print(
                 f"[runBatch] {'✅' if r['ok'] else '❌'} "
                 f"{r['artifact']} ({r['elapsed_sec']}s, phase={r['phase']})",
@@ -10213,27 +10841,9 @@ def _main_impl():
                   if not other.done():
                     other.cancel()
                 aborted = True
-                break
           finally:
-            pool.shutdown(wait=not (fail_fast and aborted))
-
-        wave_failed = any(
-          not result["ok"] for result in results[wave_result_start:]
-        )
-        if wave_failed and wave_idx < len(build_waves):
-          blocked = dependency_blocked_results(
-            build_waves,
-            failed_wave_index=wave_idx,
-          )
-          results.extend(blocked)
-          dependency_blocked = bool(blocked)
-          aborted = True
-          print(
-            f"[runBatch] ⛔ wave {wave_idx} 失败；"
-            f"{len(blocked)} 份后续 artifact 因依赖屏障未写入",
-            file=sys.stderr,
-            flush=True,
-          )
+            # Running writes cannot be cancelled; collect their real receipts.
+            pool.shutdown(wait=True)
 
       total = round(_time.time() - t_start, 2)
       succ = sum(1 for r in results if r["ok"])
@@ -10258,14 +10868,14 @@ def _main_impl():
       retained = [
         row for item in results if not item.get("ok")
         for row in ((item.get("result") or {}).get("data") or {}).get("entityResults", [])
-        if row.get("formId") and not row.get("success")
+        if row.get("formId")
       ]
       if retained:
-        summary["retainedTargets"] = retained
+        summary.setdefault("retainedTargets", retained)
         summary["metadataRetained"] = True
         summary["doNotRetryBuildMeta"] = True
         summary.setdefault("retryAdvice", "reconcile_before_retry")
-        summary["reconciliation"] = [{"command": "getFormSchema", "formId": row["formId"]} for row in retained]
+        summary.setdefault("reconciliation", [{"command": "getFormSchema", "formId": row["formId"]} for row in retained])
       _append_meta_event(
         "buildMeta.finished",
         command="runBatch",
@@ -10276,11 +10886,12 @@ def _main_impl():
         **_summary_batch,
       )
       # auto归档：批量场景下把所有成功 formNumber 一次性回写
-      if app_root and _summary_batch.get("ok") and _summary_batch.get("formNumbers"):
+      if not args.reconcile_only and app_root and _summary_batch.get("ok") and _summary_batch.get("formNumbers"):
         _archive_finalize_metadata(app_root, _summary_batch["formNumbers"])
       # auto-sync dym to repo (runBatch)
       if (
         _summary_batch.get("ok")
+        and not args.reconcile_only
         and not args.no_sync_dym
         and app_root
         and _summary_batch.get("formNumbers")
@@ -10295,7 +10906,18 @@ def _main_impl():
           file=sys.stderr,
           flush=True,
         )
-      pjson(_attach_batch_delivery(_attach_available_form_numbers(cfg, token, summary), app_root))
+      summary = _attach_batch_delivery(_attach_available_form_numbers(cfg, token, summary), app_root)
+      if progress:
+        summary["executionFinished"] = True
+        summary["processId"] = os.getpid()
+        summary.update({key: progress.receipt[key] for key in
+                        ("executionBinding", "batchIdentity", "appRoot", "artifactPaths", "resultPath", "resume", "reconcile", "notStartedArtifacts")})
+        summary.setdefault("reconciliation", []).extend(progress.receipt["reconciliation"])
+        from _core.build_receipts import _atomic_json
+        _atomic_json(progress.result_path, summary)
+      elif app_root:
+        summary = save_run_batch_result(summary, app_root, artifact_files)
+      pjson(summary)
       if args.verify:
         verified = sum(
           1 for item in results
@@ -10419,8 +11041,13 @@ def _main_impl():
 
     elif args.cmd == "getDomainModel":
       token = do_auth(cfg)
-      result = do_get_domain_model(cfg, token, args.modelType, only_entity=args.onlyEntity,
-        ext=args.ext, bizext=args.bizext, app_id=args.appId)
+      result = do_get_domain_model(
+        cfg, token, args.modelType,
+        only_entity=args.onlyEntity,
+        ext=args.ext,
+        bizext=args.bizext,
+        app_id=args.appId,
+      )
       pjson(_persist_domain_model(result, args.domain_output_file, args.modelType)
             if args.domain_output_file else result)
 
@@ -10889,7 +11516,7 @@ def _main_impl():
         plugin_config, form_number=args.formNumber,
         biz_app_id=target.get("appId"))
       result = do_register_plugin(cfg, token, form_number=args.formNumber,
-                     plugin_config=plugin_config)
+                     plugin_config=plugin_config, app_root=args.app_root)
       if _is_api_success(result):
         result = _attach_plugin_readback(
           cfg, token, args.formNumber, plugin_config, result,
@@ -11002,6 +11629,18 @@ def _main_impl():
           args.left, args.operator, args.right)
         pjson(_attach_bound_form_identity(result, args))
 
+    elif args.cmd == "ensureTimeDifferenceCalculation":
+      token = do_auth(cfg)
+      blocked = _bind_rule_domain_target(cfg, token, args, args.cmd)
+      if blocked is not None:
+        pjson(blocked)
+      else:
+        _assert_form_number_target_owned(cfg, token, args, args.cmd)
+        result = do_ensure_time_difference_calculation(
+          cfg, token, args.formNumber, args.entity, args.target,
+          args.start, args.end)
+        pjson(_attach_bound_form_identity(result, args))
+
     elif args.cmd == "ensureRuleFunctionFormula":
       token = do_auth(cfg)
       blocked = _bind_rule_domain_target(cfg, token, args, args.cmd)
@@ -11015,11 +11654,14 @@ def _main_impl():
             "RULE_FUNCTION_INPUT_INVALID: expected exactly {call:{functionId,args}}"
           )
         result = do_ensure_rule_function_formula(
-          cfg, token, args.formNumber, args.entity, args.target, payload["call"]
+          cfg, token, args.formNumber, args.entity, args.target, payload["call"],
+          args.add_events, args.events,
         )
         pjson(_attach_bound_form_identity(result, args))
 
     elif args.cmd == "ensureConditionalFieldState":
+      if args.events and args.add_events:
+        raise _CliUsageError("use --event for exact new timings or --add-event to append")
       if args.operator in {"empty", "not-empty"} and args.value is not None:
         raise _CliUsageError(f"--operator {args.operator} takes no --value")
       if args.operator not in {"empty", "not-empty"} and args.value is None:
@@ -11032,7 +11674,8 @@ def _main_impl():
         _assert_form_number_target_owned(cfg, token, args, args.cmd)
         result = do_ensure_conditional_field_state(
           cfg, token, args.formNumber, args.entity, args.condition_field,
-          args.operator, args.value, args.target, args.behavior)
+          args.operator, args.value, args.target, args.behavior,
+          args.add_events, args.events)
         pjson(_attach_bound_form_identity(result, args))
 
     elif args.cmd == "ensureConditionalEntryStyle":
@@ -11068,7 +11711,8 @@ def _main_impl():
         _assert_form_number_target_owned(cfg, token, args, args.cmd)
         result = do_ensure_conditional_control_state(
           cfg, token, args.formNumber, args.entity, args.condition_field,
-          args.operator, args.value, args.target_control, args.behavior)
+          args.operator, args.value, args.target_control, args.behavior,
+          args.add_events, args.events)
         pjson(_attach_bound_form_identity(result, args))
 
     elif args.cmd == "ensureConditionalClearFields":
@@ -11080,20 +11724,46 @@ def _main_impl():
         _assert_form_number_target_owned(cfg, token, args, args.cmd)
         result = do_ensure_conditional_clear_fields(
           cfg, token, args.formNumber, args.entity, args.condition_field,
-          args.operator, args.value, args.targets)
+          args.operator, args.value, args.targets, args.add_events, args.events)
+        pjson(_attach_bound_form_identity(result, args))
+
+    elif args.cmd == "ensureConditionalFieldChange":
+      if args.events and args.add_events:
+        raise _CliUsageError("use --event for exact new timings or --add-event to append")
+      if args.operator in {"empty", "not-empty"} and args.value is not None:
+        raise _CliUsageError(f"--operator {args.operator} takes no --value")
+      if args.operator not in {"empty", "not-empty"} and args.value is None:
+        raise _CliUsageError("--value is required with this --operator")
+      token = do_auth(cfg)
+      blocked = _bind_rule_domain_target(cfg, token, args, args.cmd)
+      if blocked is not None:
+        pjson(blocked)
+      else:
+        _assert_form_number_target_owned(cfg, token, args, args.cmd)
+        result = do_ensure_conditional_field_change(
+          cfg, token, args.formNumber, args.entity, args.condition_field,
+          args.operator, args.value, args.target, args.add_events, args.events)
         pjson(_attach_bound_form_identity(result, args))
 
     elif args.cmd == "ensureConditionalCopyFieldValue":
+      if bool(args.input_file) == bool(args.source or args.target):
+        raise _CliUsageError("use --input for several mappings, or --source/--target for one mapping")
+      if args.input_file and args.only_empty_target:
+        raise _CliUsageError("with --input put per-row onlyEmptyTarget inside mappings")
+      if not args.input_file and not all((args.condition_field, args.operator, args.value, args.source, args.target)):
+        raise _CliUsageError("single mapping requires condition-field, operator, value, source and target")
       token = do_auth(cfg)
       blocked = _bind_rule_domain_target(cfg, token, args, args.cmd)
       if blocked is not None:
         pjson(blocked)
       else:
         _assert_form_number_target_owned(cfg, token, args, args.cmd)
-        result = do_ensure_conditional_copy_field_value(
+        result = (do_ensure_copy_field_mappings(
+          cfg, token, args.formNumber, _load_mapping_request(args),
+        ) if args.input_file else do_ensure_conditional_copy_field_value(
           cfg, token, args.formNumber, args.entity, args.condition_field,
           args.operator, args.value, args.source, args.target,
-          args.only_empty_target)
+          args.only_empty_target, args.add_events, args.events))
         pjson(_attach_bound_form_identity(result, args))
 
     elif args.cmd == "ensureConditionalCalculation":
@@ -11106,20 +11776,28 @@ def _main_impl():
         result = do_ensure_conditional_calculation(
           cfg, token, args.formNumber, args.entity, args.condition_field,
           args.operator, args.value, args.target, args.left,
-          args.calculation, args.right)
+          args.calculation, args.right, args.add_events, args.events)
         pjson(_attach_bound_form_identity(result, args))
 
     elif args.cmd == "ensureConditionalCarryReferenceProperty":
+      if bool(args.input_file) == bool(args.source_reference or args.source_property or args.target):
+        raise _CliUsageError("use --input for several mappings, or --source-reference/--source-property/--target for one mapping")
+      if args.input_file and args.only_empty_target:
+        raise _CliUsageError("with --input put per-row onlyEmptyTarget inside mappings")
+      if not args.input_file and not all((args.source_reference, args.source_property, args.target)):
+        raise _CliUsageError("single mapping requires --source-reference, --source-property and --target")
       token = do_auth(cfg)
       blocked = _bind_rule_domain_target(cfg, token, args, args.cmd)
       if blocked is not None:
         pjson(blocked)
       else:
         _assert_form_number_target_owned(cfg, token, args, args.cmd)
-        result = do_ensure_conditional_carry_reference_property(
+        result = (do_ensure_carry_reference_mappings(
+          cfg, token, args.formNumber, _load_mapping_request(args),
+        ) if args.input_file else do_ensure_conditional_carry_reference_property(
           cfg, token, args.formNumber, args.entity, args.condition_field,
           args.operator, args.value, args.source_reference, args.source_property,
-          args.target, args.only_empty_target)
+          args.target, args.only_empty_target, args.add_events, args.events))
         pjson(_attach_bound_form_identity(result, args))
 
     elif args.cmd == "ensureQuantityConversion":
@@ -11131,7 +11809,7 @@ def _main_impl():
         _assert_form_number_target_owned(cfg, token, args, args.cmd)
         result = do_ensure_quantity_conversion(
           cfg, token, args.formNumber, args.entity,
-          args.source_qty, args.target_qty)
+          args.source_qty, args.target_qty, args.add_events, args.events)
         pjson(_attach_bound_form_identity(result, args))
 
     elif args.cmd == "updateRule":
@@ -11251,6 +11929,7 @@ def _main_impl():
           )
         else:
           properties = _load_ops(args.input_file)
+          properties = _normalize_key_property(args, properties)
           element_key = args.elementKey or resolve_element_for_properties(
             cfg, token, args.formNumber, args.element, properties)
           result = do_set_properties_verified(
@@ -11258,6 +11937,15 @@ def _main_impl():
             element_key=element_key, properties=properties)
         pjson(_attach_bound_form_identity(result, args))
 
+    elif args.cmd == "renameElementKey":
+      token = do_auth(cfg)
+      blocked = _bind_existing_form_target(cfg, token, args, args.cmd)
+      if blocked is not None:
+        pjson(blocked)
+      else:
+        _assert_form_number_target_owned(cfg, token, args, args.cmd)
+        pjson(_attach_bound_form_identity(_rename_element_key(cfg, token, args), args))
+
     elif args.cmd == "setFeatures":
       token = do_auth(cfg)
       blocked = _bind_existing_form_target(cfg, token, args, args.cmd)
@@ -11395,6 +12083,20 @@ def _main_impl():
         cfg, token, args.formNumber, element_key, args.css, args.clear)
       pjson(_attach_bound_form_identity(result, args))
 
+    elif args.cmd == "configureDropdownMenu":
+      token = do_auth(cfg)
+      blocked = _bind_existing_form_target(cfg, token, args, args.cmd)
+      if blocked is not None:
+        pjson(blocked)
+      else:
+        _assert_form_number_target_owned(cfg, token, args, args.cmd)
+        element_key = args.elementKey or (resolve_element_selector(
+          cfg, token, args.formNumber, args.element, category="control") if args.element else None)
+        result = do_configure_dropdown_menu(
+          cfg, token, args.formNumber, element_key, _load_ops(args.input_file),
+          locale=args.locale)
+        pjson(_attach_bound_form_identity(result, args))
+
     elif args.cmd == "setCollapseSummary":
       token = do_auth(cfg)
       blocked = _bind_existing_form_target(cfg, token, args, args.cmd)
@@ -12399,10 +13101,11 @@ def _main_impl():
       pjson(result)
 
     elif args.cmd == "addUnit":
+      unit_app_id, unit_app_number = _unit_app_target(_resolve_app_root_arg(args), args.bizAppId, args.bizAppNumber)
       token = do_auth(cfg)
       result = do_add_unit(cfg, token,
-                 biz_app_id=args.bizAppId,
-                 biz_app_number=args.bizAppNumber,
+                 biz_app_id=unit_app_id,
+                 biz_app_number=unit_app_number,
                  name=args.name,
                  number=args.number,
                  description=args.description,
@@ -12823,7 +13526,7 @@ def _main_impl():
                   app_root=_resolve_app_root_arg(args))
       pjson(result)
 
-    elif args.cmd == "ksqlListDbRoutes":
+    elif args.cmd == "ksqlListDbRoutes":  # 本地补丁 #14
       token = do_auth(cfg)
       pjson(_api_call(cfg, token, "ksqlListDbRoutes", {}, method="POST"))
 
@@ -13339,6 +14042,9 @@ def main():
   sys.argv[1:] = _normalize_argv(sys.argv[1:])
   _CLI_MACHINE_MODE = "--stdout" in sys.argv[1:]
   _CLI_RESULT_EMITTED = False
+  if _CLI_MACHINE_MODE:
+    _route_unstructured_prints_to_stderr()
+    set_stdout_mode(True)
   for index, argument in enumerate(sys.argv[1:]):
     if argument == "--output" and index + 2 <= len(sys.argv[1:]):
       set_output_file(sys.argv[1:][index + 1])