@josephyan/qingflow-cli 0.2.0-beta.59 → 0.2.0-beta.60

package/src/qingflow_mcp/builder_facade/service.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from copy import deepcopy
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 import json
 import os
 import re
@@ -129,6 +129,14 @@ class ResolvedApp:
     tag_ids: list[int]
 
 
+@dataclass(slots=True)
+class PermissionCheckOutcome:
+    block: JSONObject | None = None
+    warnings: list[dict[str, Any]] = field(default_factory=list)
+    details: JSONObject = field(default_factory=dict)
+    verification: JSONObject = field(default_factory=dict)
+
+
 class AiBuilderFacade:
     def __init__(
         self,
@@ -804,21 +812,53 @@ class AiBuilderFacade:
         app_key: str,
         app_title: str = "",
     ) -> JSONObject:
+        normalized_args = {"tag_id": tag_id, "app_key": app_key, "app_title": app_title}
         if _coerce_positive_int(tag_id) is None:
             return _failed("TAG_ID_REQUIRED", "tag_id must be positive", suggested_next_call=None)
-        package_permission_block = self._guard_package_permission(
+        permission_outcomes: list[PermissionCheckOutcome] = []
+        package_permission_outcome = self._guard_package_permission(
             profile=profile,
             tag_id=tag_id,
             required_permission="edit_app",
-            normalized_args={"tag_id": tag_id, "app_key": app_key, "app_title": app_title},
+            normalized_args=normalized_args,
         )
-        if package_permission_block is not None:
-            return package_permission_block
+        if package_permission_outcome.block is not None:
+            return package_permission_outcome.block
+        permission_outcomes.append(package_permission_outcome)
+
+        def finalize(response: JSONObject) -> JSONObject:
+            return _apply_permission_outcomes(response, *permission_outcomes)
+
         resolved = self.app_resolve(profile=profile, app_key=app_key)
         if resolved.get("status") == "failed":
-            return resolved
-        base_before = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
-        tag_ids_before = _coerce_int_list(base_before.get("tagIds"))
+            return finalize(resolved)
+        resolved_outcome = _permission_outcome_from_result(resolved)
+        if resolved_outcome is not None:
+            permission_outcomes.append(resolved_outcome)
+        try:
+            base_before = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
+            tag_ids_before = _coerce_int_list(base_before.get("tagIds"))
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            tag_ids_before = []
+            if _is_permission_restricted_api_error(api_error):
+                permission_outcomes.append(
+                    _verification_read_outcome(
+                        resource="app",
+                        target={"app_key": app_key},
+                        transport_error=api_error,
+                    )
+                )
+            else:
+                return finalize(
+                    _failed_from_api_error(
+                        "PACKAGE_ATTACH_FAILED",
+                        api_error,
+                        normalized_args=normalized_args,
+                        details={"tag_id": tag_id, "app_key": app_key},
+                        suggested_next_call={"tool_name": "package_attach_app", "arguments": {"profile": profile, "tag_id": tag_id, "app_key": app_key}},
+                    )
+                )
         already_attached = tag_id in tag_ids_before
         try:
             self._attach_app_to_package(
@@ -829,33 +869,72 @@ class AiBuilderFacade:
             )
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            return _failed_from_api_error(
-                "PACKAGE_ATTACH_FAILED",
-                api_error,
-                details={"tag_id": tag_id, "app_key": app_key},
-                suggested_next_call={"tool_name": "package_attach_app", "arguments": {"profile": profile, "tag_id": tag_id, "app_key": app_key}},
+            return finalize(
+                _failed_from_api_error(
+                    "PACKAGE_ATTACH_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details=_with_state_read_blocked_details(
+                        {"tag_id": tag_id, "app_key": app_key},
+                        resource="package",
+                        error=api_error,
+                    ),
+                    suggested_next_call={"tool_name": "package_attach_app", "arguments": {"profile": profile, "tag_id": tag_id, "app_key": app_key}},
+                )
             )
-        base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
-        tag_ids_after = _coerce_int_list(base.get("tagIds"))
-        attached = tag_id in tag_ids_after
-        return {
+        verification_error: QingflowApiError | None = None
+        try:
+            base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
+            tag_ids_after = _coerce_int_list(base.get("tagIds"))
+            attached = tag_id in tag_ids_after
+        except (QingflowApiError, RuntimeError) as error:
+            verification_error = _coerce_api_error(error)
+            tag_ids_after = []
+            attached = False
+            if _is_permission_restricted_api_error(verification_error):
+                permission_outcomes.append(
+                    _verification_read_outcome(
+                        resource="app",
+                        target={"app_key": app_key},
+                        transport_error=verification_error,
+                    )
+                )
+            else:
+                return finalize(
+                    _failed_from_api_error(
+                        "PACKAGE_ATTACH_FAILED",
+                        verification_error,
+                        normalized_args=normalized_args,
+                        details={"tag_id": tag_id, "app_key": app_key},
+                        suggested_next_call={"tool_name": "package_attach_app", "arguments": {"profile": profile, "tag_id": tag_id, "app_key": app_key}},
+                    )
+                )
+        response = {
             "status": "success" if attached else "partial_success",
-            "error_code": None,
-            "recoverable": False,
-            "message": "attached app to package" if attached else "app attachment could not be verified",
-            "normalized_args": {"tag_id": tag_id, "app_key": app_key, "app_title": app_title},
+            "error_code": None if attached else "PACKAGE_ATTACH_READBACK_PENDING",
+            "recoverable": verification_error is not None or not attached,
+            "message": "attached app to package" if attached else "app attachment could not be fully verified",
+            "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {},
             "details": {},
-            "request_id": None,
+            "request_id": verification_error.request_id if verification_error is not None else None,
             "suggested_next_call": None if attached else {"tool_name": "package_attach_app", "arguments": {"profile": profile, "tag_id": tag_id, "app_key": app_key}},
             "noop": already_attached,
-            "verification": {"tag_ids_before": tag_ids_before, "tag_ids_after": tag_ids_after},
+            "verification": {
+                "tag_ids_before": tag_ids_before,
+                "tag_ids_after": tag_ids_after,
+                "attachment_verified": attached if verification_error is None else None,
+                "readback_unavailable": verification_error is not None,
+            },
             "app_key": app_key,
             "tag_id": tag_id,
             "tag_ids_after": tag_ids_after,
             "attached": attached,
         }
+        if verification_error is not None:
+            response["details"]["verification_error"] = _transport_error_payload(verification_error)
+        return finalize(response)
 
     def app_release_edit_lock_if_mine(
         self,
@@ -979,6 +1058,42 @@ class AiBuilderFacade:
                 base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True)
             except (QingflowApiError, RuntimeError) as exc:
                 api_error = _coerce_api_error(exc)
+                if _is_permission_restricted_api_error(api_error):
+                    return {
+                        "status": "success",
+                        "error_code": None,
+                        "recoverable": False,
+                        "message": "resolved app key; metadata unverified",
+                        "normalized_args": {"app_key": app_key},
+                        "missing_fields": [],
+                        "allowed_values": {},
+                        "details": {
+                            "match_scope": "app_key",
+                            "lookup_permission_blocked": {
+                                "scope": "app",
+                                "target": {"app_key": app_key},
+                                "required_permission": None,
+                                "transport_error": _transport_error_payload(api_error),
+                            },
+                            "permission_check_skipped": True,
+                        },
+                        "request_id": api_error.request_id,
+                        "suggested_next_call": {"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+                        "noop": False,
+                        "warnings": [
+                            _warning(
+                                "PERMISSION_CHECK_SKIPPED",
+                                "app metadata lookup was permission-restricted; continuing with explicit app_key",
+                                scope="app",
+                                app_key=app_key,
+                            )
+                        ],
+                        "verification": {"metadata_unverified": True},
+                        "app_key": app_key,
+                        "app_name": app_key,
+                        "tag_ids": [],
+                        "publish_status": None,
+                    }
                 return _failed_from_api_error(
                     "APP_NOT_FOUND" if api_error.http_status == 404 else "APP_RESOLVE_FAILED",
                     api_error,
@@ -1285,67 +1400,73 @@ class AiBuilderFacade:
         app_key: str,
         required_permission: str,
         normalized_args: JSONObject,
-    ) -> JSONObject | 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)
-            return _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 _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_read_summary", "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_read_summary", "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",
         }.get(required_permission)
         if permission_key is None:
-            return None
+            return PermissionCheckOutcome()
         permission_value = permission_summary.get(permission_key)
         if permission_value is None:
-            return _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_summary": permission_summary,
-                },
-                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            return _permission_skip_outcome(
+                scope="app",
+                target={"app_key": app_key},
+                required_permission=required_permission,
+                permission_summary=permission_summary,
             )
         if permission_value is not False:
-            return None
+            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"
         )
-        return _failed(
-            error_code,
-            message,
-            normalized_args=normalized_args,
-            details={
-                "app_key": app_key,
-                "required_permission": required_permission,
-                "permission_summary": permission_summary,
-            },
-            suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+        return PermissionCheckOutcome(
+            block=_failed(
+                error_code,
+                message,
+                normalized_args=normalized_args,
+                details={
+                    "app_key": app_key,
+                    "required_permission": required_permission,
+                    "permission_summary": permission_summary,
+                },
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         )
 
     def _guard_package_permission(
@@ -1355,29 +1476,38 @@ class AiBuilderFacade:
         tag_id: int,
         required_permission: str,
         normalized_args: JSONObject,
-    ) -> JSONObject | None:
+    ) -> PermissionCheckOutcome:
         try:
             permission_summary = self._read_package_permission_summary(profile=profile, tag_id=tag_id)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            return _failed(
-                "PACKAGE_PERMISSION_UNVERIFIED",
-                "could not confirm current user's builder permissions for this package",
-                normalized_args=normalized_args,
-                details={
-                    "tag_id": tag_id,
-                    "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 _is_permission_restricted_api_error(api_error):
+                return _permission_skip_outcome(
+                    scope="package",
+                    target={"tag_id": tag_id},
+                    required_permission=required_permission,
+                    transport_error=_transport_error_payload(api_error),
+                )
+            return PermissionCheckOutcome(
+                block=_failed(
+                    "PACKAGE_PERMISSION_UNVERIFIED",
+                    "could not confirm current user's builder permissions for this package",
+                    normalized_args=normalized_args,
+                    details={
+                        "tag_id": tag_id,
+                        "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": "package_get_base", "arguments": {"profile": profile, "tag_id": tag_id}},
-                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": "package_get_base", "arguments": {"profile": profile, "tag_id": tag_id}},
+                    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_specs = {
             "add_app": (
@@ -1398,12 +1528,21 @@ class AiBuilderFacade:
         }
         permission_key, error_code, message = permission_specs.get(required_permission, (None, None, None))
         if permission_key is None:
-            return None
+            return PermissionCheckOutcome()
         permission_value = permission_summary.get(permission_key)
         if permission_value is None:
-            return _failed(
-                "PACKAGE_PERMISSION_UNVERIFIED",
-                "could not confirm current user's builder permissions for this package",
+            return _permission_skip_outcome(
+                scope="package",
+                target={"tag_id": tag_id},
+                required_permission=required_permission,
+                permission_summary=permission_summary,
+            )
+        if permission_value is not False:
+            return PermissionCheckOutcome()
+        return PermissionCheckOutcome(
+            block=_failed(
+                error_code or "PACKAGE_PERMISSION_UNVERIFIED",
+                message or "current user does not have the required package permission",
                 normalized_args=normalized_args,
                 details={
                     "tag_id": tag_id,
@@ -1412,18 +1551,6 @@ class AiBuilderFacade:
                 },
                 suggested_next_call={"tool_name": "package_get_base", "arguments": {"profile": profile, "tag_id": tag_id}},
             )
-        if permission_value is not False:
-            return None
-        return _failed(
-            error_code or "PACKAGE_PERMISSION_UNVERIFIED",
-            message or "current user does not have the required package permission",
-            normalized_args=normalized_args,
-            details={
-                "tag_id": tag_id,
-                "required_permission": required_permission,
-                "permission_summary": permission_summary,
-            },
-            suggested_next_call={"tool_name": "package_get_base", "arguments": {"profile": profile, "tag_id": tag_id}},
         )
 
     def _guard_portal_permission(
@@ -1433,25 +1560,26 @@ class AiBuilderFacade:
         dash_key: str,
         normalized_args: JSONObject,
         portal_result: dict[str, Any],
-    ) -> JSONObject | None:
+    ) -> PermissionCheckOutcome:
         permission_summary = self._read_portal_permission_summary(dash_key=dash_key, portal_result=portal_result)
         permission_value = permission_summary.get("can_edit_portal")
         if permission_value is None:
-            return _failed(
-                "PORTAL_PERMISSION_UNVERIFIED",
-                "could not confirm current user's builder permissions for this portal",
+            return _permission_skip_outcome(
+                scope="portal",
+                target={"dash_key": dash_key},
+                required_permission="edit_portal",
+                permission_summary=permission_summary,
+            )
+        if permission_value is not False:
+            return PermissionCheckOutcome()
+        return PermissionCheckOutcome(
+            block=_failed(
+                "PORTAL_EDIT_UNAUTHORIZED",
+                "current user does not have builder edit permission on this portal",
                 normalized_args=normalized_args,
                 details={"dash_key": dash_key, "permission_summary": permission_summary},
                 suggested_next_call={"tool_name": "portal_read_summary", "arguments": {"profile": profile, "dash_key": dash_key}},
             )
-        if permission_value is not False:
-            return None
-        return _failed(
-            "PORTAL_EDIT_UNAUTHORIZED",
-            "current user does not have builder edit permission on this portal",
-            normalized_args=normalized_args,
-            details={"dash_key": dash_key, "permission_summary": permission_summary},
-            suggested_next_call={"tool_name": "portal_read_summary", "arguments": {"profile": profile, "dash_key": dash_key}},
         )
 
     def app_read_summary(self, *, profile: str, app_key: str) -> JSONObject:
@@ -2226,6 +2354,7 @@ class AiBuilderFacade:
             "update_fields": [patch.model_dump(mode="json") for patch in update_fields],
             "remove_fields": [patch.model_dump(mode="json") for patch in remove_fields],
         }
+        permission_outcomes: list[PermissionCheckOutcome] = []
         requested_field_changes = bool(add_fields or update_fields or remove_fields)
         resolved: JSONObject
         if app_key:
@@ -2234,31 +2363,37 @@ class AiBuilderFacade:
             resolved = self.app_resolve(profile=profile, app_name=app_name, package_tag_id=package_tag_id)
         else:
             return _failed("APP_NAME_REQUIRED", "app_name or app_key is required", normalized_args=normalized_args, suggested_next_call=None)
+
+        def finalize(response: JSONObject) -> JSONObject:
+            return _apply_permission_outcomes(response, *permission_outcomes)
+
         if resolved.get("status") == "failed":
             if not isinstance(resolved.get("normalized_args"), dict) or not resolved.get("normalized_args"):
                 resolved["normalized_args"] = normalized_args
             if not create_if_missing or app_key or resolved.get("error_code") != "APP_NOT_FOUND":
-                return resolved
+                return finalize(resolved)
             permission_tag_id = _coerce_positive_int(package_tag_id)
             if permission_tag_id is None:
                 permission_tag_id = 0
-            add_permission_block = self._guard_package_permission(
+            add_permission_outcome = self._guard_package_permission(
                 profile=profile,
                 tag_id=permission_tag_id,
                 required_permission="add_app",
                 normalized_args=normalized_args,
             )
-            if add_permission_block is not None:
-                return add_permission_block
+            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_block = self._guard_package_permission(
+                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_block is not None:
-                    return edit_permission_block
+                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,
@@ -2267,23 +2402,27 @@ class AiBuilderFacade:
             if resolved.get("status") == "failed":
                 if not isinstance(resolved.get("normalized_args"), dict) or not resolved.get("normalized_args"):
                     resolved["normalized_args"] = normalized_args
-                return resolved
+                return finalize(resolved)
+        resolved_outcome = _permission_outcome_from_result(resolved)
+        if resolved_outcome is not None:
+            permission_outcomes.append(resolved_outcome)
         target = ResolvedApp(
             app_key=str(resolved["app_key"]),
             app_name=str(resolved["app_name"]),
             tag_ids=_coerce_int_list(resolved.get("tag_ids")),
         )
         if not bool(resolved.get("created")):
-            permission_block = self._guard_app_permission(
+            permission_outcome = self._guard_app_permission(
                 profile=profile,
                 app_key=target.app_key,
                 required_permission="edit_app",
                 normalized_args=normalized_args,
             )
-            if permission_block is not None:
-                return permission_block
+            if permission_outcome.block is not None:
+                return permission_outcome.block
+            permission_outcomes.append(permission_outcome)
         if bool(resolved.get("created")) and not requested_field_changes:
-            return {
+            return finalize({
                 "status": "success",
                 "error_code": None,
                 "recoverable": False,
@@ -2310,21 +2449,21 @@ class AiBuilderFacade:
                 "package_attached": None if package_tag_id is None else package_tag_id in target.tag_ids,
                 "publish_requested": False,
                 "published": False,
-            }
+            })
         schema_readback_delayed = False
         try:
             schema_result, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=target.app_key)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
             if not bool(resolved.get("created")) or api_error.http_status != 404:
-                return _failed_from_api_error(
+                return finalize(_failed_from_api_error(
                     "SCHEMA_READBACK_FAILED",
                     api_error,
                     normalized_args=normalized_args,
                     allowed_values={"field_types": [item.value for item in PublicFieldType]},
-                    details={"app_key": target.app_key},
+                    details=_with_state_read_blocked_details({"app_key": target.app_key}, resource="schema", error=api_error),
                     suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": target.app_key}},
-                )
+                ))
             schema_result = _empty_schema_result(target.app_name)
             _schema_source = "synthetic_new_app"
             schema_readback_delayed = True
@@ -2442,7 +2581,7 @@ class AiBuilderFacade:
                 "package_attached": package_attached,
             }
             response["details"]["relation_field_count"] = relation_field_count
-            return self._append_publish_result(profile=profile, app_key=target.app_key, publish=publish, response=response)
+            return finalize(self._append_publish_result(profile=profile, app_key=target.app_key, publish=publish, response=response))
 
         payload = _build_form_payload_from_fields(
             title=schema_result.get("formTitle") or target.app_name,
@@ -2581,7 +2720,7 @@ class AiBuilderFacade:
                 "http_status": verification_error.http_status,
                 "backend_code": verification_error.backend_code,
             }
-        return response
+        return finalize(response)
 
     def app_layout_apply(
         self,
@@ -2599,25 +2738,31 @@ class AiBuilderFacade:
             "sections": requested_sections,
             "publish": publish,
         }
-        permission_block = self._guard_app_permission(
+        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_block is not None:
-            return permission_block
+        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)
+
         try:
             schema_result, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            return _failed_from_api_error(
+            return finalize(_failed_from_api_error(
                 "LAYOUT_READ_FAILED",
                 api_error,
                 normalized_args=normalized_args,
-                details={"app_key": app_key},
+                details=_with_state_read_blocked_details({"app_key": app_key}, resource="schema", error=api_error),
                 suggested_next_call={"tool_name": "app_read_layout_summary", "arguments": {"profile": profile, "app_key": app_key}},
-            )
+            ))
         parsed = _parse_schema(schema_result)
         current_fields = parsed["fields"]
         requested_sections, missing_selectors = _resolve_layout_sections_to_names(requested_sections, current_fields)
@@ -2709,7 +2854,7 @@ class AiBuilderFacade:
                 },
                 "verified": True,
             }
-            return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
+            return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
         payload = _build_form_payload_from_existing_schema(
             current_schema=schema_result,
             layout=target_layout,
@@ -2742,7 +2887,7 @@ class AiBuilderFacade:
                     fallback_applied = "flatten_sections"
                 except (QingflowApiError, RuntimeError) as fallback_error:
                     api_fallback_error = _coerce_api_error(fallback_error)
-                    return _failed_from_api_error(
+                    return finalize(_failed_from_api_error(
                         "LAYOUT_APPLY_FAILED",
                         api_fallback_error,
                         normalized_args=normalized_args,
@@ -2755,9 +2900,9 @@ class AiBuilderFacade:
                             "fallback_layout": flattened_layout,
                         },
                         suggested_next_call={"tool_name": "app_layout_apply", "arguments": {"profile": profile, **normalized_args}},
-                    )
+                    ))
             else:
-                return _failed_from_api_error(
+                return finalize(_failed_from_api_error(
                     "LAYOUT_APPLY_FAILED",
                     api_error,
                     normalized_args=normalized_args,
@@ -2768,7 +2913,7 @@ class AiBuilderFacade:
                         "current_field_names": [field["name"] for field in current_fields],
                     },
                     suggested_next_call={"tool_name": "app_layout_apply", "arguments": {"profile": profile, **normalized_args}},
-                )
+                ))
         try:
             verified_schema, _verified_schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
         except (QingflowApiError, RuntimeError) as error:
@@ -2798,7 +2943,7 @@ class AiBuilderFacade:
                 "verified": False,
             }
             response["request_id"] = api_error.request_id
-            return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
+            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)
         raw_layout_has_content = _schema_has_layout_content(verified_schema)
@@ -2848,7 +2993,7 @@ class AiBuilderFacade:
             },
             "verified": layout_verified,
         }
-        return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
+        return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
     def app_flow_apply(
         self,
@@ -2867,34 +3012,40 @@ class AiBuilderFacade:
             "transitions": transitions,
             "publish": publish,
         }
-        permission_block = self._guard_app_permission(
+        permission_outcomes: list[PermissionCheckOutcome] = []
+        permission_outcome = self._guard_app_permission(
             profile=profile,
             app_key=app_key,
             required_permission="data_manage",
             normalized_args=normalized_args,
         )
-        if permission_block is not None:
-            return permission_block
+        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)
+
         if mode != "replace":
-            return _failed(
+            return finalize(_failed(
                 "UNSUPPORTED_FLOW_MODE",
                 "only mode='replace' is supported",
                 normalized_args=normalized_args,
                 allowed_values={"modes": ["replace"]},
                 suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}},
-            )
+            ))
         try:
             base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
             schema, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            return _failed_from_api_error(
+            return finalize(_failed_from_api_error(
                 "FLOW_READ_FAILED",
                 api_error,
                 normalized_args=normalized_args,
-                details={"app_key": app_key},
+                details=_with_state_read_blocked_details({"app_key": app_key}, resource="workflow", error=api_error),
                 suggested_next_call={"tool_name": "app_read_flow_summary", "arguments": {"profile": profile, "app_key": app_key}},
-            )
+            ))
         entity = _entity_spec_from_app(base_info=base, schema=schema, views=None)
         current_fields = _parse_schema(schema)["fields"]
         normalized_nodes, resolution_issues = self._normalize_flow_nodes(profile=profile, current_fields=current_fields, nodes=nodes)
@@ -3006,7 +3157,7 @@ class AiBuilderFacade:
                 suggested_next_call["tool_name"] = "app_flow_apply"
                 suggested_next_call["arguments"] = arguments
             failed["suggested_next_call"] = suggested_next_call
-            return failed
+            return finalize(failed)
         verified_nodes, verified_nodes_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
         workflow_structure_verified = bool(verified_nodes) and _workflow_nodes_semantically_equal(
             current_workflow=verified_nodes,
@@ -3065,7 +3216,7 @@ class AiBuilderFacade:
             "flow_diff": {"mode": "replace", "node_count": desired_node_count},
             "verified": workflow_verified,
         }
-        return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
+        return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
     def app_views_apply(
         self,
@@ -3102,27 +3253,33 @@ class AiBuilderFacade:
                 "verified": True,
             }
             return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
-        permission_block = self._guard_app_permission(
+        permission_outcomes: list[PermissionCheckOutcome] = []
+        permission_outcome = self._guard_app_permission(
             profile=profile,
             app_key=app_key,
             required_permission="data_manage",
             normalized_args=normalized_args,
         )
-        if permission_block is not None:
-            return permission_block
+        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)
+
         try:
             base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
             schema, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
             existing_views, _views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=False)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            return _failed_from_api_error(
+            return finalize(_failed_from_api_error(
                 "VIEWS_READ_FAILED",
                 api_error,
                 normalized_args=normalized_args,
-                details={"app_key": app_key},
+                details=_with_state_read_blocked_details({"app_key": app_key}, resource="views", error=api_error),
                 suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
-            )
+            ))
         existing_views = existing_views or []
         existing_by_key: dict[str, dict[str, Any]] = {}
         existing_by_name: dict[str, list[dict[str, Any]]] = {}
@@ -3475,13 +3632,13 @@ class AiBuilderFacade:
             verified_view_result, verified_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(
+            return finalize(_failed_from_api_error(
                 "VIEWS_READ_FAILED",
                 api_error,
                 normalized_args=normalized_args,
-                details={"app_key": app_key},
+                details=_with_state_read_blocked_details({"app_key": app_key}, resource="views", error=api_error),
                 suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
-            )
+            ))
         verified_names = {
             _extract_view_name(item)
             for item in (verified_view_result or [])
@@ -3636,7 +3793,7 @@ class AiBuilderFacade:
                 "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": failed_views},
                 "verified": verified and view_filters_verified,
             }
-            return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
+            return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
         warnings: list[dict[str, Any]] = []
         if filter_readback_pending or filter_mismatches:
             warnings.append(_warning("VIEW_FILTERS_UNVERIFIED", "view definitions were applied, but saved filter behavior is not fully verified"))
@@ -3670,7 +3827,7 @@ class AiBuilderFacade:
             "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": []},
             "verified": verified and view_filters_verified,
         }
-        return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
+        return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
     def app_publish_verify(
         self,
@@ -3803,18 +3960,27 @@ class AiBuilderFacade:
 
     def chart_apply(self, *, profile: str, request: ChartApplyRequest) -> JSONObject:
         normalized_args = request.model_dump(mode="json")
+        permission_outcomes: list[PermissionCheckOutcome] = []
         app_result = self.app_resolve(profile=profile, app_key=request.app_key)
         if app_result.get("status") != "success":
             return app_result
+        resolved_outcome = _permission_outcome_from_result(app_result)
+        if resolved_outcome is not None:
+            permission_outcomes.append(resolved_outcome)
         app_key = str(app_result.get("app_key") or request.app_key)
-        permission_block = self._guard_app_permission(
+        permission_outcome = self._guard_app_permission(
             profile=profile,
             app_key=app_key,
             required_permission="data_manage",
             normalized_args=normalized_args,
         )
-        if permission_block is not None:
-            return permission_block
+        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)
+
         try:
             schema_state = self._load_base_schema_state(profile=profile, app_key=app_key)
             parsed = schema_state.get("parsed") if isinstance(schema_state.get("parsed"), dict) else {}
@@ -3823,13 +3989,13 @@ class AiBuilderFacade:
             existing_chart_items, existing_chart_list_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            return _failed_from_api_error(
+            return finalize(_failed_from_api_error(
                 "CHART_APPLY_FAILED",
                 api_error,
                 normalized_args=normalized_args,
-                details={"app_key": app_key},
+                details=_with_state_read_blocked_details({"app_key": app_key}, resource="chart", error=api_error),
                 suggested_next_call={"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
-            )
+            ))
 
         field_lookup = _build_public_field_lookup(fields)
         qingbi_fields_by_id = {
@@ -4069,7 +4235,7 @@ class AiBuilderFacade:
 
         if failed_items:
             successful_changes = bool(created_ids or updated_ids or removed_ids or reordered)
-            return {
+            return finalize({
                 "status": "partial_success" if successful_changes else "failed",
                 "error_code": "CHART_APPLY_PARTIAL" if successful_changes else "CHART_APPLY_FAILED",
                 "recoverable": True,
@@ -4097,9 +4263,9 @@ class AiBuilderFacade:
                 "app_key": app_key,
                 "chart_results": chart_results,
                 "verified": False if failed_items else verified,
-            }
+            })
         result_verified = verified or noop
-        return {
+        return finalize({
             "status": "success" if result_verified else "partial_success",
             "error_code": None if result_verified else "CHART_READBACK_PENDING",
             "recoverable": not result_verified,
@@ -4125,10 +4291,11 @@ class AiBuilderFacade:
             "app_key": app_key,
             "chart_results": chart_results,
             "verified": result_verified,
-        }
+        })
 
     def portal_apply(self, *, profile: str, request: PortalApplyRequest) -> JSONObject:
         normalized_args = request.model_dump(mode="json")
+        permission_outcomes: list[PermissionCheckOutcome] = []
         dash_key = str(request.dash_key or "").strip()
         creating = not dash_key
         verify_dash_name = creating or request.dash_name is not None
@@ -4141,24 +4308,31 @@ class AiBuilderFacade:
             base_payload = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") if dash_key else {}
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            return _failed_from_api_error(
+            return _failed(
                 "PORTAL_APPLY_FAILED",
-                api_error,
+                _public_error_message("PORTAL_APPLY_FAILED", api_error),
                 normalized_args=normalized_args,
-                details={"dash_key": dash_key or None},
+                details=_with_state_read_blocked_details({"dash_key": dash_key or None}, resource="portal", error=api_error),
                 suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
+                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,
             )
         if not isinstance(base_payload, dict):
             base_payload = {}
         if not creating:
-            portal_permission_block = self._guard_portal_permission(
+            portal_permission_outcome = self._guard_portal_permission(
                 profile=profile,
                 dash_key=dash_key,
                 normalized_args=normalized_args,
                 portal_result=base_payload,
             )
-            if portal_permission_block is not None:
-                return portal_permission_block
+            if portal_permission_outcome.block is not None:
+                return portal_permission_outcome.block
+            permission_outcomes.append(portal_permission_outcome)
+
+        def finalize(response: JSONObject) -> JSONObject:
+            return _apply_permission_outcomes(response, *permission_outcomes)
         target_package_tag_id = request.package_tag_id
         if target_package_tag_id is None:
             target_package_tag_id = _coerce_positive_int(((base_payload.get("tags") or [{}])[0] if isinstance(base_payload.get("tags"), list) and base_payload.get("tags") else {}).get("tagId"))
@@ -4170,22 +4344,24 @@ class AiBuilderFacade:
                 suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
             )
         if creating:
-            package_add_block = self._guard_package_permission(
+            package_add_outcome = self._guard_package_permission(
                 profile=profile,
                 tag_id=target_package_tag_id,
                 required_permission="add_app",
                 normalized_args=normalized_args,
             )
-            if package_add_block is not None:
-                return package_add_block
-            package_edit_block = self._guard_package_permission(
+            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_block is not None:
-                return package_edit_block
+            if package_edit_outcome.block is not None:
+                return package_edit_outcome.block
+            permission_outcomes.append(package_edit_outcome)
         try:
             if creating:
                 create_payload = _build_public_portal_base_payload(
@@ -4242,7 +4418,7 @@ class AiBuilderFacade:
                 "PORTAL_APPLY_FAILED",
                 _public_error_message("PORTAL_APPLY_FAILED", api_error) if api_error else str(error),
                 normalized_args=normalized_args,
-                details={"dash_key": dash_key or None},
+                details=_with_state_read_blocked_details({"dash_key": dash_key or None}, resource="portal", error=api_error) if api_error is not None else {"dash_key": dash_key or None},
                 suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
                 request_id=api_error.request_id if api_error else None,
                 backend_code=api_error.backend_code if api_error else None,
@@ -4316,7 +4492,7 @@ class AiBuilderFacade:
             live_meta_verified=live_meta_verified,
             publish_requested=request.publish,
         )
-        return {
+        return finalize({
             "status": status,
             "error_code": error_code,
             "recoverable": not verified,
@@ -4347,7 +4523,7 @@ class AiBuilderFacade:
             "verified": verified,
             "draft_result": draft_result,
             "live_result": live_result,
-        }
+        })
 
     def _publish_current_edit_version(self, *, profile: str, app_key: str) -> JSONObject:
         normalized_args = {"app_key": app_key}
@@ -4912,6 +5088,177 @@ def _failed_from_api_error(
     )
 
 
+def _transport_error_payload(error: QingflowApiError) -> JSONObject:
+    return {
+        "http_status": error.http_status,
+        "backend_code": error.backend_code,
+        "category": error.category,
+        "request_id": error.request_id,
+    }
+
+
+def _is_permission_restricted_api_error(error: QingflowApiError) -> bool:
+    return error.backend_code in {40002, 40027}
+
+
+def _append_response_detail(details: JSONObject, *, key: str, value: Any) -> None:
+    if value is None:
+        return
+    copied_value = deepcopy(value)
+    existing = details.get(key)
+    if existing is None:
+        details[key] = copied_value
+        return
+    if isinstance(existing, list):
+        existing.append(copied_value)
+        return
+    details[key] = [existing, copied_value]
+
+
+def _permission_skip_outcome(
+    *,
+    scope: str,
+    target: JSONObject,
+    required_permission: str | None,
+    transport_error: JSONObject | None = None,
+    permission_summary: JSONObject | None = None,
+) -> PermissionCheckOutcome:
+    lookup_payload: JSONObject = {
+        "scope": scope,
+        "target": deepcopy(target),
+        "required_permission": required_permission,
+    }
+    if transport_error:
+        lookup_payload["transport_error"] = deepcopy(transport_error)
+    if permission_summary:
+        lookup_payload["permission_summary"] = deepcopy(permission_summary)
+    warning_message = (
+        "builder permission lookup was permission-restricted; continuing with downstream operations"
+        if transport_error
+        else "builder permission summary was incomplete; continuing with downstream operations"
+    )
+    return PermissionCheckOutcome(
+        warnings=[
+            _warning(
+                "PERMISSION_CHECK_SKIPPED",
+                warning_message,
+                scope=scope,
+                required_permission=required_permission,
+            )
+        ],
+        details={
+            "lookup_permission_blocked": lookup_payload,
+            "permission_check_skipped": True,
+        },
+        verification={"metadata_unverified": True},
+    )
+
+
+def _verification_read_outcome(
+    *,
+    resource: str,
+    target: JSONObject,
+    transport_error: QingflowApiError,
+) -> PermissionCheckOutcome:
+    return PermissionCheckOutcome(
+        warnings=[
+            _warning(
+                "VERIFICATION_READ_UNAVAILABLE",
+                "post-write verification readback was permission-restricted",
+                resource=resource,
+            )
+        ],
+        details={
+            "lookup_permission_blocked": {
+                "scope": resource,
+                "target": deepcopy(target),
+                "phase": "verification",
+                "transport_error": _transport_error_payload(transport_error),
+            },
+            "permission_check_skipped": True,
+        },
+        verification={"metadata_unverified": True},
+    )
+
+
+def _permission_outcome_from_result(result: JSONObject) -> PermissionCheckOutcome | None:
+    details = result.get("details") if isinstance(result.get("details"), dict) else {}
+    verification = result.get("verification") if isinstance(result.get("verification"), dict) else {}
+    warnings = result.get("warnings") if isinstance(result.get("warnings"), list) else []
+    filtered_details: JSONObject = {}
+    if details.get("lookup_permission_blocked") is not None:
+        filtered_details["lookup_permission_blocked"] = deepcopy(details["lookup_permission_blocked"])
+    if details.get("permission_check_skipped") is not None:
+        filtered_details["permission_check_skipped"] = bool(details.get("permission_check_skipped"))
+    filtered_verification: JSONObject = {}
+    if verification.get("metadata_unverified") is not None:
+        filtered_verification["metadata_unverified"] = bool(verification.get("metadata_unverified"))
+    filtered_warnings = [
+        deepcopy(item)
+        for item in warnings
+        if isinstance(item, dict) and str(item.get("code") or "") in {"PERMISSION_CHECK_SKIPPED", "VERIFICATION_READ_UNAVAILABLE"}
+    ]
+    if not filtered_details and not filtered_verification and not filtered_warnings:
+        return None
+    return PermissionCheckOutcome(
+        warnings=filtered_warnings,
+        details=filtered_details,
+        verification=filtered_verification,
+    )
+
+
+def _apply_permission_outcomes(response: JSONObject, *outcomes: PermissionCheckOutcome) -> JSONObject:
+    if not isinstance(response, dict):
+        return response
+    details = response.get("details")
+    if not isinstance(details, dict):
+        details = {}
+        response["details"] = details
+    verification = response.get("verification")
+    if not isinstance(verification, dict):
+        verification = {}
+        response["verification"] = verification
+    warnings = response.get("warnings")
+    if not isinstance(warnings, list):
+        warnings = []
+        response["warnings"] = warnings
+    for outcome in outcomes:
+        if not isinstance(outcome, PermissionCheckOutcome):
+            continue
+        for key, value in outcome.details.items():
+            if key in {"lookup_permission_blocked", "state_read_blocked"}:
+                _append_response_detail(details, key=key, value=value)
+            elif key == "permission_check_skipped":
+                details[key] = bool(details.get(key)) or bool(value)
+            elif key not in details:
+                details[key] = deepcopy(value)
+        for key, value in outcome.verification.items():
+            verification[key] = deepcopy(value)
+        for warning in outcome.warnings:
+            if warning not in warnings:
+                warnings.append(deepcopy(warning))
+    return response
+
+
+def _with_state_read_blocked_details(
+    details: JSONObject | None,
+    *,
+    resource: str,
+    error: QingflowApiError,
+) -> JSONObject:
+    merged = deepcopy(details) if isinstance(details, dict) else {}
+    if _is_permission_restricted_api_error(error):
+        _append_response_detail(
+            merged,
+            key="state_read_blocked",
+            value={
+                "resource": resource,
+                "transport_error": _transport_error_payload(error),
+            },
+        )
+    return merged
+
+
 def _from_stage_failure(stage: JSONObject, *, fallback_tool: str) -> JSONObject:
     return {
         "status": "failed",