@josephyan/qingflow-cli 0.2.0-beta.66 → 0.2.0-beta.68

package/src/qingflow_mcp/tools/record_tools.py

@@ -620,7 +620,8 @@ class RecordTools(ToolBase):
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
 
         def runner(session_profile, context):
-            schema = self._get_form_schema(profile, context, app_key, force_refresh=False)
+            self._clear_record_schema_caches(profile=profile, app_key=app_key, clear_view_caches=True)
+            schema = self._get_form_schema(profile, context, app_key, force_refresh=True)
             question_relations = _collect_question_relations(schema)
             index = _build_applicant_top_level_field_index(schema)
             runtime_linked_field_ids = _collect_linked_required_field_ids(question_relations)
@@ -754,7 +755,8 @@ class RecordTools(ToolBase):
 
         def runner(session_profile, context):
             request_route = self._request_route_payload(context)
-            app_schema = self._get_form_schema(profile, context, app_key, force_refresh=False)
+            self._clear_record_schema_caches(profile=profile, app_key=app_key, clear_view_caches=True)
+            app_schema = self._get_form_schema(profile, context, app_key, force_refresh=True)
             question_relations = _collect_question_relations(app_schema)
             app_index = _build_applicant_top_level_field_index(app_schema)
             linked_field_ids = _collect_linked_required_field_ids(question_relations)
@@ -822,7 +824,7 @@ class RecordTools(ToolBase):
                     context,
                     app_key,
                     candidate,
-                    force_refresh=False,
+                    force_refresh=True,
                 )
                 index = cast(FieldIndex, browse_scope["index"])
                 browse_writable_field_ids = cast(set[int], browse_scope["writable_field_ids"])
@@ -1671,6 +1673,34 @@ class RecordTools(ToolBase):
                 cast(list[JSONValue], answer_list),
                 selected_fields,
             )
+            if self._record_get_needs_schema_refresh(
+                answer_list=cast(list[JSONValue], answer_list),
+                selected_fields=selected_fields,
+                record=row,
+                normalized_record=normalized_record,
+            ):
+                self._clear_record_schema_caches(
+                    profile=profile,
+                    app_key=app_key,
+                    resolved_view=resolved_view,
+                    clear_view_caches=True,
+                )
+                index = self._get_browse_field_index(profile, context, app_key, resolved_view, force_refresh=True)
+                selected_fields = (
+                    self._resolve_select_columns(
+                        normalized_columns,
+                        index,
+                        max_columns=len(normalized_columns),
+                        default_limit=MAX_RECORD_COLUMN_LIMIT,
+                    )
+                    if normalized_columns
+                    else list(index.by_id.values())
+                )
+                row = _build_flat_row(cast(list[JSONValue], answer_list), selected_fields, apply_id=record_id)
+                normalized_record, normalized_ambiguous_fields = _build_normalized_row_from_answers(
+                    cast(list[JSONValue], answer_list),
+                    selected_fields,
+                )
             warnings: list[JSONObject] = []
             warnings.extend(compatibility_warnings)
             warnings.extend(_view_filter_trust_warnings(resolved_view))
@@ -1735,6 +1765,7 @@ class RecordTools(ToolBase):
             view_key=None,
             view_name=None,
         )
+        preflight_used_force_refresh = self._record_preflight_used_force_refresh(raw_preflight)
         preflight_data = cast(JSONObject, raw_preflight.get("data", {}))
         normalized_payload: JSONObject = self._record_write_normalized_payload(
             operation="insert",
@@ -1761,7 +1792,7 @@ class RecordTools(ToolBase):
                 fields={},
                 submit_type=submit_type_value,
                 verify_write=verify_write,
-                force_refresh_form=False,
+                force_refresh_form=preflight_used_force_refresh,
             )
         except QingflowApiError as exc:
             self._raise_record_write_permission_error(
@@ -1805,6 +1836,7 @@ class RecordTools(ToolBase):
             fields=cast(JSONObject, fields or {}),
             force_refresh_form=False,
         )
+        preflight_used_force_refresh = self._record_preflight_used_force_refresh(raw_preflight)
         preflight_data = cast(JSONObject, raw_preflight.get("data", {}))
         normalized_payload = self._record_write_normalized_payload(
             operation="update",
@@ -1832,7 +1864,7 @@ class RecordTools(ToolBase):
                 fields={},
                 role=1,
                 verify_write=verify_write,
-                force_refresh_form=False,
+                force_refresh_form=preflight_used_force_refresh,
             )
         except QingflowApiError as exc:
             self._raise_record_write_permission_error(
@@ -1863,178 +1895,231 @@ class RecordTools(ToolBase):
     ) -> JSONObject:
         def runner(session_profile, context):
             request_route = self._request_route_payload(context)
-            try:
-                current_answers = self._load_record_answers_for_preflight(context, app_key=app_key, apply_id=record_id)
-            except QingflowApiError:
-                return {
-                    "profile": profile,
-                    "ws_id": session_profile.selected_ws_id,
-                    "ok": True,
-                    "request_route": request_route,
-                    "data": self._build_auto_view_blocked_preflight_data(
-                        app_key=app_key,
-                        record_id=record_id,
-                        blockers=["CURRENT_RECORD_CONTEXT_UNAVAILABLE"],
-                        warnings=[
-                            "update preflight could not load the current record; automatic view selection was blocked to avoid resolving lookup fields against a partial patch."
-                        ],
-                        recommended_next_actions=[
-                            "Retry after the record becomes readable in the current workspace/profile context.",
-                            "Call record_update_schema_get to inspect the overall writable field set for this record after context access is restored.",
-                        ],
-                        view_probe_summary=[],
-                    ),
-                }
+            def build_once(*, effective_force_refresh: bool) -> JSONObject:
+                try:
+                    current_answers = self._load_record_answers_for_preflight(context, app_key=app_key, apply_id=record_id)
+                except QingflowApiError:
+                    return {
+                        "profile": profile,
+                        "ws_id": session_profile.selected_ws_id,
+                        "ok": True,
+                        "request_route": request_route,
+                        "data": self._build_auto_view_blocked_preflight_data(
+                            app_key=app_key,
+                            record_id=record_id,
+                            blockers=["CURRENT_RECORD_CONTEXT_UNAVAILABLE"],
+                            warnings=[
+                                "update preflight could not load the current record; automatic view selection was blocked to avoid resolving lookup fields against a partial patch."
+                            ],
+                            recommended_next_actions=[
+                                "Retry after the record becomes readable in the current workspace/profile context.",
+                                "Call record_update_schema_get to inspect the overall writable field set for this record after context access is restored.",
+                            ],
+                            view_probe_summary=[],
+                        ),
+                    }
 
-            candidate_routes = self._candidate_update_views(profile, context, app_key)
-            probe_summary: list[JSONObject] = []
-            matched_any = False
-            first_blocked_plan: JSONObject | None = None
-            first_confirmation_plan: JSONObject | None = None
+                candidate_routes = self._candidate_update_views(profile, context, app_key)
+                probe_summary: list[JSONObject] = []
+                matched_any = False
+                matched_routes: list[AccessibleViewRoute] = []
+                first_blocked_plan: JSONObject | None = None
+                first_confirmation_plan: JSONObject | None = None
 
-            for candidate in candidate_routes:
-                matched_record = self._record_matches_accessible_view(
-                    context,
-                    current_answers,
-                    resolved_view=candidate,
-                )
-                if not matched_record:
-                    probe_summary.append(
-                        {
-                            "view_id": candidate.view_id,
-                            "name": candidate.name,
-                            "kind": candidate.kind,
-                            "matched_record": False,
-                            "writable_field_titles": [],
-                            "missing_field_titles": [],
-                            "context_complete": True,
-                            "selected": False,
-                        }
+                for candidate in candidate_routes:
+                    matched_record = self._record_matches_accessible_view(
+                        context,
+                        current_answers,
+                        resolved_view=candidate,
                     )
-                    continue
+                    if not matched_record:
+                        probe_summary.append(
+                            {
+                                "view_id": candidate.view_id,
+                                "name": candidate.name,
+                                "kind": candidate.kind,
+                                "matched_record": False,
+                                "writable_field_titles": [],
+                                "missing_field_titles": [],
+                                "context_complete": True,
+                                "selected": False,
+                            }
+                        )
+                        continue
 
-                matched_any = True
-                browse_scope = self._build_browse_write_scope(
-                    profile,
-                    context,
-                    app_key,
-                    candidate,
-                    force_refresh=force_refresh_form,
-                )
-                browse_index = cast(FieldIndex, browse_scope["index"])
-                browse_writable_field_ids = cast(set[int], browse_scope["writable_field_ids"])
-                candidate_titles = [
-                    field.que_title
-                    for field in self._schema_fields_for_mode(
+                    matched_any = True
+                    matched_routes.append(candidate)
+                    browse_scope = self._build_browse_write_scope(
                         profile,
                         context,
                         app_key,
-                        browse_index,
-                        schema_mode="browse",
-                        resolved_view=candidate,
+                        candidate,
+                        force_refresh=effective_force_refresh,
                     )
-                    if field.que_id in browse_writable_field_ids and field.que_title
-                ]
-                plan_data = self._build_record_write_preflight(
+                    browse_index = cast(FieldIndex, browse_scope["index"])
+                    browse_writable_field_ids = cast(set[int], browse_scope["writable_field_ids"])
+                    candidate_titles = [
+                        field.que_title
+                        for field in self._schema_fields_for_mode(
+                            profile,
+                            context,
+                            app_key,
+                            browse_index,
+                            schema_mode="browse",
+                            resolved_view=candidate,
+                        )
+                        if field.que_id in browse_writable_field_ids and field.que_title
+                    ]
+                    plan_data = self._build_record_write_preflight(
+                        profile=profile,
+                        context=context,
+                        operation="update",
+                        app_key=app_key,
+                        apply_id=record_id,
+                        answers=[],
+                        fields=fields,
+                        force_refresh_form=effective_force_refresh,
+                        view_id=candidate.view_id,
+                        list_type=None,
+                        view_key=None,
+                        view_name=None,
+                        existing_answers_override=current_answers,
+                    )
+                    readonly_entries = plan_data.get("validation", {}).get("readonly_or_system_fields", []) if isinstance(plan_data.get("validation"), dict) else []
+                    invalid_entries = plan_data.get("validation", {}).get("invalid_fields", []) if isinstance(plan_data.get("validation"), dict) else []
+                    missing_field_titles: list[str] = []
+                    for entry in readonly_entries:
+                        if not isinstance(entry, dict):
+                            continue
+                        title = _normalize_optional_text(entry.get("que_title"))
+                        if title and title not in missing_field_titles:
+                            missing_field_titles.append(title)
+                    for entry in invalid_entries:
+                        if not isinstance(entry, dict):
+                            continue
+                        if _normalize_optional_text(entry.get("error_code")) != "VIEW_SCOPE_FIELD_HIDDEN":
+                            continue
+                        field_payload = entry.get("field")
+                        if isinstance(field_payload, dict):
+                            title = _normalize_optional_text(field_payload.get("que_title"))
+                            if title and title not in missing_field_titles:
+                                missing_field_titles.append(title)
+                    candidate_summary: JSONObject = {
+                        "view_id": candidate.view_id,
+                        "name": candidate.name,
+                        "kind": candidate.kind,
+                        "matched_record": True,
+                        "writable_field_titles": candidate_titles,
+                        "missing_field_titles": missing_field_titles,
+                        "context_complete": True,
+                        "selected": False,
+                    }
+                    if plan_data.get("blockers"):
+                        confirmation_requests = plan_data.get("confirmation_requests")
+                        if (
+                            isinstance(confirmation_requests, list)
+                            and confirmation_requests
+                            and first_confirmation_plan is None
+                        ):
+                            selection = plan_data.get("selection")
+                            if not isinstance(selection, dict):
+                                selection = {}
+                                plan_data["selection"] = selection
+                            view_payload = selection.get("view")
+                            if not isinstance(view_payload, dict):
+                                view_payload = _accessible_view_payload(candidate)
+                                selection["view"] = view_payload
+                            view_payload["auto_selected"] = True
+                            view_payload["selection_source"] = "first_satisfying_accessible_view"
+                            candidate_summary["selected"] = True
+                            first_confirmation_plan = plan_data
+                        elif first_blocked_plan is None:
+                            first_blocked_plan = plan_data
+                        probe_summary.append(candidate_summary)
+                        continue
+
+                    selection = plan_data.get("selection")
+                    if not isinstance(selection, dict):
+                        selection = {}
+                        plan_data["selection"] = selection
+                    view_payload = selection.get("view")
+                    if not isinstance(view_payload, dict):
+                        view_payload = _accessible_view_payload(candidate)
+                        selection["view"] = view_payload
+                    view_payload["auto_selected"] = True
+                    view_payload["selection_source"] = "first_satisfying_accessible_view"
+                    candidate_summary["selected"] = True
+                    probe_summary.append(candidate_summary)
+                    plan_data["view_probe_summary"] = probe_summary
+                    return {
+                        "profile": profile,
+                        "ws_id": session_profile.selected_ws_id,
+                        "ok": True,
+                        "request_route": request_route,
+                        "data": plan_data,
+                    }
+
+                if not matched_any:
+                    blocked_data = self._build_auto_view_blocked_preflight_data(
+                        app_key=app_key,
+                        record_id=record_id,
+                        blockers=["NO_MATCHING_ACCESSIBLE_VIEW_FOR_RECORD"],
+                        warnings=[],
+                        recommended_next_actions=[
+                            "Use record_get or record_list to confirm the record still exists in the current workspace.",
+                            "Call record_update_schema_get to inspect whether any accessible view still matches this record.",
+                        ],
+                        view_probe_summary=probe_summary,
+                    )
+                    return {
+                        "profile": profile,
+                        "ws_id": session_profile.selected_ws_id,
+                        "ok": True,
+                        "request_route": request_route,
+                        "data": blocked_data,
+                    }
+
+                if first_confirmation_plan is not None:
+                    first_confirmation_plan["view_probe_summary"] = probe_summary
+                    return {
+                        "profile": profile,
+                        "ws_id": session_profile.selected_ws_id,
+                        "ok": True,
+                        "request_route": request_route,
+                        "data": first_confirmation_plan,
+                    }
+
+                union_plan = self._build_record_update_union_preflight(
                     profile=profile,
                     context=context,
-                    operation="update",
                     app_key=app_key,
-                    apply_id=record_id,
-                    answers=[],
+                    record_id=record_id,
                     fields=fields,
-                    force_refresh_form=force_refresh_form,
-                    view_id=candidate.view_id,
-                    list_type=None,
-                    view_key=None,
-                    view_name=None,
-                    existing_answers_override=current_answers,
+                    current_answers=current_answers,
+                    matched_routes=matched_routes,
+                    force_refresh_form=effective_force_refresh,
                 )
-                readonly_entries = plan_data.get("validation", {}).get("readonly_or_system_fields", []) if isinstance(plan_data.get("validation"), dict) else []
-                invalid_entries = plan_data.get("validation", {}).get("invalid_fields", []) if isinstance(plan_data.get("validation"), dict) else []
-                missing_field_titles: list[str] = []
-                for entry in readonly_entries:
-                    if not isinstance(entry, dict):
-                        continue
-                    title = _normalize_optional_text(entry.get("que_title"))
-                    if title and title not in missing_field_titles:
-                        missing_field_titles.append(title)
-                for entry in invalid_entries:
-                    if not isinstance(entry, dict):
-                        continue
-                    if _normalize_optional_text(entry.get("error_code")) != "VIEW_SCOPE_FIELD_HIDDEN":
-                        continue
-                    field_payload = entry.get("field")
-                    if isinstance(field_payload, dict):
-                        title = _normalize_optional_text(field_payload.get("que_title"))
-                        if title and title not in missing_field_titles:
-                            missing_field_titles.append(title)
-                candidate_summary: JSONObject = {
-                    "view_id": candidate.view_id,
-                    "name": candidate.name,
-                    "kind": candidate.kind,
-                    "matched_record": True,
-                    "writable_field_titles": candidate_titles,
-                    "missing_field_titles": missing_field_titles,
-                    "context_complete": True,
-                    "selected": False,
-                }
-                if plan_data.get("blockers"):
-                    confirmation_requests = plan_data.get("confirmation_requests")
-                    if (
-                        isinstance(confirmation_requests, list)
-                        and confirmation_requests
-                        and first_confirmation_plan is None
-                    ):
-                        selection = plan_data.get("selection")
-                        if not isinstance(selection, dict):
-                            selection = {}
-                            plan_data["selection"] = selection
-                        view_payload = selection.get("view")
-                        if not isinstance(view_payload, dict):
-                            view_payload = _accessible_view_payload(candidate)
-                            selection["view"] = view_payload
-                        view_payload["auto_selected"] = True
-                        view_payload["selection_source"] = "first_satisfying_accessible_view"
-                        candidate_summary["selected"] = True
-                        first_confirmation_plan = plan_data
-                    elif first_blocked_plan is None:
-                        first_blocked_plan = plan_data
-                    probe_summary.append(candidate_summary)
-                    continue
-
-                selection = plan_data.get("selection")
-                if not isinstance(selection, dict):
-                    selection = {}
-                    plan_data["selection"] = selection
-                view_payload = selection.get("view")
-                if not isinstance(view_payload, dict):
-                    view_payload = _accessible_view_payload(candidate)
-                    selection["view"] = view_payload
-                view_payload["auto_selected"] = True
-                view_payload["selection_source"] = "first_satisfying_accessible_view"
-                candidate_summary["selected"] = True
-                probe_summary.append(candidate_summary)
-                plan_data["view_probe_summary"] = probe_summary
-                return {
-                    "profile": profile,
-                    "ws_id": session_profile.selected_ws_id,
-                    "ok": True,
-                    "request_route": request_route,
-                    "data": plan_data,
-                }
+                if union_plan is not None:
+                    union_plan["view_probe_summary"] = probe_summary
+                    return {
+                        "profile": profile,
+                        "ws_id": session_profile.selected_ws_id,
+                        "ok": True,
+                        "request_route": request_route,
+                        "data": union_plan,
+                    }
 
-            if not matched_any:
                 blocked_data = self._build_auto_view_blocked_preflight_data(
                     app_key=app_key,
                     record_id=record_id,
-                    blockers=["NO_MATCHING_ACCESSIBLE_VIEW_FOR_RECORD"],
+                    blockers=["NO_SINGLE_VIEW_CAN_UPDATE_ALL_FIELDS"],
                     warnings=[],
                     recommended_next_actions=[
-                        "Use record_get or record_list to confirm the record still exists in the current workspace.",
-                        "Call record_update_schema_get to inspect whether any accessible view still matches this record.",
+                        "Call record_update_schema_get first to inspect the overall writable field set for this record.",
+                        "Reduce the update payload until all requested fields fit inside one matched accessible view.",
                     ],
                     view_probe_summary=probe_summary,
+                    template=first_blocked_plan,
                 )
                 return {
                     "profile": profile,
@@ -2044,37 +2129,180 @@ class RecordTools(ToolBase):
                     "data": blocked_data,
                 }
 
-            if first_confirmation_plan is not None:
-                first_confirmation_plan["view_probe_summary"] = probe_summary
-                return {
-                    "profile": profile,
-                    "ws_id": session_profile.selected_ws_id,
-                    "ok": True,
-                    "request_route": request_route,
-                    "data": first_confirmation_plan,
+            result = build_once(effective_force_refresh=force_refresh_form)
+            if (
+                not force_refresh_form
+                and self._record_preflight_suggests_stale_schema(cast(JSONObject, result.get("data", {})))
+            ):
+                self._clear_record_schema_caches(profile=profile, app_key=app_key, clear_view_caches=True)
+                result = build_once(effective_force_refresh=True)
+                cast(JSONObject, result.setdefault("data", {}))["schema_force_refreshed"] = True
+            return result
+
+        return self._run_record_tool(profile, runner)
+
+    def _build_record_update_union_preflight(
+        self,
+        *,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        app_key: str,
+        record_id: int,
+        fields: JSONObject,
+        current_answers: list[JSONObject],
+        matched_routes: list[AccessibleViewRoute],
+        force_refresh_form: bool,
+    ) -> JSONObject | None:
+        if len(matched_routes) < 2:
+            return None
+
+        union_writable_field_ids: set[int] = set()
+        union_visible_question_ids: set[int] = set()
+        matched_view_payloads: list[JSONObject] = []
+
+        for candidate in matched_routes:
+            browse_scope = self._build_browse_write_scope(
+                profile,
+                context,
+                app_key,
+                candidate,
+                force_refresh=force_refresh_form,
+            )
+            union_writable_field_ids.update(cast(set[int], browse_scope["writable_field_ids"]))
+            union_visible_question_ids.update(cast(set[int], browse_scope["visible_question_ids"]))
+            matched_view_payloads.append(_accessible_view_payload(candidate))
+
+        if not union_writable_field_ids and not union_visible_question_ids:
+            return None
+
+        plan_data = self._build_record_write_preflight(
+            profile=profile,
+            context=context,
+            operation="update",
+            app_key=app_key,
+            apply_id=record_id,
+            answers=[],
+            fields=fields,
+            force_refresh_form=force_refresh_form,
+            view_id=None,
+            list_type=None,
+            view_key=None,
+            view_name=None,
+            existing_answers_override=current_answers,
+        )
+
+        schema = self._get_form_schema(profile, context, app_key, force_refresh=force_refresh_form)
+        app_index = _build_applicant_top_level_field_index(schema)
+        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", []))
+        confirmation_requests = cast(list[JSONObject], plan_data.get("confirmation_requests", []))
+
+        if union_visible_question_ids:
+            invalid_fields.extend(
+                self._validate_view_scoped_subtable_answers(
+                    normalized_answers=cast(list[JSONObject], plan_data.get("normalized_answers", [])),
+                    full_index=app_index,
+                    selector_index=app_index,
+                    visible_question_ids=union_visible_question_ids,
+                )
+            )
+
+        existing_readonly_ids = {
+            str(_coerce_count(item.get("que_id")))
+            for item in readonly_or_system_fields
+            if isinstance(item, dict) and _coerce_count(item.get("que_id")) is not None
+        }
+        for entry in cast(list[JSONObject], plan_data.get("resolved_fields", [])):
+            if not isinstance(entry, dict) or not bool(entry.get("resolved")):
+                continue
+            que_id = _coerce_count(entry.get("que_id"))
+            if que_id is None or que_id in union_writable_field_ids or str(que_id) in existing_readonly_ids:
+                continue
+            readonly_or_system_fields.append(
+                {
+                    "que_id": 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"),
+                    "reason_code": "view_readonly",
                 }
+            )
 
-            blocked_data = self._build_auto_view_blocked_preflight_data(
-                app_key=app_key,
-                record_id=record_id,
-                blockers=["NO_SINGLE_VIEW_CAN_UPDATE_ALL_FIELDS"],
-                warnings=[],
-                recommended_next_actions=[
-                    "Call record_update_schema_get first to inspect the overall writable field set for this record.",
-                    "Reduce the update payload until all requested fields fit inside one matched accessible view.",
-                ],
-                view_probe_summary=probe_summary,
-                template=first_blocked_plan,
+        warnings_payload = validation.get("warnings")
+        warnings = list(warnings_payload) if isinstance(warnings_payload, list) else []
+        union_warning = "update preflight used the union of matched accessible views because no single matched view covered the full payload."
+        if union_warning not in warnings:
+            warnings.append(union_warning)
+
+        blockers: list[str] = []
+        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 fields that are not writable in any matched accessible view")
+        if confirmation_requests:
+            blockers.append("one or more lookup fields require confirmation before the write can execute")
+
+        validation["valid"] = (
+            not invalid_fields
+            and not missing_required_fields
+            and not readonly_or_system_fields
+            and not confirmation_requests
+        )
+        validation["invalid_fields"] = invalid_fields
+        validation["missing_required_fields"] = missing_required_fields
+        validation["readonly_or_system_fields"] = readonly_or_system_fields
+        validation["warnings"] = warnings
+        plan_data["validation"] = validation
+        plan_data["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,
+        )
+        plan_data["blockers"] = blockers
+
+        recommended_next_actions = (
+            list(plan_data.get("recommended_next_actions"))
+            if isinstance(plan_data.get("recommended_next_actions"), list)
+            else []
+        )
+        if readonly_or_system_fields:
+            recommended_next_actions.append(
+                "Remove fields that are not writable in any matched accessible view for this record."
             )
-            return {
-                "profile": profile,
-                "ws_id": session_profile.selected_ws_id,
-                "ok": True,
-                "request_route": request_route,
-                "data": blocked_data,
-            }
+        if invalid_fields:
+            recommended_next_actions.append("Fix invalid_fields before applying the write.")
+        if missing_required_fields:
+            recommended_next_actions.append("Fill missing required fields before applying the write.")
+        if confirmation_requests:
+            recommended_next_actions.append(
+                "Review confirmation_requests and retry with explicit ids/objects for the ambiguous lookup fields."
+            )
+        plan_data["recommended_next_actions"] = list(dict.fromkeys(str(item) for item in recommended_next_actions))
+
+        selection = plan_data.get("selection")
+        if not isinstance(selection, dict):
+            selection = {}
+        selection["view"] = {
+            "view_id": "virtual:matched_view_union",
+            "name": "Matched accessible views (union)",
+            "kind": "virtual",
+            "analysis_supported": False,
+            "auto_selected": True,
+            "selection_source": "matched_accessible_view_union",
+            "matched_views": matched_view_payloads,
+        }
+        plan_data["selection"] = selection
 
-        return self._run_record_tool(profile, runner)
+        if invalid_fields or missing_required_fields or readonly_or_system_fields:
+            return None
+        return plan_data
 
     def _build_auto_view_blocked_preflight_data(
         self,
@@ -2278,6 +2506,7 @@ class RecordTools(ToolBase):
                 view_key=view_key,
                 view_name=view_name,
             )
+            preflight_used_force_refresh = self._record_preflight_used_force_refresh(raw_preflight)
             preflight_data = cast(JSONObject, raw_preflight.get("data", {}))
             normalized_payload: JSONObject = self._record_write_normalized_payload(
                 operation="insert",
@@ -2304,7 +2533,7 @@ class RecordTools(ToolBase):
                     fields={},
                     submit_type=submit_type_value,
                     verify_write=verify_write,
-                    force_refresh_form=False,
+                    force_refresh_form=preflight_used_force_refresh,
                 )
             except QingflowApiError as exc:
                 self._raise_record_write_permission_error(
@@ -2351,6 +2580,7 @@ class RecordTools(ToolBase):
                 view_key=view_key,
                 view_name=view_name,
             )
+            preflight_used_force_refresh = self._record_preflight_used_force_refresh(raw_preflight)
             preflight_data = cast(JSONObject, raw_preflight.get("data", {}))
             normalized_payload = self._record_write_normalized_payload(
                 operation="update",
@@ -2378,7 +2608,7 @@ class RecordTools(ToolBase):
                     fields={},
                     role=1,
                     verify_write=verify_write,
-                    force_refresh_form=False,
+                    force_refresh_form=preflight_used_force_refresh,
                 )
             except QingflowApiError as exc:
                 self._raise_record_write_permission_error(
@@ -4452,6 +4682,23 @@ class RecordTools(ToolBase):
                 view_key=view_key,
                 view_name=view_name,
             )
+            if not force_refresh_form and self._record_preflight_suggests_stale_schema(plan_data):
+                self._clear_record_schema_caches(profile=profile, app_key=app_key, clear_view_caches=True)
+                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=True,
+                    view_id=view_id,
+                    list_type=list_type,
+                    view_key=view_key,
+                    view_name=view_name,
+                )
+                plan_data["schema_force_refreshed"] = True
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -5777,6 +6024,84 @@ class RecordTools(ToolBase):
         self._view_config_cache[cache_key] = normalized
         return normalized
 
+    def _clear_record_schema_caches(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        resolved_view: AccessibleViewRoute | None = None,
+        clear_view_caches: bool = False,
+    ) -> None:
+        view_key = (
+            resolved_view.view_selection.view_key
+            if resolved_view is not None and resolved_view.view_selection is not None
+            else None
+        )
+        for cache_key in list(self._form_cache.keys()):
+            cache_profile, cache_scope, *_ = cache_key
+            if cache_profile != profile:
+                continue
+            if cache_scope == app_key:
+                self._form_cache.pop(cache_key, None)
+                continue
+            if view_key is not None and cache_scope == f"view:{view_key}":
+                self._form_cache.pop(cache_key, None)
+                continue
+            if clear_view_caches and isinstance(cache_scope, str) and cache_scope.startswith("view:"):
+                self._form_cache.pop(cache_key, None)
+        self._applicant_node_cache.pop((profile, app_key), None)
+        self._view_list_cache.pop((profile, app_key), None)
+        if view_key is not None:
+            self._view_config_cache.pop((profile, view_key), None)
+        elif clear_view_caches:
+            for cache_key in [item for item in self._view_config_cache.keys() if item[0] == profile]:
+                self._view_config_cache.pop(cache_key, None)
+
+    def _record_preflight_used_force_refresh(self, raw_preflight: JSONObject) -> bool:
+        data = raw_preflight.get("data")
+        return bool(isinstance(data, dict) and data.get("schema_force_refreshed"))
+
+    def _record_preflight_suggests_stale_schema(self, plan_data: JSONObject) -> bool:
+        validation = plan_data.get("validation")
+        invalid_fields = validation.get("invalid_fields") if isinstance(validation, dict) else None
+        if not isinstance(invalid_fields, list):
+            return False
+        return any(self._field_error_suggests_stale_schema(entry) for entry in invalid_fields if isinstance(entry, dict))
+
+    def _field_error_suggests_stale_schema(self, entry: JSONObject) -> bool:
+        error_code = _normalize_optional_text(entry.get("error_code"))
+        if error_code == "VIEW_SCOPE_FIELD_HIDDEN":
+            return False
+        if error_code == "FIELD_NOT_FOUND":
+            return True
+        expected_format = entry.get("expected_format")
+        if isinstance(expected_format, dict) and _normalize_optional_text(expected_format.get("kind")) == "subtable_rows":
+            return True
+        location = _normalize_optional_text(entry.get("location"))
+        return bool(location and "[" in location and "." in location)
+
+    def _record_get_needs_schema_refresh(
+        self,
+        *,
+        answer_list: list[JSONValue],
+        selected_fields: list[FormField],
+        record: JSONObject,
+        normalized_record: JSONObject,
+    ) -> bool:
+        for field in selected_fields:
+            if field.que_type not in SUBTABLE_QUE_TYPES:
+                continue
+            answer = _find_answer_for_field(answer_list, field)
+            if not isinstance(answer, dict):
+                continue
+            if not _subtable_answer_has_unmapped_cells(answer, field):
+                continue
+            if _subtable_output_effectively_empty(record.get(field.que_title)) or _subtable_output_effectively_empty(
+                normalized_record.get(field.que_title)
+            ):
+                return True
+        return False
+
     def _get_system_browse_schema(
         self,
         profile: str,
@@ -9943,6 +10268,45 @@ def _normalize_subtable_answer_value_for_output(answer: JSONObject, field: FormF
     return normalized_rows or None
 
 
+def _subtable_answer_has_unmapped_cells(answer: JSONObject, field: FormField) -> bool:
+    table_values = answer.get("tableValues")
+    if not isinstance(table_values, list) or not table_values:
+        return False
+    subtable_column_ids = {
+        cast(int, item["que_id"])
+        for item in _subtable_columns_for_field(field)
+        if isinstance(item.get("que_id"), int)
+    }
+    if not subtable_column_ids:
+        return False
+    for raw_row in table_values:
+        if not isinstance(raw_row, list):
+            continue
+        for cell in raw_row:
+            if not isinstance(cell, dict):
+                continue
+            que_id = _coerce_count(cell.get("queId"))
+            if que_id is None or que_id in subtable_column_ids:
+                continue
+            if _answer_has_meaningful_content(cell):
+                return True
+    return False
+
+
+def _subtable_output_effectively_empty(value: JSONValue) -> bool:
+    if value in (None, "", [], {}):
+        return True
+    if isinstance(value, dict):
+        rows = value.get("rows")
+        if not isinstance(rows, list) or not rows:
+            return True
+        return all(
+            isinstance(row, dict) and set(row.keys()) <= {"__row_id__"}
+            for row in rows
+        )
+    return False
+
+
 def _canonicalize_answer_value_for_compare(answer: JSONObject | None, field: FormField | None) -> JSONValue:
     if answer is None or field is None:
         return None