@qingflow-tech/qingflow-cli 1.1.43 → 1.1.44

package/src/qingflow_mcp/builder_facade/app_form.py

@@ -0,0 +1,3992 @@
+from __future__ import annotations
+
+import base64
+from copy import deepcopy
+from dataclasses import dataclass
+import json
+import re
+from typing import Any, Iterable
+from urllib.parse import unquote_plus
+
+from ..app_form_compat import normalize_app_form_declaration
+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_with_defaults
+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 (
+    _coerce_any_int,
+    _compile_code_block_binding_fields,
+    _compile_q_linker_binding_fields,
+    _encrypt_question_id,
+    _field_to_question,
+    _looks_like_backend_encoded_formula,
+    _normalize_formula_defaults_for_save,
+    _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 _decode_formula_default(value: Any) -> Any:
+    if not isinstance(value, str) or not _looks_like_backend_encoded_formula(value):
+        return value
+    encoded = value[16:-16]
+    try:
+        decoded = base64.b64decode(encoded, validate=True).decode("utf-8")
+        return unquote_plus(decoded)
+    except Exception:
+        return value
+
+
+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 _canonical_unlimited(value: Any) -> Any:
+    """Expose the backend -1 sentinel as the declarative null/omitted form."""
+    return None if value == -1 else value
+
+
+def _backend_unlimited(value: Any) -> Any:
+    """Translate an explicit declarative null back to the backend -1 sentinel."""
+    return -1 if value is None else value
+
+
+def _scope_items(scope: Any, key: str) -> list[JSONObject]:
+    value = scope.get(key) if isinstance(scope, dict) else None
+    return [item for item in value if isinstance(item, dict)] if isinstance(value, list) else []
+
+
+def _backend_member_scope(scope: Any) -> JSONObject | None:
+    """Translate the public member/depart scope to AuthMembersIncludeExternalBean JSON."""
+    if not isinstance(scope, dict):
+        return None
+    result: JSONObject = {
+        "member": [{"uid": item.get("uid"), "nickName": item.get("nickName")} for item in _scope_items(scope, "members")],
+        "depart": [{"deptId": item.get("deptId"), "deptName": item.get("deptName")} for item in _scope_items(scope, "departments")],
+        "role": [{"roleId": item.get("roleId"), "roleName": item.get("roleName")} for item in _scope_items(scope, "roles")],
+        "dynamic": deepcopy(_scope_items(scope, "dynamic")),
+        "externalMemberList": deepcopy(_scope_items(scope, "externalMembers")),
+        "externalDepartList": deepcopy(_scope_items(scope, "externalDepartments")),
+    }
+    if "includeSubDeparts" in scope:
+        result["includeSubDeparts"] = bool(scope.get("includeSubDeparts"))
+    return result
+
+
+def _canonical_member_scope(scope: Any, scope_type: Any, *, department: bool = False) -> JSONObject:
+    normalized_type = _positive_int(scope_type) or 1
+    if normalized_type == 1:
+        return {"mode": "all"}
+    raw = scope if isinstance(scope, dict) else {}
+    result: JSONObject = {
+        "mode": "custom" if normalized_type == 2 else "relation",
+        "includeSubDeparts": bool(raw.get("includeSubDeparts")),
+    }
+    if department:
+        result["departments"] = [
+            _without_none({"deptId": _positive_int(item.get("deptId") or item.get("id")), "deptName": item.get("deptName") or item.get("name")})
+            for item in _scope_items(raw, "depart")
+            if _positive_int(item.get("deptId") or item.get("id")) is not None
+        ]
+    else:
+        result["members"] = [
+            _without_none({"uid": _positive_int(item.get("uid")), "nickName": item.get("nickName")})
+            for item in _scope_items(raw, "member")
+            if _positive_int(item.get("uid")) is not None
+        ]
+        result["departments"] = [
+            _without_none({"deptId": _positive_int(item.get("deptId")), "deptName": item.get("deptName")})
+            for item in _scope_items(raw, "depart")
+            if _positive_int(item.get("deptId")) is not None
+        ]
+        result["roles"] = [
+            _without_none({"roleId": _positive_int(item.get("roleId")), "roleName": item.get("roleName")})
+            for item in _scope_items(raw, "role")
+            if _positive_int(item.get("roleId")) is not None
+        ]
+        result["dynamic"] = [
+            _without_none({
+                "type": _positive_int(item.get("type")),
+                "queId": item.get("queId"),
+                "queTitle": item.get("queTitle"),
+            })
+            for item in _scope_items(raw, "dynamic")
+            if _positive_int(item.get("type")) is not None
+        ]
+        result["externalMembers"] = [
+            _without_none({
+                "uid": _positive_int(item.get("uid")),
+                "nickName": item.get("nickName"),
+                "email": item.get("email"),
+            })
+            for item in _scope_items(raw, "externalMemberList")
+            if _positive_int(item.get("uid")) is not None
+        ]
+        result["externalDepartments"] = [
+            _without_none({
+                "deptId": _positive_int(item.get("deptId")),
+                "deptName": item.get("deptName"),
+            })
+            for item in _scope_items(raw, "externalDepartList")
+            if _positive_int(item.get("deptId")) is not None
+        ]
+    return _without_none(result)
+
+
+def _canonical_scope_relation(relation: Any) -> JSONObject | None:
+    if not isinstance(relation, dict):
+        return None
+    displayed = relation.get("displayedQueInfo") if isinstance(relation.get("displayedQueInfo"), dict) else {}
+    displayed_id = _positive_int(relation.get("displayedQueId") or displayed.get("queId"))
+    if displayed_id is None or not displayed.get("appKey"):
+        return None
+    result: JSONObject = {
+        "displayedField": _selector(displayed_id, displayed.get("queTitle")),
+        "targetAppKey": displayed.get("appKey"),
+        "targetAppTitle": displayed.get("appTitle"),
+        "displayedFieldType": displayed.get("queType"),
+        "matchRuleType": relation.get("matchRuleType"),
+        "matchRules": relation.get("matchRules"),
+    }
+    formula = str(relation.get("matchRuleFormula") or "").strip()
+    if formula:
+        result["matchRuleFormula"] = formula
+    return _without_none(result)
+
+
+def _canonical_attachment_default_values(value: Any) -> JSONObject | None:
+    if not isinstance(value, dict):
+        return None
+    values = []
+    for item in value.get("values") or []:
+        if not isinstance(item, dict):
+            continue
+        url = str(item.get("value") or "").strip()
+        if not url:
+            data_value = str(item.get("dataValue") or "").strip()
+            url = data_value if "://" in data_value else ""
+        if not url:
+            continue
+        file_name = str(item.get("otherInfo") or item.get("valueStr") or "").strip()
+        values.append(
+            _without_none(
+                {
+                    "value": url,
+                    "otherInfo": file_name or None,
+                    "pluginValue": item.get("pluginValue"),
+                }
+            )
+        )
+    return {"values": values} if values else None
+
+
+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.startswith("_")
+            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 _iter_backend_questions(value: Any) -> Iterable[JSONObject]:
+    if isinstance(value, list):
+        for item in value:
+            yield from _iter_backend_questions(item)
+    elif isinstance(value, dict):
+        if "queType" in value:
+            yield value
+        yield from _iter_backend_questions(value.get("innerQuestions"))
+        yield from _iter_backend_questions(value.get("subQuestions"))
+
+
+def _normalize_published_scope_omissions(form: JSONObject) -> JSONObject:
+    """Allow published GET responses that omit custom member/department scopes."""
+    result = deepcopy(form)
+    for question in _iter_backend_questions(result.get("formQues")):
+        if (
+            _positive_int(question.get("memberSelectScopeType")) == 2
+            and not isinstance(question.get("memberSelectScope"), dict)
+        ):
+            question["memberSelectScopeType"] = 1
+            question["memberSelectScope"] = {}
+        if (
+            _positive_int(question.get("deptSelectScopeType")) == 2
+            and not isinstance(question.get("deptSelectScope"), dict)
+        ):
+            question["deptSelectScopeType"] = 1
+            question["deptSelectScope"] = {}
+    return result
+
+
+def _without_selectable_scopes(resource: JSONObject) -> JSONObject:
+    """Remove only selectable scope values from a published-state comparison."""
+    result = deepcopy(resource)
+    fields = _iter_fields(result.get("spec", {}).get("body") or [])
+    for field in _iter_field_tree(fields):
+        config = field.get("config") if isinstance(field.get("config"), dict) else None
+        if config is None:
+            continue
+        config.pop("memberScope", None)
+        config.pop("departmentScope", None)
+    return result
+
+
+def _published_field_map(resource: JSONObject) -> dict[tuple[str, Any], JSONObject]:
+    fields = _iter_field_tree(_iter_fields(resource.get("spec", {}).get("body") or []))
+    result: dict[tuple[str, Any], JSONObject] = {}
+    for field in fields:
+        que_id = _positive_int(field.get("queId"))
+        key = ("id", que_id) if que_id is not None else ("name", (_field_type(field), field.get("name")))
+        result[key] = field
+    return result
+
+
+def _matching_published_field(field: JSONObject, published_fields: dict[tuple[str, Any], JSONObject]) -> JSONObject | None:
+    que_id = _positive_int(field.get("queId"))
+    if que_id is not None and ("id", que_id) in published_fields:
+        return published_fields[("id", que_id)]
+    return published_fields.get(("name", (_field_type(field), field.get("name"))))
+
+
+def _normalize_published_get_equivalents(draft: JSONObject, published: JSONObject) -> tuple[JSONObject, JSONObject]:
+    """Normalize values that the published GET endpoint omits or materializes."""
+    draft_result = _without_selectable_scopes(draft)
+    published_result = _without_selectable_scopes(published)
+    published_fields = _published_field_map(published_result)
+    for draft_field in _published_field_map(draft_result).values():
+        published_field = _matching_published_field(draft_field, published_fields)
+        if published_field is None:
+            continue
+        field_type = _field_type(draft_field)
+        draft_config = draft_field.get("config") if isinstance(draft_field.get("config"), dict) else {}
+        published_config = published_field.get("config") if isinstance(published_field.get("config"), dict) else {}
+
+        if field_type == "member":
+            draft_default = draft_config.get("defaultMembers")
+            published_default = published_config.get("defaultMembers")
+            if isinstance(draft_default, dict) and isinstance(published_default, dict):
+                # Published GET resolves department defaults into runtime members.
+                for key in ("departments", "includeSubDeparts"):
+                    if key in draft_default:
+                        published_default[key] = deepcopy(draft_default[key])
+
+        if field_type == "data_relation":
+            draft_filters = draft_config.get("filters") if isinstance(draft_config.get("filters"), dict) else {}
+            published_filters = published_config.get("filters") if isinstance(published_config.get("filters"), dict) else {}
+            draft_groups = draft_filters.get("groups") if isinstance(draft_filters.get("groups"), list) else []
+            published_groups = published_filters.get("groups") if isinstance(published_filters.get("groups"), list) else []
+            for draft_group, published_group in zip(draft_groups, published_groups):
+                if not isinstance(draft_group, list) or not isinstance(published_group, list):
+                    continue
+                for draft_rule, published_rule in zip(draft_group, published_group):
+                    if not isinstance(draft_rule, dict) or not isinstance(published_rule, dict):
+                        continue
+                    draft_source = draft_rule.get("sourceField") if isinstance(draft_rule.get("sourceField"), dict) else {}
+                    published_source = published_rule.get("sourceField") if isinstance(published_rule.get("sourceField"), dict) else {}
+                    same_source = _positive_int(draft_source.get("queId")) == _positive_int(published_source.get("queId"))
+                    if same_source and draft_source.get("name") and not published_source.get("name"):
+                        published_source["name"] = draft_source["name"]
+                    draft_operand = draft_rule.get("operand") if isinstance(draft_rule.get("operand"), dict) else {}
+                    published_operand = published_rule.get("operand") if isinstance(published_rule.get("operand"), dict) else {}
+                    if (
+                        same_source
+                        and draft_rule.get("operator") == published_rule.get("operator")
+                        and draft_operand.get("kind") == published_operand.get("kind") == "literal"
+                        and draft_operand.get("values")
+                        and published_operand.get("values") == []
+                    ):
+                        published_operand["values"] = deepcopy(draft_operand["values"])
+            # The backend intentionally emits sortConfig only for beingDraft=true.
+            if "sort" in draft_config and "sort" not in published_config:
+                published_config["sort"] = deepcopy(draft_config["sort"])
+
+        if field_type == "subtable":
+            if draft_config.get("tableRowsLimit") in {None, 200} and published_config.get("tableRowsLimit") in {None, 200}:
+                draft_config.pop("tableRowsLimit", None)
+                published_config.pop("tableRowsLimit", None)
+
+        if field_type in {"number", "amount"}:
+            if draft_config.get("currencyStatus") in {None, False} and published_config.get("currencyStatus") in {None, False}:
+                draft_config.pop("currencyStatus", None)
+                published_config.pop("currencyStatus", None)
+    return draft_result, published_result
+
+
+def _published_equal(draft: JSONObject, published: JSONObject) -> bool:
+    comparable_draft, comparable_published = _normalize_published_get_equivalents(draft, published)
+    return _canonical_equal(comparable_draft, comparable_published)
+
+
+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"),
+                    "questionType": _field_type(field),
+                    "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 _field_type(field: JSONObject) -> str:
+    """Read the AppForm field type while accepting pre-rename declarations."""
+    return str(field.get("questionType") or field.get("type") or "")
+
+
+def _field_required(field: JSONObject) -> bool:
+    """Read the AppForm required flag while accepting pre-rename declarations."""
+    return bool(field.get("beingRequired") if "beingRequired" in field else field.get("required"))
+
+
+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)]
+        select_scope_relations = [item for item in form.get("selectScopeRelations") or [] if isinstance(item, dict)]
+        field_names = self._field_index(form)
+        definitions = context.complete_schema.get("$defs") if isinstance(context.complete_schema.get("$defs"), dict) else {}
+        relation_properties = definitions.get("RelationConfig", {}).get("properties", {}) if isinstance(definitions.get("RelationConfig"), dict) else {}
+        supports_reference_default_formula = "defaultValueFormula" in relation_properties
+        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, select_scope_relations, field_names, supports_reference_default_formula) 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, select_scope_relations, field_names, supports_reference_default_formula) for question in row if isinstance(question, dict)]})
+        resource = {
+            "apiVersion": context.api_version,
+            "appKey": app_key,
+            "spec": {
+                "appName": str(form.get("formTitle") or ""),
+                "appDescription": form.get("formDesc") or None,
+                "dataTitleField": _selector(title_id, field_names.get(title_id or 0)) if title_id is not None else None,
+                "dataCoverField": _selector(cover_id, field_names.get(cover_id or 0)) if cover_id is not None else None,
+                "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],
+        select_scope_relations: list[JSONObject],
+        field_names: dict[int, str],
+        supports_reference_default_formula: bool,
+    ) -> 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 ""),
+            "questionType": field_type,
+            "beingRequired": bool(question.get("required")),
+            "questionDescription": question.get("queHint") or None,
+        }
+        default_type = _positive_int(question.get("queDefaultType"))
+        if default_type is not None and (
+            question.get("queDefaultValue") is not None
+            or (default_type != 1 and field_type != "relation")
+        ):
+            field["defaultType"] = default_type
+        raw_default_value = question.get("queDefaultValue")
+        if isinstance(raw_default_value, (dict, list)) and field_type not in {"address", "attachment", "relation", "subtable"}:
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_CONFIG",
+                "structured default value must be declared through the field-specific config",
+                "NORMALIZE",
+                details={"queId": que_id, "type": field_type},
+            )
+        if "queDefaultValue" in question and raw_default_value is not None and not isinstance(raw_default_value, (dict, list)):
+            default_value = question.get("queDefaultValue")
+            field["defaultValue"] = _decode_formula_default(default_value)
+        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 field_type in {"text", "long_text", "link", "phone", "email"}:
+            config = _without_none({
+                "minWordCount": _canonical_unlimited(question.get("minWordCount")),
+                "maxWordCount": _canonical_unlimited(question.get("maxWordCount")),
+                "noRepeat": question.get("noRepeat"),
+                "canScan": question.get("canScan"),
+                "scanType": question.get("scanType"),
+            })
+            if field_type == "phone":
+                config.update(_without_none({
+                    "msgValidateStatus": question.get("msgValidateStatus"),
+                    "fixedPhone": question.get("fixedPhone"),
+                }))
+            if config:
+                field["config"] = config
+        elif field_type in {"number", "amount"}:
+            config = _without_none({
+                "numberLimitStatus": question.get("numberLimitStatus"),
+                "minValue": question.get("minValue"),
+                "maxValue": question.get("maxValue"),
+                "decimalDigit": question.get("decimalDigit"),
+                "numberFormat": question.get("numberFormat"),
+                "currencyStatus": question.get("currencyStatus"),
+                "currencyType": question.get("currencyType"),
+                "canDecimal": question.get("canDecimal"),
+                "noRepeat": question.get("noRepeat"),
+                "canScan": question.get("canScan"),
+                "scanType": question.get("scanType"),
+            })
+            if config:
+                field["config"] = config
+        elif 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"] = _without_none({
+                "options": options,
+                "minOpts": _canonical_unlimited(question.get("minOpts")),
+                "maxOpts": _canonical_unlimited(question.get("maxOpts")),
+                "optDirection": question.get("optDirection") if question.get("optDirection") not in {None, 0} else None,
+                "optSelectMode": question.get("optSelectMode"),
+                "beingShowColor": question.get("beingShowColor"),
+                "defaultOptions": [str(item.get("optValue")) for item in question.get("options") or [] if isinstance(item, dict) and item.get("beingDefault") is True],
+            })
+            if not field["config"].get("defaultOptions"):
+                field["config"].pop("defaultOptions", None)
+        elif field_type == "member":
+            field["config"] = {
+                "memberScope": _canonical_member_scope(question.get("memberSelectScope"), question.get("memberSelectScopeType")),
+            }
+            if question.get("memberDftValue") is not None:
+                field["config"]["defaultMembers"] = _canonical_member_scope(question.get("memberDftValue"), 2)
+            relation = next((item for item in select_scope_relations if _positive_int(item.get("queId")) == que_id), None)
+            scope_relation = _canonical_scope_relation(relation)
+            if scope_relation is not None:
+                field["config"]["memberScopeRelation"] = scope_relation
+            for key in ("noRepeat", "canScan", "scanType"):
+                if question.get(key) is not None:
+                    field["config"][key] = question[key]
+        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 []
+            canonical_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
+            ]
+            scope_type = _positive_int(question.get("deptSelectScopeType")) or 1
+            if scope_type == 3:
+                field["config"] = {"departmentScope": {"mode": "relation", "includeSubDeparts": bool(scope.get("includeSubDeparts"))}}
+            elif scope_type == 2 or (question.get("deptSelectScopeType") is None and canonical_departments):
+                if not canonical_departments:
+                    raise AppFormFailure(
+                        "UNSUPPORTED_FIELD_CONFIG",
+                        "department custom scope has no departments",
+                        "NORMALIZE",
+                        details={"queId": que_id},
+                    )
+                field["config"] = {
+                    "departmentScope": {
+                        "mode": "custom",
+                        "departments": canonical_departments,
+                        "includeSubDeparts": bool(scope.get("includeSubDeparts")),
+                    }
+                }
+            else:
+                field["config"] = {"departmentScope": {"mode": "all", "includeSubDeparts": bool(scope.get("includeSubDeparts"))}}
+            if question.get("deptDftValue") is not None:
+                field["config"]["defaultDepartments"] = _canonical_member_scope(question.get("deptDftValue"), 2, department=True)
+            relation = next((item for item in select_scope_relations if _positive_int(item.get("queId")) == que_id), None)
+            scope_relation = _canonical_scope_relation(relation)
+            if scope_relation is not None:
+                field["config"]["departmentScopeRelation"] = scope_relation
+            for key in ("noRepeat", "canScan", "scanType", "beingShowParentPath"):
+                if question.get(key) is not None:
+                    field["config"][key] = question[key]
+        elif field_type == "attachment":
+            field["config"] = _without_none({
+                "fileSize": question.get("fileSize"),
+                "fileType": question.get("fileType"),
+                "fileBeingCaptureOnly": question.get("fileBeingCaptureOnly"),
+                "imageCompress": question.get("imageCompress"),
+                "pluginStatus": question.get("pluginStatus"),
+                "maxFileLimitStatus": question.get("maxFileLimitStatus"),
+                "maxFileLimit": question.get("maxFileLimit"),
+                "canScan": question.get("canScan"),
+                "scanType": question.get("scanType"),
+                "defaultValues": _canonical_attachment_default_values(question.get("queDefaultValues")),
+            })
+        elif field_type == "address":
+            field["config"] = _without_none({
+                "addressPrecision": question.get("addressPrecision"),
+                "pickPosition": question.get("pickPosition"),
+                "canScan": question.get("canScan"),
+                "scanType": question.get("scanType"),
+                "defaultValues": question.get("queDefaultValues") if isinstance(question.get("queDefaultValues"), dict) and (question.get("queDefaultValues", {}).get("values") or question.get("queDefaultValues", {}).get("tableValues")) else None,
+            })
+        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]
+            relation_config: JSONObject = {
+                "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
+                ],
+                "beingDefaultFormulaAutoFillEnabled": reference.get("beingDefaultFormulaAutoFillEnabled"),
+                "defaultValueMatchRules": reference.get("defaultValueMatchRules"),
+                "defaultValues": question.get("queDefaultValues") if isinstance(question.get("queDefaultValues"), dict) else None,
+            }
+            if supports_reference_default_formula:
+                relation_config["defaultValueFormula"] = reference.get("defaultValueFormula")
+            field["config"] = _without_none(relation_config)
+        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, select_scope_relations, field_names, supports_reference_default_formula)
+                for item in question.get("subQuestions") or []
+                if isinstance(item, dict)
+            ]
+            for subfield in field["subfields"]:
+                subfield.pop("width", None)
+            field["config"] = _without_none({
+                "tableRowsLimit": question.get("tableRowsLimit"),
+                "tableNoRepeatStatus": question.get("tableNoRepeatStatus"),
+                "tableNoRepeatQuestion": [_selector(item, field_names.get(_positive_int(item))) for item in question.get("tableNoRepeatQuestion") or [] if _positive_int(item) is not None],
+                "tableRowHeight": question.get("tableRowHeight"),
+                "defaultValues": question.get("queDefaultValues") if isinstance(question.get("queDefaultValues"), dict) and (question.get("queDefaultValues", {}).get("values") or question.get("queDefaultValues", {}).get("tableValues")) else None,
+            })
+        return field
+
+    @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:
+                    input_que_id = _positive_int(item.get("value"))
+                    inputs.append(
+                        {
+                            "field": _selector(input_que_id, field_names.get(input_que_id or -1)),
+                            "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:
+                    token = match.group("token").strip()
+                    matching_ids = [
+                        que_id
+                        for que_id, field_name in field_names.items()
+                        if field_name == name and _encrypt_question_id(que_id) == token
+                    ]
+                    json_path_inputs.setdefault(
+                        name,
+                        {
+                            "field": _selector(matching_ids[0] if len(matching_ids) == 1 else None, 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"), None)}, "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 and bool(button.get("status")):
+            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 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": True, "buttonId": button_id}
+        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:
+            details = value.get("judgeValueDetails")
+            if isinstance(details, list):
+                literal_values = [
+                    str(item.get("value") if item.get("value") is not None else item.get("id"))
+                    for item in details
+                    if isinstance(item, dict) and (item.get("value") is not None or item.get("id") is not None)
+                ]
+            else:
+                literal_values = deepcopy(value.get("judgeValues") or [])
+            condition["operand"] = {"kind": "literal", "values": literal_values}
+        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
+            field_type = _field_type(field)
+            alias_binding = {
+                "code_block": ("codeBlockBinding", "codeBlockConfig", "resultAliasPath"),
+                "q_linker": ("qLinkerBinding", "remoteLookupConfig", "resultFormatPath"),
+            }.get(field_type)
+            if alias_binding is not None:
+                binding_key, backend_config_key, backend_aliases_key = alias_binding
+                config = field.get("config") if isinstance(field.get("config"), dict) else {}
+                binding = config.get(binding_key) if isinstance(config.get(binding_key), dict) else {}
+                outputs = binding.get("outputs") if isinstance(binding.get("outputs"), list) else []
+                backend_config = question.get(backend_config_key) if isinstance(question.get(backend_config_key), dict) else {}
+                backend_aliases = [
+                    item
+                    for item in backend_config.get(backend_aliases_key) or []
+                    if isinstance(item, dict)
+                ]
+                for output_index, output in enumerate(outputs):
+                    if not isinstance(output, dict):
+                        continue
+                    alias_name = str(output.get("alias") or "").strip()
+                    alias_path = str(output.get("path") or "").strip()
+                    matches = [
+                        item
+                        for item in backend_aliases
+                        if str(item.get("aliasName") or "").strip() == alias_name
+                        and str(item.get("aliasPath") or "").strip() == alias_path
+                    ]
+                    if len(matches) != 1:
+                        raise AppFormFailure(
+                            "RELATION_REBIND_FAILED",
+                            "identity write did not return a unique output alias identity",
+                            "IDENTITY_REBOUND",
+                            details={
+                                "field": name,
+                                "fieldType": field_type,
+                                "outputIndex": output_index,
+                                "alias": alias_name,
+                                "path": alias_path,
+                                "matches": len(matches),
+                            },
+                        )
+                    alias_id = _positive_int(matches[0].get("aliasId"))
+                    if alias_id is None:
+                        raise AppFormFailure(
+                            "RELATION_REBIND_FAILED",
+                            "identity write returned an output alias without aliasId",
+                            "IDENTITY_REBOUND",
+                            details={
+                                "field": name,
+                                "fieldType": field_type,
+                                "outputIndex": output_index,
+                                "alias": alias_name,
+                                "path": alias_path,
+                            },
+                        )
+                    output["aliasId"] = alias_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"]
+        field_names = AppFormNormalizer._field_index(form)
+        title_id = _positive_int(form.get("dataTitleQueId"))
+        cover_id = _positive_int(form.get("dataCoverQueId"))
+        spec.setdefault("appName", str(form.get("formTitle") or ""))
+        spec.setdefault("appDescription", form.get("formDesc") or None)
+        spec.setdefault("dataTitleField", _selector(title_id, field_names.get(title_id or 0)) if title_id is not None else None)
+        spec.setdefault("dataCoverField", _selector(cover_id, field_names.get(cover_id or 0)) if cover_id is not None else None)
+        spec.setdefault("attachments", AppFormNormalizer._attachments(form.get("formAttach")))
+        spec.setdefault(
+            "serialNumber",
+            AppFormNormalizer._serial_number(form.get("serialNumType"), form.get("serialNumConfig")),
+        )
+        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", "appDescription", "dataTitleField", "dataCoverField", "attachments", "serialNumber"):
+            if key in declared_spec:
+                target_spec[key] = deepcopy(declared_spec[key])
+        target_spec["body"] = self._target_body(current_spec.get("body") or [], declared_spec.get("body") or [])
+        target_fields = list(_iter_fields(target_spec["body"]))
+        for key in ("dataTitleField", "dataCoverField"):
+            if key in declared_spec or not isinstance(target_spec.get(key), dict):
+                continue
+            selector_id = _positive_int(target_spec[key].get("queId"))
+            selected = [field for field in target_fields if selector_id is not None and _positive_int(field.get("queId")) == selector_id]
+            if len(selected) == 1:
+                target_spec[key] = _selector(selected[0].get("queId"), selected[0].get("name"))
+        data_title, data_cover = self._validate_target(target_spec)
+        target_spec["dataTitleField"] = _selector(data_title.get("queId"), data_title.get("name")) if data_title is not None else None
+        target_spec["dataCoverField"] = _selector(data_cover.get("queId"), data_cover.get("name")) if data_cover is not None else None
+        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:
+        declaration = self._resolve_declared_field_names(declaration, current_form)
+        spec = declaration.get("spec", {})
+        body = spec.get("body") or []
+        self._validate_target(spec, allow_missing_data_title=current_form is not None)
+        fields = list(_iter_fields(body))
+        templates = self._question_templates(current_form or {})
+        internal_fields = [self._internal_field(field, templates=templates) for field in fields]
+        self._assign_layout_temp_ids(body, internal_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 or {})
+            relation_context = deepcopy(current_form or {})
+            relation_context["questionRelations"] = relations
+            internal_fields, relations = _compile_q_linker_binding_fields(fields=internal_fields, current_schema=relation_context)
+            self._validate_unique_relation_targets(relations, internal_fields)
+        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_type(field) == "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_type(field) == "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_type(field) == "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)
+
+    @staticmethod
+    def _resolve_declared_field_names(
+        declaration: JSONObject,
+        current_form: JSONObject | None,
+    ) -> JSONObject:
+        """Fill names for ID-only updates before compilation consumes field names."""
+        result = deepcopy(declaration)
+        current_names = AppFormNormalizer._field_index(current_form or {})
+
+        def visit(field: Any, path: str) -> None:
+            if not isinstance(field, dict):
+                return
+            if not str(field.get("name") or "").strip():
+                que_id = _positive_int(field.get("queId"))
+                name = current_names.get(que_id or 0)
+                if name:
+                    field["name"] = name
+                else:
+                    raise AppFormFailure(
+                        "INVALID_SPEC",
+                        "field name is required unless queId identifies an existing field",
+                        "CONTRACT_PRECHECK",
+                        details={"path": path, "queId": field.get("queId")},
+                    )
+            for index, child in enumerate(field.get("subfields") or []):
+                visit(child, f"{path}/subfields/{index}")
+
+        spec = result.get("spec") if isinstance(result.get("spec"), dict) else {}
+        body = spec.get("body") or []
+        for block_index, block in enumerate(body):
+            if not isinstance(block, dict):
+                continue
+            rows = [block] if block.get("kind") == "row" else block.get("rows") or []
+            for row_index, row in enumerate(rows):
+                if not isinstance(row, dict):
+                    continue
+                for field_index, field in enumerate(row.get("fields") or []):
+                    visit(field, f"/spec/body/{block_index}/rows/{row_index}/fields/{field_index}")
+        return result
+
+    @staticmethod
+    def _assign_layout_temp_ids(body: list[Any], internal_fields: list[JSONObject]) -> None:
+        """Assign one temporary-ID sequence to fields and new section wrappers."""
+        temp_id = -10000
+        internal_index = 0
+
+        def assign_field(field: Any) -> None:
+            nonlocal temp_id, internal_index
+            if not isinstance(field, dict):
+                return
+            if internal_index >= len(internal_fields):
+                raise AppFormFailure(
+                    "INVALID_SPEC",
+                    "form layout and internal field list are inconsistent",
+                    "COMPILE",
+                )
+            internal = internal_fields[internal_index]
+            internal_index += 1
+            if _positive_int(field.get("queId")) is None:
+                internal["que_temp_id"] = temp_id
+            temp_id -= 100
+
+        for block in body:
+            if not isinstance(block, dict):
+                continue
+            if block.get("kind") == "row":
+                for field in block.get("fields") or []:
+                    assign_field(field)
+                continue
+            for row in block.get("rows") or []:
+                if not isinstance(row, dict):
+                    continue
+                for field in row.get("fields") or []:
+                    assign_field(field)
+            if _positive_int(block.get("sectionId")) is None:
+                temp_id -= 100
+
+        if internal_index != len(internal_fields):
+            raise AppFormFailure(
+                "INVALID_SPEC",
+                "form layout and internal field list are inconsistent",
+                "COMPILE",
+            )
+
+    @staticmethod
+    def _validate_unique_temp_ids(form_ques: list[list[JSONObject]]) -> None:
+        seen: dict[int, str] = {}
+
+        def visit(question: Any) -> None:
+            if not isinstance(question, dict):
+                return
+            temp_id = question.get("queTempId")
+            if temp_id is not None:
+                try:
+                    normalized = int(temp_id)
+                except (TypeError, ValueError):
+                    normalized = None
+                if normalized is not None:
+                    title = str(question.get("queTitle") or "")
+                    previous = seen.get(normalized)
+                    if previous is not None:
+                        raise AppFormFailure(
+                            "DUPLICATE_TEMP_ID",
+                            "form payload contains duplicate queTempId",
+                            "COMPILE",
+                            details={"queTempId": normalized, "questions": [previous, title]},
+                        )
+                    seen[normalized] = title
+            for subquestion in question.get("subQuestions") or []:
+                visit(subquestion)
+            for inner_row in question.get("innerQuestions") or []:
+                for inner_question in inner_row if isinstance(inner_row, list) else []:
+                    visit(inner_question)
+
+        for row in form_ques:
+            for question in row if isinstance(row, list) else []:
+                visit(question)
+
+    @staticmethod
+    def _validate_unique_relation_targets(relations: list[JSONObject], fields: list[JSONObject]) -> None:
+        field_names: dict[int, str] = {}
+        for field in fields:
+            field_ref = _positive_int(field.get("que_id"))
+            if field_ref is None:
+                field_ref = _coerce_any_int(field.get("que_temp_id"))
+            if field_ref is not None:
+                field_names[field_ref] = str(field.get("name") or field_ref)
+        by_target: dict[int, JSONObject] = {}
+        for relation in relations:
+            target_ref = _coerce_any_int(relation.get("queId"))
+            if target_ref is None:
+                continue
+            previous = by_target.get(target_ref)
+            if previous is None:
+                by_target[target_ref] = relation
+                continue
+            target_name = field_names.get(target_ref, str(target_ref))
+            producers = []
+            for item in (previous, relation):
+                alias_config = item.get("aliasConfig") if isinstance(item.get("aliasConfig"), dict) else {}
+                producer = str(alias_config.get("queTitle") or "").strip()
+                producers.append(producer or f"relationType={item.get('relationType')}")
+            raise ValueError(
+                f"field '{target_name}' is targeted by multiple default-value relations "
+                f"({producers[0]}, {producers[1]}); each field can receive output from only one relation"
+            )
+
+    def _target_body(
+        self,
+        current_body: list[Any],
+        declared_body: list[Any],
+        *,
+        subfields: bool = False,
+    ) -> 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("beingRequired", False)
+            target.setdefault("questionDescription", None)
+            if target.get("defaultValue") is not None:
+                target.setdefault("defaultType", 1)
+            if "defaultValue" in declared and declared.get("defaultValue") is None:
+                target.pop("defaultType", None)
+                target.pop("defaultValue", None)
+                target["_clear_default_value"] = True
+            if current is not None:
+                target["queId"] = current.get("queId")
+            else:
+                target.pop("queId", None)
+            if _field_type(target) in CHOICE_TYPES and "config" not in declared and current is None:
+                target["config"] = {"options": ["是", "否"] if _field_type(target) == "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 _field_type(candidate) != _field_type(declared):
+                        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 _field_type(current) != _field_type(declared):
+                raise AppFormFailure("FIELD_TYPE_IMMUTABLE", "field type cannot be changed in place", "CONTRACT_PRECHECK", details={"queId": current.get("queId"), "currentType": _field_type(current), "targetType": _field_type(declared)})
+            if current is not None:
+                claimed_fields.add(id(current))
+            target = merge_field(current, declared)
+            if _field_type(target) == "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 []}],
+                    subfields=True,
+                )[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=subfields) for field in block.get("fields") or []]
+                if not subfields:
+                    self._fill_widths(target_block["fields"])
+            else:
+                target_block["rows"] = []
+                for row in block.get("rows") or []:
+                    fields = [target_field(field, nested=subfields) for field in row.get("fields") or []]
+                    if not subfields:
+                        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 any(_positive_int(field.get("width")) not in {25, 50, 75, 100} for field in fields):
+                raise AppFormFailure("INVALID_ROW_WIDTH", "field widths must be one of 25, 50, 75, or 100", "CONTRACT_PRECHECK")
+            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
+        widths = {
+            1: [100],
+            2: [50, 50],
+            3: [50, 25, 25],
+            4: [25, 25, 25, 25],
+        }[len(fields)]
+        for field, width in zip(fields, widths, strict=True):
+            field["width"] = width
+
+    @staticmethod
+    def _validate_target(
+        spec: JSONObject,
+        *,
+        allow_missing_data_title: bool = False,
+    ) -> tuple[JSONObject | None, JSONObject | None]:
+        body = spec.get("body") or []
+        fields = list(_iter_fields(body))
+        names: set[str] = set()
+        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)
+            if _field_type(field) == "subtable":
+                sub_names: set[str] = set()
+                for subfield in field.get("subfields") or []:
+                    if _field_type(subfield) 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 ""))
+        title_selector = spec.get("dataTitleField")
+        data_title: JSONObject | None = None
+        if fields:
+            if title_selector is None and allow_missing_data_title and "dataTitleField" not in spec:
+                pass
+            elif not isinstance(title_selector, dict):
+                raise AppFormFailure(
+                    "INVALID_DATA_TITLE_FIELD",
+                    "non-empty body requires a dataTitleField selector",
+                    "CONTRACT_PRECHECK",
+                )
+            else:
+                data_title = _resolve_canonical_selector(title_selector, fields, "dataTitleField")
+        elif title_selector is not None:
+            raise AppFormFailure(
+                "INVALID_DATA_TITLE_FIELD",
+                "dataTitleField must be null when body is empty",
+                "CONTRACT_PRECHECK",
+            )
+
+        cover_selector = spec.get("dataCoverField")
+        data_cover: JSONObject | None = None
+        if cover_selector is not None:
+            if not isinstance(cover_selector, dict):
+                raise AppFormFailure("INVALID_DATA_COVER_FIELD", "dataCoverField must be a field selector or null", "CONTRACT_PRECHECK")
+            data_cover = _resolve_canonical_selector(cover_selector, fields, "dataCoverField")
+            if _field_type(data_cover) != "attachment":
+                raise AppFormFailure(
+                    "INVALID_DATA_COVER_FIELD",
+                    "dataCoverField must select a top-level attachment field",
+                    "CONTRACT_PRECHECK",
+                )
+        return data_title, data_cover
+
+    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]
+        self._assign_layout_temp_ids(target["spec"]["body"], internal_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)
+            self._validate_unique_relation_targets(relations, internal_fields)
+        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
+        ]
+        payload["selectScopeRelations"] = [
+            self._select_scope_relation(profile, field, internal)
+            for field, internal in _iter_field_pairs(target_fields, internal_fields)
+            if isinstance(field.get("config"), dict)
+            and (field.get("config", {}).get("memberScopeRelation") or field.get("config", {}).get("departmentScopeRelation"))
+        ]
+        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
+        self._validate_unique_temp_ids(rows)
+        data_title = _resolve_canonical_selector(target["spec"]["dataTitleField"], target_fields, "dataTitleField") if target_fields else None
+        data_cover_selector = target["spec"].get("dataCoverField")
+        data_cover = _resolve_canonical_selector(data_cover_selector, target_fields, "dataCoverField") if isinstance(data_cover_selector, dict) else 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)
+        _normalize_formula_defaults_for_save(payload.get("formQues"))
+        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_type(field) in {"q_linker", "data_relation"}
+                or _field_type(field) == "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_type(field) == "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_type(field) in {"q_linker", "data_relation"}
+                or _field_type(field) == "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_type(field) == "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 = _field_type(field)
+        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": _field_required(field),
+            "description": field.get("questionDescription"),
+            "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,
+        }
+        if "defaultValues" in config:
+            result["default_values"] = deepcopy(config.get("defaultValues"))
+        if "defaultType" in field:
+            result["default_type"] = _positive_int(field.get("defaultType")) or 1
+        if "defaultValue" in field:
+            result["default_value"] = deepcopy(field.get("defaultValue"))
+        if field.get("_clear_default_value") is True:
+            result["default_type"] = 1
+            result["default_value"] = None
+        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")),
+            }
+            default_departments = config.get("defaultDepartments")
+            if isinstance(default_departments, dict):
+                result["department_default_scope"] = {
+                    "departments": [
+                        {"dept_id": item.get("deptId"), "dept_name": item.get("deptName")}
+                        for item in default_departments.get("departments") or []
+                        if isinstance(item, dict)
+                    ],
+                    "include_sub_departs": bool(default_departments.get("includeSubDeparts")),
+                }
+        elif canonical_type == "member":
+            result["member_scope"] = deepcopy(config.get("memberScope"))
+            result["member_default_scope"] = deepcopy(config.get("defaultMembers"))
+        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 []],
+                    "reference_default_formula_auto_fill": config.get("beingDefaultFormulaAutoFillEnabled"),
+                    "reference_default_value_match_rules": deepcopy(config.get("defaultValueMatchRules")),
+                    "_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 = _field_type(field)
+        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": _field_required(field), "description": field.get("questionDescription"), "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": _field_required(field),
+                "queHint": field.get("questionDescription") or "",
+            }
+        )
+        config = field.get("config") if isinstance(field.get("config"), dict) else {}
+        if field_type in {"text", "long_text", "link", "phone", "email"}:
+            for key in ("minWordCount", "maxWordCount", "noRepeat", "canScan", "scanType"):
+                if key in config:
+                    question[key] = _backend_unlimited(config[key]) if key in {"minWordCount", "maxWordCount"} else config[key]
+            if field_type == "phone":
+                for key in ("msgValidateStatus", "fixedPhone"):
+                    if key in config:
+                        question[key] = config[key]
+        elif field_type in {"number", "amount"}:
+            for key in ("numberLimitStatus", "minValue", "maxValue", "decimalDigit", "numberFormat", "currencyStatus", "currencyType", "canDecimal", "noRepeat", "canScan", "scanType"):
+                if key in config:
+                    question[key] = config[key]
+            if field_type == "amount" and "canDecimal" not in question:
+                question["canDecimal"] = True
+        elif field_type in CHOICE_TYPES:
+            for key in ("minOpts", "maxOpts", "optDirection", "optSelectMode", "beingShowColor"):
+                if key in config:
+                    question[key] = _backend_unlimited(config[key]) if key in {"minOpts", "maxOpts"} else config[key]
+        elif field_type == "member":
+            scope = config.get("memberScope")
+            default_scope = config.get("defaultMembers")
+            if isinstance(scope, dict):
+                question["memberSelectScopeType"] = {"all": 1, "custom": 2, "relation": 3}.get(scope.get("mode"), 1)
+                question["memberSelectScope"] = _backend_member_scope(scope)
+            if isinstance(default_scope, dict):
+                question["memberDftValue"] = _backend_member_scope(default_scope)
+            for key in ("noRepeat", "canScan", "scanType"):
+                if key in config:
+                    question[key] = config[key]
+        elif field_type == "department":
+            scope = config.get("departmentScope") if isinstance(config.get("departmentScope"), dict) else None
+            if scope is not None:
+                question["deptSelectScopeType"] = {"all": 1, "custom": 2, "relation": 3}.get(scope.get("mode"), 1)
+                question["deptSelectScope"] = {
+                    "depart": [
+                        _without_none({"deptId": item.get("deptId"), "deptName": item.get("deptName")})
+                        for item in scope.get("departments") or []
+                        if isinstance(item, dict)
+                    ],
+                    "includeSubDeparts": bool(scope.get("includeSubDeparts")),
+                }
+            default_scope = config.get("defaultDepartments")
+            if isinstance(default_scope, dict):
+                question["deptDftValue"] = {
+                    "depart": [
+                        _without_none({"deptId": item.get("deptId"), "deptName": item.get("deptName")})
+                        for item in default_scope.get("departments") or []
+                        if isinstance(item, dict)
+                    ],
+                    "includeSubDeparts": bool(default_scope.get("includeSubDeparts")),
+                }
+            for key in ("noRepeat", "canScan", "scanType", "beingShowParentPath"):
+                if key in config:
+                    question[key] = config[key]
+        elif field_type == "attachment":
+            for key in ("fileSize", "fileType", "fileBeingCaptureOnly", "imageCompress", "pluginStatus", "maxFileLimitStatus", "maxFileLimit", "canScan", "scanType"):
+                if key in config:
+                    question[key] = deepcopy(config[key])
+        elif field_type == "address":
+            for key in ("addressPrecision", "pickPosition", "canScan", "scanType"):
+                if key in config:
+                    question[key] = config[key]
+        elif field_type == "subtable":
+            for key in ("tableRowsLimit", "tableNoRepeatStatus", "tableRowHeight"):
+                if key in config:
+                    question[key] = deepcopy(config[key])
+            if isinstance(config.get("tableNoRepeatQuestion"), list):
+                question["tableNoRepeatQuestion"] = [
+                    self._resolve_subfield_runtime_id(item, internal.get("subfields") or [], "tableNoRepeatQuestion")
+                    for item in config["tableNoRepeatQuestion"]
+                ]
+        if "defaultValues" in config:
+            question["queDefaultValues"] = deepcopy(config.get("defaultValues"))
+        if "defaultType" in field:
+            question["queDefaultType"] = _positive_int(field.get("defaultType")) or 1
+        if "defaultValue" in field:
+            question["queDefaultValue"] = deepcopy(field.get("defaultValue"))
+        if field.get("_clear_default_value") is True:
+            question["queDefaultType"] = 1
+            question["queDefaultValue"] = None
+        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]
+            default_options = (field.get("config") or {}).get("defaultOptions")
+            if isinstance(default_options, list):
+                for option in options:
+                    option["beingDefault"] = str(option.get("optValue")) in {str(item) for item in default_options}
+        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],
+                "beingDefaultFormulaAutoFillEnabled": config.get("beingDefaultFormulaAutoFillEnabled"),
+                "defaultValueFormula": config.get("defaultValueFormula"),
+                "defaultValueMatchRules": deepcopy(config.get("defaultValueMatchRules")),
+            }
+        )
+        if "defaultValues" in config:
+            result["queDefaultValues"] = deepcopy(config.get("defaultValues"))
+        return result
+
+    def _select_scope_relation(self, profile: str, field: JSONObject, internal: JSONObject) -> JSONObject:
+        config = field.get("config") if isinstance(field.get("config"), dict) else {}
+        relation = config.get("memberScopeRelation") or config.get("departmentScopeRelation")
+        if not isinstance(relation, dict):
+            raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "select scope relation must be an object", "COMPILE")
+        target_app_key = str(relation.get("targetAppKey") or "")
+        if not target_app_key:
+            raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "select scope relation requires targetAppKey", "COMPILE")
+        target_form = self._read_form(profile, target_app_key, being_draft=False)
+        candidates = _backend_question_candidates(target_form)
+        displayed = _resolve_backend_selector(relation.get("displayedField") or {}, candidates, "selectScopeRelation.displayedField")
+        payload: JSONObject = {
+            "queId": _positive_int(internal.get("que_id")) or int(internal.get("que_temp_id") or 0),
+            "displayedQueId": _positive_int(displayed.get("queId")),
+            "displayedQueInfo": {
+                "appKey": target_app_key,
+                "appTitle": relation.get("targetAppTitle") or target_form.get("formTitle") or "",
+                "queId": _positive_int(displayed.get("queId")),
+                "queTitle": displayed.get("queTitle") or "",
+                "queType": _positive_int(displayed.get("queType")) or 2,
+            },
+        }
+        for key in ("matchRuleType", "matchRules", "matchRuleFormula"):
+            if key in relation:
+                payload[key] = deepcopy(relation.get(key))
+        return _without_none(payload)
+
+    @staticmethod
+    def _resolve_subfield_runtime_id(selector: JSONObject, internal_fields: list[JSONObject], location: str) -> int:
+        if not isinstance(selector, dict):
+            raise AppFormFailure("INVALID_FIELD_SELECTOR", f"{location} must be an object", "COMPILE")
+        que_id = _positive_int(selector.get("queId"))
+        name = str(selector.get("name") or "")
+        matches = [
+            item for item in internal_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 subfield", "COMPILE", details={"selector": selector, "matches": len(matches)})
+        return _positive_int(matches[0].get("que_id")) or int(matches[0].get("que_temp_id") or 0)
+
+    @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_type(field) != "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":
+            judge_values, judge_value_details = cls._data_relation_literal_values(
+                source,
+                deepcopy(operand.get("values") or []),
+            )
+            payload.update(
+                {
+                    "matchType": 1,
+                    "judgeValues": judge_values,
+                    "judgeValueDetails": judge_value_details,
+                }
+            )
+        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 _data_relation_literal_values(source: JSONObject, values: list[Any]) -> tuple[list[str], list[JSONObject]]:
+        field_type = _canonical_backend_field_type(source)
+        options = [item for item in source.get("options") or [] if isinstance(item, dict)]
+        option_by_name = {
+            str(item.get("optValue")): item
+            for item in options
+            if item.get("optValue") is not None
+        }
+        option_by_id = {
+            str(item.get("optId")): item
+            for item in options
+            if _positive_int(item.get("optId")) is not None
+        }
+        judge_values: list[str] = []
+        details: list[JSONObject] = []
+        for value in values:
+            if isinstance(value, bool):
+                text = "true" if value else "false"
+            elif isinstance(value, (str, int, float)):
+                text = str(value)
+            else:
+                raise AppFormFailure(
+                    "UNSUPPORTED_FIELD_CONFIG",
+                    "literal data_relation values must be strings",
+                    "CONTRACT_PRECHECK",
+                    details={"field": AppFormCompiler._data_relation_field_name(source), "value": value},
+                )
+            if field_type in CHOICE_TYPES and options:
+                option = option_by_name.get(text) or option_by_id.get(text)
+                if option is None:
+                    raise AppFormFailure(
+                        "UNSUPPORTED_FIELD_CONFIG",
+                        f"literal value {text!r} is not an option of data_relation source field "
+                        f"{AppFormCompiler._data_relation_field_name(source)!r}",
+                        "CONTRACT_PRECHECK",
+                        details={"value": text, "allowedValues": sorted(option_by_name)},
+                    )
+                option_id = _positive_int(option.get("optId"))
+                option_name = str(option.get("optValue") or text)
+                judge_values.append(str(option_id) if option_id is not None else option_name)
+                details.append(_without_none({"id": option_id, "value": option_name}))
+                continue
+            judge_values.append(text)
+            details.append({"value": text})
+        return judge_values, details
+
+    @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_type(field)), 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 _field_type(target)))
+        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", "selectScopeRelations"}
+        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("appDescription") or ""
+        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,
+        schema_kind: str | None = None,
+    ) -> JSONObject:
+        try:
+            return {
+                "status": "success",
+                **self.registry.schema(
+                    schema_version=schema_version,
+                    field_type=field_type,
+                    schema_kind=schema_kind,
+                ),
+            }
+        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)
+            if not being_draft:
+                form = _normalize_published_scope_omissions(form)
+            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"},
+                )
+            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"] = "CREATE_IN_PROGRESS"
+            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 = self._published_resource(
+                        profile=profile,
+                        app_key=app_key,
+                        context=context,
+                        normalizer=normalizer,
+                    )
+                    publish_needed = not _published_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"
+                    diagnostics["pendingBindings"] = []
+
+            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 = self._published_resource(
+                        profile=profile,
+                        app_key=app_key,
+                        context=context,
+                        normalizer=normalizer,
+                    )
+                    diagnostics["published"] = _published_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:
+            if created and app_key:
+                return self._rollback_created_after_failure(
+                    profile=profile,
+                    app_key=app_key,
+                    error_code=error.error_code,
+                    message=error.message,
+                    phase="VALIDATE",
+                    details={**error.details, **({"path": error.path} if error.path else {})},
+                    diagnostics=diagnostics,
+                    warnings=warnings,
+                )
+            diagnostics["operation"] = {
+                "create": "CREATE_FAILED",
+                "update": "UPDATE_FAILED",
+            }.get(str(diagnostics.get("applyMode") or ""), "VALIDATION_FAILED")
+            validation_diagnostics = {
+                key: diagnostics[key]
+                for key in ("operation", "applyMode")
+                if diagnostics.get(key) is not None
+            }
+            return self._failure(
+                error.error_code,
+                error.message,
+                "VALIDATE",
+                details={**error.details, **({"path": error.path} if error.path else {})},
+                diagnostics=validation_diagnostics,
+                app_key=app_key,
+                warnings=warnings,
+            )
+        except AppFormFailure as error:
+            preserve_created_app = error.error_code == "APPLY_READBACK_MISMATCH"
+            if (
+                created
+                and app_key
+                and not preserve_created_app
+                and error.status != "unknown"
+                and diagnostics.get("writeMayHaveSucceeded") is not True
+            ):
+                return self._rollback_created_after_failure(
+                    profile=profile,
+                    app_key=app_key,
+                    error_code=error.error_code,
+                    message=error.message,
+                    phase=error.phase,
+                    details=error.details,
+                    diagnostics=diagnostics,
+                    warnings=warnings,
+                )
+            if created:
+                diagnostics["operation"] = "CREATE_INCOMPLETE"
+            else:
+                diagnostics["operation"] = {
+                    "create": "CREATE_FAILED",
+                    "update": "UPDATE_FAILED",
+                }.get(str(diagnostics.get("applyMode") or ""), "VALIDATION_FAILED")
+            status = "partial_success" if created and error.status == "failed" else error.status
+            result = self._failure(error.error_code, error.message, error.phase, status=status, details=error.details, diagnostics=diagnostics, app_key=app_key, warnings=warnings)
+            if error.error_code == "APPLY_READBACK_MISMATCH" and app_key:
+                result["requiresFurtherRepair"] = True
+                result["mustReadCurrentStateBeforeRepair"] = True
+                result["nextApplyMode"] = "update"
+                result["suggested_next_call"] = {
+                    "tool_name": "app_form_get",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "being_draft": True,
+                    },
+                }
+                if created:
+                    result["message"] = (
+                        "the application was created and its form was saved, but backend readback still differs from the apply target; "
+                        "the application was preserved and was not published"
+                    )
+                    result["createdAppPreserved"] = True
+                result["recoveryHint"] = (
+                    "first read the current draft using the returned appKey; compare it with remainingDiff, then merge the intended changes into that current state, "
+                    "keep the appKey in the declaration, validate, and apply again in update mode"
+                )
+            return result
+        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"
+            )
+            if created and app_key and not uncertain:
+                return self._rollback_created_after_failure(
+                    profile=profile,
+                    app_key=app_key,
+                    error_code=code,
+                    message=str(self._error_details(error).get("message") or error),
+                    phase="APPLY",
+                    details=self._error_details(error),
+                    diagnostics=diagnostics,
+                    warnings=warnings,
+                )
+            if created:
+                diagnostics["operation"] = "CREATE_INCOMPLETE"
+            else:
+                diagnostics["operation"] = {
+                    "create": "CREATE_FAILED",
+                    "update": "UPDATE_FAILED",
+                }.get(str(diagnostics.get("applyMode") or ""), "VALIDATION_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 _rollback_created_after_failure(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        error_code: str,
+        message: str,
+        phase: str,
+        details: JSONObject | None,
+        diagnostics: JSONObject,
+        warnings: list[JSONObject],
+    ) -> JSONObject:
+        diagnostics["createRollbackAttempted"] = True
+        failure_details = deepcopy(details or {})
+        transport_error = failure_details.pop("transportError", None)
+        if isinstance(transport_error, dict):
+            failure_details["failureCause"] = deepcopy(transport_error)
+        try:
+            self.apps.app_delete(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as rollback_error:
+            rollback_details = self._error_details(rollback_error)
+            uncertain = self._is_uncertain_api_error(rollback_error)
+            diagnostics["createRollbackSucceeded"] = None if uncertain else False
+            diagnostics["operation"] = "CREATE_ROLLBACK_UNKNOWN" if uncertain else "CREATE_ROLLBACK_FAILED"
+            failure_details["rollbackError"] = rollback_details
+            return self._failure(
+                error_code,
+                (
+                    "AppForm creation failed, and cleanup of the newly created application "
+                    f"{'could not be confirmed' if uncertain else 'also failed'}: {message}"
+                ),
+                phase,
+                status="unknown" if uncertain else "partial_success",
+                details=failure_details,
+                diagnostics=diagnostics,
+                app_key=app_key,
+                warnings=warnings,
+            )
+        diagnostics["createRollbackSucceeded"] = True
+        diagnostics["operation"] = "CREATE_ROLLED_BACK"
+        result = self._failure(
+            error_code,
+            f"AppForm creation failed and the newly created application was deleted: {message}",
+            phase,
+            status="failed",
+            details=failure_details,
+            diagnostics=diagnostics,
+            app_key=app_key,
+            warnings=warnings,
+        )
+        result["recoverable"] = True
+        result["recoveryHint"] = "fix the original failure cause, then submit the create declaration again"
+        return result
+
+    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"])
+        payload = {
+            "appName": app_name,
+            "appIcon": encode_workspace_icon_with_defaults(icon=None, color=None, 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:
+            normalizer, _compiler = self._runtime_for(context)
+            published = self._published_resource(
+                profile=profile,
+                app_key=app_key,
+                context=context,
+                normalizer=normalizer,
+            )
+            diagnostics["published"] = _published_equal(draft, published)
+        except (QingflowApiError, RuntimeError, AppFormFailure):
+            diagnostics["published"] = None
+        return diagnostics["published"]
+
+    def _published_resource(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        context: AppFormSchemaContext,
+        normalizer: AppFormNormalizer,
+    ) -> JSONObject:
+        published_form = self._read_form(profile, app_key, being_draft=False)
+        comparable_form = _normalize_published_scope_omissions(published_form)
+        return normalizer.from_backend(context=context, app_key=app_key, form=comparable_form)
+
+    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)
+        backend_message = str(details.get("message") or "").strip()
+        message = "form write failed or could not be confirmed"
+        if backend_message:
+            message = f"{message}: {backend_message}"
+        raise AppFormFailure(
+            "APPLY_RESULT_UNKNOWN" if diagnostics["writeMayHaveSucceeded"] else "RELATION_REBIND_FAILED" if not first_write else "APP_FORM_WRITE_FAILED",
+            message,
+            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:
+        output_diagnostics = deepcopy(diagnostics or {})
+        for key in ("diff", "remainingDiff"):
+            if key in output_diagnostics:
+                output_diagnostics[key] = AppFormReconciler._compact_diff(output_diagnostics[key])
+        result = {
+            "status": status,
+            "error_code": error_code,
+            "recoverable": status != "failed" or error_code in {"PUBLISH_FAILED", "PACKAGE_ATTACH_RESULT_UNKNOWN"},
+            "message": message,
+            **output_diagnostics,
+            "phase": phase,
+            **({"appKey": app_key} if app_key else {}),
+            **({"warnings": warnings} if warnings else {}),
+        }
+        if details:
+            # Apply diagnostics are already exposed at the top level. Keep only
+            # additional error context in details to avoid returning the same
+            # large diagnostic object twice.
+            compact_details = {
+                key: value
+                for key, value in details.items()
+                if key not in result
+            }
+            for key in ("diff", "remainingDiff"):
+                if key in compact_details:
+                    compact_details[key] = AppFormReconciler._compact_diff(compact_details[key])
+            if compact_details:
+                result["details"] = compact_details
+        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
+
+    @staticmethod
+    def _compact_diff(diff: Any) -> Any:
+        if not isinstance(diff, dict):
+            return diff
+        compact = deepcopy(diff)
+        for key in ("added", "updated", "removed"):
+            fields = compact.get(key)
+            if not isinstance(fields, list):
+                continue
+            compact[key] = [
+                str(field.get("name") or field.get("queId") or "unknown") if isinstance(field, dict) else str(field)
+                for field in fields
+                if isinstance(field, (dict, str, int))
+            ]
+        return compact
+
+    @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_canonical_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("name") or "") == name)
+    ]
+    if len(matches) != 1:
+        raise AppFormFailure(
+            "INVALID_FIELD_SELECTOR",
+            f"{location} must resolve to exactly one top-level 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]