@qingflow-tech/qingflow-cli 1.1.42 → 1.1.43-beta.1

package/src/qingflow_mcp/builder_facade/app_form.py

@@ -0,0 +1,2836 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+import json
+import re
+from typing import Any, Iterable
+
+from ..app_form_compat import normalize_app_form_declaration, validate_app_form_create_icon
+from ..errors import QingflowApiError, is_auth_like_error
+from ..json_types import JSONObject
+from ..solution.compiler.form_compiler import build_options, build_question, default_member_auth
+from ..solution.compiler.icon_utils import encode_workspace_icon
+from ..solution.spec_models import FieldType
+from ..tools.app_tools import AppTools
+from ..tools.package_tools import PackageTools
+from .app_form_schema import AppFormContractError, AppFormSchemaContext, AppFormSchemaRegistry
+from .service import (
+    _compile_code_block_binding_fields,
+    _compile_q_linker_binding_fields,
+    _field_to_question,
+    _normalize_and_validate_code_block_fields_for_write,
+)
+
+
+API_VERSION = "builder.qingflow.com/v1alpha1"
+QUE_TYPE_TO_CANONICAL = {
+    2: "text",
+    3: "long_text",
+    5: "member",
+    6: "email",
+    7: "phone",
+    9: "link",
+    10: "single_choice",
+    11: "single_select",
+    12: "multi_select",
+    13: "attachment",
+    18: "subtable",
+    19: "data_relation",
+    20: "q_linker",
+    21: "address",
+    22: "department",
+    25: "relation",
+    26: "code_block",
+}
+CANONICAL_TO_QUE_TYPE = {
+    "text": 2,
+    "long_text": 3,
+    "number": 8,
+    "amount": 8,
+    "link": 9,
+    "date": 4,
+    "datetime": 4,
+    "member": 5,
+    "department": 22,
+    "single_choice": 10,
+    "single_select": 11,
+    "multi_select": 12,
+    "phone": 7,
+    "email": 6,
+    "address": 21,
+    "attachment": 13,
+    "q_linker": 20,
+    "code_block": 26,
+    "data_relation": 19,
+    "relation": 25,
+    "subtable": 18,
+}
+SUBFIELD_TYPES = {
+    "text",
+    "long_text",
+    "number",
+    "link",
+    "date",
+    "phone",
+    "email",
+    "single_choice",
+    "single_select",
+    "multi_select",
+    "attachment",
+    "data_relation",
+    "relation",
+    "member",
+    "department",
+}
+CHOICE_TYPES = {"single_choice", "single_select", "multi_select"}
+INTEGRATION_TARGET_TYPES = {
+    "text",
+    "long_text",
+    "number",
+    "amount",
+    "date",
+    "datetime",
+    "single_choice",
+    "single_select",
+    "multi_select",
+}
+AGGREGATION_TO_BACKEND = {
+    "sum": 0,
+    "average": 1,
+    "max": 2,
+    "min": 3,
+    "first": 4,
+    "last": 5,
+    "filled_count": 6,
+    "empty_count": 7,
+    "count": 8,
+}
+REPEAT_PERIOD_TO_BACKEND = {"none": 0, "day": 1, "week": 2, "month": 3, "year": 4}
+DATE_FORMAT_TO_BACKEND = {"year": 1, "year_month": 2, "year_month_day": 3}
+JUDGE_TYPE_TO_BACKEND = {
+    "equal": 0,
+    "not_equal": 1,
+    "contains": 2,
+    "not_contains": 3,
+    "greater_than": 4,
+    "greater_or_equal": 5,
+    "less_than": 6,
+    "less_or_equal": 7,
+    "dynamic_range": 8,
+    "equal_any": 9,
+    "not_equal_any": 10,
+    "is_empty": 11,
+    "is_not_empty": 12,
+    "belongs_to": 13,
+    "not_belongs_to": 14,
+    "subordinate_to": 15,
+    "not_subordinate_to": 16,
+    "subordinate_included": 17,
+    "subordinate_not_included": 18,
+    "fuzzy_match": 19,
+    "contains_any": 20,
+    "contains_all": 21,
+    "decimal_range": 22,
+}
+BACKEND_TO_JUDGE_TYPE = {value: key for key, value in JUDGE_TYPE_TO_BACKEND.items()}
+EMPTY_OPERATORS = {"is_empty", "is_not_empty"}
+APP_FORM_MAX_BYTES = 2 * 1024 * 1024
+APP_FORM_MAX_DEPTH = 64
+Q_LINKER_VALUE_REFERENCE_RE = re.compile(r"\{(?P<name>[^{}$]+)\$\$(?P<token>[^{}$]+)\$\$\}")
+
+
+@dataclass(slots=True)
+class AppFormFailure(Exception):
+    error_code: str
+    message: str
+    phase: str
+    status: str = "failed"
+    details: JSONObject | None = None
+
+
+def _positive_int(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    try:
+        result = int(value)
+    except (TypeError, ValueError):
+        return None
+    return result if result > 0 else None
+
+
+def _without_none(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {key: _without_none(item) for key, item in value.items() if item is not None}
+    if isinstance(value, list):
+        return [_without_none(item) for item in value]
+    return value
+
+
+def _selector(que_id: Any, name: Any) -> JSONObject:
+    result: JSONObject = {}
+    normalized_id = _positive_int(que_id)
+    normalized_name = str(name or "").strip()
+    if normalized_id is not None:
+        result["queId"] = normalized_id
+    if normalized_name:
+        result["name"] = normalized_name
+    return result
+
+
+def _require_selector(que_id: Any, name: Any, *, message: str, details: JSONObject | None = None) -> JSONObject:
+    result = _selector(que_id, name)
+    if not result:
+        raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", message, "NORMALIZE", details=details)
+    return result
+
+
+def _iter_fields(body: Iterable[Any]) -> Iterable[JSONObject]:
+    for block in body:
+        if not isinstance(block, dict):
+            continue
+        rows = [block] if block.get("kind") == "row" else block.get("rows") or []
+        for row in rows:
+            if not isinstance(row, dict):
+                continue
+            for field in row.get("fields") or []:
+                if isinstance(field, dict):
+                    yield field
+
+
+def _iter_field_tree(fields: Iterable[Any]) -> Iterable[JSONObject]:
+    for field in fields:
+        if not isinstance(field, dict):
+            continue
+        yield field
+        yield from _iter_field_tree(field.get("subfields") or [])
+
+
+def _iter_field_pairs(fields: Iterable[Any], internal_fields: Iterable[Any]) -> Iterable[tuple[JSONObject, JSONObject]]:
+    for field, internal in zip(fields, internal_fields):
+        if not isinstance(field, dict) or not isinstance(internal, dict):
+            continue
+        yield field, internal
+        yield from _iter_field_pairs(field.get("subfields") or [], internal.get("subfields") or [])
+
+
+def _semantic(value: Any) -> Any:
+    if isinstance(value, dict):
+        identity_keys = {"packageId", "queId", "sectionId", "attachId", "aliasId", "id"}
+        return {
+            key: _semantic(item)
+            for key, item in sorted(value.items())
+            if key not in identity_keys
+            and not (key == "sort" and isinstance(item, dict) and item.get("enabled") is False)
+        }
+    if isinstance(value, list):
+        if value and all(isinstance(item, dict) and {"fileName", "fileUrl"}.issubset(item) for item in value):
+            return sorted((_semantic(item) for item in value), key=lambda item: (item["fileName"], item["fileUrl"]))
+        return [_semantic(item) for item in value]
+    return value
+
+
+def _canonical_equal(left: JSONObject, right: JSONObject) -> bool:
+    return _semantic(left) == _semantic(right)
+
+
+def _layout_semantic(body: list[Any]) -> list[JSONObject]:
+    def row_layout(row: Any) -> JSONObject:
+        fields = row.get("fields") if isinstance(row, dict) else []
+        return {
+            "fields": [
+                {
+                    "name": field.get("name"),
+                    "type": field.get("type"),
+                    "width": field.get("width"),
+                }
+                for field in fields or []
+                if isinstance(field, dict)
+            ]
+        }
+
+    result = []
+    for block in body:
+        if not isinstance(block, dict):
+            continue
+        if block.get("kind") == "section":
+            result.append(
+                {
+                    "kind": "section",
+                    "title": block.get("title"),
+                    "rows": [row_layout(row) for row in block.get("rows") or []],
+                }
+            )
+        else:
+            result.append({"kind": "row", **row_layout(block)})
+    return result
+
+
+def _deep_overlay(current: JSONObject, declared: JSONObject) -> JSONObject:
+    result = deepcopy(current)
+    for key, value in declared.items():
+        if isinstance(value, dict) and isinstance(result.get(key), dict):
+            result[key] = _deep_overlay(result[key], value)
+        else:
+            result[key] = deepcopy(value)
+    return result
+
+
+def _field_semantic(value: JSONObject) -> Any:
+    return _semantic({key: item for key, item in value.items() if key != "width"})
+
+
+def _validate_payload_limits(value: Any) -> None:
+    stack = [(value, 1)]
+    while stack:
+        item, depth = stack.pop()
+        if depth > APP_FORM_MAX_DEPTH:
+            raise AppFormContractError(
+                "INVALID_SPEC",
+                f"AppForm payload exceeds maximum nesting depth {APP_FORM_MAX_DEPTH}",
+                path="/",
+                details={"maxDepth": APP_FORM_MAX_DEPTH, "actualDepth": depth},
+            )
+        if isinstance(item, dict):
+            stack.extend((child, depth + 1) for child in item.values())
+        elif isinstance(item, list):
+            stack.extend((child, depth + 1) for child in item)
+    encoded = json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    if len(encoded) > APP_FORM_MAX_BYTES:
+        raise AppFormContractError(
+            "INVALID_SPEC",
+            f"AppForm payload exceeds {APP_FORM_MAX_BYTES} bytes",
+            path="/",
+            details={"maxBytes": APP_FORM_MAX_BYTES, "actualBytes": len(encoded)},
+        )
+
+
+class AppFormNormalizer:
+    def from_backend(self, *, context: AppFormSchemaContext, app_key: str, form: JSONObject) -> JSONObject:
+        relations = [item for item in form.get("questionRelations") or [] if isinstance(item, dict)]
+        field_names = self._field_index(form)
+        title_id = _positive_int(form.get("dataTitleQueId"))
+        cover_id = _positive_int(form.get("dataCoverQueId"))
+        body: list[JSONObject] = []
+        for row in form.get("formQues") or []:
+            if not isinstance(row, list) or not row:
+                continue
+            if len(row) == 1 and isinstance(row[0], dict) and _positive_int(row[0].get("queType")) == 24:
+                section = row[0]
+                section_id = _positive_int(section.get("queId")) or _positive_int(section.get("sectionId"))
+                if section_id is None:
+                    raise AppFormFailure("UNSUPPORTED_LAYOUT", "existing section has no stable ID", "NORMALIZE")
+                rows = [
+                    {"fields": [self._field(question, relations, title_id, cover_id, field_names) for question in inner if isinstance(question, dict)]}
+                    for inner in section.get("innerQuestions") or []
+                    if isinstance(inner, list) and inner
+                ]
+                if not rows:
+                    raise AppFormFailure("UNSUPPORTED_LAYOUT", "existing section is empty", "NORMALIZE")
+                body.append({"kind": "section", "sectionId": str(section_id), "title": str(section.get("queTitle") or ""), "rows": rows})
+            else:
+                body.append({"kind": "row", "fields": [self._field(question, relations, title_id, cover_id, field_names) for question in row if isinstance(question, dict)]})
+        resource = {
+            "apiVersion": context.api_version,
+            "appKey": app_key,
+            "spec": {
+                "appName": str(form.get("formTitle") or ""),
+                "description": form.get("formDesc") or None,
+                "theme": form.get("formTheme"),
+                "style": self._style(form.get("formStyle")),
+                "attachments": self._attachments(form.get("formAttach")),
+                "serialNumber": self._serial_number(form.get("serialNumType"), form.get("serialNumConfig")),
+                "body": body,
+            },
+        }
+        return resource
+
+    def _field(
+        self,
+        question: JSONObject,
+        relations: list[JSONObject],
+        title_id: int | None,
+        cover_id: int | None,
+        field_names: dict[int, str],
+    ) -> JSONObject:
+        que_id = _positive_int(question.get("queId"))
+        if que_id is None:
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_CONFIG",
+                "existing business field has no stable queId",
+                "NORMALIZE",
+                details={"name": question.get("queTitle"), "queType": question.get("queType")},
+            )
+        que_type = _positive_int(question.get("queType"))
+        if que_type == 4:
+            field_type = "datetime" if question.get("dateType") not in {None, 0} else "date"
+        elif que_type == 8:
+            field_type = "amount" if question.get("canDecimal") is True else "number"
+        else:
+            field_type = QUE_TYPE_TO_CANONICAL.get(que_type or -1)
+        if field_type is None:
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_TYPE",
+                f"unsupported backend field type: {que_type}",
+                "NORMALIZE",
+                details={"queId": que_id, "queType": que_type},
+            )
+        field: JSONObject = {
+            "name": str(question.get("queTitle") or ""),
+            "type": field_type,
+            "required": bool(question.get("required")),
+            "description": question.get("queHint") or None,
+        }
+        if que_id is not None:
+            field["queId"] = que_id
+        width = _positive_int(question.get("queWidth"))
+        if width is not None:
+            field["width"] = width
+        if title_id is not None and que_id == title_id:
+            field["dataTitle"] = True
+        if cover_id is not None and que_id == cover_id:
+            field["dataCover"] = True
+        if field_type in CHOICE_TYPES:
+            options = [str(item.get("optValue")) for item in question.get("options") or [] if isinstance(item, dict) and item.get("optValue") is not None]
+            if not options and field_type == "single_choice":
+                options = ["是", "否"]
+            field["config"] = {"options": options}
+        elif field_type == "department":
+            scope = question.get("deptSelectScope") if isinstance(question.get("deptSelectScope"), dict) else {}
+            departments = scope.get("depart") if isinstance(scope.get("depart"), list) else []
+            if departments:
+                field["config"] = {
+                    "departmentScope": {
+                        "mode": "custom",
+                        "departments": [
+                            _without_none({"deptId": _positive_int(item.get("deptId") or item.get("id")), "deptName": item.get("deptName") or item.get("name")})
+                            for item in departments
+                            if isinstance(item, dict) and _positive_int(item.get("deptId") or item.get("id")) is not None
+                        ],
+                        "includeSubDeparts": bool(scope.get("includeSubDeparts")),
+                    }
+                }
+            else:
+                field["config"] = {"departmentScope": {"mode": "all", "includeSubDeparts": bool(scope.get("includeSubDeparts"))}}
+        elif field_type == "relation":
+            reference = question.get("referenceConfig") if isinstance(question.get("referenceConfig"), dict) else {}
+            refer_questions = [item for item in reference.get("referQuestions") or [] if isinstance(item, dict)]
+            display_id = _positive_int(reference.get("referQueId"))
+            display = next((item for item in refer_questions if _positive_int(item.get("queId")) == display_id), None)
+            visible = [item for item in refer_questions if _positive_int(item.get("queAuth")) != 2]
+            field["config"] = _without_none(
+                {
+                    "targetAppKey": reference.get("referAppKey"),
+                    "relationMode": "multiple" if _positive_int(reference.get("optionalDataNum")) not in {None, 1} else "single",
+                    "displayField": _require_selector(
+                        display_id,
+                        (display or {}).get("queTitle"),
+                        message="relation display field cannot be normalized",
+                        details={"queId": que_id},
+                    ),
+                    "visibleFields": [
+                        _require_selector(
+                            item.get("queId"),
+                            item.get("queTitle"),
+                            message="relation visible field cannot be normalized",
+                            details={"queId": que_id},
+                        )
+                        for item in visible
+                    ],
+                }
+            )
+        elif field_type == "q_linker":
+            field["config"] = {"qLinkerBinding": self._q_linker_binding(question, relations, field_names)}
+        elif field_type == "code_block":
+            field["config"] = {"codeBlockBinding": self._code_block_binding(question, relations, field_names)}
+        elif field_type == "data_relation":
+            field["config"] = self._data_relation_config(question, relations)
+        elif field_type == "subtable":
+            field["subfields"] = [
+                self._field(item, relations, None, None, field_names)
+                for item in question.get("subQuestions") or []
+                if isinstance(item, dict)
+            ]
+            for subfield in field["subfields"]:
+                subfield.pop("width", None)
+                subfield.pop("dataTitle", None)
+                subfield.pop("dataCover", None)
+        return field
+
+    @staticmethod
+    def _style(value: Any) -> JSONObject | None:
+        if not isinstance(value, dict) or not any(value.get(key) is not None for key in ("bgImage", "bgColor", "opacity", "headerImage", "headerColor", "fontColor")):
+            return None
+        return {key: value.get(key) for key in ("bgImage", "bgColor", "opacity", "headerImage", "headerColor", "fontColor") if key in value}
+
+    @staticmethod
+    def _attachments(value: Any) -> list[JSONObject]:
+        result = [
+            _without_none(
+                {
+                    "attachId": _positive_int(item.get("attachId") or item.get("id")),
+                    "fileName": item.get("fileName") or item.get("name"),
+                    "fileUrl": item.get("fileUrl") or item.get("url"),
+                }
+            )
+            for item in value or []
+            if isinstance(item, dict) and (item.get("fileName") or item.get("name")) and (item.get("fileUrl") or item.get("url"))
+        ]
+        return sorted(result, key=lambda item: (item.get("attachId", 0), item["fileName"], item["fileUrl"]))
+
+    @staticmethod
+    def _serial_number(serial_type: Any, value: Any) -> JSONObject:
+        if _positive_int(serial_type) != 2:
+            return {"mode": "default"}
+        type_names = {1: "auto_count", 2: "submit_datetime", 3: "fixed_text", 4: "field"}
+        repeat_names = {item: name for name, item in REPEAT_PERIOD_TO_BACKEND.items()}
+        date_names = {item: name for name, item in DATE_FORMAT_TO_BACKEND.items()}
+        components = []
+        for item in value or []:
+            if not isinstance(item, dict) or _positive_int(item.get("type")) not in type_names:
+                continue
+            kind = type_names[_positive_int(item.get("type")) or 1]
+            component: JSONObject = _without_none({"id": _positive_int(item.get("id")), "type": kind})
+            if kind == "auto_count":
+                component.update({"length": int(item.get("length") or 3), "repeatPeriod": repeat_names.get(item.get("repeatPeriod"), "none")})
+            elif kind == "submit_datetime":
+                component["dateFormat"] = date_names.get(item.get("dateFormat"), "year_month_day")
+            elif kind == "fixed_text":
+                component["value"] = str(item.get("customTitle") or "")
+            else:
+                component["field"] = _selector(item.get("queId"), item.get("queTitle"))
+                if item.get("dateFormat") is not None:
+                    component["dateFormat"] = date_names.get(item.get("dateFormat"), "year_month_day")
+            components.append(component)
+        return {"mode": "custom", "components": components}
+
+    @staticmethod
+    def _field_index(question: JSONObject) -> dict[int, str]:
+        result: dict[int, str] = {}
+        for row in question.get("formQues") or []:
+            for item in row if isinstance(row, list) else []:
+                if not isinstance(item, dict):
+                    continue
+                if _positive_int(item.get("queType")) == 24:
+                    for inner in item.get("innerQuestions") or []:
+                        for nested in inner if isinstance(inner, list) else []:
+                            if isinstance(nested, dict) and _positive_int(nested.get("queId")):
+                                result[_positive_int(nested.get("queId")) or 0] = str(nested.get("queTitle") or "")
+                elif _positive_int(item.get("queId")):
+                    result[_positive_int(item.get("queId")) or 0] = str(item.get("queTitle") or "")
+        return result
+
+    @staticmethod
+    def _q_linker_binding(question: JSONObject, relations: list[JSONObject], field_names: dict[int, str]) -> JSONObject:
+        config = question.get("remoteLookupConfig") if isinstance(question.get("remoteLookupConfig"), dict) else {}
+        source_id = _positive_int(question.get("queId"))
+        outputs = []
+        for alias in config.get("resultFormatPath") or []:
+            if not isinstance(alias, dict):
+                continue
+            name = str(alias.get("aliasName") or "")
+            relation = next(
+                (
+                    item
+                    for item in relations
+                    if _positive_int((item.get("aliasConfig") or {}).get("queId")) == source_id
+                    and str((item.get("aliasConfig") or {}).get("qlinkerAlias") or item.get("qlinkerAlias") or "") == name
+                ),
+                {},
+            )
+            outputs.append(
+                _without_none(
+                    {
+                        "alias": name,
+                        "path": str(alias.get("aliasPath") or ""),
+                        "aliasId": _positive_int(alias.get("aliasId")) or _positive_int((relation.get("aliasConfig") or {}).get("aliasId")),
+                        "targetField": _require_selector(
+                            relation.get("queId"),
+                            relation.get("queTitle") or field_names.get(_positive_int(relation.get("queId")) or -1),
+                            message="Q-Linker output target cannot be normalized",
+                            details={"queId": source_id, "alias": name},
+                        ),
+                    }
+                )
+            )
+        type_to_source = {"headers": "header", "queryParams": "query_param", "urlEncodedValue": "url_encoded"}
+        inputs = []
+        static: dict[str, list[JSONObject]] = {"headers": [], "queryParams": [], "urlEncodedValue": []}
+        for key, source in type_to_source.items():
+            for item in config.get(key) or []:
+                if not isinstance(item, dict):
+                    continue
+                if _positive_int(item.get("type")) == 2:
+                    inputs.append({"field": _selector(item.get("value"), None), "key": str(item.get("key") or ""), "source": source})
+                else:
+                    static[key].append({"key": str(item.get("key") or ""), "value": item.get("value")})
+        request_values = {
+            "url": config.get("url"),
+            "jsonValue": config.get("jsonValue"),
+            "xmlValue": config.get("xmlValue"),
+        }
+        json_path_inputs: dict[str, JSONObject] = {}
+        for request_key, raw_value in tuple(request_values.items()):
+            if not isinstance(raw_value, str):
+                continue
+
+            def replace_reference(match: re.Match[str]) -> str:
+                name = match.group("name").strip()
+                if name:
+                    json_path_inputs.setdefault(
+                        name,
+                        {"field": {"name": name}, "key": name, "source": "json_path"},
+                    )
+                return "{{" + name + "}}"
+
+            request_values[request_key] = Q_LINKER_VALUE_REFERENCE_RE.sub(replace_reference, raw_value)
+        inputs.extend(json_path_inputs.values())
+        request = _without_none(
+            {
+                "url": request_values["url"],
+                "method": config.get("method") or "GET",
+                **static,
+                "bodyType": {1: "url_encoded", 2: "json", 3: "xml"}.get(_positive_int(config.get("bodyType")) or 1, "url_encoded"),
+                "jsonValue": request_values["jsonValue"],
+                "xmlValue": request_values["xmlValue"],
+                "resultType": {1: "json", 2: "xml", 3: "text"}.get(_positive_int(config.get("resultType")) or 1, "json"),
+                "autoTrigger": bool(question.get("autoTrigger")),
+                "customButtonTextEnabled": bool(question.get("customBtnTextStatus")),
+                "customButtonText": str(question.get("customBtnText") or ""),
+                "insertValueDirectly": bool(config.get("beingInsertValueDirectly")),
+                "hideOnForm": bool(config.get("beingHideOnForm")),
+            }
+        )
+        return {"inputs": inputs, "request": request, "outputs": outputs}
+
+    @staticmethod
+    def _code_block_binding(question: JSONObject, relations: list[JSONObject], field_names: dict[int, str]) -> JSONObject:
+        config = question.get("codeBlockConfig") if isinstance(question.get("codeBlockConfig"), dict) else {}
+        source_id = _positive_int(question.get("queId"))
+        outputs = []
+        for alias in config.get("resultAliasPath") or []:
+            if not isinstance(alias, dict):
+                continue
+            name = str(alias.get("aliasName") or "")
+            relation = next(
+                (
+                    item
+                    for item in relations
+                    if _positive_int((item.get("aliasConfig") or {}).get("queId")) == source_id
+                    and str((item.get("aliasConfig") or {}).get("qlinkerAlias") or "") == name
+                ),
+                {},
+            )
+            output = {
+                "alias": name,
+                "path": str(alias.get("aliasPath") or ""),
+                "targetField": _require_selector(
+                    relation.get("queId"),
+                    relation.get("queTitle") or field_names.get(_positive_int(relation.get("queId")) or -1),
+                    message="code block output target cannot be normalized",
+                    details={"queId": source_id, "alias": name},
+                ),
+            }
+            if _positive_int(alias.get("aliasId")):
+                output["aliasId"] = _positive_int(alias.get("aliasId"))
+            outputs.append(output)
+        code = str(config.get("codeContent") or "")
+        inputs = []
+        lines = code.splitlines()
+        while lines and lines[0].strip().startswith("const ") and "qf_field.{" in lines[0]:
+            line = lines.pop(0).strip()
+            var = line[6:].split("=", 1)[0].strip()
+            name = line.split("qf_field.{", 1)[1].split("$$", 1)[0]
+            inputs.append({"field": {"name": name}, "var": var})
+        return _without_none(
+            {
+                "inputs": inputs,
+                "code": "\n".join(lines).lstrip("\n"),
+                "autoTrigger": question.get("autoTrigger"),
+                "customButtonTextEnabled": question.get("customBtnTextStatus"),
+                "customButtonText": question.get("customBtnText"),
+                "hideOnForm": config.get("beingHideOnForm"),
+                "outputs": outputs,
+            }
+        )
+
+    @staticmethod
+    def _data_relation_config(question: JSONObject, relations: list[JSONObject]) -> JSONObject:
+        que_id = _positive_int(question.get("queId"))
+        relation = next((item for item in relations if _positive_int(item.get("queId")) == que_id), None)
+        if relation is None:
+            raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "data_relation has no question relation", "NORMALIZE", details={"queId": que_id})
+        relation_type = _positive_int(relation.get("relationType")) or 1
+        displayed = relation.get("displayedQueInfo") if isinstance(relation.get("displayedQueInfo"), dict) else {}
+        alias = relation.get("aliasConfig") if isinstance(relation.get("aliasConfig"), dict) else {}
+        if relation_type == 1:
+            if not str(displayed.get("appKey") or "").strip():
+                raise AppFormFailure(
+                    "UNSUPPORTED_FIELD_CONFIG",
+                    "data_relation source app cannot be normalized",
+                    "NORMALIZE",
+                    details={"queId": que_id},
+                )
+            source = {
+                "kind": "app",
+                "appKey": displayed.get("appKey"),
+                "field": _require_selector(
+                    relation.get("displayedQueId"),
+                    displayed.get("queTitle"),
+                    message="data_relation source field cannot be normalized",
+                    details={"queId": que_id},
+                ),
+            }
+        else:
+            producer = _require_selector(
+                alias.get("queId"),
+                alias.get("queTitle"),
+                message="data_relation producer cannot be normalized",
+                details={"queId": que_id},
+            )
+            alias_name = str(alias.get("qlinkerAlias") or relation.get("qlinkerAlias") or "").strip()
+            if not alias_name:
+                raise AppFormFailure(
+                    "UNSUPPORTED_FIELD_CONFIG",
+                    "data_relation alias cannot be normalized",
+                    "NORMALIZE",
+                    details={"queId": que_id},
+                )
+            source = {
+                "kind": "q_linker" if relation_type == 2 else "code_block",
+                "producer": producer,
+                "alias": _without_none({"name": alias_name, "aliasId": _positive_int(alias.get("aliasId"))}),
+            }
+        result: JSONObject = {"source": source}
+        backend_aggregation = question.get("aggreType")
+        aggregation_names = {value: key for key, value in AGGREGATION_TO_BACKEND.items()}
+        if backend_aggregation in aggregation_names:
+            result["aggregation"] = aggregation_names[backend_aggregation]
+        if _positive_int(relation.get("matchRuleType")) == 2 or relation.get("matchRuleFormula"):
+            if not str(relation.get("matchRuleFormula") or "").strip():
+                raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "data_relation advanced formula is missing", "NORMALIZE", details={"queId": que_id})
+            result["filters"] = {"mode": "advanced", "formula": str(relation.get("matchRuleFormula"))}
+        else:
+            groups = []
+            for group in relation.get("matchRules") or []:
+                if not isinstance(group, list):
+                    raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "data_relation match rules are malformed", "NORMALIZE", details={"queId": que_id})
+                groups.append([AppFormNormalizer._data_relation_condition(item, que_id=que_id) for item in group if isinstance(item, dict)])
+            result["filters"] = {"mode": "simple", "groups": groups}
+        sort = relation.get("sortConfig") if isinstance(relation.get("sortConfig"), dict) else None
+        if sort is not None:
+            if not bool(sort.get("status")):
+                result["sort"] = {"enabled": False}
+            elif _positive_int(sort.get("queId")):
+                result["sort"] = {"enabled": True, "by": {"kind": "field", "field": _selector(sort.get("queId"), sort.get("queTitle"))}, "direction": "asc" if sort.get("ascend") else "desc"}
+            elif str(sort.get("qlinkerAlias") or "").strip():
+                producer = _require_selector(
+                    alias.get("queId"),
+                    alias.get("queTitle"),
+                    message="data_relation alias sort producer cannot be normalized",
+                    details={"queId": que_id},
+                )
+                alias_name = str(sort.get("qlinkerAlias") or "").strip()
+                result["sort"] = {
+                    "enabled": True,
+                    "by": {
+                        "kind": "alias",
+                        "producer": producer,
+                        "alias": _without_none({"name": alias_name, "aliasId": _positive_int(alias.get("aliasId")) if alias_name == str(alias.get("qlinkerAlias") or "") else None}),
+                    },
+                    "direction": "asc" if sort.get("ascend") else "desc",
+                }
+            else:
+                raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "data_relation sort cannot be normalized", "NORMALIZE", details={"queId": que_id})
+        button = question.get("customButtonConfig") if isinstance(question.get("customButtonConfig"), dict) else None
+        if button is not None:
+            detail = button.get("customButtonDetailInfo") if isinstance(button.get("customButtonDetailInfo"), dict) else {}
+            button_id = _positive_int(detail.get("buttonId")) or _positive_int(button.get("buttonId"))
+            if bool(button.get("status")) and button_id is None:
+                raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "enabled data_relation custom button has no buttonId", "NORMALIZE", details={"queId": que_id})
+            result["customButton"] = {"enabled": bool(button.get("status")), **({"buttonId": button_id} if bool(button.get("status")) and button_id else {})}
+        return result
+
+    @staticmethod
+    def _data_relation_condition(value: JSONObject, *, que_id: int | None) -> JSONObject:
+        judge_type = value.get("judgeType")
+        if isinstance(judge_type, bool) or not isinstance(judge_type, int) or judge_type not in BACKEND_TO_JUDGE_TYPE:
+            raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "data_relation judgeType cannot be normalized", "NORMALIZE", details={"queId": que_id, "judgeType": judge_type})
+        condition: JSONObject = {
+            "sourceField": _require_selector(value.get("queId"), value.get("queTitle"), message="data_relation source field cannot be normalized", details={"queId": que_id}),
+            "operator": BACKEND_TO_JUDGE_TYPE[judge_type],
+        }
+        match_type = _positive_int(value.get("matchType")) or 1
+        if match_type == 1:
+            condition["operand"] = {"kind": "literal", "values": deepcopy(value.get("judgeValues") or [])}
+        elif match_type == 2:
+            detail = value.get("judgeQueDetail") if isinstance(value.get("judgeQueDetail"), dict) else {}
+            condition["operand"] = {
+                "kind": "current_field",
+                "field": _require_selector(detail.get("queId"), detail.get("queTitle"), message="data_relation current-field operand cannot be normalized", details={"queId": que_id}),
+            }
+        elif match_type == 7:
+            alias = value.get("aliasConfig") if isinstance(value.get("aliasConfig"), dict) else {}
+            alias_name = str(alias.get("qlinkerAlias") or "").strip()
+            if not alias_name:
+                raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "data_relation alias operand cannot be normalized", "NORMALIZE", details={"queId": que_id})
+            condition["operand"] = {
+                "kind": "alias",
+                "producer": _require_selector(alias.get("queId"), alias.get("queTitle"), message="data_relation alias producer cannot be normalized", details={"queId": que_id}),
+                "alias": _without_none({"name": alias_name, "aliasId": _positive_int(alias.get("aliasId"))}),
+            }
+        else:
+            raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "data_relation matchType cannot be normalized", "NORMALIZE", details={"queId": que_id, "matchType": match_type})
+        return condition
+
+
+class AppFormCompiler:
+    def __init__(self, apps: AppTools) -> None:
+        self.apps = apps
+
+    @staticmethod
+    def is_unbound_intermediate_error(error: AppFormFailure) -> bool:
+        return error.error_code == "UNSUPPORTED_FIELD_CONFIG" and error.message in {
+            "Q-Linker output target cannot be normalized",
+            "code block output target cannot be normalized",
+            "data_relation has no question relation",
+        }
+
+    def bind_backend_identities(self, *, form: JSONObject, resource: JSONObject) -> JSONObject:
+        result = deepcopy(resource)
+        questions_by_name: dict[str, list[JSONObject]] = {}
+        sections_by_title: dict[str, list[JSONObject]] = {}
+
+        def register_question(question: JSONObject) -> None:
+            name = str(question.get("queTitle") or "")
+            if name:
+                questions_by_name.setdefault(name, []).append(question)
+
+        for row in form.get("formQues") or []:
+            if not isinstance(row, list):
+                continue
+            for question in row:
+                if not isinstance(question, dict):
+                    continue
+                if _positive_int(question.get("queType")) == 24:
+                    title = str(question.get("queTitle") or "")
+                    if title:
+                        sections_by_title.setdefault(title, []).append(question)
+                    for inner_row in question.get("innerQuestions") or []:
+                        for inner_question in inner_row if isinstance(inner_row, list) else []:
+                            if isinstance(inner_question, dict):
+                                register_question(inner_question)
+                    continue
+                register_question(question)
+
+        def resolve_question(field: JSONObject, candidates: list[JSONObject], *, parent: str | None = None) -> JSONObject:
+            field_id = _positive_int(field.get("queId"))
+            if field_id is not None:
+                matched = [item for item in candidates if _positive_int(item.get("queId")) == field_id]
+                if len(matched) == 1:
+                    return matched[0]
+            name = str(field.get("name") or "")
+            matched = [item for item in candidates if str(item.get("queTitle") or "") == name]
+            if len(matched) != 1:
+                raise AppFormFailure(
+                    "RELATION_REBIND_FAILED",
+                    "identity write did not return a unique field identity",
+                    "IDENTITY_REBOUND",
+                    details={"field": name, "parent": parent, "matches": len(matched)},
+                )
+            return matched[0]
+
+        def bind_field(field: JSONObject) -> None:
+            name = str(field.get("name") or "")
+            question = resolve_question(field, questions_by_name.get(name) or [])
+            que_id = _positive_int(question.get("queId"))
+            if que_id is None:
+                raise AppFormFailure(
+                    "RELATION_REBIND_FAILED",
+                    "identity write returned a field without queId",
+                    "IDENTITY_REBOUND",
+                    details={"field": name},
+                )
+            field["queId"] = que_id
+            subquestions = [item for item in question.get("subQuestions") or [] if isinstance(item, dict)]
+            for subfield in field.get("subfields") or []:
+                if not isinstance(subfield, dict):
+                    continue
+                subquestion = resolve_question(subfield, subquestions, parent=name)
+                sub_que_id = _positive_int(subquestion.get("queId"))
+                if sub_que_id is None:
+                    raise AppFormFailure(
+                        "RELATION_REBIND_FAILED",
+                        "identity write returned a subfield without queId",
+                        "IDENTITY_REBOUND",
+                        details={"field": subfield.get("name"), "parent": name},
+                    )
+                subfield["queId"] = sub_que_id
+
+        claimed_sections: set[int] = set()
+        for block in result.get("spec", {}).get("body") or []:
+            if not isinstance(block, dict):
+                continue
+            rows = [block]
+            if block.get("kind") == "section":
+                title = str(block.get("title") or "")
+                section_id = _positive_int(block.get("sectionId"))
+                candidates = [
+                    item
+                    for item in sections_by_title.get(title) or []
+                    if id(item) not in claimed_sections
+                    and (section_id is None or _positive_int(item.get("queId")) == section_id)
+                ]
+                if len(candidates) != 1:
+                    raise AppFormFailure(
+                        "RELATION_REBIND_FAILED",
+                        "identity write did not return a unique section identity",
+                        "IDENTITY_REBOUND",
+                        details={"section": title, "matches": len(candidates)},
+                    )
+                section = candidates[0]
+                claimed_sections.add(id(section))
+                resolved_section_id = _positive_int(section.get("queId"))
+                if resolved_section_id is None:
+                    raise AppFormFailure(
+                        "RELATION_REBIND_FAILED",
+                        "identity write returned a section without sectionId",
+                        "IDENTITY_REBOUND",
+                        details={"section": title},
+                    )
+                block["sectionId"] = str(resolved_section_id)
+                rows = block.get("rows") or []
+            for row in rows:
+                if not isinstance(row, dict):
+                    continue
+                for field in row.get("fields") or []:
+                    if isinstance(field, dict):
+                        bind_field(field)
+        return result
+
+    def recovery_resource(
+        self,
+        *,
+        context: AppFormSchemaContext,
+        app_key: str,
+        form: JSONObject,
+        declaration: JSONObject,
+    ) -> JSONObject:
+        resource = self.bind_backend_identities(form=form, resource=declaration)
+        spec = resource["spec"]
+        spec.setdefault("appName", str(form.get("formTitle") or ""))
+        spec.setdefault("description", form.get("formDesc") or None)
+        spec.setdefault("theme", form.get("formTheme"))
+        spec.setdefault("style", AppFormNormalizer._style(form.get("formStyle")))
+        spec.setdefault("attachments", AppFormNormalizer._attachments(form.get("formAttach")))
+        spec.setdefault(
+            "serialNumber",
+            AppFormNormalizer._serial_number(form.get("serialNumType"), form.get("serialNumConfig")),
+        )
+        spec.pop("icon", None)
+        spec.pop("color", None)
+        resource["apiVersion"] = context.api_version
+        resource["appKey"] = app_key
+        resource.pop("packageId", None)
+        return resource
+
+    def target_resource(self, *, context: AppFormSchemaContext, app_key: str, current: JSONObject, declaration: JSONObject) -> JSONObject:
+        current_spec = current["spec"]
+        declared_spec = declaration["spec"]
+        target_spec = deepcopy(current_spec)
+        for key in ("appName", "description", "theme", "attachments", "serialNumber"):
+            if key in declared_spec:
+                target_spec[key] = deepcopy(declared_spec[key])
+        if "style" in declared_spec:
+            if declared_spec["style"] is None:
+                target_spec["style"] = None
+            else:
+                merged = deepcopy(current_spec.get("style") or {})
+                merged.update(deepcopy(declared_spec["style"]))
+                target_spec["style"] = merged or None
+        target_spec["body"] = self._target_body(current_spec.get("body") or [], declared_spec.get("body") or [])
+        self._validate_target(target_spec["body"])
+        return {"apiVersion": context.api_version, "appKey": app_key, "spec": target_spec}
+
+    def preflight(self, *, profile: str, app_key: str, declaration: JSONObject, current_form: JSONObject | None) -> None:
+        body = declaration.get("spec", {}).get("body") or []
+        self._validate_target(body)
+        fields = list(_iter_fields(body))
+        templates = self._question_templates(current_form or {})
+        internal_fields = [self._internal_field(field, templates=templates) for field in fields]
+        for index, internal in enumerate(internal_fields):
+            if _positive_int(internal.get("que_id")) is None:
+                internal["que_temp_id"] = -10000 - (index * 100)
+        try:
+            internal_fields, _ = _normalize_and_validate_code_block_fields_for_write(fields=internal_fields)
+            internal_fields, relations = _compile_code_block_binding_fields(fields=internal_fields, current_schema=current_form or {})
+            relation_context = deepcopy(current_form or {})
+            relation_context["questionRelations"] = relations
+            internal_fields, _ = _compile_q_linker_binding_fields(fields=internal_fields, current_schema=relation_context)
+        except (KeyError, ValueError) as error:
+            raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", str(error), "CONTRACT_PRECHECK") from error
+        self._assign_subfield_temp_ids(internal_fields)
+        for field in fields:
+            config = field.get("config") if isinstance(field.get("config"), dict) else {}
+            if field.get("type") == "relation":
+                template = templates.get(_positive_int(field.get("queId")) or -1, {}).get("referenceConfig")
+                self._reference_config(profile, config, template if isinstance(template, dict) else None)
+            elif field.get("type") == "q_linker":
+                for index, item in enumerate((config.get("qLinkerBinding") or {}).get("inputs") or []):
+                    if not isinstance(item, dict) or item.get("source") != "json_path":
+                        continue
+                    selected = _resolve_internal_selector(item.get("field") or {}, internal_fields, f"qLinkerBinding.inputs[{index}].field")
+                    if str(item.get("key") or "") != str(selected.get("name") or ""):
+                        raise AppFormFailure(
+                            "UNSUPPORTED_FIELD_CONFIG",
+                            "json_path input key must equal the selected field name for lossless readback",
+                            "CONTRACT_PRECHECK",
+                            details={"key": item.get("key"), "field": selected.get("name")},
+                        )
+            elif field.get("type") == "data_relation" and "customButton" in config:
+                template = templates.get(_positive_int(field.get("queId")) or -1)
+                self._data_relation_custom_button(config.get("customButton") or {}, template)
+        self._data_relation_relations(profile, app_key, fields, internal_fields)
+
+    def _target_body(self, current_body: list[Any], declared_body: list[Any]) -> list[JSONObject]:
+        current_fields = list(_iter_fields(current_body))
+        by_id = {_positive_int(field.get("queId")): field for field in current_fields if _positive_int(field.get("queId"))}
+        sections_by_id = {
+            str(block.get("sectionId")): block
+            for block in current_body
+            if isinstance(block, dict) and block.get("kind") == "section" and block.get("sectionId")
+        }
+        current_sections = [
+            block for block in current_body if isinstance(block, dict) and block.get("kind") == "section"
+        ]
+        claimed_fields: set[int] = set()
+        claimed_sections: set[int] = set()
+
+        def merge_field(current: JSONObject | None, declared: JSONObject) -> JSONObject:
+            target = _deep_overlay(current or {}, declared)
+            if "config" in declared:
+                target["config"] = deepcopy(declared["config"])
+            target.setdefault("required", False)
+            target.setdefault("description", None)
+            if current is not None:
+                target["queId"] = current.get("queId")
+            else:
+                target.pop("queId", None)
+            if target.get("type") in CHOICE_TYPES and "config" not in declared and current is None:
+                target["config"] = {"options": ["是", "否"] if target.get("type") == "single_choice" else []}
+            return target
+
+        def target_field(declared: JSONObject, *, nested: bool) -> JSONObject:
+            que_id = _positive_int(declared.get("queId"))
+            current = by_id.get(que_id) if que_id is not None else None
+            if current is not None and id(current) in claimed_fields:
+                current = None
+            if current is None:
+                comparable = deepcopy(declared)
+                comparable.pop("queId", None)
+                candidates = []
+                for candidate in current_fields:
+                    if id(candidate) in claimed_fields or candidate.get("type") != declared.get("type"):
+                        continue
+                    merged = merge_field(candidate, comparable)
+                    if _field_semantic(merged) == _field_semantic(candidate):
+                        candidates.append(candidate)
+                if len(candidates) > 1:
+                    raise AppFormFailure(
+                        "AMBIGUOUS_FIELD_MATCH",
+                        "field declaration matches multiple existing fields",
+                        "CONTRACT_PRECHECK",
+                        details={"name": declared.get("name"), "queIds": [item.get("queId") for item in candidates]},
+                    )
+                current = candidates[0] if candidates else None
+            if current is not None and current.get("type") != declared.get("type"):
+                raise AppFormFailure("FIELD_TYPE_IMMUTABLE", "field type cannot be changed in place", "CONTRACT_PRECHECK", details={"queId": current.get("queId"), "currentType": current.get("type"), "targetType": declared.get("type")})
+            if current is not None:
+                claimed_fields.add(id(current))
+            target = merge_field(current, declared)
+            if target.get("type") == "subtable":
+                current_subfields = current.get("subfields") if isinstance((current or {}).get("subfields"), list) else []
+                target["subfields"] = self._target_body(
+                    [{"kind": "row", "fields": current_subfields}],
+                    [{"kind": "row", "fields": target.get("subfields") or []}],
+                )[0]["fields"]
+                for item in target["subfields"]:
+                    item.pop("width", None)
+            if nested:
+                target.pop("width", None)
+            return target
+
+        result = []
+        for block in declared_body:
+            target_block = deepcopy(block)
+            if block.get("kind") == "row":
+                target_block["fields"] = [target_field(field, nested=False) for field in block.get("fields") or []]
+                self._fill_widths(target_block["fields"])
+            else:
+                target_block["rows"] = []
+                for row in block.get("rows") or []:
+                    fields = [target_field(field, nested=False) for field in row.get("fields") or []]
+                    self._fill_widths(fields)
+                    target_block["rows"].append({"fields": fields})
+                section_id = str(block.get("sectionId") or "")
+                current_section = sections_by_id.get(section_id) if section_id else None
+                if current_section is not None and id(current_section) in claimed_sections:
+                    current_section = None
+                if current_section is None:
+                    comparable = deepcopy(target_block)
+                    comparable.pop("sectionId", None)
+                    candidates = [
+                        candidate
+                        for candidate in current_sections
+                        if id(candidate) not in claimed_sections
+                        and _semantic({key: value for key, value in candidate.items() if key != "sectionId"})
+                        == _semantic(comparable)
+                    ]
+                    if len(candidates) > 1:
+                        raise AppFormFailure(
+                            "AMBIGUOUS_LAYOUT_SECTION",
+                            "section declaration matches multiple existing sections",
+                            "CONTRACT_PRECHECK",
+                            details={"title": block.get("title"), "sectionIds": [item.get("sectionId") for item in candidates]},
+                        )
+                    current_section = candidates[0] if candidates else None
+                if current_section is not None:
+                    claimed_sections.add(id(current_section))
+                    target_block["sectionId"] = current_section["sectionId"]
+                else:
+                    target_block.pop("sectionId", None)
+            result.append(target_block)
+        return result
+
+    @staticmethod
+    def _fill_widths(fields: list[JSONObject]) -> None:
+        if not fields:
+            raise AppFormFailure("INVALID_SPEC", "a row must contain at least one field", "CONTRACT_PRECHECK")
+        present = ["width" in field for field in fields]
+        if any(present) and not all(present):
+            raise AppFormFailure("INVALID_ROW_WIDTH", "all fields in a row must provide width together", "CONTRACT_PRECHECK")
+        if all(present):
+            if sum(int(field["width"]) for field in fields) != 100:
+                raise AppFormFailure("INVALID_ROW_WIDTH", "field widths in a row must total 100", "CONTRACT_PRECHECK")
+            return
+        width, remainder = divmod(100, len(fields))
+        for index, field in enumerate(fields):
+            field["width"] = width + (1 if index < remainder else 0)
+
+    @staticmethod
+    def _validate_target(body: list[JSONObject]) -> None:
+        fields = list(_iter_fields(body))
+        names: set[str] = set()
+        title_count = 0
+        cover_count = 0
+        for field in fields:
+            name = str(field.get("name") or "")
+            if name in names:
+                raise AppFormFailure("DUPLICATE_FIELD_NAME", f"duplicate top-level field name: {name}", "CONTRACT_PRECHECK")
+            names.add(name)
+            title_count += int(bool(field.get("dataTitle")))
+            cover_count += int(bool(field.get("dataCover")))
+            if field.get("dataCover") and field.get("type") != "attachment":
+                raise AppFormFailure("INVALID_DATA_COVER_FIELD", "dataCover must be an attachment field", "CONTRACT_PRECHECK")
+            if field.get("type") == "subtable":
+                sub_names: set[str] = set()
+                for subfield in field.get("subfields") or []:
+                    if subfield.get("type") not in SUBFIELD_TYPES:
+                        raise AppFormFailure("INVALID_SPEC", "unsupported subtable field type", "CONTRACT_PRECHECK", details={"allowedTypes": sorted(SUBFIELD_TYPES)})
+                    if subfield.get("name") in sub_names:
+                        raise AppFormFailure("DUPLICATE_FIELD_NAME", f"duplicate subtable field name: {subfield.get('name')}", "CONTRACT_PRECHECK")
+                    sub_names.add(str(subfield.get("name") or ""))
+        if fields and title_count != 1:
+            raise AppFormFailure("INVALID_DATA_TITLE_FIELD", "non-empty body must contain exactly one dataTitle field", "CONTRACT_PRECHECK")
+        if cover_count > 1:
+            raise AppFormFailure("INVALID_DATA_COVER_FIELD", "body can contain at most one dataCover field", "CONTRACT_PRECHECK")
+
+    def payload(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        current_form: JSONObject,
+        target: JSONObject,
+        edit_version_no: int,
+    ) -> JSONObject:
+        target_fields = list(_iter_fields(target["spec"]["body"]))
+        templates = self._question_templates(current_form)
+        internal_fields = [self._internal_field(field, templates=templates) for field in target_fields]
+        try:
+            internal_fields, _ = _normalize_and_validate_code_block_fields_for_write(fields=internal_fields)
+            internal_fields, relations = _compile_code_block_binding_fields(fields=internal_fields, current_schema=current_form)
+            relation_context = deepcopy(current_form)
+            relation_context["questionRelations"] = relations
+            internal_fields, relations = _compile_q_linker_binding_fields(fields=internal_fields, current_schema=relation_context)
+        except (KeyError, ValueError) as error:
+            raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", str(error), "COMPILE") from error
+        self._assign_subfield_temp_ids(internal_fields)
+        data_relations = self._data_relation_relations(profile, app_key, target_fields, internal_fields)
+        internal_by_key = {(field.get("que_id"), field.get("name")): field for field in internal_fields}
+        payload = self._save_base(current_form)
+        self._apply_form_settings(payload, current_form=current_form, target_spec=target["spec"], internal_fields=internal_fields)
+        payload["editVersionNo"] = edit_version_no
+        payload["questionRelations"] = [
+            relation
+            for relation in relations
+            if _positive_int(relation.get("relationType")) != 1
+        ]
+        rows: list[list[JSONObject]] = []
+        temp_id = -10000
+        for block in target["spec"]["body"]:
+            if block["kind"] == "row":
+                row = []
+                for field in block["fields"]:
+                    internal = internal_by_key.get((_positive_int(field.get("queId")), field.get("name")))
+                    question = self._question(profile, app_key, field, internal or {}, temp_id, relations)
+                    temp_id -= 100
+                    row.append(question)
+                rows.append(row)
+            else:
+                inner_rows = []
+                for target_row in block["rows"]:
+                    inner = []
+                    for field in target_row["fields"]:
+                        internal = internal_by_key.get((_positive_int(field.get("queId")), field.get("name")))
+                        inner.append(self._question(profile, app_key, field, internal or {}, temp_id, relations))
+                        temp_id -= 100
+                    inner_rows.append(inner)
+                section_id = _positive_int(block.get("sectionId"))
+                section = {
+                    "queId": section_id or 0,
+                    "queType": 24,
+                    "queTitle": block["title"],
+                    "queWidth": 100,
+                    "required": False,
+                    "queHint": "",
+                    "queDefaultType": 1,
+                    "innerQuestions": inner_rows,
+                }
+                if section_id is None:
+                    section["queTempId"] = temp_id
+                    temp_id -= 100
+                rows.append([section])
+        payload["formQues"] = rows
+        data_title = next((field for field in target_fields if field.get("dataTitle")), None)
+        data_cover = next((field for field in target_fields if field.get("dataCover")), None)
+        payload["dataTitleQueId"] = self._field_runtime_id(data_title, internal_fields)
+        payload["dataCoverQueId"] = self._field_runtime_id(data_cover, internal_fields) if data_cover else None
+        payload["questionRelations"].extend(data_relations)
+        return payload
+
+    @staticmethod
+    def needs_identity_write(target: JSONObject) -> bool:
+        fields = list(_iter_field_tree(_iter_fields(target["spec"]["body"])))
+        missing_names = {str(field.get("name")) for field in fields if _positive_int(field.get("queId")) is None}
+        for field in fields:
+            config = field.get("config") if isinstance(field.get("config"), dict) else {}
+            binding = config.get("qLinkerBinding") or config.get("codeBlockBinding")
+            if _positive_int(field.get("queId")) is None and (
+                field.get("type") in {"q_linker", "data_relation"}
+                or field.get("type") == "code_block" and bool((binding or {}).get("outputs"))
+            ):
+                return True
+            if isinstance(binding, dict):
+                selectors = [item.get("field") for item in binding.get("inputs") or [] if isinstance(item, dict)]
+                selectors += [item.get("targetField") for item in binding.get("outputs") or [] if isinstance(item, dict)]
+                if any(isinstance(selector, dict) and not _positive_int(selector.get("queId")) and selector.get("name") in missing_names for selector in selectors):
+                    return True
+            if field.get("type") == "data_relation" and json.dumps(config, ensure_ascii=False, sort_keys=True):
+                for selector in _walk_selectors(config):
+                    if not _positive_int(selector.get("queId")) and selector.get("name") in missing_names:
+                        return True
+        return False
+
+    @staticmethod
+    def pending_bindings(target: JSONObject) -> list[JSONObject]:
+        fields = list(_iter_field_tree(_iter_fields(target["spec"]["body"])))
+        missing_names = {str(field.get("name")) for field in fields if _positive_int(field.get("queId")) is None}
+        pending: list[JSONObject] = []
+        for field in fields:
+            config = field.get("config") if isinstance(field.get("config"), dict) else {}
+            binding = config.get("qLinkerBinding") or config.get("codeBlockBinding")
+            if _positive_int(field.get("queId")) is None and (
+                field.get("type") in {"q_linker", "data_relation"}
+                or field.get("type") == "code_block" and bool((binding or {}).get("outputs"))
+            ):
+                pending.append(
+                    {
+                        "field": field.get("name"),
+                        "path": "identity",
+                        "selector": {"name": field.get("name")},
+                    }
+                )
+            if isinstance(binding, dict):
+                for index, item in enumerate(binding.get("inputs") or []):
+                    selector = item.get("field") if isinstance(item, dict) else None
+                    if isinstance(selector, dict) and not _positive_int(selector.get("queId")) and selector.get("name") in missing_names:
+                        pending.append({"field": field.get("name"), "path": f"inputs/{index}", "selector": deepcopy(selector)})
+                for index, item in enumerate(binding.get("outputs") or []):
+                    selector = item.get("targetField") if isinstance(item, dict) else None
+                    if isinstance(selector, dict) and not _positive_int(selector.get("queId")) and selector.get("name") in missing_names:
+                        pending.append({"field": field.get("name"), "path": f"outputs/{index}", "selector": deepcopy(selector)})
+            if field.get("type") == "data_relation":
+                for selector in _walk_selectors(config):
+                    if not _positive_int(selector.get("queId")) and selector.get("name") in missing_names:
+                        pending.append({"field": field.get("name"), "path": "config", "selector": deepcopy(selector)})
+        return pending
+
+    def identity_target(self, *, current: JSONObject, target: JSONObject) -> JSONObject:
+        """Keep pending deletions in the first relation-binding write."""
+        identity = deepcopy(target)
+        target_ids = {
+            _positive_int(field.get("queId"))
+            for field in _iter_fields(identity["spec"]["body"])
+            if _positive_int(field.get("queId")) is not None
+        }
+        target_sections = {
+            str(block.get("sectionId")): block
+            for block in identity["spec"]["body"]
+            if isinstance(block, dict) and block.get("kind") == "section" and block.get("sectionId")
+        }
+
+        def retained_fields(fields: list[Any]) -> list[JSONObject]:
+            retained = [
+                deepcopy(field)
+                for field in fields
+                if isinstance(field, dict) and _positive_int(field.get("queId")) not in target_ids
+            ]
+            for field in retained:
+                field.pop("width", None)
+            if retained:
+                self._fill_widths(retained)
+            return retained
+
+        for block in current["spec"]["body"]:
+            if not isinstance(block, dict):
+                continue
+            if block.get("kind") == "row":
+                fields = retained_fields(block.get("fields") or [])
+                if fields:
+                    identity["spec"]["body"].append({"kind": "row", "fields": fields})
+                continue
+            retained_rows = []
+            for row in block.get("rows") or []:
+                if not isinstance(row, dict):
+                    continue
+                fields = retained_fields(row.get("fields") or [])
+                if fields:
+                    retained_rows.append({"fields": fields})
+            if not retained_rows:
+                continue
+            section_id = str(block.get("sectionId") or "")
+            target_section = target_sections.get(section_id)
+            if target_section is not None:
+                target_section["rows"].extend(retained_rows)
+            else:
+                retained_section = deepcopy(block)
+                retained_section["rows"] = retained_rows
+                identity["spec"]["body"].append(retained_section)
+        return identity
+
+    @staticmethod
+    def _question_templates(form: JSONObject) -> dict[int, JSONObject]:
+        result = {}
+
+        def add(question: JSONObject) -> None:
+            que_id = _positive_int(question.get("queId"))
+            if que_id is not None:
+                result[que_id] = question
+            for subquestion in question.get("subQuestions") or []:
+                if isinstance(subquestion, dict):
+                    add(subquestion)
+
+        for row in form.get("formQues") or []:
+            for question in row if isinstance(row, list) else []:
+                if not isinstance(question, dict):
+                    continue
+                if _positive_int(question.get("queType")) == 24:
+                    for inner in question.get("innerQuestions") or []:
+                        for item in inner if isinstance(inner, list) else []:
+                            if isinstance(item, dict):
+                                add(item)
+                else:
+                    add(question)
+        return result
+
+    @staticmethod
+    def _assign_subfield_temp_ids(fields: list[JSONObject]) -> None:
+        temp_id = -1_000_000
+        for field in fields:
+            for subfield in field.get("subfields") or []:
+                if _positive_int(subfield.get("que_id")) is None:
+                    subfield["que_temp_id"] = temp_id
+                    temp_id -= 1
+
+    def _internal_field(self, field: JSONObject, *, templates: dict[int, JSONObject]) -> JSONObject:
+        canonical_type = str(field.get("type"))
+        internal_type = "boolean" if canonical_type == "single_choice" else canonical_type
+        config = field.get("config") if isinstance(field.get("config"), dict) else {}
+        result: JSONObject = {
+            "name": field["name"],
+            "type": internal_type,
+            "required": bool(field.get("required")),
+            "description": field.get("description"),
+            "que_id": _positive_int(field.get("queId")),
+            "options": deepcopy(config.get("options") or []),
+            "subfields": [self._internal_field(item, templates=templates) for item in field.get("subfields") or []],
+            "_app_form_type": canonical_type,
+        }
+        template = templates.get(result["que_id"] or -1)
+        if template is not None:
+            result["_question_template"] = deepcopy(template)
+        if canonical_type == "department":
+            scope = config.get("departmentScope") or {"mode": "all"}
+            result["department_scope"] = {
+                "mode": scope.get("mode"),
+                "departments": [
+                    {"dept_id": item.get("deptId"), "dept_name": item.get("deptName")}
+                    for item in scope.get("departments") or []
+                ],
+                "include_sub_departs": bool(scope.get("includeSubDeparts")),
+            }
+        elif canonical_type == "relation":
+            result.update(
+                {
+                    "target_app_key": config.get("targetAppKey"),
+                    "relation_mode": config.get("relationMode") or "single",
+                    "display_field": _snake_selector(config.get("displayField")),
+                    "visible_fields": [_snake_selector(item) for item in config.get("visibleFields") or []],
+                    "_relation_config_explicit": True,
+                }
+            )
+        elif canonical_type == "q_linker":
+            result["q_linker_binding"] = _snake_q_linker(config.get("qLinkerBinding") or {})
+            if template is not None and isinstance(template.get("remoteLookupConfig"), dict):
+                result["remote_lookup_config"] = deepcopy(template["remoteLookupConfig"])
+        elif canonical_type == "code_block":
+            result["code_block_binding"] = _snake_code_block(config.get("codeBlockBinding") or {})
+        return result
+
+    def _question(self, profile: str, app_key: str, field: JSONObject, internal: JSONObject, temp_id: int, relations: list[JSONObject]) -> JSONObject:
+        field_type = str(field["type"])
+        que_type = CANONICAL_TO_QUE_TYPE[field_type]
+        build_type = "boolean" if field_type == "single_choice" else "text" if field_type in {"link", "data_relation"} else field_type
+        built_internal = deepcopy(internal)
+        built_internal["type"] = build_type
+        if build_type == "subtable":
+            built_internal["subfields"] = []
+        try:
+            generated = _field_to_question(built_internal, temp_id=temp_id)
+        except (KeyError, ValueError):
+            generated, _ = build_question(
+                {"label": field["name"], "type": FieldType.text, "required": bool(field.get("required")), "description": field.get("description"), "config": {}},
+                temp_id,
+            )
+        template = internal.get("_question_template") if isinstance(internal.get("_question_template"), dict) else None
+        question = deepcopy(template) if template is not None else generated
+        for key, value in generated.items():
+            if key in {"queId", "queTempId", "queType", "queTitle", "queWidth", "required", "queHint", "options", "deptSelectScope", "deptSelectScopeType", "referenceConfig", "remoteLookupConfig", "codeBlockConfig", "autoTrigger", "customBtnTextStatus", "customBtnText", "queDefaultType"}:
+                question[key] = deepcopy(value)
+        que_id = _positive_int(field.get("queId"))
+        question["queId"] = que_id or 0
+        if que_id is None:
+            question["queTempId"] = internal.get("que_temp_id") or temp_id
+        else:
+            question.pop("queTempId", None)
+        question.update(
+            {
+                "queType": que_type,
+                "queTitle": field["name"],
+                "queWidth": int(field.get("width") or 100),
+                "required": bool(field.get("required")),
+                "queHint": field.get("description") or "",
+            }
+        )
+        if field_type == "date":
+            question["dateType"] = 0
+        elif field_type == "datetime":
+            question["dateType"] = 1
+        elif field_type in CHOICE_TYPES:
+            old_options = {
+                str(item.get("optValue")): item
+                for item in (template or {}).get("options") or []
+                if isinstance(item, dict) and item.get("optValue") is not None
+            }
+            options = build_options((field.get("config") or {}).get("options") or [], start_temp_id=temp_id - 1)
+            for option in options:
+                old = old_options.get(str(option.get("optValue")))
+                if old is not None:
+                    option.update({key: deepcopy(value) for key, value in old.items() if key not in {"optValue"}})
+            question["options"] = options
+            question["unnamedOptions"] = [item.get("optValue") for item in options]
+            question["optDirection"] = 0
+        elif field_type == "subtable":
+            question["subQuestions"] = [
+                self._question(profile, app_key, subfield, sub_internal, temp_id - ((index + 1) * 10), relations)
+                for index, (subfield, sub_internal) in enumerate(zip(field.get("subfields") or [], internal.get("subfields") or []))
+            ]
+            for subquestion in question["subQuestions"]:
+                subquestion["queWidth"] = 100
+        elif field_type == "relation":
+            current_reference = (template or {}).get("referenceConfig")
+            question["referenceConfig"] = self._reference_config(
+                profile,
+                field.get("config") or {},
+                current_reference if isinstance(current_reference, dict) else None,
+            )
+        elif field_type == "data_relation":
+            config = field.get("config") or {}
+            related_que_id = _positive_int(internal.get("data_relation_related_que_id"))
+            if related_que_id is None:
+                question.pop("relatedQueId", None)
+            else:
+                question["relatedQueId"] = related_que_id
+            que_origin_type = _positive_int(internal.get("data_relation_origin_type"))
+            if que_origin_type is None:
+                raise AppFormFailure(
+                    "UNSUPPORTED_FIELD_CONFIG",
+                    "data_relation source type could not be derived",
+                    "COMPILE",
+                    details={"field": field.get("name")},
+                )
+            question["queOriginType"] = que_origin_type
+            aggregation = config.get("aggregation")
+            if aggregation is None:
+                question.pop("aggreType", None)
+            else:
+                question["aggreType"] = AGGREGATION_TO_BACKEND[aggregation]
+            if "customButton" in config:
+                question["customButtonConfig"] = self._data_relation_custom_button(
+                    config.get("customButton") or {},
+                    template,
+                )
+        return question
+
+    def _reference_config(self, profile: str, config: JSONObject, template: JSONObject | None = None) -> JSONObject:
+        target_app_key = str(config.get("targetAppKey") or "")
+        target_form = self._read_form(profile, target_app_key, being_draft=False)
+        candidates = _backend_question_candidates(target_form)
+        display = _resolve_backend_selector(config.get("displayField") or {}, candidates, "displayField")
+        visible = [_resolve_backend_selector(item, candidates, "visibleFields") for item in config.get("visibleFields") or []]
+        if all(_positive_int(item.get("queId")) != _positive_int(display.get("queId")) for item in visible):
+            visible.insert(0, display)
+        result = deepcopy(template or {})
+        result.update(
+            {
+                "referAppKey": target_app_key,
+                "referQueId": display["queId"],
+                "optionalDataNum": 1 if config.get("relationMode", "single") == "single" else 2,
+                "referQuestions": [
+                {"queId": item["queId"], "queTitle": item["queTitle"], "queType": item["queType"], "queAuth": 3, "ordinal": index}
+                for index, item in enumerate(visible)
+                ],
+                "referAuthQues": [{"queId": item["queId"], "queAuth": 1} for item in visible],
+            }
+        )
+        return result
+
+    @staticmethod
+    def _data_relation_custom_button(config: JSONObject, template: JSONObject | None) -> JSONObject:
+        current = (template or {}).get("customButtonConfig")
+        current = current if isinstance(current, dict) else {}
+        detail = current.get("customButtonDetailInfo")
+        detail = detail if isinstance(detail, dict) else {}
+        if not bool(config.get("enabled")):
+            return {"status": False, **({"customButtonDetailInfo": deepcopy(detail)} if detail else {})}
+        declared_id = _positive_int(config.get("buttonId"))
+        current_id = _positive_int(detail.get("buttonId")) or _positive_int(current.get("buttonId"))
+        if declared_id is None or current_id != declared_id:
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_CONFIG",
+                "enabled data_relation custom button must reference the field's current buttonId",
+                "CONTRACT_PRECHECK",
+                details={"declaredButtonId": declared_id, "currentButtonId": current_id},
+            )
+        return {"status": True, "customButtonDetailInfo": deepcopy(detail)}
+
+    def _data_relation_relations(self, profile: str, app_key: str, fields: list[JSONObject], internal_fields: list[JSONObject]) -> list[JSONObject]:
+        available_internal_fields = list(_iter_field_tree(internal_fields))
+        result = []
+        for field, internal in _iter_field_pairs(fields, internal_fields):
+            if field.get("type") != "data_relation":
+                continue
+            config = field.get("config") or {}
+            source = config.get("source") or {}
+            field_id = _positive_int(internal.get("que_id")) or int(internal.get("que_temp_id") or 0) or None
+            relation: JSONObject = {
+                "queId": field_id,
+                "relationType": {"app": 1, "q_linker": 2, "code_block": 3}.get(source.get("kind"), 1),
+                "matchRuleType": 1,
+                "matchRules": [],
+                "matchRuleFormula": None,
+                "tableMatchRules": [],
+                "sortConfig": None,
+            }
+            source_producer: JSONObject | None = None
+            source_fields = available_internal_fields
+            source_fields_are_backend = False
+            if source.get("kind") == "app":
+                target_form = self._read_form(profile, str(source.get("appKey") or ""), being_draft=False)
+                source_fields = _backend_question_candidates(target_form)
+                source_fields_are_backend = True
+                target = _resolve_backend_selector(source.get("field") or {}, source_fields, "source.field")
+                relation.update(
+                    {
+                        "displayedQueId": target["queId"],
+                        "displayedQueInfo": {
+                            "appKey": source.get("appKey"),
+                            "queId": target["queId"],
+                            "queTitle": target["queTitle"],
+                            "queType": target["queType"],
+                        },
+                    }
+                )
+                internal["data_relation_related_que_id"] = target["queId"]
+                internal["data_relation_origin_type"] = target["queType"]
+            else:
+                producer = _resolve_internal_selector(source.get("producer") or {}, available_internal_fields, "source.producer")
+                source_producer = producer
+                alias = source.get("alias") or {}
+                alias_origin_type, resolved_alias_id = self._data_relation_alias_metadata(
+                    producer=producer,
+                    alias=alias,
+                    internal_fields=available_internal_fields,
+                )
+                relation.update(
+                    {
+                        "displayedQueId": None,
+                        "displayedQueInfo": None,
+                        "qlinkerAlias": alias.get("name"),
+                        "aliasConfig": _without_none(
+                            {
+                                "queId": producer.get("que_id") or producer.get("que_temp_id"),
+                                "queTitle": producer.get("name"),
+                                "qlinkerAlias": alias.get("name"),
+                                "aliasId": resolved_alias_id,
+                            }
+                        ),
+                    }
+                )
+                internal.pop("data_relation_related_que_id", None)
+                internal["data_relation_origin_type"] = alias_origin_type
+            filters = config.get("filters")
+            if isinstance(filters, dict) and filters.get("mode") == "advanced":
+                relation["matchRuleFormula"] = filters.get("formula")
+            elif isinstance(filters, dict):
+                relation["matchRules"] = [
+                    [
+                        self._data_relation_condition(
+                            item,
+                            source_fields=source_fields,
+                            current_fields=available_internal_fields,
+                            source_fields_are_backend=source_fields_are_backend,
+                        )
+                        for item in group
+                    ]
+                    for group in filters.get("groups") or []
+                ]
+            sort = config.get("sort")
+            if isinstance(sort, dict):
+                if not sort.get("enabled"):
+                    relation["sortConfig"] = {"status": False}
+                elif (sort.get("by") or {}).get("kind") == "field":
+                    sort_field = self._resolve_data_relation_source_field(
+                        (sort.get("by") or {}).get("field") or {},
+                        source_fields=source_fields,
+                        source_fields_are_backend=source_fields_are_backend,
+                        location="sort.by.field",
+                    )
+                    relation["sortConfig"] = {
+                        "status": True,
+                        "queId": self._data_relation_field_ref(sort_field),
+                        "queTitle": self._data_relation_field_name(sort_field),
+                        "ascend": sort.get("direction") == "asc",
+                    }
+                else:
+                    by = sort.get("by") or {}
+                    producer = _resolve_internal_selector(by.get("producer") or {}, available_internal_fields, "sort.by.producer")
+                    alias = by.get("alias") or {}
+                    alias_name = str(alias.get("name") or "").strip()
+                    if not alias_name:
+                        raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "alias data_relation sort requires an alias name", "CONTRACT_PRECHECK")
+                    relation["sortConfig"] = {
+                        "status": True,
+                        "queId": None,
+                        "qlinkerAlias": alias_name,
+                        "ascend": sort.get("direction") == "asc",
+                    }
+                    if producer.get("_app_form_type") not in {"q_linker", "code_block"}:
+                        raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "alias sort producer must be Q-Linker or code block", "CONTRACT_PRECHECK")
+                    if source_producer is None or (
+                        producer.get("que_id") or producer.get("que_temp_id"),
+                        producer.get("name"),
+                    ) != (
+                        source_producer.get("que_id") or source_producer.get("que_temp_id"),
+                        source_producer.get("name"),
+                    ):
+                        raise AppFormFailure(
+                            "UNSUPPORTED_FIELD_CONFIG",
+                            "alias sort producer must match the data_relation source producer",
+                            "CONTRACT_PRECHECK",
+                        )
+            result.append(relation)
+            if config.get("aggregation") is not None:
+                internal["aggre_type"] = AGGREGATION_TO_BACKEND[config["aggregation"]]
+        return result
+
+    @classmethod
+    def _data_relation_condition(
+        cls,
+        condition: JSONObject,
+        *,
+        source_fields: list[JSONObject],
+        current_fields: list[JSONObject],
+        source_fields_are_backend: bool,
+    ) -> JSONObject:
+        source = cls._resolve_data_relation_source_field(
+            condition.get("sourceField") or {},
+            source_fields=source_fields,
+            source_fields_are_backend=source_fields_are_backend,
+            location="sourceField",
+        )
+        operand = condition.get("operand") or {}
+        operator = str(condition.get("operator") or "")
+        cls._validate_data_relation_operator(source, operator, operand)
+        payload: JSONObject = {
+            "queId": cls._data_relation_field_ref(source),
+            "queTitle": cls._data_relation_field_name(source),
+            "queType": cls._data_relation_que_type(source),
+            "judgeType": JUDGE_TYPE_TO_BACKEND[operator],
+        }
+        if operand.get("kind") == "literal":
+            payload.update({"matchType": 1, "judgeValues": deepcopy(operand.get("values") or [])})
+        elif operand.get("kind") == "current_field":
+            target = _resolve_internal_selector(operand.get("field") or {}, current_fields, "operand.field")
+            target_id = target.get("que_id") or target.get("que_temp_id")
+            payload.update({"matchType": 2, "judgeValues": [str(target_id)], "judgeQueDetail": {"queId": target_id, "queTitle": target.get("name")}})
+        else:
+            producer = _resolve_internal_selector(operand.get("producer") or {}, current_fields, "operand.producer")
+            alias = operand.get("alias") or {}
+            payload.update(
+                {
+                    "matchType": 7,
+                    "judgeValues": [str(alias.get("name") or "")],
+                    "aliasConfig": _without_none({"queId": producer.get("que_id") or producer.get("que_temp_id"), "queTitle": producer.get("name"), "qlinkerAlias": alias.get("name"), "aliasId": _positive_int(alias.get("aliasId"))}),
+                }
+            )
+        return payload
+
+    @staticmethod
+    def _resolve_data_relation_source_field(
+        selector: JSONObject,
+        *,
+        source_fields: list[JSONObject],
+        source_fields_are_backend: bool,
+        location: str,
+    ) -> JSONObject:
+        if source_fields_are_backend:
+            return _resolve_backend_selector(selector, source_fields, location)
+        return _resolve_internal_selector(selector, source_fields, location)
+
+    @staticmethod
+    def _data_relation_field_ref(field: JSONObject) -> int | None:
+        return _positive_int(field.get("queId")) or _positive_int(field.get("que_id")) or int(field.get("que_temp_id") or 0) or None
+
+    @staticmethod
+    def _data_relation_field_name(field: JSONObject) -> str:
+        return str(field.get("queTitle") or field.get("name") or "")
+
+    @staticmethod
+    def _data_relation_que_type(field: JSONObject) -> int:
+        backend_type = _positive_int(field.get("queType"))
+        if backend_type is not None:
+            return backend_type
+        return CANONICAL_TO_QUE_TYPE.get(str(field.get("_app_form_type") or field.get("type") or ""), 2)
+
+    @staticmethod
+    def _data_relation_alias_metadata(
+        *,
+        producer: JSONObject,
+        alias: JSONObject,
+        internal_fields: list[JSONObject],
+    ) -> tuple[int, int | None]:
+        binding_key = "q_linker_binding" if producer.get("_app_form_type") == "q_linker" else "code_block_binding"
+        binding = producer.get(binding_key) if isinstance(producer.get(binding_key), dict) else {}
+        alias_name = str(alias.get("name") or "")
+        alias_id = _positive_int(alias.get("aliasId"))
+        matches = []
+        for output in binding.get("outputs") or []:
+            if not isinstance(output, dict):
+                continue
+            output_name = str(output.get("alias_name") or output.get("alias") or "")
+            output_id = _positive_int(output.get("alias_id") or output.get("aliasId"))
+            if output_name != alias_name or (alias_id is not None and output_id is not None and output_id != alias_id):
+                continue
+            matches.append(output)
+        if len(matches) != 1:
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_CONFIG",
+                "data_relation alias must resolve to exactly one producer output",
+                "CONTRACT_PRECHECK",
+                details={"producer": producer.get("name"), "alias": alias, "matches": len(matches)},
+            )
+        output = matches[0]
+        selector = output.get("target_field") or output.get("targetField") or {}
+        target = _resolve_internal_selector(selector, internal_fields, "source.alias.targetField")
+        origin_type = CANONICAL_TO_QUE_TYPE.get(str(target.get("_app_form_type") or target.get("type") or ""))
+        if origin_type is None:
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_CONFIG",
+                "data_relation alias output type is unsupported",
+                "CONTRACT_PRECHECK",
+                details={"producer": producer.get("name"), "alias": alias, "target": target.get("name")},
+            )
+        resolved_alias_id = alias_id or _positive_int(output.get("alias_id") or output.get("aliasId"))
+        return origin_type, resolved_alias_id
+
+    @staticmethod
+    def _validate_data_relation_operator(source: JSONObject, operator: str, operand: JSONObject) -> None:
+        common = {"equal", "not_equal", "is_empty", "is_not_empty"}
+        text_ops = common | {"contains", "not_contains", "equal_any", "not_equal_any", "fuzzy_match", "contains_any", "contains_all"}
+        ordered_ops = common | {"greater_than", "greater_or_equal", "less_than", "less_or_equal", "dynamic_range", "decimal_range"}
+        organization_ops = common | {"belongs_to", "not_belongs_to", "subordinate_to", "not_subordinate_to", "subordinate_included", "subordinate_not_included", "contains_any", "contains_all"}
+        field_type = _canonical_backend_field_type(source)
+        if field_type in {"number", "amount", "date", "datetime"}:
+            allowed = ordered_ops
+        elif field_type in {"member", "department"}:
+            allowed = organization_ops
+        else:
+            allowed = text_ops
+        if operator not in allowed:
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_CONFIG",
+                f"operator {operator!r} is not supported for {field_type or 'unknown'} fields",
+                "CONTRACT_PRECHECK",
+                details={"field": source.get("name"), "fieldType": field_type, "operator": operator},
+            )
+        values = operand.get("values") if operand.get("kind") == "literal" else None
+        if operator in EMPTY_OPERATORS:
+            if operand.get("kind") != "literal" or values not in ([], None):
+                raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "empty-value operators require an empty literal operand", "CONTRACT_PRECHECK")
+        elif operand.get("kind") == "literal" and not values:
+            raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "literal data_relation operands must contain at least one value", "CONTRACT_PRECHECK")
+
+    @staticmethod
+    def _field_runtime_id(field: JSONObject | None, internal_fields: list[JSONObject]) -> int | None:
+        if field is None:
+            return None
+        internal = next((item for item in internal_fields if item.get("name") == field.get("name")), None)
+        if internal is None:
+            return _positive_int(field.get("queId"))
+        return _positive_int(internal.get("que_id")) or int(internal.get("que_temp_id") or 0) or None
+
+    @staticmethod
+    def _save_base(current: JSONObject) -> JSONObject:
+        read_only = {"appKey", "formId", "baseQues", "applyAuthType", "canCurrentApply", "wsType", "accountLevel", "collectionStatus", "editVersionNo", "formQues", "questionRelations"}
+        return {key: deepcopy(value) for key, value in current.items() if key not in read_only}
+
+    def _apply_form_settings(self, payload: JSONObject, *, current_form: JSONObject, target_spec: JSONObject, internal_fields: list[JSONObject]) -> None:
+        payload["formTitle"] = target_spec["appName"]
+        payload["formDesc"] = target_spec.get("description") or ""
+        payload["formTheme"] = target_spec.get("theme")
+        payload["formStyle"] = deepcopy(target_spec.get("style"))
+        current_attachments = {
+            (str(item.get("fileName") or item.get("name") or ""), str(item.get("fileUrl") or item.get("url") or "")): item
+            for item in current_form.get("formAttach") or []
+            if isinstance(item, dict)
+        }
+        current_attachments_by_id = {
+            _positive_int(item.get("attachId") or item.get("id")): item
+            for item in current_form.get("formAttach") or []
+            if isinstance(item, dict) and _positive_int(item.get("attachId") or item.get("id")) is not None
+        }
+        payload["formAttach"] = []
+        for item in target_spec.get("attachments") or []:
+            backend = {"fileName": item["fileName"], "fileUrl": item["fileUrl"]}
+            attach_id = _positive_int(item.get("attachId"))
+            if attach_id is not None:
+                current_item = current_attachments_by_id.get(attach_id)
+                current_identity = (
+                    str((current_item or {}).get("fileName") or (current_item or {}).get("name") or ""),
+                    str((current_item or {}).get("fileUrl") or (current_item or {}).get("url") or ""),
+                )
+                if current_item is None or current_identity != (item["fileName"], item["fileUrl"]):
+                    attach_id = None
+            if attach_id is None:
+                attach_id = _positive_int(current_attachments.get((item["fileName"], item["fileUrl"]), {}).get("attachId"))
+            if attach_id is not None:
+                backend["attachId"] = attach_id
+            payload["formAttach"].append(backend)
+        serial = target_spec.get("serialNumber") or {"mode": "default"}
+        payload["serialNumType"] = 1 if serial.get("mode") == "default" else 2
+        payload["serialNumConfig"] = [] if serial.get("mode") == "default" else self._serial_components(
+            serial.get("components") or [],
+            internal_fields,
+            current_form.get("serialNumConfig") or [],
+        )
+
+    @staticmethod
+    def _serial_components(components: list[JSONObject], fields: list[JSONObject], current: list[Any] | None = None) -> list[JSONObject]:
+        type_ids = {"auto_count": 1, "submit_datetime": 2, "fixed_text": 3, "field": 4}
+        result = []
+        current = current or []
+        for index, item in enumerate(components):
+            component_id = _positive_int(item.get("id"))
+            if component_id is None and index < len(current) and isinstance(current[index], dict):
+                current_item = current[index]
+                if _positive_int(current_item.get("type")) == type_ids[item["type"]]:
+                    component_id = _positive_int(current_item.get("id"))
+            payload: JSONObject = _without_none({"id": component_id, "type": type_ids[item["type"]]})
+            if item["type"] == "auto_count":
+                payload.update({"length": item["length"], "repeatPeriod": REPEAT_PERIOD_TO_BACKEND[item["repeatPeriod"]]})
+            elif item["type"] == "submit_datetime":
+                payload["dateFormat"] = DATE_FORMAT_TO_BACKEND[item["dateFormat"]]
+            elif item["type"] == "fixed_text":
+                payload["customTitle"] = item["value"]
+            else:
+                field = _resolve_internal_selector(item["field"], fields, "serialNumber.components.field")
+                payload.update({"queId": field.get("que_id") or field.get("que_temp_id"), "queTitle": field.get("name")})
+                if item.get("dateFormat"):
+                    payload["dateFormat"] = DATE_FORMAT_TO_BACKEND[item["dateFormat"]]
+            result.append(payload)
+        return result
+
+    def _read_form(self, profile: str, app_key: str, *, being_draft: bool) -> JSONObject:
+        response = self.apps.app_get_form_schema(
+            profile=profile,
+            app_key=app_key,
+            form_type=1,
+            being_draft=being_draft,
+            being_apply=None,
+            audit_node_id=None,
+            include_raw=True,
+        )
+        value = response.get("result")
+        if not isinstance(value, dict):
+            raise AppFormFailure("FORM_READ_FAILED", "backend returned an invalid form", "READ")
+        return value
+
+
+class AppFormReconciler:
+    RUNTIME_VERSION = "v1alpha1"
+
+    def __init__(self, *, apps: AppTools, packages: PackageTools, registry: AppFormSchemaRegistry) -> None:
+        self.apps = apps
+        self.packages = packages
+        self.registry = registry
+        self.normalizer = AppFormNormalizer()
+        self.compiler = AppFormCompiler(apps)
+
+    def schema(self, *, schema_version: str | None, field_type: str | None) -> JSONObject:
+        try:
+            return {"status": "success", **self.registry.schema(schema_version=schema_version, field_type=field_type)}
+        except AppFormContractError as error:
+            return self._failure(error.error_code, error.message, "SCHEMA", details=error.details)
+
+    def _runtime_for(self, context: AppFormSchemaContext) -> tuple[AppFormNormalizer, AppFormCompiler]:
+        if context.normalizer_version != self.RUNTIME_VERSION:
+            raise AppFormContractError(
+                "SCHEMA_VERSION_MISMATCH",
+                "AppForm schema version has no matching reconciler runtime",
+                details={
+                    "schemaVersion": context.schema_version,
+                    "normalizerVersion": context.normalizer_version,
+                    "runtimeVersion": self.RUNTIME_VERSION,
+                },
+            )
+        return self.normalizer, self.compiler
+
+    def get(self, *, profile: str, app_key: str, schema_version: str | None, being_draft: bool) -> JSONObject:
+        try:
+            context = self.registry.resolve_schema_version(schema_version)
+            normalizer, _compiler = self._runtime_for(context)
+            form = self._read_form(profile, app_key, being_draft=being_draft)
+            resource = normalizer.from_backend(context=context, app_key=app_key, form=form)
+            context.validate(resource)
+            return {"status": "success", "schemaVersion": context.schema_version, "source": "draft" if being_draft else "published", "resource": resource}
+        except (AppFormContractError, AppFormFailure) as error:
+            return self._from_error(error)
+        except (QingflowApiError, RuntimeError) as error:
+            return self._api_failure("FORM_READ_FAILED", error, "GET")
+
+    def apply(self, *, profile: str, spec: JSONObject) -> JSONObject:
+        warnings: list[JSONObject] = []
+        app_key: str | None = None
+        created = False
+        binding_repair_needed = False
+        diagnostics = self._diagnostics()
+        try:
+            if not isinstance(spec, dict):
+                raise AppFormContractError("INVALID_SPEC", "AppForm apply payload must be an object", path="/")
+            _validate_payload_limits(spec)
+            api_version = spec.get("apiVersion")
+            if not isinstance(api_version, str) or not api_version.strip():
+                raise AppFormContractError("INVALID_SPEC", "apiVersion is required", path="/apiVersion")
+            context = self.registry.resolve_api_version(api_version)
+            normalizer, compiler = self._runtime_for(context)
+            declaration, warnings = normalize_app_form_declaration(spec)
+            is_update = "appKey" in declaration
+            diagnostics["applyMode"] = "update" if is_update else "create"
+            if not is_update and (
+                _positive_int(declaration.get("packageId")) is None
+                or not isinstance(declaration.get("spec"), dict)
+                or not str(declaration["spec"].get("appName") or "").strip()
+            ):
+                raise AppFormContractError(
+                    "INVALID_APPLY_TARGET",
+                    "create mode requires packageId and spec.appName",
+                    details={"mode": "create"},
+                )
+            if not is_update:
+                validate_app_form_create_icon(declaration)
+            apply_dto = context.parse_apply(declaration)
+            context.assert_apply_dto(apply_dto)
+            declaration = apply_dto.resource
+            package_id = _positive_int(declaration.get("packageId"))
+            diagnostics["packageId"] = package_id
+            preliminary_form: JSONObject | None = None
+            if is_update:
+                app_key = str(declaration["appKey"])
+                try:
+                    self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True)
+                    preliminary_form = self._read_form(profile, app_key, being_draft=True)
+                    compiler.preflight(
+                        profile=profile,
+                        app_key=app_key,
+                        declaration=declaration,
+                        current_form=preliminary_form,
+                    )
+                except (QingflowApiError, RuntimeError) as error:
+                    if self._is_not_found_error(error):
+                        raise AppFormFailure("APP_NOT_FOUND", "target application was not found", "TARGET_PRECHECK") from error
+                    raise
+            else:
+                try:
+                    self._read_package(profile, package_id or 0)
+                except (QingflowApiError, RuntimeError) as error:
+                    if self._is_not_found_error(error):
+                        raise AppFormFailure("PACKAGE_NOT_FOUND", "target package was not found", "TARGET_PRECHECK") from error
+                    raise
+                try:
+                    compiler.preflight(
+                        profile=profile,
+                        app_key="",
+                        declaration=declaration,
+                        current_form=None,
+                    )
+                except (QingflowApiError, RuntimeError) as error:
+                    if self._is_not_found_error(error):
+                        raise AppFormFailure("APP_NOT_FOUND", "referenced application was not found", "REFERENCE_PRECHECK") from error
+                    raise
+                app_key = self._create(profile, declaration)
+                created = True
+                diagnostics["operation"] = "CREATED"
+            try:
+                package_attached = self._package_contains(profile, package_id, app_key) if package_id is not None else None
+            except (QingflowApiError, RuntimeError) as error:
+                if self._is_not_found_error(error):
+                    raise AppFormFailure("PACKAGE_NOT_FOUND", "target package was not found", "TARGET_PRECHECK") from error
+                raise
+            diagnostics["packagePhase"] = "SKIPPED_UNMANAGED" if package_id is None else "SKIPPED_ALREADY_ATTACHED" if package_attached else "PENDING"
+            diagnostics["packageAttached"] = package_attached
+
+            if preliminary_form is None:
+                preliminary_form = self._read_form(profile, app_key, being_draft=True)
+            try:
+                current = normalizer.from_backend(context=context, app_key=app_key, form=preliminary_form)
+            except AppFormFailure as error:
+                if not compiler.is_unbound_intermediate_error(error):
+                    raise
+                diagnostics["pendingBindings"] = compiler.pending_bindings(declaration)
+                declaration = compiler.bind_backend_identities(form=preliminary_form, resource=declaration)
+                current = compiler.recovery_resource(
+                    context=context,
+                    app_key=app_key,
+                    form=preliminary_form,
+                    declaration=declaration,
+                )
+                binding_repair_needed = True
+            target = compiler.target_resource(context=context, app_key=app_key, current=current, declaration=declaration)
+            form_changed = binding_repair_needed or not _canonical_equal(current, target)
+            publish_needed = created
+            if not form_changed and not created:
+                try:
+                    published_form = self._read_form(profile, app_key, being_draft=False)
+                    published = normalizer.from_backend(context=context, app_key=app_key, form=published_form)
+                    publish_needed = not _canonical_equal(current, published)
+                except (QingflowApiError, RuntimeError, AppFormFailure) as error:
+                    raise AppFormFailure("PUBLISHED_FORM_READ_FAILED", str(error), "PRECHECK_PUBLISHED_READ") from error
+            diagnostics["diff"] = self._diff(current, target)
+
+            if not form_changed and not publish_needed:
+                diagnostics["targetApplied"] = True
+                diagnostics["remainingDiff"] = self._diff(current, target)
+                diagnostics["published"] = True
+                if package_id is not None and not package_attached:
+                    self._attach_package(profile, package_id, app_key, target["spec"]["appName"], diagnostics)
+                    diagnostics["operation"] = "APPLIED"
+                else:
+                    diagnostics["operation"] = "UNCHANGED"
+                return self._success(context, target, diagnostics, warnings)
+
+            edit_version_no = self._edit_version(profile, app_key)
+            authoritative_form = self._read_form(profile, app_key, being_draft=True)
+            if binding_repair_needed:
+                authoritative = compiler.recovery_resource(
+                    context=context,
+                    app_key=app_key,
+                    form=authoritative_form,
+                    declaration=declaration,
+                )
+            else:
+                authoritative = normalizer.from_backend(context=context, app_key=app_key, form=authoritative_form)
+            target = compiler.target_resource(context=context, app_key=app_key, current=authoritative, declaration=declaration)
+            form_changed = binding_repair_needed or not _canonical_equal(authoritative, target)
+            diagnostics["diff"] = self._diff(authoritative, target)
+            wrote_form = False
+            if form_changed:
+                needs_identity_write = compiler.needs_identity_write(target)
+                if needs_identity_write:
+                    diagnostics["pendingBindings"] = compiler.pending_bindings(target)
+                first_target = compiler.identity_target(current=authoritative, target=target) if needs_identity_write else target
+                payload = compiler.payload(
+                    profile=profile,
+                    app_key=app_key,
+                    current_form=authoritative_form,
+                    target=first_target,
+                    edit_version_no=edit_version_no,
+                )
+                diagnostics["writeAttempts"] += 1
+                diagnostics["formPhase"] = (
+                    "IDENTITY_WRITE"
+                    if needs_identity_write
+                    else "RELATION_REBIND"
+                    if binding_repair_needed
+                    else "DIRECT_WRITE"
+                )
+                try:
+                    self.apps.app_update_form_schema(profile=profile, app_key=app_key, payload=payload)
+                except (QingflowApiError, RuntimeError) as error:
+                    self._raise_write_failure(error, diagnostics, first_write=True)
+                diagnostics["writeCount"] += 1
+                wrote_form = True
+                if needs_identity_write:
+                    rebound_form = self._read_form(profile, app_key, being_draft=True)
+                    rebound_target = compiler.bind_backend_identities(form=rebound_form, resource=target)
+                    rebound_payload = compiler.payload(
+                        profile=profile,
+                        app_key=app_key,
+                        current_form=rebound_form,
+                        target=rebound_target,
+                        edit_version_no=edit_version_no,
+                    )
+                    diagnostics["writeAttempts"] += 1
+                    try:
+                        self.apps.app_update_form_schema(profile=profile, app_key=app_key, payload=rebound_payload)
+                    except (QingflowApiError, RuntimeError) as error:
+                        self._raise_write_failure(error, diagnostics, first_write=False)
+                    diagnostics["writeCount"] += 1
+                    diagnostics["formPhase"] = "RELATION_REBIND"
+
+            if wrote_form:
+                draft_form = self._read_form(profile, app_key, being_draft=True)
+                draft = normalizer.from_backend(context=context, app_key=app_key, form=draft_form)
+                bound_target = compiler.bind_backend_identities(form=draft_form, resource=target)
+                expected_form = compiler.payload(
+                    profile=profile,
+                    app_key=app_key,
+                    current_form=draft_form,
+                    target=bound_target,
+                    edit_version_no=edit_version_no,
+                )
+                expected = normalizer.from_backend(context=context, app_key=app_key, form=expected_form)
+            else:
+                draft = authoritative
+                expected = target
+
+            diagnostics["targetApplied"] = _canonical_equal(draft, expected)
+            diagnostics["remainingDiff"] = self._diff(draft, expected)
+            if diagnostics["targetApplied"] is not True:
+                raise AppFormFailure(
+                    "APPLY_READBACK_MISMATCH",
+                    "form readback did not match the complete apply target",
+                    "FORM_READBACK",
+                    status="partial_success",
+                    details={"remainingDiff": deepcopy(diagnostics["remainingDiff"])},
+                )
+
+            publish_needed = created or wrote_form
+            if not publish_needed:
+                try:
+                    published_form = self._read_form(profile, app_key, being_draft=False)
+                    published = normalizer.from_backend(context=context, app_key=app_key, form=published_form)
+                    diagnostics["published"] = _canonical_equal(draft, published)
+                    publish_needed = not diagnostics["published"]
+                except (QingflowApiError, RuntimeError, AppFormFailure) as error:
+                    self._finish_edit(profile, app_key, edit_version_no, diagnostics)
+                    raise AppFormFailure(
+                        "PUBLISHED_FORM_READ_FAILED",
+                        str(error),
+                        "AUTHORITATIVE_PUBLISHED_READ",
+                        status="partial_success",
+                        details=diagnostics,
+                    ) from error
+
+            if publish_needed:
+                self._publish_and_verify(
+                    profile=profile,
+                    app_key=app_key,
+                    edit_version_no=edit_version_no,
+                    context=context,
+                    draft=draft,
+                    diagnostics=diagnostics,
+                )
+            else:
+                self._finish_edit(profile, app_key, edit_version_no, diagnostics)
+            if package_id is not None and not package_attached:
+                self._attach_package(profile, package_id, app_key, draft["spec"]["appName"], diagnostics)
+            diagnostics["operation"] = "CREATED" if created else "APPLIED" if wrote_form or publish_needed or diagnostics["packageAttachCount"] else "UNCHANGED"
+            return self._success(context, draft, diagnostics, warnings)
+        except AppFormContractError as error:
+            return self._failure(error.error_code, error.message, "VALIDATE", details={**error.details, **({"path": error.path} if error.path else {})}, diagnostics=diagnostics, app_key=app_key, warnings=warnings)
+        except AppFormFailure as error:
+            status = "partial_success" if created and error.status == "failed" else error.status
+            return self._failure(error.error_code, error.message, error.phase, status=status, details=error.details, diagnostics=diagnostics, app_key=app_key, warnings=warnings)
+        except (QingflowApiError, RuntimeError) as error:
+            uncertain = self._is_uncertain_api_error(error)
+            code = (
+                "APP_CREATE_RESULT_UNKNOWN"
+                if not app_key and uncertain
+                else "APP_CREATE_FAILED"
+                if not app_key
+                else "APPLY_RESULT_UNKNOWN"
+                if uncertain
+                else "APP_FORM_APPLY_FAILED"
+            )
+            mutation_started = bool(
+                created
+                or diagnostics["writeAttempts"]
+                or diagnostics["publishAttempted"]
+                or diagnostics["packageAttachAttempted"]
+            )
+            status = "unknown" if uncertain else "partial_success" if mutation_started else "failed"
+            return self._api_failure(code, error, "CREATE" if not app_key else "APPLY", status=status, diagnostics=diagnostics, app_key=app_key, warnings=warnings)
+
+    def delete(self, *, profile: str, app_key: str) -> JSONObject:
+        try:
+            result = self.apps.app_delete(profile=profile, app_key=app_key)
+            return {"status": "success", "operation": "DELETED", "appKey": app_key, "result": result.get("result")}
+        except (QingflowApiError, RuntimeError) as error:
+            return self._api_failure("APP_DELETE_FAILED", error, "DELETE", app_key=app_key)
+
+    def _create(self, profile: str, declaration: JSONObject) -> str:
+        spec = declaration["spec"]
+        app_name = str(spec["appName"])
+        package_id = int(declaration["packageId"])
+        icon = str(spec["icon"])
+        color = str(spec["color"])
+        payload = {
+            "appName": app_name,
+            "appIcon": encode_workspace_icon(icon=icon, color=color, title=app_name),
+            "auth": default_member_auth(),
+            "tagIds": [package_id],
+        }
+        created = self.apps.app_create(profile=profile, payload=payload, retry_without_qf_version=False)
+        result = created.get("result") if isinstance(created.get("result"), dict) else {}
+        app_key = str(result.get("appKey") or ((result.get("appKeys") or [""])[0] if isinstance(result.get("appKeys"), list) else ""))
+        if not app_key:
+            raise AppFormFailure("APP_CREATE_RESULT_UNKNOWN", "create response did not contain appKey", "CREATE", status="unknown", details={"createResult": result})
+        return app_key
+
+    def _publish_and_verify(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        edit_version_no: int,
+        context: AppFormSchemaContext,
+        draft: JSONObject,
+        diagnostics: JSONObject,
+    ) -> None:
+        for attempt in range(2):
+            try:
+                self._publish_once(profile, app_key, edit_version_no, diagnostics)
+                break
+            except AppFormFailure as error:
+                if error.error_code == "PUBLISH_FAILED":
+                    diagnostics["published"] = False
+                    raise
+                if error.error_code != "APPLY_RESULT_UNKNOWN":
+                    raise
+            except (QingflowApiError, RuntimeError) as error:
+                details = self._error_details(error)
+                if self._looks_like_version_conflict(details):
+                    raise AppFormFailure(
+                        "EDIT_VERSION_CONFLICT",
+                        "the application edit version changed during publish",
+                        "PUBLISH",
+                        status="partial_success",
+                        details={**diagnostics, "transportError": details},
+                    ) from error
+                if not self._is_uncertain_api_error(error):
+                    diagnostics.update({"publishResponseAccepted": False, "published": False})
+                    raise AppFormFailure(
+                        "PUBLISH_FAILED",
+                        "publish request was rejected",
+                        "PUBLISH",
+                        status="partial_success",
+                        details={**diagnostics, "transportError": self._error_details(error)},
+                    ) from error
+
+            diagnostics["publishResponseAccepted"] = None
+            recovered = self._published_matches(profile, app_key, context, draft, diagnostics)
+            if recovered is True:
+                finish_error: AppFormFailure | None = None
+                try:
+                    self._finish_edit(profile, app_key, edit_version_no, diagnostics)
+                except AppFormFailure as error:
+                    finish_error = error
+                self._published_matches(profile, app_key, context, draft, diagnostics)
+                if finish_error is not None:
+                    self._raise_finish_failure(finish_error, diagnostics)
+                if diagnostics["published"] is not True:
+                    raise AppFormFailure(
+                        "PUBLISH_FAILED" if diagnostics["published"] is False else "APPLY_RESULT_UNKNOWN",
+                        "published form changed during publish recovery",
+                        "PUBLISH_READBACK",
+                        status="partial_success" if diagnostics["published"] is False else "unknown",
+                        details=diagnostics,
+                    )
+                return
+            if attempt == 0 and recovered is False:
+                continue
+            raise AppFormFailure(
+                "APPLY_RESULT_UNKNOWN",
+                "publish result could not be confirmed",
+                "PUBLISH",
+                status="unknown",
+                details=diagnostics,
+            )
+
+        finish_error: AppFormFailure | None = None
+        try:
+            self._finish_edit(profile, app_key, edit_version_no, diagnostics)
+        except AppFormFailure as error:
+            finish_error = error
+        self._published_matches(profile, app_key, context, draft, diagnostics)
+        if finish_error is not None:
+            self._raise_finish_failure(finish_error, diagnostics)
+        if diagnostics["published"] is not True:
+            raise AppFormFailure(
+                "PUBLISH_FAILED" if diagnostics["published"] is False else "APPLY_RESULT_UNKNOWN",
+                "published form could not be verified against the draft",
+                "PUBLISH_READBACK",
+                status="partial_success" if diagnostics["published"] is False else "unknown",
+                details=diagnostics,
+            )
+
+    def _publish_once(self, profile: str, app_key: str, edit_version_no: int, diagnostics: JSONObject) -> None:
+        diagnostics["publishAttempted"] = True
+        diagnostics["publishAttempts"] += 1
+        response = self.apps.app_publish_raw(
+            profile=profile,
+            app_key=app_key,
+            payload={"editVersionNo": edit_version_no},
+        )
+        http_status = response.get("http_status")
+        raw = response.get("response")
+        if self._looks_like_version_conflict({"http_status": http_status, "response": raw}):
+            raise AppFormFailure(
+                "EDIT_VERSION_CONFLICT",
+                "the application edit version changed during publish",
+                "PUBLISH",
+                status="partial_success",
+                details={**diagnostics, "response": deepcopy(raw)},
+            )
+        if not isinstance(http_status, int) or not 200 <= http_status < 300 or not isinstance(raw, dict):
+            raise AppFormFailure(
+                "APPLY_RESULT_UNKNOWN",
+                "publish response did not contain a valid HTTP result envelope",
+                "PUBLISH",
+                status="unknown",
+                details=diagnostics,
+            )
+
+        has_success = "success" in raw
+        has_code = "code" in raw
+        success_ok = raw.get("success") is True if has_success else None
+        code_value = raw.get("code")
+        code_ok = isinstance(code_value, int) and not isinstance(code_value, bool) and code_value == 0 if has_code else None
+        if not has_success and not has_code:
+            raise AppFormFailure(
+                "APPLY_RESULT_UNKNOWN",
+                "publish response omitted the ResponseResult success indicator",
+                "PUBLISH",
+                status="unknown",
+                details=diagnostics,
+            )
+        if success_ok is False or code_ok is False or (success_ok is not None and code_ok is not None and success_ok != code_ok):
+            diagnostics["publishResponseAccepted"] = False
+            raise AppFormFailure(
+                "PUBLISH_FAILED",
+                "publish ResponseResult reported failure",
+                "PUBLISH",
+                status="partial_success",
+                details={**diagnostics, "response": deepcopy(raw)},
+            )
+
+        result = next((raw[key] for key in ("result", "data", "page", "obj") if key in raw), None)
+        if not isinstance(result, dict):
+            raise AppFormFailure(
+                "APPLY_RESULT_UNKNOWN",
+                "publish response did not contain a PublishRes object",
+                "PUBLISH",
+                status="unknown",
+                details=diagnostics,
+            )
+        diagnostics["appPublishStatus"] = result.get("appPublishStatus")
+        diagnostics["publishDetails"] = deepcopy(result.get("details") or [])
+        if result.get("publishSuccess") is False:
+            diagnostics["publishResponseAccepted"] = False
+            raise AppFormFailure(
+                "PUBLISH_FAILED",
+                "publish checks did not pass",
+                "PUBLISH",
+                status="partial_success",
+                details=diagnostics,
+            )
+        if result.get("publishSuccess") is not True:
+            raise AppFormFailure(
+                "APPLY_RESULT_UNKNOWN",
+                "PublishRes.publishSuccess was missing or invalid",
+                "PUBLISH",
+                status="unknown",
+                details=diagnostics,
+            )
+        diagnostics["publishResponseAccepted"] = True
+        diagnostics["publishCount"] += 1
+
+    def _published_matches(
+        self,
+        profile: str,
+        app_key: str,
+        context: AppFormSchemaContext,
+        draft: JSONObject,
+        diagnostics: JSONObject,
+    ) -> bool | None:
+        try:
+            published_form = self._read_form(profile, app_key, being_draft=False)
+            normalizer, _compiler = self._runtime_for(context)
+            published = normalizer.from_backend(context=context, app_key=app_key, form=published_form)
+            diagnostics["published"] = _canonical_equal(draft, published)
+        except (QingflowApiError, RuntimeError, AppFormFailure):
+            diagnostics["published"] = None
+        return diagnostics["published"]
+
+    def _finish_edit(self, profile: str, app_key: str, edit_version_no: int, diagnostics: JSONObject) -> None:
+        try:
+            self.apps.app_edit_finished(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
+        except (QingflowApiError, RuntimeError) as error:
+            details = self._error_details(error)
+            if self._looks_like_version_conflict(details):
+                raise AppFormFailure(
+                    "EDIT_VERSION_CONFLICT",
+                    "the application edit version changed before editing could be finished",
+                    "EDIT_FINISHED",
+                    status="partial_success",
+                    details={**diagnostics, "transportError": details},
+                ) from error
+            raise AppFormFailure(
+                "EDIT_FINISHED_FAILED",
+                "application editing could not be finished",
+                "EDIT_FINISHED",
+                status="partial_success",
+                details={**diagnostics, "transportError": details},
+            ) from error
+        diagnostics["editFinished"] = True
+
+    @staticmethod
+    def _raise_finish_failure(error: AppFormFailure, diagnostics: JSONObject) -> None:
+        raise AppFormFailure(
+            error.error_code,
+            error.message,
+            error.phase,
+            status=error.status,
+            details={**(error.details or {}), **diagnostics},
+        ) from error
+
+    def _raise_write_failure(self, error: QingflowApiError | RuntimeError, diagnostics: JSONObject, *, first_write: bool) -> None:
+        details = self._error_details(error)
+        if self._looks_like_version_conflict(details):
+            raise AppFormFailure(
+                "EDIT_VERSION_CONFLICT",
+                "the application edit version changed during apply",
+                diagnostics["formPhase"],
+                status="failed" if first_write else "partial_success",
+                details={**diagnostics, "transportError": details},
+            ) from error
+        diagnostics["writeMayHaveSucceeded"] = self._is_uncertain_api_error(error)
+        raise AppFormFailure(
+            "APPLY_RESULT_UNKNOWN" if diagnostics["writeMayHaveSucceeded"] else "RELATION_REBIND_FAILED" if not first_write else "APP_FORM_WRITE_FAILED",
+            "form write failed or could not be confirmed",
+            diagnostics["formPhase"],
+            status="unknown" if diagnostics["writeMayHaveSucceeded"] else "partial_success" if not first_write else "failed",
+            details={**diagnostics, "transportError": details},
+        ) from error
+
+    @staticmethod
+    def _error_details(error: QingflowApiError | RuntimeError) -> JSONObject:
+        if isinstance(error, QingflowApiError):
+            return error.to_dict()
+        try:
+            value = json.loads(str(error))
+        except (TypeError, json.JSONDecodeError):
+            return {"message": str(error)}
+        return value if isinstance(value, dict) else {"message": str(error)}
+
+    @classmethod
+    def _is_uncertain_api_error(cls, error: QingflowApiError | RuntimeError) -> bool:
+        return str(cls._error_details(error).get("category") or "").lower() == "network"
+
+    @staticmethod
+    def _looks_like_version_conflict(details: JSONObject) -> bool:
+        rendered = json.dumps(details, ensure_ascii=False, sort_keys=True).lower()
+        codes = {
+            details.get("backend_code"),
+            details.get("code"),
+            details.get("http_status"),
+        }
+        return (
+            "editversion" in rendered
+            or "edit version" in rendered
+            or "编辑版本" in rendered
+            or any(code in {409, "409", 49613, "49613"} for code in codes)
+        )
+
+    @classmethod
+    def _is_not_found_error(cls, error: QingflowApiError | RuntimeError) -> bool:
+        if isinstance(error, QingflowApiError) and is_auth_like_error(error):
+            return False
+        details = cls._error_details(error)
+        return details.get("http_status") == 404 or details.get("backend_code") in {404, "404", 40002, "40002", 40027, "40027"}
+
+    def _attach_package(self, profile: str, package_id: int, app_key: str, title: str, diagnostics: JSONObject) -> None:
+        diagnostics["packageAttachAttempted"] = True
+        package = self._read_package(profile, package_id)
+        items = [deepcopy(item) for item in package.get("tagItems") or [] if isinstance(item, dict)]
+        if any(str(item.get("appKey") or "") == app_key for item in items):
+            diagnostics.update({"packagePhase": "SKIPPED_ALREADY_ATTACHED", "packageAttached": True})
+            return
+        items.append({"itemType": 1, "appKey": app_key, "title": title, "iconUrl": None})
+        try:
+            self.packages.package_sort_items(profile=profile, tag_id=package_id, tag_items=items)
+        except (QingflowApiError, RuntimeError) as error:
+            uncertain = self._is_uncertain_api_error(error)
+            diagnostics["packageAttachMayHaveSucceeded"] = uncertain
+            raise AppFormFailure(
+                "PACKAGE_ATTACH_RESULT_UNKNOWN" if uncertain else "PACKAGE_ATTACH_FAILED",
+                "package attachment failed or could not be confirmed",
+                "PACKAGE_ATTACH",
+                status="unknown" if uncertain else "partial_success",
+                details={**diagnostics, "transportError": self._error_details(error)},
+            ) from error
+        diagnostics["packageAttachCount"] = 1
+        try:
+            attached = self._package_contains(profile, package_id, app_key)
+        except (QingflowApiError, RuntimeError, AppFormFailure) as error:
+            diagnostics["packageAttachMayHaveSucceeded"] = True
+            raise AppFormFailure(
+                "PACKAGE_ATTACH_RESULT_UNKNOWN",
+                "package attachment could not be read back",
+                "PACKAGE_ATTACH",
+                status="unknown",
+                details={**diagnostics, "readbackError": str(error)},
+            ) from error
+        if not attached:
+            diagnostics["packageAttachMayHaveSucceeded"] = True
+            raise AppFormFailure(
+                "PACKAGE_ATTACH_RESULT_UNKNOWN",
+                "package attachment was not present on readback",
+                "PACKAGE_ATTACH",
+                status="partial_success",
+                details=diagnostics,
+            )
+        diagnostics.update({"packagePhase": "ATTACHED", "packageAttached": True})
+
+    def _read_form(self, profile: str, app_key: str, *, being_draft: bool) -> JSONObject:
+        response = self.apps.app_get_form_schema(profile=profile, app_key=app_key, form_type=1, being_draft=being_draft, being_apply=None, audit_node_id=None, include_raw=True)
+        result = response.get("result")
+        if not isinstance(result, dict):
+            raise AppFormFailure("FORM_READ_FAILED", "backend returned invalid FormInfo", "READ")
+        return result
+
+    def _read_package(self, profile: str, package_id: int) -> JSONObject:
+        response = self.packages.package_get(profile=profile, tag_id=package_id, include_raw=True)
+        result = response.get("result")
+        if not isinstance(result, dict):
+            raise AppFormFailure("PACKAGE_READ_FAILED", "backend returned invalid package detail", "TARGET_PRECHECK")
+        return result
+
+    def _package_contains(self, profile: str, package_id: int | None, app_key: str) -> bool | None:
+        if package_id is None:
+            return None
+        package = self._read_package(profile, package_id)
+        return any(str(item.get("appKey") or "") == app_key for item in package.get("tagItems") or [] if isinstance(item, dict))
+
+    def _edit_version(self, profile: str, app_key: str) -> int:
+        response = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key)
+        result = response.get("result")
+        version = _positive_int(result.get("editVersionNo")) if isinstance(result, dict) else _positive_int(result)
+        if version is None:
+            raise AppFormFailure("EDIT_VERSION_READ_FAILED", "editVersionNo response was invalid", "EDIT_VERSION")
+        return version
+
+    @staticmethod
+    def _diff(current: JSONObject, target: JSONObject) -> JSONObject:
+        current_fields = {_positive_int(item.get("queId")) or f"name:{item.get('name')}": item for item in _iter_fields(current["spec"]["body"])}
+        target_fields = {_positive_int(item.get("queId")) or f"name:{item.get('name')}": item for item in _iter_fields(target["spec"]["body"])}
+        return {
+            "added": [deepcopy(item) for key, item in target_fields.items() if key not in current_fields],
+            "updated": [deepcopy(item) for key, item in target_fields.items() if key in current_fields and _semantic(item) != _semantic(current_fields[key])],
+            "removed": [deepcopy(item) for key, item in current_fields.items() if key not in target_fields],
+            "layoutChanged": _layout_semantic(current["spec"]["body"]) != _layout_semantic(target["spec"]["body"]),
+            "configChanged": _semantic({key: value for key, value in target["spec"].items() if key != "body"}) != _semantic({key: value for key, value in current["spec"].items() if key != "body"}),
+        }
+
+    @staticmethod
+    def _diagnostics() -> JSONObject:
+        return {
+            "operation": "APPLIED",
+            "applyMode": None,
+            "packageId": None,
+            "diff": {},
+            "targetApplied": None,
+            "remainingDiff": {},
+            "writeCount": 0,
+            "writeAttempts": 0,
+            "writeMayHaveSucceeded": False,
+            "formPhase": "NO_WRITE",
+            "pendingBindings": [],
+            "publishAttempted": False,
+            "publishAttempts": 0,
+            "publishResponseAccepted": None,
+            "publishCount": 0,
+            "published": None,
+            "editFinished": False,
+            "packageAttachAttempted": False,
+            "packageAttachCount": 0,
+            "packageAttached": None,
+            "packageAttachMayHaveSucceeded": False,
+            "packagePhase": "SKIPPED_UNMANAGED",
+        }
+
+    @staticmethod
+    def _success(context: AppFormSchemaContext, resource: JSONObject, diagnostics: JSONObject, warnings: list[JSONObject]) -> JSONObject:
+        diff = diagnostics.get("diff") if isinstance(diagnostics.get("diff"), dict) else {}
+        changes: JSONObject = {}
+        for source_key, result_key in (
+            ("added", "addedFields"),
+            ("updated", "updatedFields"),
+            ("removed", "removedFields"),
+        ):
+            fields = diff.get(source_key)
+            if isinstance(fields, list) and fields:
+                changes[result_key] = [
+                    str(field.get("name") or field.get("queId") or "unknown")
+                    for field in fields
+                    if isinstance(field, dict)
+                ]
+        if diff.get("layoutChanged") is True:
+            changes["layoutChanged"] = True
+        if diff.get("configChanged") is True:
+            changes["configChanged"] = True
+
+        actions = {
+            key: value
+            for key, value in {
+                "formWrites": diagnostics.get("writeCount"),
+                "publishes": diagnostics.get("publishCount"),
+                "packageAttachments": diagnostics.get("packageAttachCount"),
+            }.items()
+            if isinstance(value, int) and value > 0
+        }
+        return {
+            "status": "success",
+            "schemaVersion": context.schema_version,
+            "operation": diagnostics["operation"],
+            "appKey": resource["appKey"],
+            "appName": resource["spec"]["appName"],
+            **({"changes": changes} if changes else {}),
+            **({"actions": actions} if actions else {}),
+            **({"warnings": warnings} if warnings else {}),
+        }
+
+    @staticmethod
+    def _failure(error_code: str, message: str, phase: str, *, status: str = "failed", details: JSONObject | None = None, diagnostics: JSONObject | None = None, app_key: str | None = None, warnings: list[JSONObject] | None = None) -> JSONObject:
+        result = {
+            "status": status,
+            "error_code": error_code,
+            "recoverable": status != "failed" or error_code in {"PUBLISH_FAILED", "PACKAGE_ATTACH_RESULT_UNKNOWN"},
+            "message": message,
+            **(diagnostics or {}),
+            "phase": phase,
+            **({"appKey": app_key} if app_key else {}),
+            **({"details": details} if details else {}),
+            **({"warnings": warnings} if warnings else {}),
+        }
+        recovery = {
+            "EDIT_VERSION_CONFLICT": "read the latest draft, rebuild the complete declaration, validate, and retry once",
+            "EDIT_FINISHED_FAILED": "if published equals draft, release the current account's edit lock without publishing again",
+            "APP_CREATE_RESULT_UNKNOWN": "do not replay the create declaration without an appKey",
+            "APPLY_READBACK_MISMATCH": "read the latest draft, rebuild the complete declaration, validate, and retry once",
+            "PACKAGE_ATTACH_RESULT_UNKNOWN": "retain appKey, packageId, and the complete spec before recovery",
+        }.get(error_code)
+        if recovery:
+            result["recoveryHint"] = recovery
+        return result
+
+    @classmethod
+    def _from_error(cls, error: AppFormContractError | AppFormFailure) -> JSONObject:
+        if isinstance(error, AppFormContractError):
+            return cls._failure(error.error_code, error.message, "VALIDATE", details={**error.details, **({"path": error.path} if error.path else {})})
+        return cls._failure(error.error_code, error.message, error.phase, status=error.status, details=error.details)
+
+    @classmethod
+    def _api_failure(cls, error_code: str, error: QingflowApiError | RuntimeError, phase: str, *, status: str = "failed", diagnostics: JSONObject | None = None, app_key: str | None = None, warnings: list[JSONObject] | None = None) -> JSONObject:
+        details = cls._error_details(error)
+        return cls._failure(
+            error_code,
+            str(details.get("message") or error),
+            phase,
+            status=status,
+            details=_without_none(details),
+            diagnostics=diagnostics,
+            app_key=app_key,
+            warnings=warnings,
+        )
+
+
+def _walk_selectors(value: Any) -> Iterable[JSONObject]:
+    if isinstance(value, dict):
+        if "queId" in value or "name" in value:
+            yield value
+        for item in value.values():
+            yield from _walk_selectors(item)
+    elif isinstance(value, list):
+        for item in value:
+            yield from _walk_selectors(item)
+
+
+def _snake_selector(value: Any) -> JSONObject:
+    value = value if isinstance(value, dict) else {}
+    return _without_none({"que_id": _positive_int(value.get("queId")), "name": value.get("name")})
+
+
+def _snake_q_linker(value: JSONObject) -> JSONObject:
+    request = value.get("request") if isinstance(value.get("request"), dict) else {}
+    return {
+        "inputs": [
+            {"field": _snake_selector(item.get("field")), "key": item.get("key"), "source": item.get("source")}
+            for item in value.get("inputs") or []
+            if isinstance(item, dict)
+        ],
+        "request": _without_none(
+            {
+                "url": request.get("url"),
+                "method": request.get("method") or "GET",
+                "headers": deepcopy(request.get("headers") or []),
+                "query_params": deepcopy(request.get("queryParams") or []),
+                "body_type": {"url_encoded": 1, "json": 2, "xml": 3}.get(request.get("bodyType"), 1),
+                "url_encoded_value": deepcopy(request.get("urlEncodedValue") or []),
+                "json_value": request.get("jsonValue"),
+                "xml_value": request.get("xmlValue"),
+                "result_type": {"json": 1, "xml": 2, "text": 3}.get(request.get("resultType"), 1),
+                "auto_trigger": request.get("autoTrigger"),
+                "custom_button_text_enabled": request.get("customButtonTextEnabled"),
+                "custom_button_text": request.get("customButtonText"),
+                "being_insert_value_directly": request.get("insertValueDirectly"),
+                "being_hide_on_form": request.get("hideOnForm"),
+            }
+        ),
+        "outputs": [
+            _without_none({"alias": item.get("alias"), "path": item.get("path"), "alias_id": _positive_int(item.get("aliasId")), "target_field": _snake_selector(item.get("targetField"))})
+            for item in value.get("outputs") or []
+            if isinstance(item, dict)
+        ],
+    }
+
+
+def _snake_code_block(value: JSONObject) -> JSONObject:
+    return _without_none(
+        {
+            "inputs": [
+                _without_none({"field": _snake_selector(item.get("field")), "var": item.get("var")})
+                for item in value.get("inputs") or []
+                if isinstance(item, dict)
+            ],
+            "code": value.get("code"),
+            "auto_trigger": value.get("autoTrigger"),
+            "custom_button_text_enabled": value.get("customButtonTextEnabled"),
+            "custom_button_text": value.get("customButtonText"),
+            "being_hide_on_form": value.get("hideOnForm"),
+            "outputs": [
+                _without_none({"alias": item.get("alias"), "path": item.get("path"), "alias_id": _positive_int(item.get("aliasId")), "target_field": _snake_selector(item.get("targetField"))})
+                for item in value.get("outputs") or []
+                if isinstance(item, dict)
+            ],
+        }
+    )
+
+
+def _backend_question_candidates(form: JSONObject) -> list[JSONObject]:
+    result = []
+    for item in form.get("baseQues") or []:
+        if isinstance(item, dict):
+            result.append(item)
+    for row in form.get("formQues") or []:
+        for item in row if isinstance(row, list) else []:
+            if not isinstance(item, dict):
+                continue
+            if _positive_int(item.get("queType")) == 24:
+                for inner in item.get("innerQuestions") or []:
+                    result.extend(nested for nested in inner if isinstance(inner, list) and isinstance(nested, dict))
+            else:
+                result.append(item)
+    return result
+
+
+def _canonical_backend_field_type(field: JSONObject) -> str:
+    internal_type = str(field.get("_app_form_type") or "")
+    if internal_type:
+        return internal_type
+    que_type = _positive_int(field.get("queType"))
+    if que_type == 4:
+        return "datetime" if field.get("dateType") not in {None, 0} else "date"
+    if que_type == 8:
+        return "amount" if field.get("canDecimal") is True else "number"
+    return QUE_TYPE_TO_CANONICAL.get(que_type or -1, "")
+
+
+def _resolve_backend_selector(selector: JSONObject, candidates: list[JSONObject], location: str) -> JSONObject:
+    que_id = _positive_int(selector.get("queId"))
+    name = str(selector.get("name") or "")
+    matches = [
+        item
+        for item in candidates
+        if (que_id is None or _positive_int(item.get("queId")) == que_id)
+        and (not name or str(item.get("queTitle") or "") == name)
+    ]
+    if len(matches) != 1:
+        raise AppFormFailure("INVALID_FIELD_SELECTOR", f"{location} must resolve to exactly one field", "CONTRACT_PRECHECK", details={"selector": selector, "matches": len(matches)})
+    return matches[0]
+
+
+def _resolve_internal_selector(selector: JSONObject, fields: list[JSONObject], location: str) -> JSONObject:
+    que_id = _positive_int(selector.get("queId") or selector.get("que_id"))
+    name = str(selector.get("name") or "")
+    matches = [
+        item
+        for item in fields
+        if (que_id is None or _positive_int(item.get("que_id")) == que_id)
+        and (not name or str(item.get("name") or "") == name)
+    ]
+    if len(matches) != 1:
+        raise AppFormFailure("INVALID_FIELD_SELECTOR", f"{location} must resolve to exactly one field", "COMPILE", details={"selector": selector, "matches": len(matches)})
+    return matches[0]