@qingflow-tech/qingflow-app-builder-mcp 1.0.11 → 1.0.12

package/src/qingflow_mcp/builder_facade/service.py

@@ -14,7 +14,7 @@ from urllib.parse import quote_plus, unquote_plus
 from uuid import uuid4
 
 from ..backend_client import BackendRequestContext
-from ..errors import QingflowApiError
+from ..errors import QingflowApiError, backend_code_int, backend_code_value_int, is_auth_like_error
 from ..json_types import JSONObject
 from ..list_type_labels import RECORD_LIST_TYPE_LABELS, SYSTEM_VIEW_ID_TO_LIST_TYPE
 from ..solution.build_assembly_store import BuildAssemblyStore, default_artifacts, default_manifest
@@ -374,7 +374,18 @@ class AiBuilderFacade:
         if existing.get("error_code") == "AMBIGUOUS_PACKAGE":
             return existing
         if existing.get("error_code") == "PACKAGE_RESOLVE_FAILED":
-            if existing.get("backend_code") not in {40002, 40027}:
+            existing_details = existing.get("details") if isinstance(existing.get("details"), dict) else {}
+            existing_transport_error = (
+                existing_details.get("transport_error") if isinstance(existing_details.get("transport_error"), dict) else {}
+            )
+            existing_error = QingflowApiError(
+                category=str(existing_transport_error.get("category") or ""),
+                message=str(existing.get("message") or ""),
+                backend_code=existing.get("backend_code"),
+                http_status=existing.get("http_status"),
+                request_id=existing.get("request_id"),
+            )
+            if is_auth_like_error(existing_error) or backend_code_value_int(existing.get("backend_code")) not in {40002, 40027}:
                 return existing
             lookup_permission_blocked = {
                 "backend_code": existing.get("backend_code"),
@@ -468,7 +479,17 @@ class AiBuilderFacade:
         try:
             detail_result = self.packages.package_get(profile=profile, tag_id=effective_package_id, include_raw=True)
         except (QingflowApiError, RuntimeError) as error:
-            detail_read_error = _coerce_api_error(error)
+            api_error = _coerce_api_error(error)
+            if _is_optional_builder_lookup_error(api_error):
+                detail_read_error = api_error
+            else:
+                return _failed_from_api_error(
+                    "PACKAGE_GET_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details={"package_id": effective_package_id},
+                    suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": effective_package_id}},
+                )
 
         detail = detail_result.get("result") if isinstance(detail_result, dict) and isinstance(detail_result.get("result"), dict) else {}
         base = base_result.get("result") if isinstance(base_result.get("result"), dict) else {}
@@ -476,14 +497,17 @@ class AiBuilderFacade:
         source = detail if detail else base
         layout_tag_items = _select_package_layout_tag_items(detail=detail, base=base)
         warnings: list[JSONObject] = []
+        if isinstance(detail_result, dict) and isinstance(detail_result.get("warnings"), list):
+            warnings.extend(deepcopy(item) for item in detail_result.get("warnings", []) if isinstance(item, dict))
         if detail_read_error is not None:
             warnings.append(
-                {
-                    "code": "PACKAGE_DETAIL_READ_DEGRADED",
-                    "message": "package_get used baseInfo because the package detail endpoint was not readable",
-                    "backend_code": detail_read_error.backend_code,
-                    "http_status": detail_read_error.http_status,
-                }
+                _warning(
+                    "PACKAGE_DETAIL_READ_DEGRADED",
+                    "package_get used baseInfo because the package detail endpoint was not readable",
+                    backend_code=detail_read_error.backend_code,
+                    http_status=detail_read_error.http_status,
+                    request_id=detail_read_error.request_id,
+                )
             )
         public_items = _public_package_items_from_tag_items(layout_tag_items)
         item_count = summary.get("itemCount")
@@ -624,8 +648,34 @@ class AiBuilderFacade:
             if layout_result.get("status") not in {"success", "partial_success"}:
                 return _apply_permission_outcomes(layout_result, *permission_outcomes)
 
+        write_executed = bool(
+            created
+            or (
+                metadata_requested
+                and isinstance(update_result, dict)
+                and update_result.get("status") in {"success", "partial_success"}
+                and not bool(update_result.get("noop"))
+            )
+            or (
+                items is not None
+                and isinstance(layout_result, dict)
+                and layout_result.get("status") in {"success", "partial_success"}
+                and not bool(layout_result.get("noop"))
+            )
+        )
         verification = self.package_get(profile=profile, package_id=effective_package_id)
         if verification.get("status") != "success":
+            if write_executed:
+                return _apply_permission_outcomes(
+                    _post_write_readback_pending_result(
+                        error_code="PACKAGE_READBACK_PENDING",
+                        message="applied package; final package readback is unavailable",
+                        normalized_args=normalized_args,
+                        details={"package_id": effective_package_id, "verification_result": verification},
+                        suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": effective_package_id}},
+                    ),
+                    *permission_outcomes,
+                )
             return _apply_permission_outcomes(verification, *permission_outcomes)
         expected_visibility = None
         if visibility is not None:
@@ -643,6 +693,11 @@ class AiBuilderFacade:
         layout_verified = True
         if items is not None and layout_result is not None:
             layout_verified = bool(layout_result.get("verified"))
+        layout_error_code = (
+            str(layout_result.get("error_code") or "").strip()
+            if isinstance(layout_result, dict) and layout_result.get("error_code")
+            else None
+        )
         response_verification: JSONObject = {
             "package_exists": True,
             "package_created": created,
@@ -660,21 +715,36 @@ class AiBuilderFacade:
                     if key in update_verification:
                         response_verification[key] = deepcopy(update_verification.get(key))
         response_verified = metadata_verified and layout_verified and response_verification.get("visibility_verified") is not False
+        response_warnings = []
+        if isinstance(layout_result, dict) and isinstance(layout_result.get("warnings"), list):
+            response_warnings.extend(deepcopy(layout_result.get("warnings") or []))
         response: JSONObject = {
             "status": "success" if response_verified else "partial_success",
-            "error_code": None,
+            "error_code": None if response_verified else layout_error_code,
             "recoverable": False,
             "message": "applied package" if response_verified else "applied package with unverified readback",
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {},
-            "details": {"layout_result": layout_result} if layout_result is not None else {},
+            "details": {
+                **({"layout_result": layout_result} if layout_result is not None else {}),
+                **(
+                    {"layout_write_error": layout_result.get("details", {}).get("write_error")}
+                    if isinstance(layout_result, dict)
+                    and isinstance(layout_result.get("details"), dict)
+                    and isinstance(layout_result.get("details", {}).get("write_error"), dict)
+                    else {}
+                ),
+            },
             "request_id": None,
             "suggested_next_call": None,
             "noop": not (created or metadata_requested or items is not None),
-            "warnings": [],
+            "warnings": response_warnings,
             "verification": response_verification,
             "verified": response_verified,
+            "write_executed": write_executed,
+            "write_succeeded": write_executed,
+            "safe_to_retry": not write_executed,
             **{
                 key: deepcopy(value)
                 for key, value in verification.items()
@@ -719,7 +789,6 @@ class AiBuilderFacade:
         if _coerce_positive_int(tag_id) is None:
             return _failed("TAG_ID_REQUIRED", "tag_id must be positive", normalized_args=normalized_args, suggested_next_call=None)
         try:
-            current = self.packages.package_get(profile=profile, tag_id=tag_id, include_raw=True)
             current_base = self.packages.package_get_base(profile=profile, tag_id=tag_id, include_raw=True)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
@@ -730,8 +799,37 @@ class AiBuilderFacade:
                 details={"tag_id": tag_id},
                 suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "tag_id": tag_id}},
             )
-        raw_current = current.get("result") if isinstance(current.get("result"), dict) else {}
+        current: JSONObject | None = None
+        detail_read_error: QingflowApiError | None = None
+        try:
+            current = self.packages.package_get(profile=profile, tag_id=tag_id, include_raw=True)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if _is_optional_builder_lookup_error(api_error):
+                detail_read_error = api_error
+            else:
+                return _failed_from_api_error(
+                    "PACKAGE_UPDATE_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details={"tag_id": tag_id},
+                    suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "tag_id": tag_id}},
+                )
+        raw_current = current.get("result") if isinstance(current, dict) and isinstance(current.get("result"), dict) else {}
         raw_current_base = current_base.get("result") if isinstance(current_base.get("result"), dict) else {}
+        warnings: list[JSONObject] = []
+        if isinstance(current, dict) and isinstance(current.get("warnings"), list):
+            warnings.extend(deepcopy(item) for item in current.get("warnings", []) if isinstance(item, dict))
+        if detail_read_error is not None:
+            warnings.append(
+                _warning(
+                    "PACKAGE_DETAIL_READ_DEGRADED",
+                    "package_update used baseInfo because the package detail endpoint was not readable",
+                    backend_code=detail_read_error.backend_code,
+                    http_status=detail_read_error.http_status,
+                    request_id=detail_read_error.request_id,
+                )
+            )
         current_name = str(raw_current.get("tagName") or raw_current_base.get("tagName") or "").strip() or None
         desired_name = str(package_name or current_name or "").strip() or current_name or "未命名应用包"
         desired_icon = encode_workspace_icon_with_defaults(
@@ -772,7 +870,13 @@ class AiBuilderFacade:
             )
         verification = self.package_get(profile=profile, package_id=tag_id)
         if verification.get("status") != "success":
-            return verification
+            return _post_write_readback_pending_result(
+                error_code="PACKAGE_UPDATE_READBACK_PENDING",
+                message="updated package; package readback is unavailable",
+                normalized_args=normalized_args,
+                details={"tag_id": tag_id, "package_id": tag_id, "verification_result": verification},
+                suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": tag_id}},
+            )
         package_name_verified = str(verification.get("package_name") or "").strip() == desired_name
         package_icon_verified = str(verification.get("icon") or "").strip() == desired_icon
         visibility_verified = _visibility_matches_expected(
@@ -792,7 +896,7 @@ class AiBuilderFacade:
             "request_id": update_result.get("request_id") if isinstance(update_result, dict) else None,
             "suggested_next_call": None if verified else {"tool_name": "package_get", "arguments": {"profile": profile, "package_id": tag_id}},
             "noop": False,
-            "warnings": [],
+            "warnings": warnings,
             "verification": {
                 "package_exists": True,
                 "package_name_verified": package_name_verified,
@@ -800,6 +904,8 @@ class AiBuilderFacade:
                 "visibility_verified": visibility_verified,
             },
             "verified": verified,
+            "write_executed": True,
+            "safe_to_retry": False,
             **{
                 key: deepcopy(value)
                 for key, value in verification.items()
@@ -876,6 +982,8 @@ class AiBuilderFacade:
             "suggested_next_call": None,
             "noop": False,
             "verification": {},
+            "write_executed": True,
+            "safe_to_retry": False,
         }
 
     def package_list(self, *, profile: str, trial_status: str = "all", query: str = "") -> JSONObject:
@@ -927,6 +1035,14 @@ class AiBuilderFacade:
             current_detail_result = self.packages.package_get(profile=profile, tag_id=package_id, include_raw=True)
         except (QingflowApiError, RuntimeError) as detail_error:
             detail_api_error = _coerce_api_error(detail_error)
+            if not _is_optional_builder_lookup_error(detail_api_error):
+                return _failed_from_api_error(
+                    "PACKAGE_LAYOUT_READ_FAILED",
+                    detail_api_error,
+                    normalized_args=normalized_args,
+                    details={"package_id": package_id},
+                    suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": package_id}},
+                )
         try:
             current_base_result = self.packages.package_get_base(profile=profile, tag_id=package_id, include_raw=True)
         except (QingflowApiError, RuntimeError) as base_error:
@@ -1007,7 +1123,9 @@ class AiBuilderFacade:
         permission_outcomes: list[PermissionCheckOutcome] = []
         needs_group_create = any(_coerce_positive_int(group.get("group_id")) is None for group in desired_groups)
         needs_group_delete = bool(deleted_group_ids)
-        needs_edit_app = bool(normalized_items)
+        # sortGroupUnderPackage is always called for a layout apply and is guarded by
+        # backend MoveGroupAuth, which maps to package editAppStatus.
+        needs_edit_app = True
         for required_permission in (
             (["add_app"] if needs_group_create else [])
             + (["edit_app"] if needs_edit_app else [])
@@ -1105,13 +1223,47 @@ class AiBuilderFacade:
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
                 return _apply_permission_outcomes(
-                    _failed_from_api_error(
-                        "PACKAGE_GROUP_DELETE_FAILED",
-                        api_error,
-                        normalized_args=normalized_args,
-                        details={"package_id": package_id, "group_id": group_id},
-                        suggested_next_call=None,
-                    ),
+                    {
+                        "status": "partial_success",
+                        "error_code": "PACKAGE_APPLY_PARTIAL",
+                        "recoverable": True,
+                        "message": "package layout sort was applied, but a later group delete failed",
+                        "normalized_args": normalized_args,
+                        "missing_fields": [],
+                        "allowed_values": {},
+                        "details": {
+                            "package_id": package_id,
+                            "group_id": group_id,
+                            "group_operations": group_operations,
+                            "sort_result": sort_result,
+                            "write_error": {
+                                "message": api_error.message,
+                                "transport_error": _transport_error_payload(api_error),
+                            },
+                        },
+                        "request_id": api_error.request_id,
+                        "backend_code": api_error.backend_code,
+                        "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                        "suggested_next_call": None,
+                        "noop": False,
+                        "warnings": [
+                            _warning(
+                                "PACKAGE_WRITE_INCOMPLETE_AFTER_PARTIAL_WRITE",
+                                "package layout write was partially applied before a later write step failed; do not blindly repeat the same package apply",
+                                **_transport_error_payload(api_error),
+                            )
+                        ],
+                        "verification": {
+                            "layout_applied": True,
+                            "write_incomplete": True,
+                            "metadata_unverified": True,
+                        },
+                        "verified": False,
+                        "package_id": package_id,
+                        "write_executed": True,
+                        "write_succeeded": True,
+                        "safe_to_retry": False,
+                    },
                     *permission_outcomes,
                 )
             group_operations.append({"action": "delete", "group_id": group_id})
@@ -1166,6 +1318,25 @@ class AiBuilderFacade:
                 details={"query": requested},
                 suggested_next_call={"tool_name": "member_search", "arguments": {"profile": profile, **normalized_args}},
             )
+        if listed.get("status") == "failed" and listed.get("error_code") == "CONTACT_DIRECTORY_PERMISSION_DENIED":
+            return _failed(
+                "CONTACT_DIRECTORY_PERMISSION_DENIED",
+                str(listed.get("message") or "Contact-directory management data is not readable for the current user."),
+                normalized_args=normalized_args,
+                details={
+                    "query": requested,
+                    "permission_boundary": "contact_directory",
+                    "fix_hint": (
+                        "This builder member lookup uses the contact-directory management route. "
+                        "For record member/department field candidates, use record_member_candidates "
+                        "or record_department_candidates instead."
+                    ),
+                },
+                suggested_next_call=None,
+                request_id=listed.get("request_id") if isinstance(listed.get("request_id"), str) else None,
+                backend_code=listed.get("backend_code"),
+                http_status=listed.get("http_status"),
+            )
         items = []
         for item in _extract_directory_items(listed):
             uid = _coerce_positive_int(item.get("uid") or item.get("id"))
@@ -1211,6 +1382,23 @@ class AiBuilderFacade:
                 details={"keyword": requested},
                 suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, **normalized_args}},
             )
+        if listed.get("status") == "failed":
+            permission_boundary = "contact_role" if listed.get("error_code") == "CONTACT_ROLE_PERMISSION_DENIED" else None
+            return _failed(
+                str(listed.get("error_code") or "ROLE_SEARCH_FAILED"),
+                str(listed.get("message") or "role search failed"),
+                normalized_args=normalized_args,
+                details={
+                    "keyword": requested,
+                    "permission_boundary": permission_boundary,
+                },
+                suggested_next_call=None
+                if permission_boundary
+                else {"tool_name": "role_search", "arguments": {"profile": profile, **normalized_args}},
+                backend_code=listed.get("backend_code"),
+                request_id=listed.get("request_id"),
+                http_status=listed.get("http_status"),
+            )
         page = listed.get("page") if isinstance(listed.get("page"), dict) else {}
         raw_items = page.get("list") if isinstance(page.get("list"), list) else []
         items = []
@@ -1283,6 +1471,8 @@ class AiBuilderFacade:
                     "role_id": exact[0]["role_id"],
                     "role_name": exact[0]["role_name"],
                     "role_icon": exact[0].get("role_icon"),
+                    "write_executed": False,
+                    "safe_to_retry": True,
                 }
             if len(exact) > 1:
                 return _failed(
@@ -1343,6 +1533,8 @@ class AiBuilderFacade:
             "role_id": role_id,
             "role_name": requested_name,
             "role_icon": normalized_args["role_icon"],
+            "write_executed": True,
+            "safe_to_retry": False,
         }
 
     def _resolve_role_references(
@@ -1373,6 +1565,18 @@ class AiBuilderFacade:
             if not requested:
                 continue
             matches_result = self.role_search(profile=profile, keyword=requested, page_num=1, page_size=50)
+            if matches_result.get("status") != "success":
+                issues.append(
+                    {
+                        "kind": "role",
+                        "value": requested,
+                        "error_code": matches_result.get("error_code") or "ROLE_SEARCH_FAILED",
+                        "message": matches_result.get("message"),
+                        "backend_code": matches_result.get("backend_code"),
+                        "request_id": matches_result.get("request_id"),
+                    }
+                )
+                continue
             items = matches_result.get("items", []) if matches_result.get("status") == "success" else []
             exact = [item for item in items if isinstance(item, dict) and item.get("role_name") == requested]
             if len(exact) != 1:
@@ -1434,6 +1638,18 @@ class AiBuilderFacade:
             if not requested:
                 continue
             matches = self.member_search(profile=profile, query=requested, page_num=1, page_size=50, contain_disable=False)
+            if matches.get("status") != "success":
+                issues.append(
+                    {
+                        "kind": "member_email",
+                        "value": requested,
+                        "error_code": matches.get("error_code") or "MEMBER_SEARCH_FAILED",
+                        "message": matches.get("message"),
+                        "backend_code": matches.get("backend_code"),
+                        "request_id": matches.get("request_id"),
+                    }
+                )
+                continue
             items = matches.get("items", []) if matches.get("status") == "success" else []
             exact = [item for item in items if isinstance(item, dict) and str(item.get("email") or "").strip().lower() == requested.lower()]
             if len(exact) != 1:
@@ -1453,6 +1669,18 @@ class AiBuilderFacade:
             if not requested:
                 continue
             matches = self.member_search(profile=profile, query=requested, page_num=1, page_size=50, contain_disable=False)
+            if matches.get("status") != "success":
+                issues.append(
+                    {
+                        "kind": "member_name",
+                        "value": requested,
+                        "error_code": matches.get("error_code") or "MEMBER_SEARCH_FAILED",
+                        "message": matches.get("message"),
+                        "backend_code": matches.get("backend_code"),
+                        "request_id": matches.get("request_id"),
+                    }
+                )
+                continue
             items = matches.get("items", []) if matches.get("status") == "success" else []
             exact = [item for item in items if isinstance(item, dict) and str(item.get("name") or "").strip() == requested]
             if len(exact) != 1:
@@ -1481,23 +1709,6 @@ class AiBuilderFacade:
         seen_ids: set[int] = set()
         if not dept_ids and not dept_names:
             return {"department_entries": resolved, "issues": issues}
-        listed = self.directory.directory_list_all_departments(
-            profile=profile,
-            parent_dept_id=None,
-            max_depth=20,
-            max_items=5000,
-        )
-        items = _extract_directory_items(listed)
-        by_id: dict[int, dict[str, Any]] = {}
-        by_name: dict[str, list[dict[str, Any]]] = {}
-        for item in items:
-            dept_id = _coerce_positive_int(item.get("deptId") or item.get("id"))
-            if dept_id is None:
-                continue
-            by_id[dept_id] = item
-            dept_name = str(item.get("deptName") or item.get("departName") or item.get("name") or "").strip()
-            if dept_name:
-                by_name.setdefault(dept_name, []).append(item)
 
         def add_department(item: dict[str, Any], *, fallback_name: str | None = None) -> None:
             dept_id = _coerce_positive_int(item.get("deptId") or item.get("id"))
@@ -1517,7 +1728,40 @@ class AiBuilderFacade:
             normalized = _coerce_positive_int(dept_id)
             if normalized is None:
                 continue
-            add_department(by_id.get(normalized) or {"deptId": normalized}, fallback_name=str(normalized))
+            add_department({"deptId": normalized}, fallback_name=str(normalized))
+
+        if not dept_names:
+            return {"department_entries": resolved, "issues": issues}
+
+        listed = self.directory.directory_list_all_departments(
+            profile=profile,
+            parent_dept_id=None,
+            max_depth=20,
+            max_items=5000,
+        )
+        if listed.get("status") == "failed" and listed.get("error_code") == "CONTACT_DIRECTORY_PERMISSION_DENIED":
+            for dept_name in dept_names:
+                requested = str(dept_name or "").strip()
+                if not requested:
+                    continue
+                issues.append(
+                    {
+                        "kind": "department_name",
+                        "value": requested,
+                        "error_code": "CONTACT_DIRECTORY_PERMISSION_DENIED",
+                        "message": "department names require contact-directory lookup; pass dept_ids or grant directory access",
+                        "backend_code": listed.get("backend_code"),
+                        "request_id": listed.get("request_id"),
+                    }
+                )
+            return {"department_entries": resolved, "issues": issues}
+
+        items = _extract_directory_items(listed)
+        by_name: dict[str, list[dict[str, Any]]] = {}
+        for item in items:
+            dept_name = str(item.get("deptName") or item.get("departName") or item.get("name") or "").strip()
+            if dept_name:
+                by_name.setdefault(dept_name, []).append(item)
 
         for dept_name in dept_names:
             requested = str(dept_name or "").strip()
@@ -1584,6 +1828,18 @@ class AiBuilderFacade:
                 page_size=100,
                 simple=True,
             )
+            if listed.get("status") == "failed":
+                issues.append(
+                    {
+                        "kind": "external_member_email",
+                        "value": requested,
+                        "error_code": listed.get("error_code") or "EXTERNAL_MEMBER_SEARCH_FAILED",
+                        "message": listed.get("message"),
+                        "backend_code": listed.get("backend_code"),
+                        "request_id": listed.get("request_id"),
+                    }
+                )
+                continue
             items = _extract_directory_items(listed)
             exact = [
                 item
@@ -1618,6 +1874,9 @@ class AiBuilderFacade:
         elif error_code.endswith("_NOT_FOUND"):
             public_code = "VISIBILITY_SUBJECT_NOT_FOUND"
             message = f"{kind} '{requested_value}' was not found in the visibility directory"
+        elif "PERMISSION_DENIED" in error_code or error_code.endswith("_FAILED"):
+            public_code = "VISIBILITY_SUBJECT_LOOKUP_FAILED"
+            message = f"{kind} '{requested_value}' could not be resolved because the visibility directory lookup failed"
         else:
             public_code = "VISIBILITY_SUBJECT_UNSUPPORTED"
             message = f"{kind} visibility selector is unsupported"
@@ -2033,6 +2292,9 @@ class AiBuilderFacade:
             "tag_id": tag_id,
             "tag_ids_after": tag_ids_after,
             "attached": attached,
+            "write_executed": not already_attached,
+            "write_succeeded": not already_attached or attached,
+            "safe_to_retry": bool(already_attached),
         }
         if verification_error is not None:
             response["details"]["verification_error"] = _transport_error_payload(verification_error)
@@ -2145,6 +2407,8 @@ class AiBuilderFacade:
             "verification": {"released": True},
             "app_key": app_key,
             "released": True,
+            "write_executed": True,
+            "safe_to_retry": False,
         }
 
     def app_resolve(
@@ -2225,11 +2489,20 @@ class AiBuilderFacade:
         if not requested:
             return _failed("APP_NAME_REQUIRED", "app_name or app_key is required", suggested_next_call=None)
         if package_tag_id is not None and package_tag_id > 0:
-            package_matches = self._resolve_app_matches_in_package(
-                profile=profile,
-                app_name=requested,
-                package_tag_id=package_tag_id,
-            )
+            try:
+                package_matches = self._resolve_app_matches_in_package(
+                    profile=profile,
+                    app_name=requested,
+                    package_tag_id=package_tag_id,
+                )
+            except (QingflowApiError, RuntimeError) as exc:
+                api_error = _coerce_api_error(exc)
+                return _failed_from_api_error(
+                    "APP_RESOLVE_FAILED",
+                    api_error,
+                    details={"app_name": requested, "package_tag_id": package_tag_id, "match_scope": "package"},
+                    suggested_next_call=None,
+                )
             if len(package_matches) == 1:
                 match = package_matches[0]
                 return {
@@ -2254,12 +2527,50 @@ class AiBuilderFacade:
                     details={"app_name": requested, "package_tag_id": package_tag_id, "matches": package_matches},
                     suggested_next_call=None,
                 )
+        try:
+            visible_matches = self._resolve_app_matches_in_visible_apps(
+                profile=profile,
+                app_name=requested,
+                package_tag_id=package_tag_id,
+            )
+        except (QingflowApiError, RuntimeError) as exc:
+            api_error = _coerce_api_error(exc)
+            return _failed_from_api_error(
+                "APP_RESOLVE_FAILED",
+                api_error,
+                details={"app_name": requested, "package_tag_id": package_tag_id, "match_scope": "visible_apps"},
+                suggested_next_call=None,
+            )
+        if len(visible_matches) == 1:
+            match = visible_matches[0]
+            return {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": "resolved app",
+                "normalized_args": {"app_name": requested, "package_tag_id": package_tag_id},
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {"match_scope": "visible_apps"},
+                "request_id": None,
+                "suggested_next_call": None,
+                "noop": False,
+                "verification": {},
+                **match,
+            }
+        if len(visible_matches) > 1:
+            return _failed(
+                "AMBIGUOUS_APP",
+                f"multiple apps matched '{requested}'",
+                details={"app_name": requested, "package_tag_id": package_tag_id, "matches": visible_matches},
+                suggested_next_call=None,
+            )
         search_error: QingflowApiError | None = None
         try:
             search = self.apps.app_search(profile=profile, keyword=requested, page_num=1, page_size=200)
         except (QingflowApiError, RuntimeError) as exc:
             api_error = _coerce_api_error(exc)
-            if package_tag_id is None or package_tag_id <= 0 or api_error.backend_code not in {40002, 40027}:
+            if is_auth_like_error(api_error) or package_tag_id is None or package_tag_id <= 0 or backend_code_int(api_error) not in {40002, 40027}:
                 return _failed_from_api_error(
                     "APP_NOT_FOUND" if api_error.http_status == 404 else "APP_RESOLVE_FAILED",
                     api_error,
@@ -2268,6 +2579,7 @@ class AiBuilderFacade:
                 )
             search = {}
             search_error = api_error
+        search_permission_blocked = _search_permission_blocked_from_warnings(search) if isinstance(search, dict) else None
         apps = search.get("apps") if isinstance(search.get("apps"), list) else []
         matches = []
         for item in apps:
@@ -2286,8 +2598,16 @@ class AiBuilderFacade:
             if package_tag_id is not None and package_tag_id > 0:
                 try:
                     base = self.apps.app_get_base(profile=profile, app_key=candidate_key, include_raw=True)
-                except (QingflowApiError, RuntimeError):
-                    continue
+                except (QingflowApiError, RuntimeError) as exc:
+                    api_error = _coerce_api_error(exc)
+                    if _is_optional_builder_lookup_error(api_error):
+                        continue
+                    return _failed_from_api_error(
+                        "APP_RESOLVE_FAILED",
+                        api_error,
+                        details={"app_name": requested, "candidate_app_key": candidate_key, "package_tag_id": package_tag_id},
+                        suggested_next_call=None,
+                    )
                 result = base.get("result") if isinstance(base.get("result"), dict) else {}
                 resolved_tag_ids = _coerce_int_list(result.get("tagIds"))
                 if resolved_tag_ids:
@@ -2301,12 +2621,7 @@ class AiBuilderFacade:
                     "tag_ids": tag_ids,
                 }
             )
-        if not matches and package_tag_id is not None and package_tag_id > 0 and search_error is not None:
-            visible_matches = self._resolve_app_matches_in_visible_apps(
-                profile=profile,
-                app_name=requested,
-                package_tag_id=package_tag_id,
-            )
+        if not matches and search_error is not None:
             if len(visible_matches) == 1:
                 match = visible_matches[0]
                 return {
@@ -2366,6 +2681,14 @@ class AiBuilderFacade:
                         if search_error is not None
                         else {}
                     ),
+                    **(
+                        {
+                            "search_permission_blocked": search_permission_blocked,
+                            "match_scope": "visible_apps_fallback",
+                        }
+                        if search_permission_blocked is not None
+                        else {}
+                    ),
                 },
                 suggested_next_call=None,
             )
@@ -2551,21 +2874,45 @@ class AiBuilderFacade:
         normalized_args = request.model_dump(mode="json")
         app_key = request.app_key
         permission_outcomes: list[PermissionCheckOutcome] = []
-        permission_outcome = self._guard_app_permission(
-            profile=profile,
-            app_key=app_key,
-            required_permission="edit_app",
-            normalized_args=normalized_args,
-        )
-        if permission_outcome.block is not None:
-            return permission_outcome.block
-        permission_outcomes.append(permission_outcome)
+        button_write_intent = bool(request.upsert_buttons or request.patch_buttons or request.remove_buttons)
+        if button_write_intent:
+            permission_outcome = self._guard_app_permission(
+                profile=profile,
+                app_key=app_key,
+                required_permission="edit_app",
+                normalized_args=normalized_args,
+            )
+            if permission_outcome.block is not None:
+                return permission_outcome.block
+            permission_outcomes.append(permission_outcome)
+        if request.view_configs:
+            permission_outcome = self._guard_app_permission(
+                profile=profile,
+                app_key=app_key,
+                required_permission="view_manage",
+                normalized_args=normalized_args,
+            )
+            if permission_outcome.block is not None:
+                return permission_outcome.block
+            permission_outcomes.append(permission_outcome)
 
         def finalize(response: JSONObject) -> JSONObject:
             return _apply_permission_outcomes(response, *permission_outcomes)
 
+        view_config_refs = [
+            binding.button_ref
+            for config in request.view_configs
+            for binding in config.buttons
+        ]
+        needs_button_inventory = button_write_intent or any(
+            _coerce_positive_int(ref) is None for ref in view_config_refs
+        )
         try:
-            existing_buttons = self._load_custom_buttons_for_builder(profile=profile, app_key=app_key)
+            existing_buttons = (
+                self._load_custom_buttons_for_builder(profile=profile, app_key=app_key)
+                if needs_button_inventory
+                else []
+            )
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
             return finalize(_failed_from_api_error(
@@ -2796,19 +3143,22 @@ class AiBuilderFacade:
                 )
             )
 
-        edit_version_no, edit_context_error = self._ensure_app_edit_context(
-            profile=profile,
-            app_key=app_key,
-            normalized_args=normalized_args,
-            failure_code="CUSTOM_BUTTON_APPLY_FAILED",
-        )
-        if edit_context_error is not None:
-            return finalize(edit_context_error)
+        edit_version_no = None
+        if button_write_intent:
+            edit_version_no, edit_context_error = self._ensure_app_edit_context(
+                profile=profile,
+                app_key=app_key,
+                normalized_args=normalized_args,
+                failure_code="CUSTOM_BUTTON_APPLY_FAILED",
+            )
+            if edit_context_error is not None:
+                return finalize(edit_context_error)
 
         created: list[dict[str, Any]] = []
         updated: list[dict[str, Any]] = []
         removed: list[dict[str, Any]] = []
         failed: list[dict[str, Any]] = []
+        readback_errors: list[JSONObject] = []
         client_key_map: dict[str, int] = {}
         write_executed = False
 
@@ -2831,7 +3181,15 @@ class AiBuilderFacade:
                             ]
                             if len(matches) == 1:
                                 button_id = _coerce_positive_int(matches[0].get("button_id"))
-                        except (QingflowApiError, RuntimeError):
+                        except (QingflowApiError, RuntimeError) as error:
+                            readback_errors.append(
+                                {
+                                    "resource": "custom_buttons",
+                                    "phase": "create_id_lookup",
+                                    "index": op["index"],
+                                    "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                                }
+                            )
                             button_id = None
                     entry = {
                         "index": op["index"],
@@ -2919,13 +3277,20 @@ class AiBuilderFacade:
                     }
                 )
 
-        needs_button_list_readback = bool(created or updated or request.view_configs)
+        needs_button_list_readback = bool(created or updated or (request.view_configs and needs_button_inventory))
         readback_buttons: list[dict[str, Any]] = []
         readback_failed = False
         if needs_button_list_readback:
             try:
                 readback_buttons = self._load_custom_buttons_for_builder(profile=profile, app_key=app_key)
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as error:
+                readback_errors.append(
+                    {
+                        "resource": "custom_buttons",
+                        "phase": "final_list",
+                        "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                    }
+                )
                 readback_failed = True
         readback_ids = {
             button_id
@@ -3018,6 +3383,13 @@ class AiBuilderFacade:
                     "custom button delete was sent, but deletion readback is not fully verified; do not blindly repeat delete",
                 )
             )
+        if readback_errors:
+            warnings.append(
+                _warning(
+                    "CUSTOM_BUTTON_READBACK_UNAVAILABLE",
+                    "custom button write was executed but readback is unavailable",
+                )
+            )
         response = {
             "status": status,
             "error_code": error_code,
@@ -3033,6 +3405,7 @@ class AiBuilderFacade:
                 "edit_version_no": edit_version_no,
                 "button_ids_by_client_key": client_key_map,
                 "readback_failed": readback_failed,
+                **({"readback_errors": readback_errors} if readback_errors else {}),
                 "compiled_match_rules": {
                     str(index): _summarize_compiled_match_rules(config.get("que_relation") or [])
                     for index, config in compiled_add_data_configs.items()
@@ -3066,7 +3439,15 @@ class AiBuilderFacade:
             "write_succeeded": write_succeeded,
             "safe_to_retry": not write_executed,
         }
-        return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=write_succeeded, response=response, edit_version_no=edit_version_no))
+        return finalize(
+            self._append_publish_result(
+                profile=profile,
+                app_key=app_key,
+                publish=bool(write_succeeded and button_write_intent),
+                response=response,
+                edit_version_no=edit_version_no,
+            )
+        )
 
     def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
         normalized_args = {"app_key": app_key}
@@ -3235,6 +3616,9 @@ class AiBuilderFacade:
                 "verified": False,
                 "app_key": app_key,
                 "button_id": button_id,
+                "write_executed": True,
+                "write_succeeded": True,
+                "safe_to_retry": False,
             }
             if _is_permission_restricted_api_error(api_error):
                 response = _apply_permission_outcomes(
@@ -3348,6 +3732,9 @@ class AiBuilderFacade:
                 "verified": False,
                 "app_key": app_key,
                 "button_id": button_id,
+                "write_executed": True,
+                "write_succeeded": True,
+                "safe_to_retry": False,
             }
             if _is_permission_restricted_api_error(api_error):
                 response = _apply_permission_outcomes(
@@ -3686,15 +4073,32 @@ class AiBuilderFacade:
         normalized_args = request.model_dump(mode="json", exclude_none=True)
         app_key = request.app_key
         permission_outcomes: list[PermissionCheckOutcome] = []
-        permission_outcome = self._guard_app_permission(
-            profile=profile,
-            app_key=app_key,
-            required_permission="data_manage",
-            normalized_args=normalized_args,
+        resource_write_intent = bool(
+            request.upsert_resources
+            or request.patch_resources
+            or request.remove_associated_item_ids
+            or request.reorder_associated_item_ids
         )
-        if permission_outcome.block is not None:
-            return permission_outcome.block
-        permission_outcomes.append(permission_outcome)
+        if resource_write_intent:
+            permission_outcome = self._guard_app_permission(
+                profile=profile,
+                app_key=app_key,
+                required_permission="edit_app",
+                normalized_args=normalized_args,
+            )
+            if permission_outcome.block is not None:
+                return permission_outcome.block
+            permission_outcomes.append(permission_outcome)
+        if request.view_configs:
+            permission_outcome = self._guard_app_permission(
+                profile=profile,
+                app_key=app_key,
+                required_permission="view_manage",
+                normalized_args=normalized_args,
+            )
+            if permission_outcome.block is not None:
+                return permission_outcome.block
+            permission_outcomes.append(permission_outcome)
 
         def finalize(response: JSONObject) -> JSONObject:
             return _apply_permission_outcomes(response, *permission_outcomes)
@@ -3957,14 +4361,16 @@ class AiBuilderFacade:
             }
             return finalize(response)
 
-        edit_version_no, edit_context_error = self._ensure_app_edit_context(
-            profile=profile,
-            app_key=app_key,
-            normalized_args=normalized_args,
-            failure_code="ASSOCIATED_RESOURCES_APPLY_FAILED",
-        )
-        if edit_context_error is not None:
-            return finalize(edit_context_error)
+        edit_version_no = None
+        if resource_write_intent:
+            edit_version_no, edit_context_error = self._ensure_app_edit_context(
+                profile=profile,
+                app_key=app_key,
+                normalized_args=normalized_args,
+                failure_code="ASSOCIATED_RESOURCES_APPLY_FAILED",
+            )
+            if edit_context_error is not None:
+                return finalize(edit_context_error)
 
         created: list[dict[str, Any]] = []
         updated: list[dict[str, Any]] = []
@@ -3973,6 +4379,8 @@ class AiBuilderFacade:
         reordered: list[int] = []
         view_config_results: list[dict[str, Any]] = []
         failed: list[dict[str, Any]] = []
+        readback_errors: list[JSONObject] = []
+        verification_errors: list[JSONObject] = []
         write_executed = False
 
         for op in upsert_ops:
@@ -3985,20 +4393,33 @@ class AiBuilderFacade:
                         client_key_to_id[str(patch.client_key)] = item_id
                 elif op["operation"] == "create":
                     write_executed = True
-                    self._associated_resource_create(
+                    create_result = self._associated_resource_create(
                         profile=profile,
                         app_key=app_key,
                         patch=patch,
                         match_rules_override=compiled_resource_match_rules.get(int(op["index"])),
                     )
-                    readback_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-                    matches = [
-                        item
-                        for item in readback_resources
-                        if _associated_resource_matches_patch(item, patch)
-                        and _coerce_positive_int(item.get("associated_item_id")) is not None
-                    ]
-                    created_id = _coerce_positive_int(matches[0].get("associated_item_id")) if len(matches) == 1 else None
+                    created_id = _extract_associated_resource_id_from_result(create_result)
+                    try:
+                        readback_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
+                        matches = [
+                            item
+                            for item in readback_resources
+                            if _associated_resource_matches_patch(item, patch)
+                            and _coerce_positive_int(item.get("associated_item_id")) is not None
+                        ]
+                        readback_id = _coerce_positive_int(matches[0].get("associated_item_id")) if len(matches) == 1 else None
+                        if readback_id is not None:
+                            created_id = readback_id
+                    except (QingflowApiError, RuntimeError) as error:
+                        readback_errors.append(
+                            {
+                                "resource": "associated_resources",
+                                "phase": "create_id_lookup",
+                                "index": op["index"],
+                                "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                            }
+                        )
                     created.append(_associated_resource_result_entry("create", op["index"], patch, associated_item_id=created_id))
                     if created_id is not None and patch.client_key:
                         client_key_to_id[str(patch.client_key)] = created_id
@@ -4064,7 +4485,8 @@ class AiBuilderFacade:
             try:
                 resources_after = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
                 resources_after_loaded = True
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as error:
+                readback_errors.append({"resource": "associated_resources", "phase": "pre_view_config", "transport_error": _transport_error_payload(_coerce_api_error(error))})
                 resources_after = []
                 resources_after_readback_failed = True
 
@@ -4126,7 +4548,15 @@ class AiBuilderFacade:
                             available_resources=refreshed_resources,
                         )
                         verified_config = _associated_resources_config_matches(expected_config, actual_config)
-                except (QingflowApiError, RuntimeError):
+                except (QingflowApiError, RuntimeError) as error:
+                    verification_errors.append(
+                        {
+                            "resource": "view_associated_resources_config",
+                            "phase": "view_config_readback",
+                            "view_key": view_config.view_key,
+                            "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                        }
+                    )
                     actual_config = {}
                     verified_config = False
                 view_config_results.append({"index": index, "view_key": view_config.view_key, "view_name": view_name, "status": "success" if verified_config else "partial_success", "associated_resources_verified": verified_config, "expected": expected_config, "actual": actual_config})
@@ -4139,7 +4569,8 @@ class AiBuilderFacade:
         if not resources_after_loaded and not resources_after_readback_failed:
             try:
                 final_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as error:
+                readback_errors.append({"resource": "associated_resources", "phase": "final_pool", "transport_error": _transport_error_payload(_coerce_api_error(error))})
                 readback_failed = True
         final_by_id = _associated_resource_index(final_resources)
         if removed:
@@ -4199,6 +4630,20 @@ class AiBuilderFacade:
                     "associated resource delete was sent, but deletion readback is not fully verified; do not blindly repeat delete",
                 )
             )
+        if readback_errors:
+            warnings.append(
+                _warning(
+                    "ASSOCIATED_RESOURCES_READBACK_UNAVAILABLE",
+                    "associated resource write was executed but readback is unavailable",
+                )
+            )
+        if verification_errors:
+            warnings.append(
+                _warning(
+                    "ASSOCIATED_RESOURCE_VIEW_CONFIG_VERIFICATION_UNAVAILABLE",
+                    "associated resource view config write was executed but verification readback is unavailable",
+                )
+            )
         response = {
             "status": status,
             "error_code": error_code,
@@ -4211,6 +4656,8 @@ class AiBuilderFacade:
                 "edit_version_no": edit_version_no,
                 "associated_item_ids_by_client_key": client_key_to_id,
                 "readback_failed": readback_failed,
+                **({"readback_errors": readback_errors} if readback_errors else {}),
+                **({"verification_errors": verification_errors} if verification_errors else {}),
                 "compiled_match_rules": {
                     str(index): _summarize_compiled_match_rules(rules)
                     for index, rules in compiled_resource_match_rules.items()
@@ -4246,11 +4693,39 @@ class AiBuilderFacade:
             "safe_to_retry": not write_executed,
             "associated_resources": final_resources,
         }
-        response = self._append_publish_result(profile=profile, app_key=app_key, publish=write_succeeded, response=response, edit_version_no=edit_version_no)
+        response = self._append_publish_result(
+            profile=profile,
+            app_key=app_key,
+            publish=bool(write_succeeded and resource_write_intent),
+            response=response,
+            edit_version_no=edit_version_no,
+        )
         if response.get("published") and view_config_results:
             try:
                 post_publish_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as error:
+                details = response.get("details") if isinstance(response.get("details"), dict) else {}
+                response["details"] = details
+                post_publish_readback_errors = details.get("readback_errors") if isinstance(details.get("readback_errors"), list) else []
+                post_publish_readback_errors.append(
+                    {
+                        "resource": "associated_resources",
+                        "phase": "post_publish_pool",
+                        "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                    }
+                )
+                details["readback_errors"] = post_publish_readback_errors
+                warnings = response.get("warnings")
+                if not isinstance(warnings, list):
+                    warnings = []
+                    response["warnings"] = warnings
+                if not any(isinstance(warning, dict) and warning.get("code") == "ASSOCIATED_RESOURCES_READBACK_UNAVAILABLE" for warning in warnings):
+                    warnings.append(
+                        _warning(
+                            "ASSOCIATED_RESOURCES_READBACK_UNAVAILABLE",
+                            "associated resource write was executed but readback is unavailable",
+                        )
+                    )
                 post_publish_resources = final_resources
             if post_publish_resources:
                 response["associated_resources"] = post_publish_resources
@@ -4268,7 +4743,30 @@ class AiBuilderFacade:
                         config if isinstance(config, dict) else {},
                         available_resources=post_publish_resources,
                     )
-                except (QingflowApiError, RuntimeError):
+                except (QingflowApiError, RuntimeError) as error:
+                    details = response.get("details") if isinstance(response.get("details"), dict) else {}
+                    response["details"] = details
+                    post_publish_verification_errors = details.get("verification_errors") if isinstance(details.get("verification_errors"), list) else []
+                    post_publish_verification_errors.append(
+                        {
+                            "resource": "view_associated_resources_config",
+                            "phase": "post_publish_view_config_readback",
+                            "view_key": view_key,
+                            "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                        }
+                    )
+                    details["verification_errors"] = post_publish_verification_errors
+                    warnings = response.get("warnings")
+                    if not isinstance(warnings, list):
+                        warnings = []
+                        response["warnings"] = warnings
+                    if not any(isinstance(warning, dict) and warning.get("code") == "ASSOCIATED_RESOURCE_VIEW_CONFIG_VERIFICATION_UNAVAILABLE" for warning in warnings):
+                        warnings.append(
+                            _warning(
+                                "ASSOCIATED_RESOURCE_VIEW_CONFIG_VERIFICATION_UNAVAILABLE",
+                                "associated resource view config write was executed but verification readback is unavailable",
+                            )
+                        )
                     continue
                 if _associated_resources_config_matches(expected_config, actual_config):
                     result["status"] = "success"
@@ -4318,11 +4816,14 @@ class AiBuilderFacade:
         *,
         profile: str,
         app_name: str,
-        package_tag_id: int,
+        package_tag_id: int | None,
     ) -> list[JSONObject]:
         try:
             listing = self.apps.app_list(profile=profile, ship_auth=False)
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as exc:
+            api_error = _coerce_api_error(exc)
+            if not _is_optional_builder_lookup_error(api_error):
+                raise
             return []
         items = listing.get("items") if isinstance(listing.get("items"), list) else []
         matches: list[JSONObject] = []
@@ -4340,7 +4841,7 @@ class AiBuilderFacade:
             tag_id = _coerce_positive_int(item.get("tag_id"))
             if tag_id is not None and tag_id not in tag_ids:
                 tag_ids.append(tag_id)
-            if package_tag_id not in tag_ids:
+            if package_tag_id is not None and package_tag_id > 0 and package_tag_id not in tag_ids:
                 continue
             seen_app_keys.add(candidate_key)
             matches.append({"app_key": candidate_key, "app_name": title, "tag_ids": tag_ids})
@@ -4355,7 +4856,10 @@ class AiBuilderFacade:
     ) -> list[JSONObject]:
         try:
             package_result = self.packages.package_get(profile=profile, tag_id=package_tag_id, include_raw=True)
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as exc:
+            api_error = _coerce_api_error(exc)
+            if not _is_optional_builder_lookup_error(api_error):
+                raise
             return []
         raw_package = package_result.get("result") if isinstance(package_result.get("result"), dict) else {}
         tag_items = raw_package.get("tagItems") if isinstance(raw_package.get("tagItems"), list) else []
@@ -4394,23 +4898,15 @@ class AiBuilderFacade:
             "tag_ids": _coerce_int_list(base.get("tagIds")),
             "can_edit_app": _coerce_optional_bool(base.get("editItemStatus")),
             "can_manage_data": _coerce_optional_bool(base.get("dataManageStatus")),
+            "can_manage_views": (
+                _coerce_optional_bool(base.get("beingViewManageStatus"))
+                if "beingViewManageStatus" in base
+                else _coerce_optional_bool(base.get("dataManageStatus"))
+            ),
             "can_delete_app": _coerce_optional_bool(base.get("deleteItemStatus")),
             "can_copy_app": _coerce_optional_bool(base.get("copyAppStatus")),
         }
 
-    def _derive_can_edit_app_base(self, *, profile: str, permission_summary: JSONObject) -> bool:
-        if permission_summary.get("can_edit_app") is not True:
-            return False
-        tag_ids = _coerce_int_list(permission_summary.get("tag_ids"))
-        for tag_id in tag_ids:
-            try:
-                package_permission = self._read_package_permission_summary(profile=profile, tag_id=tag_id)
-            except (QingflowApiError, RuntimeError):
-                return False
-            if package_permission.get("can_edit_tag") is not True:
-                return False
-        return True
-
     def _read_portal_permission_summary(self, *, dash_key: str, portal_result: dict[str, Any]) -> JSONObject:
         tag_ids = _coerce_int_list(portal_result.get("tagIds"))
         if not tag_ids:
@@ -4435,42 +4931,45 @@ class AiBuilderFacade:
         app_key: str,
         required_permission: str,
         normalized_args: JSONObject,
+        permission_summary: JSONObject | None = None,
     ) -> PermissionCheckOutcome:
-        try:
-            permission_summary = self._read_app_permission_summary(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError) as error:
-            api_error = _coerce_api_error(error)
-            if _is_permission_restricted_api_error(api_error):
-                return _permission_skip_outcome(
-                    scope="app",
-                    target={"app_key": app_key},
-                    required_permission=required_permission,
-                    transport_error=_transport_error_payload(api_error),
-                )
-            return PermissionCheckOutcome(
-                block=_failed(
-                    "APP_PERMISSION_UNVERIFIED",
-                    "could not confirm current user's builder permissions for this app",
-                    normalized_args=normalized_args,
-                    details={
-                        "app_key": app_key,
-                        "required_permission": required_permission,
-                        "permission_read_error": {
-                            "message": api_error.message,
-                            "http_status": api_error.http_status,
-                            "backend_code": api_error.backend_code,
-                            "category": api_error.category,
+        if permission_summary is None:
+            try:
+                permission_summary = self._read_app_permission_summary(profile=profile, app_key=app_key)
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                if _is_permission_restricted_api_error(api_error):
+                    return _permission_skip_outcome(
+                        scope="app",
+                        target={"app_key": app_key},
+                        required_permission=required_permission,
+                        transport_error=_transport_error_payload(api_error),
+                    )
+                return PermissionCheckOutcome(
+                    block=_failed(
+                        "APP_PERMISSION_UNVERIFIED",
+                        "could not confirm current user's builder permissions for this app",
+                        normalized_args=normalized_args,
+                        details={
+                            "app_key": app_key,
+                            "required_permission": required_permission,
+                            "permission_read_error": {
+                                "message": api_error.message,
+                                "http_status": api_error.http_status,
+                                "backend_code": api_error.backend_code,
+                                "category": api_error.category,
+                            },
                         },
-                    },
-                    suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
-                    request_id=api_error.request_id,
-                    backend_code=api_error.backend_code,
-                    http_status=None if api_error.http_status == 404 else api_error.http_status,
+                        suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+                        request_id=api_error.request_id,
+                        backend_code=api_error.backend_code,
+                        http_status=None if api_error.http_status == 404 else api_error.http_status,
+                    )
                 )
-            )
         permission_key = {
             "edit_app": "can_edit_app",
             "data_manage": "can_manage_data",
+            "view_manage": "can_manage_views",
         }.get(required_permission)
         if permission_key is None:
             return PermissionCheckOutcome()
@@ -4484,12 +4983,15 @@ class AiBuilderFacade:
             )
         if permission_value is not False:
             return PermissionCheckOutcome()
-        error_code = "EDIT_APP_UNAUTHORIZED" if required_permission == "edit_app" else "DATA_MANAGE_UNAUTHORIZED"
-        message = (
-            "current user does not have builder edit-app permission on this app"
-            if required_permission == "edit_app"
-            else "current user does not have data-management permission on this app"
-        )
+        if required_permission == "edit_app":
+            error_code = "EDIT_APP_UNAUTHORIZED"
+            message = "current user does not have builder edit-app permission on this app"
+        elif required_permission == "view_manage":
+            error_code = "VIEW_MANAGE_UNAUTHORIZED"
+            message = "current user does not have view-management permission on this app"
+        else:
+            error_code = "DATA_MANAGE_UNAUTHORIZED"
+            message = "current user does not have data-management permission on this app"
         return PermissionCheckOutcome(
             block=_failed(
                 error_code,
@@ -4652,38 +5154,78 @@ class AiBuilderFacade:
                     details={"app_key": app_key},
                     suggested_next_call={"tool_name": "app_resolve", "arguments": {"profile": profile, "app_key": app_key}},
                 )
-        views, views_unavailable = self._load_views_result(
+        views, views_unavailable, views_read_error = self._load_views_result(
             profile=profile,
             app_key=app_key,
             tolerate_404=True,
             tolerate_permission_restricted=True,
+            include_error=True,
         )
         view_summaries = _summarize_views(views)
+        readback_errors: list[JSONObject] = []
         charts_unavailable = False
         try:
             chart_items, _chart_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
             chart_summaries = _summarize_charts(chart_items)
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as error:
             charts_unavailable = True
             chart_summaries = []
+            readback_errors.append(
+                {
+                    "resource": "charts",
+                    "phase": "summary",
+                    "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                }
+            )
         associated_resources_unavailable = False
         try:
             associated_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as error:
             associated_resources_unavailable = True
             associated_resources = []
+            readback_errors.append(
+                {
+                    "resource": "associated_resources",
+                    "phase": "summary",
+                    "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                }
+            )
         custom_buttons_unavailable = False
         try:
             custom_buttons = self._load_custom_buttons_for_builder(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as error:
             custom_buttons_unavailable = True
             custom_buttons = []
-        workflow, workflow_unavailable = self._load_workflow_result(
+            readback_errors.append(
+                {
+                    "resource": "custom_buttons",
+                    "phase": "summary",
+                    "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                }
+            )
+        workflow, workflow_unavailable, workflow_read_error = self._load_workflow_result(
             profile=profile,
             app_key=app_key,
             tolerate_404=True,
             tolerate_permission_restricted=True,
+            include_error=True,
         )
+        if views_read_error is not None:
+            readback_errors.append(
+                {
+                    "resource": "views",
+                    "phase": "summary",
+                    "transport_error": _transport_error_payload(views_read_error),
+                }
+            )
+        if workflow_read_error is not None:
+            readback_errors.append(
+                {
+                    "resource": "workflow",
+                    "phase": "summary",
+                    "transport_error": _transport_error_payload(workflow_read_error),
+                }
+            )
         verification_hints = _build_verification_hints(
             tag_ids=_coerce_int_list(base_result.get("tagIds")),
             fields=parsed["fields"],
@@ -4751,7 +5293,7 @@ class AiBuilderFacade:
             "normalized_args": {"app_key": app_key},
             "missing_fields": [],
             "allowed_values": {},
-            "details": {},
+            "details": {"readback_errors": readback_errors} if readback_errors else {},
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
@@ -4780,13 +5322,54 @@ class AiBuilderFacade:
             if not result.get("suggested_next_call"):
                 result["suggested_next_call"] = {"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}}
             return result
-        permission_summary = self._read_app_permission_summary(profile=profile, app_key=app_key)
+        try:
+            permission_summary = self._read_app_permission_summary(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if not _is_permission_restricted_api_error(api_error):
+                raise
+            result["message"] = "read app config summary; editability unverified"
+            result["editability"] = {
+                "can_edit_app_base": None,
+                "can_edit_form": None,
+                "can_edit_flow": None,
+                "can_edit_views": None,
+                "can_edit_charts": None,
+            }
+            details = result.get("details") if isinstance(result.get("details"), dict) else {}
+            permission_read_errors = details.get("permission_read_errors") if isinstance(details.get("permission_read_errors"), list) else []
+            permission_read_errors.append(
+                {
+                    "resource": "app_permission",
+                    "app_key": app_key,
+                    "required_permission": None,
+                    "transport_error": _transport_error_payload(api_error),
+                }
+            )
+            details["permission_read_errors"] = permission_read_errors
+            details["permission_check_skipped"] = True
+            result["details"] = details
+            warnings = result.get("warnings") if isinstance(result.get("warnings"), list) else []
+            warnings.append(
+                _warning(
+                    "APP_EDITABILITY_UNAVAILABLE",
+                    "could not confirm current user's builder permissions for this app; app summary remains available",
+                    app_key=app_key,
+                    **_transport_error_payload(api_error),
+                )
+            )
+            result["warnings"] = warnings
+            verification = result.get("verification") if isinstance(result.get("verification"), dict) else {}
+            verification["editability_unavailable"] = True
+            result["verification"] = verification
+            result["verified"] = False
+            return result
         result["message"] = "read app config summary"
         result["editability"] = {
-            "can_edit_app_base": self._derive_can_edit_app_base(profile=profile, permission_summary=permission_summary),
+            "can_edit_app_base": permission_summary.get("can_edit_app"),
             "can_edit_form": permission_summary.get("can_edit_app"),
-            "can_edit_flow": permission_summary.get("can_manage_data"),
-            "can_edit_views": permission_summary.get("can_manage_data"),
+            "can_edit_flow": permission_summary.get("can_edit_app"),
+            "can_edit_views": permission_summary.get("can_manage_views"),
             "can_edit_charts": permission_summary.get("can_manage_data"),
         }
         return result
@@ -4994,6 +5577,8 @@ class AiBuilderFacade:
                     "would_update": bool(update_fields),
                 },
                 "verified": True,
+                "write_executed": False,
+                "safe_to_retry": True,
                 "app_key": app_key,
                 "apply": False,
                 "repair_plan": plans,
@@ -5020,6 +5605,8 @@ class AiBuilderFacade:
                     "applied": False,
                 },
                 "verified": True,
+                "write_executed": False,
+                "safe_to_retry": True,
                 "app_key": app_key,
                 "apply": True,
                 "repair_plan": plans,
@@ -5037,6 +5624,7 @@ class AiBuilderFacade:
         )
         if apply_result.get("status") == "failed":
             return apply_result
+        verification_error: JSONObject | None = None
         try:
             reread = self._load_base_schema_state(profile=profile, app_key=app_key)
             verified_fields = cast(list[dict[str, Any]], reread["parsed"].get("fields") or [])
@@ -5057,17 +5645,36 @@ class AiBuilderFacade:
                     if plan["would_update"]:
                         plan["applied"] = True
                         applied_fields.append(plan["field_name"])
-        except (QingflowApiError, RuntimeError):
-            pass
+        except (QingflowApiError, RuntimeError) as error:
+            verification_error = _transport_error_payload(_coerce_api_error(error))
         apply_result["message"] = "repaired code block fields"
         apply_result["apply"] = True
         apply_result["repair_plan"] = plans
         apply_result["applied_fields"] = applied_fields
+        if verification_error is None:
+            existing_details = apply_result.get("details") if isinstance(apply_result.get("details"), dict) else {}
+            existing_verification_error = existing_details.get("verification_error") if isinstance(existing_details, dict) else None
+            if isinstance(existing_verification_error, dict):
+                verification_error = deepcopy(existing_verification_error)
+        if verification_error is not None:
+            details = apply_result.get("details") if isinstance(apply_result.get("details"), dict) else {}
+            details = deepcopy(details)
+            details["code_block_repair_verification_error"] = verification_error
+            apply_result["details"] = details
+            warnings = apply_result.get("warnings") if isinstance(apply_result.get("warnings"), list) else []
+            apply_result["warnings"] = [
+                *warnings,
+                _warning(
+                    "CODE_BLOCK_REPAIR_VERIFICATION_UNAVAILABLE",
+                    "code block repair write was executed but post-write verification readback is unavailable",
+                ),
+            ]
         apply_result["verification"] = {
             **(apply_result.get("verification") if isinstance(apply_result.get("verification"), dict) else {}),
             "code_block_fields_scanned": len(plans),
             "would_update": bool(update_fields),
             "applied": bool(applied_fields),
+            **({"code_block_repair_verification_unavailable": True} if verification_error is not None else {}),
         }
         return apply_result
 
@@ -5120,6 +5727,17 @@ class AiBuilderFacade:
             )
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
+            if is_auth_like_error(api_error) or (
+                backend_code_int(api_error) not in {40002, 40027, 404}
+                and api_error.http_status != 404
+            ):
+                return _failed_from_api_error(
+                    "APP_GET_FIELDS_FAILED",
+                    api_error,
+                    normalized_args={"app_key": app_key},
+                    details={"app_key": app_key, "resource": "qingbi_fields"},
+                    suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
+                )
             warnings.append(
                 _warning(
                     "QINGBI_FIELDS_READ_FAILED",
@@ -5388,13 +6006,23 @@ class AiBuilderFacade:
                 continue
             try:
                 portal_result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") or {}
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                if not _is_optional_builder_lookup_error(api_error):
+                    return _failed_from_api_error(
+                        "PORTAL_LIST_FAILED",
+                        api_error,
+                        normalized_args={},
+                        details={"dash_key": dash_key, "resource": "portal_detail"},
+                        suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key}},
+                    )
                 permission_verified = False
                 warnings.append(
                     _warning(
                         "PORTAL_PERMISSION_READ_UNAVAILABLE",
                         f"builder portal_list skipped `{dash_key}` because portal detail readback was unavailable during permission verification",
                         dash_key=dash_key,
+                        **_transport_error_payload(api_error),
                     )
                 )
                 continue
@@ -5446,8 +6074,10 @@ class AiBuilderFacade:
             sorted_items = self.charts.qingbi_report_list_sorted(profile=profile, app_key=app_key, page_num=1, page_size=500).get("items") or []
             if isinstance(sorted_items, list):
                 return sorted_items, "sorted"
-        except (QingflowApiError, RuntimeError):
-            pass
+        except (QingflowApiError, RuntimeError) as exc:
+            api_error = _coerce_api_error(exc)
+            if not _is_optional_builder_lookup_error(api_error):
+                raise
         fallback_items = self.charts.qingbi_report_list(profile=profile, app_key=app_key).get("items") or []
         return list(fallback_items) if isinstance(fallback_items, list) else [], "fallback"
 
@@ -5890,6 +6520,7 @@ class AiBuilderFacade:
             if button_id is not None:
                 button_inventory[button_id] = item
         valid_custom_button_ids = (set(button_inventory) | set(created_ids) | set(updated_ids)) - set(removed_ids)
+        allow_unverified_numeric_button_ids = not bool(valid_custom_button_ids)
         write_executed = False
         write_succeeded = False
         all_verified = True
@@ -5941,6 +6572,7 @@ class AiBuilderFacade:
                     button_inventory=button_inventory,
                     valid_custom_button_ids=valid_custom_button_ids,
                     reason_path=f"view_configs[{config_index}].buttons[{button_index}].button_ref",
+                    allow_unverified_numeric_id=allow_unverified_numeric_button_ids,
                 )
                 if ref_issue:
                     config_issues.append(ref_issue)
@@ -5952,6 +6584,7 @@ class AiBuilderFacade:
                     binding=view_binding,
                     current_fields_by_name=current_fields_by_name,
                     valid_custom_button_ids=valid_custom_button_ids,
+                    allow_unverified_custom_button_id=allow_unverified_numeric_button_ids,
                 )
                 if binding_issues:
                     config_issues.extend(binding_issues)
@@ -6249,6 +6882,7 @@ class AiBuilderFacade:
             )
 
         warnings: list[dict[str, Any]] = []
+        readback_errors: list[JSONObject] = []
         verification = {
             "view_exists": True,
             "base_info_verified": True,
@@ -6259,39 +6893,133 @@ class AiBuilderFacade:
 
         base_info: dict[str, Any] = {}
         try:
-            base_info_payload = self.views.view_get_base_info(profile=profile, viewgraph_key=view_key, passcode=None).get("result") or {}
+            base_info_response = self.views.view_get_base_info(profile=profile, viewgraph_key=view_key, passcode=None)
+            base_info_payload = base_info_response.get("result") or {}
             if isinstance(base_info_payload, dict):
                 base_info = deepcopy(base_info_payload)
-        except (QingflowApiError, RuntimeError):
+            base_info_verification = (
+                base_info_response.get("verification")
+                if isinstance(base_info_response.get("verification"), dict)
+                else {}
+            )
+            if base_info_verification.get("base_info_verified") is False:
+                verification["base_info_verified"] = False
+                for warning in base_info_response.get("warnings") or []:
+                    if not isinstance(warning, dict):
+                        continue
+                    warnings.append(deepcopy(warning))
+                    readback_errors.append(
+                        {
+                            "resource": "view_base_info",
+                            "phase": "view_get",
+                            "view_key": view_key,
+                            "transport_error": {
+                                "http_status": warning.get("http_status"),
+                                "backend_code": warning.get("backend_code"),
+                                "category": warning.get("category"),
+                                "request_id": warning.get("request_id"),
+                            },
+                        }
+                    )
+        except (QingflowApiError, RuntimeError) as error:
             verification["base_info_verified"] = False
-            warnings.append(_warning("VIEW_BASE_INFO_UNAVAILABLE", "view base info readback is unavailable"))
+            api_error = _coerce_api_error(error)
+            if not _is_optional_builder_lookup_error(api_error):
+                return _failed_from_api_error(
+                    "VIEW_GET_FAILED",
+                    api_error,
+                    normalized_args={"view_key": view_key},
+                    details={"view_key": view_key, "resource": "view_base_info"},
+                    suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, "view_key": view_key}},
+                )
+            readback_errors.append(
+                {
+                    "resource": "view_base_info",
+                    "phase": "view_get",
+                    "view_key": view_key,
+                    "transport_error": _transport_error_payload(api_error),
+                }
+            )
+            warnings.append(_warning("VIEW_BASE_INFO_UNAVAILABLE", "view base info readback is unavailable", **_transport_error_payload(api_error)))
 
         questions: list[dict[str, Any]] = []
         try:
             questions_payload = self.views.view_list_questions(profile=profile, viewgraph_key=view_key).get("result") or []
             if isinstance(questions_payload, list):
                 questions = [deepcopy(item) for item in questions_payload if isinstance(item, dict)]
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as error:
             verification["questions_verified"] = False
-            warnings.append(_warning("VIEW_QUESTIONS_UNAVAILABLE", "view question list readback is unavailable"))
+            api_error = _coerce_api_error(error)
+            if not _is_optional_builder_lookup_error(api_error):
+                return _failed_from_api_error(
+                    "VIEW_GET_FAILED",
+                    api_error,
+                    normalized_args={"view_key": view_key},
+                    details={"view_key": view_key, "resource": "view_questions"},
+                    suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, "view_key": view_key}},
+                )
+            readback_errors.append(
+                {
+                    "resource": "view_questions",
+                    "phase": "view_get",
+                    "view_key": view_key,
+                    "transport_error": _transport_error_payload(api_error),
+                }
+            )
+            warnings.append(_warning("VIEW_QUESTIONS_UNAVAILABLE", "view question list readback is unavailable", **_transport_error_payload(api_error)))
 
         associations: list[dict[str, Any]] = []
         try:
             associations_payload = self.views.view_list_associations(profile=profile, viewgraph_key=view_key).get("result") or []
             if isinstance(associations_payload, list):
                 associations = [deepcopy(item) for item in associations_payload if isinstance(item, dict)]
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as error:
             verification["associations_verified"] = False
-            warnings.append(_warning("VIEW_ASSOCIATIONS_UNAVAILABLE", "view association list readback is unavailable"))
+            api_error = _coerce_api_error(error)
+            if not _is_optional_builder_lookup_error(api_error):
+                return _failed_from_api_error(
+                    "VIEW_GET_FAILED",
+                    api_error,
+                    normalized_args={"view_key": view_key},
+                    details={"view_key": view_key, "resource": "view_associations"},
+                    suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, "view_key": view_key}},
+                )
+            readback_errors.append(
+                {
+                    "resource": "view_associations",
+                    "phase": "view_get",
+                    "view_key": view_key,
+                    "transport_error": _transport_error_payload(api_error),
+                }
+            )
+            warnings.append(_warning("VIEW_ASSOCIATIONS_UNAVAILABLE", "view association list readback is unavailable", **_transport_error_payload(api_error)))
 
         app_key = str(_first_present(config, "appKey", "formKey") or _first_present(base_info, "appKey", "formKey") or "").strip()
         associated_resources: list[dict[str, Any]] = []
         if app_key:
             try:
                 associated_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as error:
                 verification["associated_resources_verified"] = False
-                warnings.append(_warning("VIEW_ASSOCIATED_RESOURCES_UNAVAILABLE", "view associated resource pool readback is unavailable"))
+                api_error = _coerce_api_error(error)
+                if not _is_optional_builder_lookup_error(api_error):
+                    return _failed_from_api_error(
+                        "VIEW_GET_FAILED",
+                        api_error,
+                        normalized_args={"view_key": view_key},
+                        details={"view_key": view_key, "app_key": app_key, "resource": "associated_resources"},
+                        suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, "view_key": view_key}},
+                    )
+                readback_errors.append(
+                    {
+                        "resource": "associated_resources",
+                        "phase": "view_get",
+                        "view_key": view_key,
+                        "app_key": app_key,
+                        "transport_error": _transport_error_payload(api_error),
+                    }
+                )
+                warnings.append(_warning("VIEW_ASSOCIATED_RESOURCES_UNAVAILABLE", "view associated resource pool readback is unavailable", **_transport_error_payload(api_error)))
         associated_resources_config = _extract_view_associated_resources_config(
             config if isinstance(config, dict) else {},
             available_resources=associated_resources,
@@ -6324,7 +7052,7 @@ class AiBuilderFacade:
             "normalized_args": {"view_key": view_key},
             "missing_fields": [],
             "allowed_values": {},
-            "details": {},
+            "details": {"readback_errors": readback_errors} if readback_errors else {},
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
@@ -6361,15 +7089,34 @@ class AiBuilderFacade:
             )
 
         try:
-            config = self.charts.qingbi_report_get_config(profile=profile, chart_id=chart_id).get("result") or {}
+            config_response = self.charts.qingbi_report_get_config(profile=profile, chart_id=chart_id)
+            config = config_response.get("result") or {}
+            config_warnings = config_response.get("warnings") if isinstance(config_response.get("warnings"), list) else []
+            warnings.extend(item for item in config_warnings if isinstance(item, dict))
+            config_verification = (
+                config_response.get("verification") if isinstance(config_response.get("verification"), dict) else {}
+            )
+            if config_verification:
+                verification.update(config_verification)
         except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if not _is_optional_builder_lookup_error(api_error) and backend_code_int(api_error) != 81007:
+                return _failed_from_api_error(
+                    "CHART_GET_FAILED",
+                    api_error,
+                    normalized_args={"chart_id": chart_id},
+                    details={"chart_id": chart_id, "resource": "chart_config"},
+                    suggested_next_call={"tool_name": "chart_get", "arguments": {"profile": profile, "chart_id": chart_id}},
+                )
             fallback_config: dict[str, Any] | None = None
+            fallback_api_error: QingflowApiError | None = None
             try:
                 data_fallback = self.charts.qingbi_report_get_data(profile=profile, chart_id=chart_id, payload={}).get("result") or {}
                 config_from_data = data_fallback.get("config") if isinstance(data_fallback, dict) else None
                 if isinstance(config_from_data, dict):
                     fallback_config = deepcopy(config_from_data)
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as fallback_error:
+                fallback_api_error = _coerce_api_error(fallback_error)
                 fallback_config = None
             if isinstance(fallback_config, dict):
                 config = fallback_config
@@ -6380,12 +7127,17 @@ class AiBuilderFacade:
                     )
                 )
             else:
-                api_error = _coerce_api_error(error)
+                details: JSONObject = {
+                    "chart_id": chart_id,
+                    "config_error": _transport_error_payload(api_error),
+                }
+                if fallback_api_error is not None:
+                    details["data_fallback_error"] = _transport_error_payload(fallback_api_error)
                 return _failed_from_api_error(
                     "CHART_GET_FAILED",
                     api_error,
                     normalized_args={"chart_id": chart_id},
-                    details={"chart_id": chart_id},
+                    details=details,
                     suggested_next_call={"tool_name": "chart_get", "arguments": {"profile": profile, "chart_id": chart_id}},
                 )
 
@@ -7097,16 +7849,6 @@ class AiBuilderFacade:
             if add_permission_outcome.block is not None:
                 return add_permission_outcome.block
             permission_outcomes.append(add_permission_outcome)
-            if requested_field_changes:
-                edit_permission_outcome = self._guard_package_permission(
-                    profile=profile,
-                    tag_id=permission_tag_id,
-                    required_permission="edit_app",
-                    normalized_args=normalized_args,
-                )
-                if edit_permission_outcome.block is not None:
-                    return edit_permission_outcome.block
-                permission_outcomes.append(edit_permission_outcome)
             resolved = self._create_target_app_shell(
                 profile=profile,
                 app_name=app_name,
@@ -7206,6 +7948,9 @@ class AiBuilderFacade:
                 "created": True,
                 "field_diff": {"added": [], "updated": [], "removed": []},
                 "verified": True,
+                "write_executed": True,
+                "write_succeeded": True,
+                "safe_to_retry": False,
                 "tag_ids_after": list(target.tag_ids),
                 "package_attached": None if package_tag_id is None else package_tag_id in target.tag_ids,
                 "publish_requested": False,
@@ -7434,7 +8179,34 @@ class AiBuilderFacade:
         )
 
         if not added and not updated and not removed and not normalized_code_block_fields and not data_display_selection.has_any and not bool(resolved.get("created")):
-            base_info = self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}
+            try:
+                base_info = self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                if bool(visual_result.get("updated")):
+                    return finalize(_post_write_readback_pending_result(
+                        error_code="APP_BASE_READBACK_PENDING",
+                        message="updated app base metadata; app base readback is unavailable",
+                        normalized_args=normalized_args,
+                        details={
+                            "app_key": target.app_key,
+                            "verification_error": _transport_error_payload(api_error),
+                            "app_name_after": effective_app_name,
+                            "app_base_updated": True,
+                            "field_diff": {"added": [], "updated": [], "removed": []},
+                        },
+                        suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": target.app_key}},
+                        request_id=api_error.request_id,
+                        backend_code=api_error.backend_code,
+                        http_status=None if api_error.http_status == 404 else api_error.http_status,
+                    ))
+                return finalize(_failed_from_api_error(
+                    "APP_BASE_READBACK_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details=_with_state_read_blocked_details({"app_key": target.app_key}, resource="app_base", error=api_error),
+                    suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": target.app_key}},
+                ))
             tag_ids_after = _coerce_int_list(base_info.get("tagIds"))
             package_attached = None if package_tag_id is None else package_tag_id in tag_ids_after
             actual_app_name = str(base_info.get("formTitle") or effective_app_name).strip() or effective_app_name
@@ -7472,6 +8244,9 @@ class AiBuilderFacade:
                 "created": False,
                 "field_diff": {"added": [], "updated": [], "removed": []},
                 "verified": verified,
+                "write_executed": bool(visual_result.get("updated")),
+                "write_succeeded": bool(visual_result.get("updated")),
+                "safe_to_retry": not bool(visual_result.get("updated")),
                 "tag_ids_after": tag_ids_after,
                 "package_attached": package_attached,
             }
@@ -7509,7 +8284,7 @@ class AiBuilderFacade:
             self.apps.app_update_form_schema(profile=profile, app_key=target.app_key, payload=payload)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            if api_error.backend_code == 49614:
+            if backend_code_int(api_error) == 49614:
                 return _failed(
                     "MULTIPLE_RELATION_FIELDS_UNSUPPORTED",
                     "backend currently rejects apps with more than one relation field; keep one real relation field and use text/reference summary fields for additional cross-object links.",
@@ -7681,6 +8456,9 @@ class AiBuilderFacade:
                 after_fields=current_fields,
             ),
             "verified": False,
+            "write_executed": True,
+            "write_succeeded": True,
+            "safe_to_retry": False,
             "tag_ids_after": [],
             "package_attached": None,
         }
@@ -7786,8 +8564,7 @@ class AiBuilderFacade:
                 response["details"] = details
             details["verification_error"] = {
                 "message": verification_error.message,
-                "http_status": verification_error.http_status,
-                "backend_code": verification_error.backend_code,
+                **_transport_error_payload(verification_error),
             }
         return finalize(response)
 
@@ -7924,6 +8701,9 @@ class AiBuilderFacade:
                     "fallback_applied": None,
                 },
                 "verified": True,
+                "write_executed": False,
+                "write_succeeded": False,
+                "safe_to_retry": True,
             }
             return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
         payload = _build_form_payload_from_existing_schema(
@@ -7941,7 +8721,7 @@ class AiBuilderFacade:
             self.apps.app_update_form_schema(profile=profile, app_key=app_key, payload=payload)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            if api_error.backend_code == 400 and target_layout.get("sections"):
+            if backend_code_int(api_error) == 400 and target_layout.get("sections"):
                 flattened_layout = _flatten_layout_sections(target_layout)
                 fallback_payload = _build_form_payload_from_existing_schema(
                     current_schema=schema_result,
@@ -7997,11 +8777,21 @@ class AiBuilderFacade:
                 "normalized_args": normalized_args,
                 "missing_fields": [],
                 "allowed_values": {"modes": ["merge", "replace"]},
-                "details": {},
-                "request_id": None,
+                "details": {"readback_error": _transport_error_payload(api_error)},
+                "request_id": api_error.request_id,
+                "backend_code": api_error.backend_code,
+                "http_status": None if api_error.http_status == 404 else api_error.http_status,
                 "suggested_next_call": {"tool_name": "app_get_layout", "arguments": {"profile": profile, "app_key": app_key}},
                 "noop": False,
-                "warnings": [],
+                "warnings": [
+                    _warning(
+                        "READBACK_UNAVAILABLE_AFTER_WRITE",
+                        "write was executed but layout readback is unavailable",
+                        backend_code=api_error.backend_code,
+                        http_status=None if api_error.http_status == 404 else api_error.http_status,
+                        request_id=api_error.request_id,
+                    )
+                ],
                 "verification": {"layout_verified": False, "layout_summary_verified": False, "layout_read_unavailable": True},
                 "app_key": app_key,
                 "app_name": app_name,
@@ -8013,8 +8803,10 @@ class AiBuilderFacade:
                     "fallback_applied": fallback_applied,
                 },
                 "verified": False,
+                "write_executed": True,
+                "write_succeeded": True,
+                "safe_to_retry": False,
             }
-            response["request_id"] = api_error.request_id
             return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
         verified_layout = _parse_schema(verified_schema)["layout"]
         layout_verified = _layouts_equal(verified_layout, applied_layout) or _layouts_semantically_equal(verified_layout, applied_layout)
@@ -8070,6 +8862,9 @@ class AiBuilderFacade:
                 "fallback_applied": fallback_applied,
             },
             "verified": layout_verified,
+            "write_executed": True,
+            "write_succeeded": True,
+            "safe_to_retry": False,
         }
         return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
@@ -8094,7 +8889,7 @@ class AiBuilderFacade:
         permission_outcome = self._guard_app_permission(
             profile=profile,
             app_key=app_key,
-            required_permission="data_manage",
+            required_permission="edit_app",
             normalized_args=normalized_args,
         )
         if permission_outcome.block is not None:
@@ -8295,6 +9090,9 @@ class AiBuilderFacade:
             "app_name": app_name,
             "flow_diff": {"mode": "replace", "node_count": desired_node_count},
             "verified": workflow_verified,
+            "write_executed": True,
+            "write_succeeded": True,
+            "safe_to_retry": False,
         }
         return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
@@ -8339,15 +9137,57 @@ class AiBuilderFacade:
                 "app_key": app_key,
                 "views_diff": {"created": [], "updated": [], "removed": []},
                 "verified": True,
+                "write_executed": False,
+                "write_succeeded": False,
+                "safe_to_retry": True,
             }
             return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
         permission_outcomes: list[PermissionCheckOutcome] = []
-        permission_outcome = self._guard_app_permission(
-            profile=profile,
-            app_key=app_key,
-            required_permission="data_manage",
-            normalized_args=normalized_args,
-        )
+        app_permission_summary: JSONObject | None = None
+        app_permission_error: QingflowApiError | None = None
+        try:
+            app_permission_summary = self._read_app_permission_summary(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            app_permission_error = _coerce_api_error(error)
+            app_permission_summary = None
+        if app_permission_error is not None:
+            if _is_permission_restricted_api_error(app_permission_error):
+                permission_outcome = _permission_skip_outcome(
+                    scope="app",
+                    target={"app_key": app_key},
+                    required_permission="view_manage",
+                    transport_error=_transport_error_payload(app_permission_error),
+                )
+            else:
+                permission_outcome = PermissionCheckOutcome(
+                    block=_failed(
+                        "APP_PERMISSION_UNVERIFIED",
+                        "could not confirm current user's builder permissions for this app",
+                        normalized_args=normalized_args,
+                        details={
+                            "app_key": app_key,
+                            "required_permission": "view_manage",
+                            "permission_read_error": {
+                                "message": app_permission_error.message,
+                                "http_status": app_permission_error.http_status,
+                                "backend_code": app_permission_error.backend_code,
+                                "category": app_permission_error.category,
+                            },
+                        },
+                        suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+                        request_id=app_permission_error.request_id,
+                        backend_code=app_permission_error.backend_code,
+                        http_status=None if app_permission_error.http_status == 404 else app_permission_error.http_status,
+                    )
+                )
+        else:
+            permission_outcome = self._guard_app_permission(
+                profile=profile,
+                app_key=app_key,
+                required_permission="view_manage",
+                normalized_args=normalized_args,
+                permission_summary=app_permission_summary,
+            )
         if permission_outcome.block is not None:
             return permission_outcome.block
         permission_outcomes.append(permission_outcome)
@@ -8380,6 +9220,35 @@ class AiBuilderFacade:
             if name and key:
                 existing_by_key[key] = view
                 existing_by_name.setdefault(name, []).append(view)
+        creating_view_names = [
+            patch.name
+            for patch in upsert_views
+            if not patch.view_key and not existing_by_name.get(patch.name)
+        ]
+        if creating_view_names:
+            if app_permission_error is not None and _is_permission_restricted_api_error(app_permission_error):
+                create_permission_outcome = _permission_skip_outcome(
+                    scope="app",
+                    target={"app_key": app_key},
+                    required_permission="data_manage",
+                    transport_error=_transport_error_payload(app_permission_error),
+                )
+            else:
+                create_permission_outcome = self._guard_app_permission(
+                    profile=profile,
+                    app_key=app_key,
+                    required_permission="data_manage",
+                    normalized_args=normalized_args,
+                    permission_summary=app_permission_summary,
+                )
+            if create_permission_outcome.block is not None:
+                details = create_permission_outcome.block.get("details")
+                if isinstance(details, dict):
+                    details["operation"] = "view_create"
+                    details["view_names"] = creating_view_names
+                    details["also_required_permission"] = "view_manage"
+                return create_permission_outcome.block
+            permission_outcomes.append(create_permission_outcome)
         parsed_schema = _parse_schema(schema)
         field_names = {field["name"] for field in parsed_schema["fields"]}
         if patch_views:
@@ -8454,8 +9323,26 @@ class AiBuilderFacade:
                         being_draft=True,
                         include_raw=False,
                     )
-                except (QingflowApiError, RuntimeError):
-                    continue
+                except (QingflowApiError, RuntimeError) as error:
+                    api_error = _coerce_api_error(error)
+                    if _is_optional_builder_lookup_error(api_error):
+                        continue
+                    failed = _failed_from_api_error(
+                        "CUSTOM_BUTTON_DETAIL_READ_FAILED",
+                        api_error,
+                        normalized_args=normalized_args,
+                        details=_with_state_read_blocked_details(
+                            {"app_key": app_key, "button_id": button_id},
+                            resource="custom_button",
+                            error=api_error,
+                        ),
+                        suggested_next_call={
+                            "tool_name": "app_custom_button_get",
+                            "arguments": {"profile": profile, "app_key": app_key, "button_id": button_id},
+                        },
+                    )
+                    failed.update({"write_executed": False, "write_succeeded": False, "safe_to_retry": True})
+                    return finalize(failed)
                 detail_result = detail.get("result")
                 if isinstance(detail_result, dict):
                     custom_button_details_by_id[button_id] = _normalize_custom_button_detail(detail_result)
@@ -8930,7 +9817,7 @@ class AiBuilderFacade:
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
                 should_retry_minimal = operation_phase != "default_view_apply_config_sync" and (
-                    api_error.backend_code == 48104
+                    backend_code_int(api_error) == 48104
                     or (patch.type.value == "table" and bool(patch.filters) and api_error.http_status is not None and api_error.http_status >= 500)
                 )
                 if should_retry_minimal:
@@ -9526,6 +10413,9 @@ class AiBuilderFacade:
                 "app_name": app_name,
                 "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": failed_views},
                 "verified": verified and view_filters_verified and view_query_conditions_verified and view_associated_resources_verified and view_buttons_verified,
+                "write_executed": bool(created or updated or removed),
+                "write_succeeded": bool(created or updated or removed),
+                "safe_to_retry": not bool(created or updated or removed),
             }
             return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
         warnings: list[dict[str, Any]] = []
@@ -9607,6 +10497,9 @@ class AiBuilderFacade:
             "app_name": app_name,
             "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": []},
             "verified": all_verified,
+            "write_executed": bool(created or updated or removed),
+            "write_succeeded": bool(created or updated or removed),
+            "safe_to_retry": not bool(created or updated or removed),
         }
         return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
@@ -9667,8 +10560,21 @@ class AiBuilderFacade:
                 "tag_ids_after": tag_ids_before,
                 "views_ok": True,
                 "verified": True,
+                "write_executed": False,
+                "write_succeeded": False,
+                "safe_to_retry": True,
             }
-        version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+        try:
+            version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "PUBLISH_PRECHECK_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key, "phase": "prepare_publish_edit_version"},
+                suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         edit_version_no = _coerce_positive_int(version_result.get("editVersionNo") or version_result.get("versionNo")) or 1
         try:
             self.apps.app_publish(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
@@ -9686,13 +10592,18 @@ class AiBuilderFacade:
             base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            return _failed_from_api_error(
-                "APP_READ_FAILED",
-                api_error,
+            result = _post_write_readback_pending_result(
+                error_code="PUBLISH_READBACK_PENDING",
+                message="published app; app base readback is unavailable",
                 normalized_args=normalized_args,
-                details={"app_key": app_key},
+                details={"app_key": app_key, "edit_version_no": edit_version_no, "readback_error": _transport_error_payload(api_error)},
                 suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+                request_id=api_error.request_id,
+                backend_code=api_error.backend_code,
+                http_status=None if api_error.http_status == 404 else api_error.http_status,
             )
+            result.update({"app_key": app_key, "published": None, "verified": False})
+            return result
         tag_ids_after = _coerce_int_list(base.get("tagIds"))
         app_name_after = str(base.get("formTitle") or base.get("title") or base.get("appName") or app_name_before or "").strip() or None
         package_attached = None if not expected_package_tag_id else expected_package_tag_id in tag_ids_after
@@ -9700,13 +10611,18 @@ class AiBuilderFacade:
             views, views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            return _failed_from_api_error(
-                "VIEWS_READ_FAILED",
-                api_error,
+            result = _post_write_readback_pending_result(
+                error_code="VIEWS_READBACK_PENDING",
+                message="published app; views readback is unavailable",
                 normalized_args=normalized_args,
-                details={"app_key": app_key},
+                details={"app_key": app_key, "edit_version_no": edit_version_no, "readback_error": _transport_error_payload(api_error)},
                 suggested_next_call={"tool_name": "app_get_views", "arguments": {"profile": profile, "app_key": app_key}},
+                request_id=api_error.request_id,
+                backend_code=api_error.backend_code,
+                http_status=None if api_error.http_status == 404 else api_error.http_status,
             )
+            result.update({"app_key": app_key, "app_name": app_name_after, "published": bool(base.get("appPublishStatus") in {1, 2}), "verified": False})
+            return result
         views = views or []
         views_ok = isinstance(views, list) and not views_unavailable
         verified = bool(base.get("appPublishStatus") in {1, 2}) and (package_attached is not False) and views_ok
@@ -9741,6 +10657,9 @@ class AiBuilderFacade:
             "tag_ids_after": tag_ids_after,
             "views_ok": views_ok,
             "verified": verified,
+            "write_executed": True,
+            "write_succeeded": True,
+            "safe_to_retry": False,
         }
 
     def _expand_chart_partial_patches(
@@ -9904,7 +10823,15 @@ class AiBuilderFacade:
 
     def _verify_custom_button_deleted_by_id(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
         try:
-            self.buttons.custom_button_get(profile=profile, app_key=app_key, button_id=button_id, being_draft=True, include_raw=False)
+            def runner(_: Any, context: BackendRequestContext) -> object:
+                return self.buttons.backend.request(
+                    "GET",
+                    context,
+                    f"/app/{app_key}/customButton/{button_id}",
+                    params={"beingDraft": True},
+                )
+
+            self.buttons._run(profile, runner)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
             if _delete_readback_is_not_found(api_error):
@@ -10185,18 +11112,21 @@ class AiBuilderFacade:
                     create_result = self.charts.qingbi_report_create(profile=profile, payload=create_payload).get("result") or {}
                     created_chart_id = _extract_chart_identifier(create_result or {})
                     if not created_chart_id:
-                        refreshed_items, _ = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
-                        refreshed_matches = _find_charts_by_name(
-                            refreshed_items,
-                            chart_name=patch.name,
-                            chart_type=target_type,
-                        )
-                        if len(refreshed_matches) == 1:
-                            created_chart_id = _extract_chart_identifier(refreshed_matches[0])
-                        elif len(refreshed_matches) > 1:
-                            raise ValueError(
-                                f"created chart '{patch.name}' could not be uniquely resolved from readback; supply chart_id on the next update"
+                        try:
+                            refreshed_items, _ = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
+                            refreshed_matches = _find_charts_by_name(
+                                refreshed_items,
+                                chart_name=patch.name,
+                                chart_type=target_type,
                             )
+                            if len(refreshed_matches) == 1:
+                                created_chart_id = _extract_chart_identifier(refreshed_matches[0])
+                            elif len(refreshed_matches) > 1:
+                                raise ValueError(
+                                    f"created chart '{patch.name}' could not be uniquely resolved from readback; supply chart_id on the next update"
+                                )
+                        except (QingflowApiError, RuntimeError):
+                            created_chart_id = temp_chart_id
                     if not created_chart_id:
                         raise ValueError(
                             f"created chart '{patch.name}' did not return a real chart_id and could not be confirmed from readback"
@@ -10352,10 +11282,13 @@ class AiBuilderFacade:
                 chart_results.append(failure)
 
         noop = not created_ids and not updated_ids and not removed_ids and not reordered and not failed_items
+        write_executed = bool(created_ids or updated_ids or removed_ids or reordered)
+        write_succeeded = write_executed
         needs_list_readback = bool(created_ids or updated_ids or reordered)
         delete_readback_unavailable = any(item.get("readback_status") == "unavailable" for item in delete_readback_issues)
         deletes_verified = not delete_readback_issues
         readback_unavailable = False
+        readback_error: QingflowApiError | None = None
         readback_list_source: str | None = existing_chart_list_source
         if needs_list_readback:
             try:
@@ -10375,7 +11308,8 @@ class AiBuilderFacade:
                     requested_existing = [chart_id for chart_id in request.reorder_chart_ids if chart_id in ordered_readback]
                     verified = verified and readback_list_source == "sorted" and ordered_readback[: len(requested_existing)] == requested_existing
                 readback_unavailable = False
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as error:
+                readback_error = _coerce_api_error(error)
                 verified = False
                 readback_unavailable = True
                 readback_list_source = None
@@ -10394,11 +11328,14 @@ class AiBuilderFacade:
                 "normalized_args": normalized_args,
                 "missing_fields": [],
                 "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
-                "details": {"per_chart_results": chart_results},
-                "request_id": failed_items[0].get("request_id"),
+                "details": {
+                    "per_chart_results": chart_results,
+                    **({"readback_error": _transport_error_payload(readback_error)} if readback_error is not None else {}),
+                },
+                "request_id": failed_items[0].get("request_id") or (readback_error.request_id if readback_error is not None else None),
                 "suggested_next_call": {"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
-                "backend_code": failed_items[0].get("backend_code"),
-                "http_status": failed_items[0].get("http_status"),
+                "backend_code": failed_items[0].get("backend_code") or (readback_error.backend_code if readback_error is not None else None),
+                "http_status": failed_items[0].get("http_status") or (None if readback_error is None or readback_error.http_status == 404 else readback_error.http_status),
                 "noop": noop,
                 "warnings": _chart_apply_warnings(
                     failed_items=failed_items,
@@ -10417,6 +11354,9 @@ class AiBuilderFacade:
                 "app_name": app_name,
                 "chart_results": chart_results,
                 "verified": False if failed_items else verified,
+                "write_executed": write_executed,
+                "write_succeeded": write_succeeded,
+                "safe_to_retry": not write_executed,
             })
         result_verified = verified or noop
         pending_delete = bool(delete_readback_issues)
@@ -10435,9 +11375,11 @@ class AiBuilderFacade:
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
-            "details": {},
-            "request_id": None,
+            "details": {"readback_error": _transport_error_payload(readback_error)} if readback_error is not None else {},
+            "request_id": readback_error.request_id if readback_error is not None else None,
             "suggested_next_call": None if result_verified else pending_suggestion,
+            "backend_code": readback_error.backend_code if readback_error is not None else None,
+            "http_status": None if readback_error is None or readback_error.http_status == 404 else readback_error.http_status,
             "noop": noop,
             "warnings": _chart_apply_warnings(
                 failed_items=[],
@@ -10456,6 +11398,9 @@ class AiBuilderFacade:
             "app_name": app_name,
             "chart_results": chart_results,
             "verified": result_verified,
+            "write_executed": write_executed,
+            "write_succeeded": write_succeeded,
+            "safe_to_retry": not write_executed,
         })
 
     def portal_apply(self, *, profile: str, request: PortalApplyRequest) -> JSONObject:
@@ -10536,15 +11481,6 @@ class AiBuilderFacade:
             if package_add_outcome.block is not None:
                 return package_add_outcome.block
             permission_outcomes.append(package_add_outcome)
-            package_edit_outcome = self._guard_package_permission(
-                profile=profile,
-                tag_id=target_package_tag_id,
-                required_permission="edit_app",
-                normalized_args=normalized_args,
-            )
-            if package_edit_outcome.block is not None:
-                return package_edit_outcome.block
-            permission_outcomes.append(package_edit_outcome)
         if not sections_requested:
             unsupported_base_only_keys: list[str] = []
             if request.hide_copyright is not None:
@@ -10564,6 +11500,10 @@ class AiBuilderFacade:
                     },
                     suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
                 )
+        write_executed = False
+        draft_readback_error: JSONObject | None = None
+        live_readback_error: JSONObject | None = None
+        update_payload: dict[str, Any] = {}
         try:
             layout_diagnostics: dict[str, Any] = _empty_portal_layout_diagnostics()
             if creating:
@@ -10579,6 +11519,7 @@ class AiBuilderFacade:
                     base_payload=None,
                 )
                 create_result = self.portals.portal_create(profile=profile, payload=create_payload)
+                write_executed = True
                 created = create_result.get("result") if isinstance(create_result.get("result"), dict) else {}
                 dash_key = str(created.get("dashKey") or "")
                 if not dash_key:
@@ -10589,7 +11530,15 @@ class AiBuilderFacade:
                         details={"create_result": created},
                         suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
                     )
-                base_payload = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") or {}
+                try:
+                    base_payload = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") or {}
+                except (QingflowApiError, RuntimeError) as read_error:
+                    api_read_error = _coerce_api_error(read_error)
+                    draft_readback_error = {
+                        "phase": "created_portal_draft_readback",
+                        "transport_error": _transport_error_payload(api_read_error),
+                    }
+                    base_payload = {}
             update_payload = _build_public_portal_base_payload(
                 dash_name=request.dash_name or str(base_payload.get("dashName") or "").strip() or "未命名门户",
                 package_tag_id=target_package_tag_id,
@@ -10610,6 +11559,7 @@ class AiBuilderFacade:
                 layout_diagnostics = _portal_layout_diagnostics(request.sections, component_payload)
                 update_payload["components"] = component_payload
                 self.portals.portal_update(profile=profile, dash_key=dash_key, payload=update_payload)
+                write_executed = True
             self.portals.portal_update_base_info(
                 profile=profile,
                 dash_key=dash_key,
@@ -10620,9 +11570,70 @@ class AiBuilderFacade:
                     "tags": deepcopy(update_payload.get("tags") or []),
                 },
             )
-            draft_result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") or {}
+            write_executed = True
+            try:
+                draft_result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") or {}
+            except (QingflowApiError, RuntimeError) as read_error:
+                api_read_error = _coerce_api_error(read_error)
+                draft_readback_error = {
+                    "phase": "portal_draft_readback",
+                    "transport_error": _transport_error_payload(api_read_error),
+                }
+                draft_result = {}
         except (QingflowApiError, RuntimeError, ValueError) as error:
             api_error = _coerce_api_error(error) if not isinstance(error, ValueError) else None
+            if write_executed:
+                transport_error = _transport_error_payload(api_error) if api_error is not None else None
+                warning = _warning(
+                    "PORTAL_WRITE_INCOMPLETE_AFTER_PARTIAL_WRITE",
+                    "one or more portal write steps executed before a later write step failed",
+                )
+                if transport_error is not None:
+                    for key in ("backend_code", "http_status", "request_id"):
+                        if transport_error.get(key) is not None:
+                            warning[key] = transport_error.get(key)
+                return finalize({
+                    "status": "partial_success",
+                    "error_code": "PORTAL_APPLY_PARTIAL",
+                    "recoverable": True,
+                    "message": "some portal write steps executed; a later portal write step failed",
+                    "normalized_args": normalized_args,
+                    "missing_fields": [],
+                    "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"]},
+                    "details": {
+                        "dash_key": dash_key or None,
+                        "write_error": (
+                            {"message": api_error.message, "transport_error": transport_error}
+                            if api_error is not None
+                            else {"message": str(error)}
+                        ),
+                    },
+                    "request_id": api_error.request_id if api_error else None,
+                    "backend_code": api_error.backend_code if api_error else None,
+                    "http_status": None if api_error is None or api_error.http_status == 404 else api_error.http_status,
+                    "suggested_next_call": {"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key}},
+                    "noop": False,
+                    "warnings": [warning],
+                    "verification": {
+                        "draft_verified": False,
+                        "draft_metadata_verified": False,
+                        "live_verified": None,
+                        "live_metadata_verified": None,
+                        "published": False,
+                        "publish_failed": False,
+                        "write_incomplete": True,
+                        "readback_unavailable": False,
+                        "metadata_unverified": True,
+                    },
+                    "dash_key": dash_key,
+                    "dash_name": update_payload.get("dashName") if isinstance(update_payload, dict) else None,
+                    "package_id": target_package_tag_id,
+                    "created": creating,
+                    "published": False,
+                    "verified": False,
+                    "write_executed": True,
+                    "safe_to_retry": False,
+                })
             return _failed(
                 "PORTAL_APPLY_FAILED",
                 _public_error_message("PORTAL_APPLY_FAILED", api_error) if api_error else str(error),
@@ -10637,19 +11648,35 @@ class AiBuilderFacade:
         live_result: dict[str, Any] | None = None
         published = False
         publish_failed = False
+        publish_error: JSONObject | None = None
         if request.publish:
             try:
                 self.portals.portal_publish(profile=profile, dash_key=dash_key)
                 published = True
-                live_result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=False).get("result") or {}
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
                 publish_failed = True
+                publish_error = {
+                    "message": api_error.message,
+                    "transport_error": _transport_error_payload(api_error),
+                }
+            if published:
+                try:
+                    live_result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=False).get("result") or {}
+                except (QingflowApiError, RuntimeError) as read_error:
+                    api_read_error = _coerce_api_error(read_error)
+                    live_readback_error = {
+                        "phase": "portal_live_readback",
+                        "transport_error": _transport_error_payload(api_read_error),
+                    }
 
         draft_components = draft_result.get("components") if isinstance(draft_result, dict) else None
         expected_count = len(request.sections) if sections_requested else None
         draft_verified = isinstance(draft_result, dict) and (
             expected_count is None or (isinstance(draft_components, list) and len(draft_components) == expected_count)
         )
+        if draft_readback_error is not None:
+            draft_verified = False
         draft_meta_verified, draft_meta_mismatches = _verify_portal_readback(
             actual=draft_result,
             expected_payload=update_payload,
@@ -10677,6 +11704,8 @@ class AiBuilderFacade:
                     )
                 )
             )
+            if live_readback_error is not None:
+                live_verified = False
             live_meta_verified, live_meta_mismatches = _verify_portal_readback(
                 actual=live_result,
                 expected_payload=update_payload,
@@ -10710,6 +11739,23 @@ class AiBuilderFacade:
             live_meta_verified=live_meta_verified,
             publish_requested=request.publish,
         )
+        details_payload = {
+            "verification_mismatches": {
+                "draft": draft_meta_mismatches,
+                "live": live_meta_mismatches,
+            },
+            **({"publish_error": publish_error} if publish_error is not None else {}),
+            **({"draft_readback_error": draft_readback_error} if draft_readback_error is not None else {}),
+            **({"live_readback_error": live_readback_error} if live_readback_error is not None else {}),
+        }
+        readback_transport_error = _readback_transport_error_from_details(details_payload)
+        if draft_readback_error is not None or live_readback_error is not None:
+            warning = _warning("READBACK_UNAVAILABLE_AFTER_WRITE", "write was executed but portal readback is unavailable")
+            if readback_transport_error is not None:
+                for key in ("backend_code", "http_status", "request_id"):
+                    if readback_transport_error.get(key) is not None:
+                        warning[key] = readback_transport_error.get(key)
+            warnings.append(warning)
         warnings.extend(_portal_layout_warning_items(layout_diagnostics))
         return finalize({
             "status": status,
@@ -10727,13 +11773,10 @@ class AiBuilderFacade:
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"]},
-            "details": {
-                "verification_mismatches": {
-                    "draft": draft_meta_mismatches,
-                    "live": live_meta_mismatches,
-                }
-            },
-            "request_id": None,
+            "details": details_payload,
+            "request_id": (readback_transport_error or {}).get("request_id"),
+            "backend_code": (readback_transport_error or {}).get("backend_code"),
+            "http_status": (readback_transport_error or {}).get("http_status"),
             "suggested_next_call": None if verified else {"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
             "noop": False,
             "warnings": warnings,
@@ -10745,6 +11788,8 @@ class AiBuilderFacade:
                 "live_metadata_verified": live_meta_verified,
                 "published": published,
                 "publish_failed": publish_failed,
+                "readback_unavailable": draft_readback_error is not None or live_readback_error is not None,
+                "metadata_unverified": draft_readback_error is not None or live_readback_error is not None,
             },
             "dash_key": dash_key,
             "dash_name": update_payload.get("dashName"),
@@ -10752,6 +11797,8 @@ class AiBuilderFacade:
             "created": creating,
             "published": published,
             "verified": verified,
+            "write_executed": write_executed or published,
+            "safe_to_retry": not (write_executed or published),
             "draft_result": draft_result,
             "live_result": live_result,
         })
@@ -10759,7 +11806,17 @@ class AiBuilderFacade:
     def _publish_current_edit_version(self, *, profile: str, app_key: str, edit_version_no: int | None = None) -> JSONObject:
         normalized_args = {"app_key": app_key}
         if edit_version_no is None:
-            version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+            try:
+                version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                return _failed_from_api_error(
+                    "PUBLISH_PRECHECK_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details={"app_key": app_key, "phase": "prepare_publish_edit_version"},
+                    suggested_next_call={"tool_name": "app_publish_verify", "arguments": {"profile": profile, "app_key": app_key}},
+                )
             edit_version_no = _coerce_positive_int(version_result.get("editVersionNo") or version_result.get("versionNo")) or 1
         try:
             self.apps.app_publish(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
@@ -10893,6 +11950,7 @@ class AiBuilderFacade:
             response["status"] = "partial_success"
             response["error_code"] = response.get("error_code") or publish_result.get("error_code")
             response["recoverable"] = True
+            response["verified"] = False
             response["message"] = f"{response.get('message') or 'apply succeeded'}; publish failed"
             if not response.get("suggested_next_call"):
                 response["suggested_next_call"] = publish_result.get("suggested_next_call")
@@ -10981,7 +12039,8 @@ class AiBuilderFacade:
         app_key: str,
         tolerate_404: bool,
         tolerate_permission_restricted: bool = False,
-    ) -> tuple[Any, bool]:
+        include_error: bool = False,
+    ) -> tuple[Any, bool] | tuple[Any, bool, QingflowApiError | None]:
         try:
             views = self.views.view_list_flat(profile=profile, app_key=app_key)
         except (QingflowApiError, RuntimeError) as error:
@@ -11003,18 +12062,19 @@ class AiBuilderFacade:
                             )
                         )
                     ):
-                        return [], True
+                        return ([], True, legacy_api_error) if include_error else ([], True)
                     raise
                 legacy_result = legacy_views.get("result")
                 if _is_view_collection_shape(legacy_result):
-                    return _normalize_view_collection(legacy_result), False
+                    result = _normalize_view_collection(legacy_result)
+                    return (result, False, api_error) if include_error else (result, False)
                 if tolerate_404:
-                    return [], True
+                    return ([], True, api_error) if include_error else ([], True)
                 raise error
             raise
         normalized_views = _normalize_view_collection(views.get("result"))
         if normalized_views:
-            return normalized_views, False
+            return (normalized_views, False, None) if include_error else (normalized_views, False)
         try:
             legacy_views = self.views.view_list(profile=profile, app_key=app_key)
         except (QingflowApiError, RuntimeError) as legacy_error:
@@ -11029,11 +12089,12 @@ class AiBuilderFacade:
                     )
                 )
             ):
-                return normalized_views, False
+                return (normalized_views, False, legacy_api_error) if include_error else (normalized_views, False)
             raise
         legacy_result = legacy_views.get("result")
         legacy_normalized = _normalize_view_collection(legacy_result)
-        return legacy_normalized or normalized_views, False
+        result = legacy_normalized or normalized_views
+        return (result, False, None) if include_error else (result, False)
 
     def _load_workflow_result(
         self,
@@ -11042,7 +12103,8 @@ class AiBuilderFacade:
         app_key: str,
         tolerate_404: bool,
         tolerate_permission_restricted: bool = False,
-    ) -> tuple[Any, bool]:
+        include_error: bool = False,
+    ) -> tuple[Any, bool] | tuple[Any, bool, QingflowApiError | None]:
         try:
             workflow = self.workflows.workflow_list_nodes(profile=profile, app_key=app_key)
         except (QingflowApiError, RuntimeError) as error:
@@ -11051,9 +12113,10 @@ class AiBuilderFacade:
                 api_error.http_status == 404
                 or (tolerate_permission_restricted and _is_permission_restricted_api_error(api_error))
             ):
-                return [], True
+                return ([], True, api_error) if include_error else ([], True)
             raise
-        return workflow.get("result"), False
+        result = workflow.get("result")
+        return (result, False, None) if include_error else (result, False)
 
     def _load_app_state(self, *, profile: str, app_key: str) -> dict[str, Any]:
         state = self._load_base_schema_state(profile=profile, app_key=app_key)
@@ -12206,10 +13269,11 @@ def _resolve_custom_button_view_button_ref(
     button_inventory: dict[int, dict[str, Any]],
     valid_custom_button_ids: set[int],
     reason_path: str,
+    allow_unverified_numeric_id: bool = False,
 ) -> tuple[int | None, dict[str, Any] | None]:
     explicit_id = _coerce_positive_int(button_ref)
     if explicit_id is not None:
-        if explicit_id in valid_custom_button_ids:
+        if explicit_id in valid_custom_button_ids or allow_unverified_numeric_id:
             return explicit_id, None
         return None, {
             "error_code": "UNKNOWN_CUSTOM_BUTTON",
@@ -12486,11 +13550,16 @@ def _failed_from_api_error(
     suggested_next_call: JSONObject | None = None,
     recoverable: bool = True,
 ) -> JSONObject:
-    effective_error_code = "APP_EDIT_LOCKED" if error.backend_code == 40074 else error_code
+    if is_auth_like_error(error):
+        effective_error_code = "AUTH_REQUIRED"
+    elif backend_code_int(error) == 40074:
+        effective_error_code = "APP_EDIT_LOCKED"
+    else:
+        effective_error_code = error_code
     public_message = _public_error_message(effective_error_code, error)
     public_http_status = None if error.http_status == 404 else error.http_status
     merged_details = dict(details or {})
-    if error.backend_code == 40074:
+    if backend_code_int(error) == 40074:
         owner = _extract_edit_lock_owner(error.message)
         merged_details.setdefault("lock_owner_name", owner.get("lock_owner_name"))
         merged_details.setdefault("lock_owner_email", owner.get("lock_owner_email"))
@@ -12532,6 +13601,91 @@ def _failed_from_api_error(
     )
 
 
+def _post_write_readback_pending_result(
+    *,
+    error_code: str,
+    message: str,
+    normalized_args: JSONObject | None = None,
+    details: JSONObject | None = None,
+    suggested_next_call: JSONObject | None = None,
+    request_id: str | None = None,
+    backend_code: Any = None,
+    http_status: int | None = None,
+) -> JSONObject:
+    effective_details = details or {}
+    transport_error = _readback_transport_error_from_details(effective_details)
+    effective_backend_code = backend_code if backend_code is not None else (transport_error or {}).get("backend_code")
+    effective_http_status = http_status if http_status is not None else (transport_error or {}).get("http_status")
+    effective_request_id = request_id if request_id is not None else (transport_error or {}).get("request_id")
+    warning = _warning("READBACK_UNAVAILABLE_AFTER_WRITE", "write was executed but post-write readback is unavailable")
+    for key, value in (
+        ("backend_code", effective_backend_code),
+        ("http_status", effective_http_status),
+        ("request_id", effective_request_id),
+    ):
+        if value is not None:
+            warning[key] = value
+    return {
+        "status": "partial_success",
+        "error_code": error_code,
+        "recoverable": True,
+        "message": message,
+        "normalized_args": normalized_args or {},
+        "missing_fields": [],
+        "allowed_values": {},
+        "details": effective_details,
+        "suggested_next_call": suggested_next_call,
+        "request_id": effective_request_id,
+        "backend_code": effective_backend_code,
+        "http_status": effective_http_status,
+        "noop": False,
+        "warnings": [warning],
+        "verification": {
+            "readback_unavailable": True,
+            "metadata_unverified": True,
+        },
+        "verified": False,
+        "write_executed": True,
+        "write_succeeded": True,
+        "safe_to_retry": False,
+    }
+
+
+def _readback_transport_error_from_details(details: JSONObject) -> JSONObject | None:
+    direct = details.get("transport_error")
+    if isinstance(direct, dict):
+        return direct
+    for key in (
+        "readback_error",
+        "verification_error",
+        "draft_readback_error",
+        "live_readback_error",
+        "state_read_blocked",
+    ):
+        value = details.get(key)
+        if isinstance(value, dict) and isinstance(value.get("transport_error"), dict):
+            return value.get("transport_error")
+    verification_result = details.get("verification_result")
+    if isinstance(verification_result, dict):
+        verification_details = verification_result.get("details")
+        if isinstance(verification_details, dict):
+            nested = verification_details.get("transport_error")
+            if isinstance(nested, dict):
+                payload = dict(nested)
+                for key in ("backend_code", "http_status", "request_id", "category"):
+                    if payload.get(key) is None and verification_result.get(key) is not None:
+                        payload[key] = verification_result.get(key)
+                return payload
+        payload = {
+            key: verification_result.get(key)
+            for key in ("backend_code", "http_status", "request_id", "category")
+            if verification_result.get(key) is not None
+        }
+        if payload:
+            return payload
+    return None
+
+
 def _transport_error_payload(error: QingflowApiError) -> JSONObject:
     return {
         "http_status": error.http_status,
@@ -12542,7 +13696,30 @@ def _transport_error_payload(error: QingflowApiError) -> JSONObject:
 
 
 def _is_permission_restricted_api_error(error: QingflowApiError) -> bool:
-    return error.backend_code in {40002, 40027}
+    if is_auth_like_error(error):
+        return False
+    return backend_code_int(error) in {40002, 40027}
+
+
+def _is_optional_builder_lookup_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    return backend_code_int(error) in {40002, 40027, 404} or error.http_status == 404
+
+
+def _search_permission_blocked_from_warnings(payload: JSONObject) -> JSONObject | None:
+    warnings = payload.get("warnings")
+    if not isinstance(warnings, list):
+        return None
+    for item in warnings:
+        if not isinstance(item, dict) or item.get("code") != "APP_SEARCH_FALLBACK_VISIBLE_APPS":
+            continue
+        return {
+            "backend_code": item.get("backend_code"),
+            "http_status": item.get("http_status"),
+            "request_id": item.get("request_id"),
+        }
+    return None
 
 
 def _append_response_detail(details: JSONObject, *, key: str, value: Any) -> None:
@@ -12743,7 +13920,7 @@ def _coerce_api_error(error: Exception) -> QingflowApiError:
 
 
 def _public_error_message(error_code: str, error: QingflowApiError) -> str:
-    if error.backend_code == 40074 or error_code == "APP_EDIT_LOCKED":
+    if backend_code_int(error) == 40074 or error_code == "APP_EDIT_LOCKED":
         owner = _extract_edit_lock_owner(error.message)
         owner_label = owner.get("lock_owner_email") or owner.get("lock_owner_name")
         if owner_label:
@@ -12777,7 +13954,9 @@ def _chart_delete_readback_is_not_found(error: QingflowApiError) -> bool:
 
 
 def _delete_readback_is_not_found(error: QingflowApiError) -> bool:
-    backend_code = int(error.backend_code or 0) if str(error.backend_code or "").isdigit() else error.backend_code
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
     if error.http_status == 404 or backend_code in {404, 40038, 81007}:
         return True
     message = str(error.message or "").lower()
@@ -13619,7 +14798,7 @@ def _explain_chart_backend_validation_error(
     chart_type: str,
     payload: dict[str, Any] | None,
 ) -> dict[str, Any] | None:
-    backend_code = api_error.backend_code
+    backend_code = backend_code_int(api_error)
     if backend_code not in {81002, 81005}:
         return None
     chart_type = str(chart_type or (payload or {}).get("chartType") or "").strip().lower()
@@ -14902,7 +16081,9 @@ def _department_scope_equal(left: Any, right: Any) -> bool:
 
 
 def _is_relation_target_metadata_read_restricted_api_error(error: QingflowApiError) -> bool:
-    return error.backend_code in {40002, 40027, 40161}
+    if is_auth_like_error(error):
+        return False
+    return backend_code_int(error) in {40002, 40027, 40161}
 
 
 def _relation_target_field_matches(left: dict[str, Any], right: dict[str, Any]) -> bool:
@@ -20781,8 +21962,13 @@ def _serialize_view_button_binding(
     binding: ViewButtonBindingPatch,
     current_fields_by_name: dict[str, dict[str, Any]],
     valid_custom_button_ids: set[int],
+    allow_unverified_custom_button_id: bool = False,
 ) -> tuple[dict[str, Any], list[dict[str, Any]]]:
-    if binding.button_type == PublicViewButtonType.custom and binding.button_id not in valid_custom_button_ids:
+    if (
+        binding.button_type == PublicViewButtonType.custom
+        and binding.button_id not in valid_custom_button_ids
+        and not allow_unverified_custom_button_id
+    ):
         return {}, [
             {
                 "error_code": "UNKNOWN_CUSTOM_BUTTON",
@@ -22087,6 +23273,20 @@ def _associated_resource_patch_has_match_config(patch: AssociatedResourceUpsertP
     return bool(patch.match_mappings) or bool(patch.match_rules) or "match_mappings" in fields_set
 
 
+def _extract_associated_resource_id_from_result(result: Any) -> int | None:
+    if isinstance(result, dict):
+        for key in ("associated_item_id", "associatedItemId", "asosChartId", "id"):
+            item_id = _coerce_positive_int(result.get(key))
+            if item_id is not None:
+                return item_id
+        nested = result.get("result") or result.get("data")
+        if nested is not None and nested is not result:
+            return _extract_associated_resource_id_from_result(nested)
+    if isinstance(result, list) and len(result) == 1:
+        return _extract_associated_resource_id_from_result(result[0])
+    return None
+
+
 def _serialize_associated_resource_match_rules(match_rules: list[Any]) -> list[list[dict[str, Any]]]:
     if not match_rules:
         return []