@josephyan/qingflow-app-user-mcp 0.2.0-beta.21 → 0.2.0-beta.22

package/src/qingflow_mcp/tools/record_tools.py

@@ -243,7 +243,8 @@ class RecordTools(ToolBase):
         @mcp.tool(
             description=(
                 "Write Qingflow records with a SQL-like JSON DSL. "
-                "Use record_schema_get first, then choose operation=insert|update|delete and mode=plan|apply. "
+                "Use record_schema_get first, then choose operation=insert|update|delete. "
+                "This tool performs internal preflight validation before any write is applied. "
                 "This route does not accept raw SQL strings or free-form WHERE clauses."
             )
         )
@@ -251,7 +252,6 @@ class RecordTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             operation: str = "insert",
-            mode: str = "plan",
             record_id: int | None = None,
             record_ids: list[int] | None = None,
             values: list[JSONObject] | None = None,
@@ -264,7 +264,6 @@ class RecordTools(ToolBase):
                 profile=profile,
                 app_key=app_key,
                 operation=operation,
-                mode=mode,
                 record_id=record_id,
                 record_ids=record_ids or [],
                 values=values or [],
@@ -564,7 +563,6 @@ class RecordTools(ToolBase):
         profile: str,
         app_key: str,
         operation: str,
-        mode: str,
         record_id: int | None,
         record_ids: list[int],
         values: list[JSONObject],
@@ -572,14 +570,18 @@ class RecordTools(ToolBase):
         submit_type: str | int,
         verify_write: bool,
         output_profile: str,
+        mode: str | None = None,
     ) -> JSONObject:
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
         normalized_operation = operation.strip().lower()
-        normalized_mode = mode.strip().lower()
         if normalized_operation not in {"insert", "update", "delete"}:
             raise_tool_error(QingflowApiError.config_error("operation must be insert, update, or delete"))
-        if normalized_mode not in {"plan", "apply"}:
-            raise_tool_error(QingflowApiError.config_error("mode must be plan or apply"))
+        if mode is not None:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    "record_write no longer accepts mode; it now runs internal preflight automatically before apply"
+                )
+            )
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         normalized_record_ids = [item for item in record_ids if isinstance(item, int) and item > 0]
@@ -591,34 +593,36 @@ class RecordTools(ToolBase):
             if set:
                 raise_tool_error(QingflowApiError.config_error("insert must use values, not set"))
             normalized_answers = self._normalize_record_write_clauses(values, location="values")
-            normalized_payload: JSONObject = {
-                "operation": "insert",
-                "record_id": None,
-                "record_ids": [],
-                "answers": normalized_answers,
-                "submit_type": submit_type_value,
-            }
-            if normalized_mode == "plan":
-                raw_plan = self.record_write_plan(
-                    profile=profile,
-                    operation="create",
-                    app_key=app_key,
-                    apply_id=None,
-                    answers=normalized_answers,
-                    fields={},
-                    force_refresh_form=False,
-                )
-                return self._record_write_plan_response(
-                    raw_plan,
+            raw_preflight = self._preflight_record_write(
+                profile=profile,
+                operation="create",
+                app_key=app_key,
+                apply_id=None,
+                answers=normalized_answers,
+                fields={},
+                force_refresh_form=False,
+            )
+            preflight_data = cast(JSONObject, raw_preflight.get("data", {}))
+            normalized_payload: JSONObject = self._record_write_normalized_payload(
+                operation="insert",
+                record_id=None,
+                record_ids=[],
+                normalized_answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
+                submit_type=submit_type_value,
+            )
+            if preflight_data.get("blockers"):
+                return self._record_write_blocked_response(
+                    raw_preflight,
                     operation="insert",
                     normalized_payload=normalized_payload,
                     output_profile=normalized_output_profile,
                     human_review=False,
+                    target_resource={"type": "record", "app_key": app_key, "record_id": None, "record_ids": []},
                 )
             raw_apply = self.record_create(
                 profile=profile,
                 app_key=app_key,
-                answers=normalized_answers,
+                answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
                 fields={},
                 submit_type=submit_type_value,
                 verify_write=verify_write,
@@ -630,6 +634,7 @@ class RecordTools(ToolBase):
                 normalized_payload=normalized_payload,
                 output_profile=normalized_output_profile,
                 human_review=False,
+                preflight=raw_preflight,
             )
 
         if normalized_operation == "update":
@@ -640,35 +645,37 @@ class RecordTools(ToolBase):
             if values:
                 raise_tool_error(QingflowApiError.config_error("update must use set, not values"))
             normalized_answers = self._normalize_record_write_clauses(set, location="set")
-            normalized_payload = {
-                "operation": "update",
-                "record_id": record_id,
-                "record_ids": [],
-                "answers": normalized_answers,
-                "submit_type": submit_type_value,
-            }
-            if normalized_mode == "plan":
-                raw_plan = self.record_write_plan(
-                    profile=profile,
-                    operation="update",
-                    app_key=app_key,
-                    apply_id=record_id,
-                    answers=normalized_answers,
-                    fields={},
-                    force_refresh_form=False,
-                )
-                return self._record_write_plan_response(
-                    raw_plan,
+            raw_preflight = self._preflight_record_write(
+                profile=profile,
+                operation="update",
+                app_key=app_key,
+                apply_id=record_id,
+                answers=normalized_answers,
+                fields={},
+                force_refresh_form=False,
+            )
+            preflight_data = cast(JSONObject, raw_preflight.get("data", {}))
+            normalized_payload = self._record_write_normalized_payload(
+                operation="update",
+                record_id=record_id,
+                record_ids=[],
+                normalized_answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
+                submit_type=submit_type_value,
+            )
+            if preflight_data.get("blockers"):
+                return self._record_write_blocked_response(
+                    raw_preflight,
                     operation="update",
                     normalized_payload=normalized_payload,
                     output_profile=normalized_output_profile,
                     human_review=True,
+                    target_resource={"type": "record", "app_key": app_key, "record_id": record_id, "record_ids": []},
                 )
             raw_apply = self.record_update(
                 profile=profile,
                 app_key=app_key,
                 apply_id=record_id,
-                answers=normalized_answers,
+                answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
                 fields={},
                 role=1,
                 verify_write=verify_write,
@@ -680,6 +687,7 @@ class RecordTools(ToolBase):
                 normalized_payload=normalized_payload,
                 output_profile=normalized_output_profile,
                 human_review=True,
+                preflight=raw_preflight,
             )
 
         if values or set:
@@ -694,22 +702,6 @@ class RecordTools(ToolBase):
             "answers": [],
             "submit_type": submit_type_value,
         }
-        if normalized_mode == "plan":
-            return {
-                "profile": profile,
-                "ok": True,
-                "request_route": None,
-                "warnings": [],
-                "output_profile": normalized_output_profile,
-                "data": {
-                    "action": {"operation": "delete", "mode": "plan"},
-                    "resource": {"type": "record", "app_key": app_key, "record_id": record_id, "record_ids": delete_ids},
-                    "verification": None,
-                    "normalized_payload": normalized_payload,
-                    "blockers": [],
-                    "human_review": self._record_write_human_review_payload("delete", enabled=True),
-                },
-            }
         raw_apply = self._record_delete_many(profile=profile, app_key=app_key, record_ids=delete_ids)
         return self._record_write_apply_response(
             raw_apply,
@@ -717,6 +709,7 @@ class RecordTools(ToolBase):
             normalized_payload=normalized_payload,
             output_profile=normalized_output_profile,
             human_review=True,
+            preflight=None,
         )
 
     def _schema_field_payload(self, field: FormField) -> JSONObject:
@@ -1259,7 +1252,6 @@ class RecordTools(ToolBase):
         requested_pages = int(analysis_paging["requested_pages"])
         scan_max_pages = int(analysis_paging["scan_max_pages"])
         auto_expand_pages = bool(analysis_paging["auto_expand_pages"])
-        query_id = _query_id()
         pages_to_scan = min(max(requested_pages, 1), max(scan_max_pages, 1))
         current_page = 1
         scanned_pages = 0
@@ -1349,82 +1341,101 @@ class RecordTools(ToolBase):
             ]
             all_rows = self._sort_analyze_rows(all_rows, sort, dimensions, metrics)
             rows_truncated = len(all_rows) > limit
-            limited_rows = all_rows[:limit]
-            rows = limited_rows
-            rows_returned = len(limited_rows)
+            rows = all_rows[:limit]
             group_count = len(all_rows)
             statement_scope = "returned_groups_only" if rows_truncated else "full_population"
         else:
             rows_truncated = False
             rows = [{"dimensions": {}, "metrics": metric_totals}]
-            rows_returned = 1
             group_count = 1
             statement_scope = "full_population"
         raw_scan_complete = not has_more
         completeness_status = "complete" if raw_scan_complete else "incomplete"
         reason_code = "LOCAL_VIEW_FILTERING" if local_filtering and raw_scan_complete else ("SOURCE_EXHAUSTED" if raw_scan_complete else "SCAN_LIMIT_HIT")
-        totals = {
-            "scanned_count": matched_rows,
-            "group_count": group_count,
-            "metric_totals": metric_totals,
+        query_payload: JSONObject = {
+            "app_key": app_key,
+            "dimensions": [
+                {
+                    "field_id": cast(FormField, item["field"]).que_id,
+                    "alias": item["alias"],
+                    "bucket": item["bucket"],
+                }
+                for item in dimensions
+            ],
+            "metrics": [
+                {
+                    "op": item["op"],
+                    **(
+                        {"field_id": cast(FormField, item["field"]).que_id}
+                        if item["field"] is not None
+                        else {}
+                    ),
+                    "alias": item["alias"],
+                }
+                for item in metrics
+            ],
+            "filters": [
+                {
+                    "field_id": cast(FormField, item["field"]).que_id,
+                    "op": item["op"],
+                    **({"value": item.get("value")} if item.get("value") is not None else {}),
+                }
+                for item in filters
+            ],
+            "sort": [{"by": item["by"], "order": item["order"]} for item in sort],
+            "limit": limit,
+            "strict_full": strict_full,
         }
-        data: JSONObject = {
-            "query": {
-                "app_key": app_key,
-                "dimensions": [
-                    {
-                        "field_id": cast(FormField, item["field"]).que_id,
-                        "title": cast(FormField, item["field"]).que_title,
-                        "alias": item["alias"],
-                        "bucket": item["bucket"],
-                    }
-                    for item in dimensions
-                ],
-                "metrics": [
-                    {
-                        "op": item["op"],
-                        "field_id": cast(FormField | None, item["field"]).que_id if item["field"] is not None else None,
-                        "title": cast(FormField | None, item["field"]).que_title if item["field"] is not None else None,
-                        "alias": item["alias"],
-                    }
-                    for item in metrics
-                ],
-                "filters": [
-                    {
-                        "field_id": cast(FormField, item["field"]).que_id,
-                        "title": cast(FormField, item["field"]).que_title,
-                        "op": item["op"],
-                        "value": item.get("value"),
-                    }
-                    for item in filters
-                ],
-                "applied_sort": [{"by": item["by"], "order": item["order"]} for item in sort],
-                "view": _view_selection_payload(view_selection),
-            },
-            "rows": rows,
-            "totals": totals,
-            "completeness": {
-                "status": completeness_status,
-                "reason_code": reason_code,
-                "local_filtering_applied": local_filtering,
-                "safe_for_final_conclusion": completeness_status == "complete",
-            },
-            "presentation": {
-                "row_limit": limit,
-                "rows_returned": rows_returned,
-                "rows_truncated": rows_truncated,
-                "statement_scope": statement_scope,
-            },
-            "warnings": self._build_analyze_warnings(local_filtering=local_filtering, rows_truncated=rows_truncated),
+        view_payload = _view_selection_payload(view_selection)
+        if view_payload:
+            query_payload["view"] = view_payload
+
+        ranking: JSONObject | None = None
+        if dimensions and sort:
+            primary_sort = sort[0]
+            ranking = {
+                "order_by": primary_sort["by"],
+                "order_direction": primary_sort["order"],
+                "ranked": True,
+            }
+            rows = [
+                {
+                    "dimensions": cast(JSONObject, row["dimensions"]),
+                    "metrics": cast(JSONObject, row["metrics"]),
+                    "rank": idx,
+                }
+                for idx, row in enumerate(rows, start=1)
+            ]
+
+        warnings = self._build_analyze_warnings(local_filtering=local_filtering, rows_truncated=rows_truncated)
+        completeness: JSONObject = {
+            "status": completeness_status,
+            "safe_for_final_conclusion": completeness_status == "complete",
+            "rows_truncated": rows_truncated,
+            "statement_scope": statement_scope,
+            "warnings": warnings,
         }
+        if completeness_status != "complete":
+            completeness["reason_code"] = reason_code
+
         response: JSONObject = {
-            "profile": profile,
-            "ws_id": session_profile.selected_ws_id,
             "ok": True,
             "status": "success" if raw_scan_complete else "partial",
-            "query_id": query_id,
-            "request_route": self._request_route_payload(context),
-            "data": data,
+            "query": query_payload,
+            "result": {
+                "totals": {
+                    "metric_totals": metric_totals,
+                },
+                "rows": rows,
+                "row_count": len(rows),
+            },
+            "ranking": ranking,
+            "ratios": None,
+            "completeness": completeness,
+            "presentation": {
+                "returned_group_count": len(rows),
+                "total_group_count": group_count,
+            },
         }
         if strict_full and not raw_scan_complete:
             response["ok"] = False
@@ -1435,13 +1446,15 @@ class RecordTools(ToolBase):
                 "fix_hint": "Narrow the scope with view/filter constraints, or retry after reducing the dataset size.",
             }
         if output_profile == "verbose":
-            response["data"]["debug"] = {
+            response["debug"] = {
+                "request_route": self._request_route_payload(context),
                 "elapsed_ms": int((time.perf_counter() - started_at) * 1000),
                 "backend_total_hint": scan_control.get("backend_total_count", result_amount),
                 "backend_page_amount": scan_control.get("backend_page_amount"),
                 "source_pages": source_pages,
-                "raw_scan_complete": raw_scan_complete,
                 "scan_control": scan_control,
+                "reason_code": reason_code,
+                "local_filtering_applied": local_filtering,
             }
         return response
 
@@ -1559,19 +1572,9 @@ class RecordTools(ToolBase):
     def _build_analyze_warnings(self, *, local_filtering: bool, rows_truncated: bool) -> list[JSONObject]:
         warnings: list[JSONObject] = []
         if local_filtering:
-            warnings.append(
-                {
-                    "code": "LOCAL_FILTERING_APPLIED",
-                    "message": "Current analysis applies local filtering after scanning source pages.",
-                }
-            )
+            warnings.append({"code": "LOCAL_VIEW_FILTERING"})
         if rows_truncated:
-            warnings.append(
-                {
-                    "code": "ROWS_TRUNCATED",
-                    "message": "Result rows were truncated by limit; totals remain based on the full analyzed result set.",
-                }
-            )
+            warnings.append({"code": "ROWS_TRUNCATED"})
         return warnings
 
     def record_write_plan(
@@ -1589,123 +1592,180 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         inferred_operation = operation if operation in {"create", "update"} else ("update" if apply_id else "create")
 
+        return self._preflight_record_write(
+            profile=profile,
+            operation=inferred_operation,
+            app_key=app_key,
+            apply_id=apply_id,
+            answers=answers or [],
+            fields=fields or {},
+            force_refresh_form=force_refresh_form,
+        )
+
+    def _preflight_record_write(
+        self,
+        *,
+        profile: str,
+        operation: str,
+        app_key: str,
+        apply_id: int | None,
+        answers: list[JSONObject],
+        fields: JSONObject,
+        force_refresh_form: bool,
+    ) -> JSONObject:
+        if not app_key:
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+
         def runner(session_profile, context):
-            schema = self._get_form_schema(profile, context, app_key, force_refresh=force_refresh_form)
-            index = _build_field_index(schema)
-            normalized_fields = fields or {}
-            normalized_answers_input = answers or []
-            resolved_fields = self._collect_write_plan_field_refs(fields=normalized_fields, answers=normalized_answers_input, index=index)
-            support_matrix = _summarize_write_support(resolved_fields)
-            invalid_fields: list[JSONObject] = []
-            normalized_answers: list[JSONObject] = []
-            try:
-                normalized_answers = self._resolve_answers(
-                    profile,
-                    context,
-                    app_key,
-                    answers=normalized_answers_input,
-                    fields=normalized_fields,
-                    force_refresh_form=force_refresh_form,
-                )
-            except RecordInputError as error:
-                invalid_fields.append(
-                    {
-                        "location": _stringify_json(error.details.get("location") if error.details else None),
-                        "message": error.message,
-                        "error_code": error.error_code,
-                        "field": error.details.get("field") if error.details and isinstance(error.details.get("field"), dict) else None,
-                        "expected_format": error.details.get("expected_format") if error.details and isinstance(error.details.get("expected_format"), dict) else None,
-                        "received_value": error.details.get("received_value") if error.details else None,
-                    }
-                )
-            readonly_or_system_fields = [
-                {
-                    "que_id": entry.get("que_id"),
-                    "que_title": entry.get("que_title"),
-                    "que_type": entry.get("que_type"),
-                    "readonly": entry.get("readonly"),
-                    "system": entry.get("system"),
-                    "source": entry.get("source"),
-                    "requested": entry.get("requested"),
-                }
-                for entry in resolved_fields
-                if bool(entry.get("resolved")) and (bool(entry.get("readonly")) or bool(entry.get("system")))
-            ]
-            provided_field_ids = {
-                str(answer.get("queId"))
-                for answer in normalized_answers
-                if isinstance(answer.get("queId"), int) and int(answer["queId"]) > 0
-            }
-            missing_required_fields = []
-            for field in index.by_id.values():
-                if not field.required or str(field.que_id) in provided_field_ids:
-                    continue
-                missing_required_fields.append(
-                    {
-                        "que_id": field.que_id,
-                        "que_title": field.que_title,
-                        "que_type": field.que_type,
-                        "reason": "required field not provided",
-                    }
-                )
-            question_relations = _collect_question_relations(schema)
-            option_links = _collect_option_links(resolved_fields)
-            validation = {
-                "valid": not invalid_fields and not missing_required_fields and not readonly_or_system_fields,
-                "missing_required_fields": missing_required_fields,
-                "likely_hidden_required_fields": [],
-                "readonly_or_system_fields": readonly_or_system_fields,
-                "invalid_fields": invalid_fields,
-                "warnings": [
-                    "record_write_plan is a static preflight built from form metadata; runtime visibility and dynamic linkage can still reject writes."
-                ],
-            }
-            blockers = []
-            if invalid_fields:
-                blockers.append("payload contains invalid field values")
-            if missing_required_fields:
-                blockers.append("required fields are missing")
-            if readonly_or_system_fields:
-                blockers.append("payload writes readonly or system-managed fields")
-            if question_relations:
-                validation["warnings"].append("form contains questionRelations; linked visibility and runtime required rules may differ at submit time.")
-            actions = ["Use record_schema_get when field titles or field ids are ambiguous."]
-            if support_matrix["restricted"]:
-                actions.append("Review write_format.required_presteps for restricted fields before submit.")
-            if invalid_fields:
-                actions.append("Fix invalid_fields before calling record_create or record_update.")
-            if missing_required_fields:
-                actions.append("Fill missing required fields before submit.")
-            if readonly_or_system_fields:
-                actions.append("Remove readonly/system fields from payload before submit.")
-            if question_relations:
-                actions.append("Treat ready_to_submit as static-only because linked fields can still appear at runtime.")
+            plan_data = self._build_record_write_preflight(
+                profile=profile,
+                context=context,
+                operation=operation,
+                app_key=app_key,
+                apply_id=apply_id,
+                answers=answers,
+                fields=fields,
+                force_refresh_form=force_refresh_form,
+            )
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "ok": True,
                 "request_route": self._request_route_payload(context),
-                "data": {
-                    "operation": inferred_operation,
-                    "app_key": app_key,
-                    "apply_id": apply_id,
-                    "normalized_answers": normalized_answers,
-                    "resolved_fields": resolved_fields,
-                    "support_matrix": support_matrix,
-                    "validation": validation,
-                    "dependencies": {
-                        "question_relations_present": bool(question_relations),
-                        "question_relations": question_relations,
-                        "option_links": option_links,
-                    },
-                    "ready_to_submit": validation["valid"],
-                    "blockers": blockers,
-                    "recommended_next_actions": actions,
-                },
+                "data": plan_data,
             }
 
         return self._run_record_tool(profile, runner)
 
+    def _build_record_write_preflight(
+        self,
+        *,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        operation: str,
+        app_key: str,
+        apply_id: int | None,
+        answers: list[JSONObject],
+        fields: JSONObject,
+        force_refresh_form: bool,
+    ) -> JSONObject:
+        schema = self._get_form_schema(profile, context, app_key, force_refresh=force_refresh_form)
+        index = _build_field_index(schema)
+        normalized_fields = fields or {}
+        normalized_answers_input = answers or []
+        resolved_fields = self._collect_write_plan_field_refs(fields=normalized_fields, answers=normalized_answers_input, index=index)
+        support_matrix = _summarize_write_support(resolved_fields)
+        invalid_fields: list[JSONObject] = []
+        normalized_answers: list[JSONObject] = []
+        try:
+            normalized_answers = self._resolve_answers(
+                profile,
+                context,
+                app_key,
+                answers=normalized_answers_input,
+                fields=normalized_fields,
+                force_refresh_form=force_refresh_form,
+            )
+        except RecordInputError as error:
+            invalid_fields.append(
+                {
+                    "location": _stringify_json(error.details.get("location") if error.details else None),
+                    "message": error.message,
+                    "error_code": error.error_code,
+                    "field": error.details.get("field") if error.details and isinstance(error.details.get("field"), dict) else None,
+                    "expected_format": error.details.get("expected_format") if error.details and isinstance(error.details.get("expected_format"), dict) else None,
+                    "received_value": error.details.get("received_value") if error.details else None,
+                }
+            )
+        readonly_or_system_fields = [
+            {
+                "que_id": entry.get("que_id"),
+                "que_title": entry.get("que_title"),
+                "que_type": entry.get("que_type"),
+                "readonly": entry.get("readonly"),
+                "system": entry.get("system"),
+                "source": entry.get("source"),
+                "requested": entry.get("requested"),
+            }
+            for entry in resolved_fields
+            if bool(entry.get("resolved")) and (bool(entry.get("readonly")) or bool(entry.get("system")))
+        ]
+        provided_field_ids = {
+            str(answer.get("queId"))
+            for answer in normalized_answers
+            if isinstance(answer.get("queId"), int) and int(answer["queId"]) > 0
+        }
+        missing_required_fields = []
+        for field in index.by_id.values():
+            if not field.required or str(field.que_id) in provided_field_ids:
+                continue
+            missing_required_fields.append(
+                {
+                    "que_id": field.que_id,
+                    "que_title": field.que_title,
+                    "que_type": field.que_type,
+                    "reason": "required field not provided",
+                }
+            )
+        question_relations = _collect_question_relations(schema)
+        option_links = _collect_option_links(resolved_fields)
+        validation_warnings = [
+            "record_write performs static preflight from form metadata before apply; runtime visibility and dynamic linkage can still reject writes."
+        ]
+        if question_relations:
+            validation_warnings.append(
+                "form contains questionRelations; linked visibility and runtime required rules may differ at submit time."
+            )
+        validation = {
+            "valid": not invalid_fields and not missing_required_fields and not readonly_or_system_fields,
+            "missing_required_fields": missing_required_fields,
+            "likely_hidden_required_fields": [],
+            "readonly_or_system_fields": readonly_or_system_fields,
+            "invalid_fields": invalid_fields,
+            "warnings": validation_warnings,
+        }
+        field_errors = self._record_write_field_errors(
+            invalid_fields=invalid_fields,
+            missing_required_fields=missing_required_fields,
+            readonly_or_system_fields=readonly_or_system_fields,
+        )
+        blockers = []
+        if invalid_fields:
+            blockers.append("payload contains invalid field values")
+        if missing_required_fields:
+            blockers.append("required fields are missing")
+        if readonly_or_system_fields:
+            blockers.append("payload writes readonly or system-managed fields")
+        actions = ["Use record_schema_get when field titles or field ids are ambiguous."]
+        if support_matrix["restricted"]:
+            actions.append("Review write_format.required_presteps for restricted fields before submit.")
+        if invalid_fields:
+            actions.append("Fix invalid_fields before applying the write.")
+        if missing_required_fields:
+            actions.append("Fill missing required fields before applying the write.")
+        if readonly_or_system_fields:
+            actions.append("Remove readonly/system fields from payload before applying the write.")
+        if question_relations:
+            actions.append("Treat static preflight as conservative only because linked fields can still appear at runtime.")
+        return {
+            "operation": operation if operation in {"create", "update"} else ("update" if apply_id else "create"),
+            "app_key": app_key,
+            "apply_id": apply_id,
+            "normalized_answers": normalized_answers,
+            "resolved_fields": resolved_fields,
+            "support_matrix": support_matrix,
+            "validation": validation,
+            "field_errors": field_errors,
+            "dependencies": {
+                "question_relations_present": bool(question_relations),
+                "question_relations": question_relations,
+                "option_links": option_links,
+            },
+            "ready_to_submit": validation["valid"],
+            "blockers": blockers,
+            "recommended_next_actions": actions,
+        }
+
     def record_query(
         self,
         *,
@@ -2950,6 +3010,23 @@ class RecordTools(ToolBase):
             normalized.append(payload)
         return normalized
 
+    def _record_write_normalized_payload(
+        self,
+        *,
+        operation: str,
+        record_id: int | None,
+        record_ids: list[int],
+        normalized_answers: list[JSONObject],
+        submit_type: int,
+    ) -> JSONObject:
+        return {
+            "operation": operation,
+            "record_id": record_id,
+            "record_ids": record_ids,
+            "answers": normalized_answers,
+            "submit_type": submit_type,
+        }
+
     def _record_write_human_review_payload(self, operation: str, *, enabled: bool) -> JSONObject | None:
         if not enabled:
             return None
@@ -2959,38 +3036,41 @@ class RecordTools(ToolBase):
             "message": "Read the current record first and confirm the exact target before applying this high-risk write.",
         }
 
-    def _record_write_plan_response(
+    def _record_write_blocked_response(
         self,
-        raw_plan: JSONObject,
+        raw_preflight: JSONObject,
         *,
         operation: str,
         normalized_payload: JSONObject,
         output_profile: str,
         human_review: bool,
+        target_resource: JSONObject,
     ) -> JSONObject:
-        plan_data = cast(JSONObject, raw_plan.get("data", {}))
+        plan_data = cast(JSONObject, raw_preflight.get("data", {}))
         validation = cast(JSONObject, plan_data.get("validation", {}))
+        field_errors = self._record_write_public_field_errors(plan_data)
         warnings_payload = validation.get("warnings", [])
-        warnings = [{"code": "PLAN_WARNING", "message": str(item)} for item in warnings_payload] if isinstance(warnings_payload, list) else []
+        warnings = [{"code": "PREFLIGHT_WARNING", "message": str(item)} for item in warnings_payload] if isinstance(warnings_payload, list) else []
         response: JSONObject = {
-            "profile": raw_plan.get("profile"),
-            "ws_id": raw_plan.get("ws_id"),
-            "ok": bool(raw_plan.get("ok", True)),
-            "request_route": raw_plan.get("request_route"),
+            "profile": raw_preflight.get("profile"),
+            "ws_id": raw_preflight.get("ws_id"),
+            "ok": False,
+            "request_route": raw_preflight.get("request_route"),
             "warnings": warnings,
             "output_profile": output_profile,
             "data": {
-                "action": {"operation": operation, "mode": "plan"},
-                "resource": {"type": "record", "app_key": plan_data.get("app_key"), "record_id": plan_data.get("apply_id")},
+                "action": {"operation": operation, "executed": False},
+                "resource": target_resource,
                 "verification": None,
                 "normalized_payload": normalized_payload,
                 "blockers": plan_data.get("blockers", []),
+                "field_errors": field_errors,
                 "human_review": self._record_write_human_review_payload(operation, enabled=human_review),
             },
         }
         if output_profile == "verbose":
             response["data"]["debug"] = {
-                "legacy_plan": plan_data,
+                "preflight": plan_data,
             }
         return response
 
@@ -3002,31 +3082,107 @@ class RecordTools(ToolBase):
         normalized_payload: JSONObject,
         output_profile: str,
         human_review: bool,
+        preflight: JSONObject | None,
     ) -> JSONObject:
+        preflight_data = cast(JSONObject, preflight.get("data", {})) if isinstance(preflight, dict) else {}
+        validation = cast(JSONObject, preflight_data.get("validation", {}))
+        warnings_payload = validation.get("warnings", [])
+        warnings = [{"code": "PREFLIGHT_WARNING", "message": str(item)} for item in warnings_payload] if isinstance(warnings_payload, list) else []
         response: JSONObject = {
             "profile": raw_apply.get("profile"),
             "ws_id": raw_apply.get("ws_id"),
             "ok": bool(raw_apply.get("ok", True)),
             "request_route": raw_apply.get("request_route"),
-            "warnings": [],
+            "warnings": warnings,
             "output_profile": output_profile,
             "data": {
-                "action": {"operation": operation, "mode": "apply"},
+                "action": {"operation": operation, "executed": True},
                 "resource": raw_apply.get("resource"),
                 "verification": raw_apply.get("verification"),
                 "normalized_payload": normalized_payload,
                 "blockers": [],
+                "field_errors": [],
                 "human_review": self._record_write_human_review_payload(operation, enabled=human_review),
             },
         }
         if output_profile == "verbose":
-            response["data"]["debug"] = {
+            debug: JSONObject = {
                 "legacy_result": raw_apply.get("result"),
                 "status": raw_apply.get("status"),
                 "write_verified": raw_apply.get("write_verified"),
             }
+            if preflight_data:
+                debug["preflight"] = preflight_data
+            response["data"]["debug"] = debug
         return response
 
+    def _record_write_public_field_errors(self, plan_data: JSONObject) -> list[JSONObject]:
+        existing = plan_data.get("field_errors")
+        if isinstance(existing, list):
+            return [cast(JSONObject, item) for item in existing if isinstance(item, dict)]
+        validation = cast(JSONObject, plan_data.get("validation", {}))
+        invalid_fields = cast(list[JSONObject], validation.get("invalid_fields", []))
+        missing_required_fields = cast(list[JSONObject], validation.get("missing_required_fields", []))
+        readonly_or_system_fields = cast(list[JSONObject], validation.get("readonly_or_system_fields", []))
+        return self._record_write_field_errors(
+            invalid_fields=invalid_fields,
+            missing_required_fields=missing_required_fields,
+            readonly_or_system_fields=readonly_or_system_fields,
+        )
+
+    def _record_write_field_errors(
+        self,
+        *,
+        invalid_fields: list[JSONObject],
+        missing_required_fields: list[JSONObject],
+        readonly_or_system_fields: list[JSONObject],
+    ) -> list[JSONObject]:
+        errors: list[JSONObject] = []
+        for item in invalid_fields:
+            errors.append(
+                {
+                    "error_code": item.get("error_code") or "INVALID_FIELD_VALUE",
+                    "message": item.get("message") or "invalid field value",
+                    "field": item.get("field"),
+                    "location": item.get("location"),
+                    "expected_format": item.get("expected_format"),
+                    "received_value": item.get("received_value"),
+                }
+            )
+        for item in missing_required_fields:
+            errors.append(
+                {
+                    "error_code": "MISSING_REQUIRED_FIELD",
+                    "message": item.get("reason") or "required field not provided",
+                    "field": {
+                        "que_id": item.get("que_id"),
+                        "que_title": item.get("que_title"),
+                        "que_type": item.get("que_type"),
+                    },
+                    "location": "fields",
+                    "expected_format": None,
+                    "received_value": None,
+                }
+            )
+        for item in readonly_or_system_fields:
+            errors.append(
+                {
+                    "error_code": "READONLY_OR_SYSTEM_FIELD",
+                    "message": "field is readonly or system-managed",
+                    "field": {
+                        "que_id": item.get("que_id"),
+                        "que_title": item.get("que_title"),
+                        "que_type": item.get("que_type"),
+                        "readonly": item.get("readonly"),
+                        "system": item.get("system"),
+                    },
+                    "location": item.get("source") or "fields",
+                    "expected_format": None,
+                    "received_value": item.get("requested"),
+                }
+            )
+        return errors
+
     def _record_delete_many(self, *, profile: str, app_key: str, record_ids: list[int]) -> JSONObject:
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
@@ -3122,11 +3278,11 @@ class RecordTools(ToolBase):
         )
 
     def _resolve_field_from_answer_item(self, item: JSONObject, index: FieldIndex) -> FormField:
-        for key in ("queId", "que_id", "queTitle", "que_title"):
+        for key in ("queId", "que_id", "queTitle", "que_title", "field_id", "fieldId"):
             if key in item:
                 return self._resolve_field_selector(cast(str | int, item[key]), index, location="answers")
         raise RecordInputError(
-            message="answer item requires queId/que_id or queTitle/que_title",
+            message="answer item requires queId/que_id, queTitle/que_title, or field_id",
             error_code="MISSING_FIELD_SELECTOR",
             fix_hint="Provide a field selector in each answer item.",
         )
@@ -3452,7 +3608,10 @@ class RecordTools(ToolBase):
         for item in answers:
             if not isinstance(item, dict):
                 continue
-            selector = item.get("queId", item.get("que_id", item.get("queTitle", item.get("que_title"))))
+            selector = item.get(
+                "field_id",
+                item.get("fieldId", item.get("queId", item.get("que_id", item.get("queTitle", item.get("que_title"))))),
+            )
             if selector is None:
                 continue
             refs.append(self._resolve_write_plan_field_ref("answers", str(selector), index))