@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/_core/report_ops.py

@@ -1,18 +1,18 @@
 # -*- coding: utf-8 -*-
 """Report-specific API operations for cosmic_api.
 
-Provides functions to manage report data sources, columns, filters, sorts,
-and plugins via the Cosmic OpenAPI. Each function follows the incremental-modify
-pattern: fetch current schema → merge changes → submit via setComplexProperty
-or setProperties.
+管理报表查询数据源、列、过滤和插件的 API 写入与独立回读。
+默认排序属于 Java 查询契约；有缺陷的 ReportSorts 写入被阻断。
 
 Dependencies: only standard library + project-internal _core.config._api_call.
 """
 
+import copy
 import json
 import os
 import re
 import sys
+import urllib.error
 import xml.etree.ElementTree as ET
 
 from _core.cmd_forms import parse_schema_text
@@ -51,6 +51,109 @@ _FILTER_UNPERSISTED_KEYS = ("mustInput", "visible", "defaultValue")
 # says so once and every filter's comparison lands in the plugin contract for query() to apply.
 _FILTER_UNPERSISTED_COMPARE = "compare"
 
+# ─── Typed report filter editors ──────────────────────────────────────────────
+# The platform's report filter API (complexType "ReportFilters") takes an optional per-filter
+# `fieldType` that builds the filter's native editor — an F7 picker, a dropdown, a date range —
+# instead of a text box. It ships as a platform patch, while this skill ships with the client,
+# so a client can be newer than the platform it writes to. The tables below mirror the patch's
+# own ReportFilterFieldBuilder, so a request the patch would refuse fails here before the write.
+# What a platform WITHOUT the patch does instead is never assumed: it ignores `fieldType` and
+# renders the legacy control, and that is decided after the write from the platform's receipt
+# and the read-back (see build_filter_editor_outcome / resolve_filter_editors).
+REPORT_FILTER_FIELD_TYPES = (
+    "TextField", "IntegerField", "BigIntField", "DecimalField", "DateField", "DateTimeField",
+    "DateRangeField", "TimeField", "TimeRangeField", "CheckBoxField", "ComboField",
+    "MulComboField", "CheckBoxGroupField", "BasedataField", "MulBasedataField", "OrgField",
+    "UserField", "CurrencyField", "UnitField", "MaterielField", "CustomerField",
+    "SupplierField", "AssistantField", "ItemClassTypeField", "ItemClassField",
+)
+# The patch resolves these spellings case-insensitively; accepting the same set keeps any value
+# the platform accepts acceptable here, while every artifact is normalized to the class name.
+_REPORT_FILTER_TYPE_ALIASES = {
+    **{name.lower(): name for name in REPORT_FILTER_FIELD_TYPES},
+    "text": "TextField", "integer": "IntegerField", "int": "IntegerField",
+    "bigint": "BigIntField", "decimal": "DecimalField", "number": "DecimalField",
+    "date": "DateField", "datetime": "DateTimeField", "daterange": "DateRangeField",
+    "time": "TimeField", "timerange": "TimeRangeField", "checkbox": "CheckBoxField",
+    "boolean": "CheckBoxField", "switch": "CheckBoxField", "combo": "ComboField",
+    "mulcombo": "MulComboField", "checkboxgroup": "CheckBoxGroupField",
+    "basedata": "BasedataField", "mulbasedata": "MulBasedataField", "org": "OrgField",
+    "user": "UserField", "currency": "CurrencyField", "unit": "UnitField",
+    "material": "MaterielField", "materiel": "MaterielField", "customer": "CustomerField",
+    "supplier": "SupplierField", "assistant": "AssistantField",
+    "itemclasstype": "ItemClassTypeField", "itemclass": "ItemClassField",
+}
+# Parameter -> the editor types that take it. The patch refuses a parameter sent with any other
+# type, and one sent without `fieldType` at all.
+_REPORT_FILTER_TYPE_PARAMS = {
+    "basedataNumber": {"BasedataField", "MulBasedataField"},
+    "comboItems": {"ComboField", "MulComboField", "CheckBoxGroupField"},
+    "itemClassTypes": {"ItemClassTypeField"},
+    "typeFieldKey": {"ItemClassField"},
+    "asstTypeId": {"AssistantField"},
+    "orgFuncs": {"OrgField"},
+    "showStyle": {"CheckBoxField"},
+    "startDateFieldKey": {"DateRangeField", "TimeRangeField"},
+    "endDateFieldKey": {"DateRangeField", "TimeRangeField"},
+}
+# The parameter a new editor of that type cannot be built without. setReportFilters replaces the
+# whole filter set, so every request is the complete desired state and always carries it.
+_REPORT_FILTER_REQUIRED_PARAMS = {
+    "BasedataField": "basedataNumber", "MulBasedataField": "basedataNumber",
+    "ComboField": "comboItems", "MulComboField": "comboItems",
+    "CheckBoxGroupField": "comboItems", "ItemClassTypeField": "itemClassTypes",
+    "ItemClassField": "typeFieldKey", "AssistantField": "asstTypeId",
+}
+# Range editors split one filter into two runtime items. A single date or time editor asked to
+# filter a range becomes the matching range editor, exactly as a legacy `between` filter does.
+_REPORT_FILTER_RANGE_ITEM_SUFFIXES = {
+    "DateRangeField": ("_startdate", "_enddate"),
+    "TimeRangeField": ("_starttime", "_endtime"),
+}
+_REPORT_FILTER_RANGE_OF = {
+    "DateField": "DateRangeField", "DateTimeField": "DateRangeField", "TimeField": "TimeRangeField",
+}
+# F7 editors take no `defaultValue`: the patch refuses it and points at defValueDesign instead.
+_REPORT_FILTER_F7_TYPES = {
+    "BasedataField", "MulBasedataField", "OrgField", "UserField", "CurrencyField", "UnitField",
+    "MaterielField", "CustomerField", "SupplierField", "AssistantField", "ItemClassField",
+}
+REPORT_FILTER_MULTI_VALUE_TYPES = {"MulBasedataField", "MulComboField", "CheckBoxGroupField"}
+# The patch builds these two from optional extension classes and falls back to a plain
+# BasedataField on the same base data when the class is absent, so either one is the editor.
+_REPORT_FILTER_EQUIVALENT_TYPES = {
+    "CustomerField": {"BasedataField"},
+    "SupplierField": {"BasedataField"},
+}
+# How the plugin reads each editor's value from ReportQueryParam.getFilter(): the FilterInfo
+# accessor (api/entity/report/FilterInfo.md), the Java value it yields, and how sure that is.
+# "measured" shapes are recorded in references/report-filter-contract.md; "observeOnce" ones
+# have a documented accessor but no measured value class yet, so the plugin confirms them with
+# one request-scoped observation instead of trusting this table.
+_REPORT_FILTER_VALUE_SHAPES = {
+    "TextField": ("getString", "String", "measured"),
+    "IntegerField": ("getValue", "Integer", "observeOnce"),
+    "BigIntField": ("getValue", "Long", "observeOnce"),
+    "DecimalField": ("getBigDecimal", "BigDecimal", "observeOnce"),
+    "DateField": ("getDate", "java.util.Date", "observeOnce"),
+    "DateTimeField": ("getDate", "java.util.Date", "observeOnce"),
+    "DateRangeField": ("getFilterItems", "java.util.Date per range item", "measured"),
+    "TimeField": ("getValue", "Integer seconds after midnight", "observeOnce"),
+    "TimeRangeField": ("getFilterItems", "Integer seconds after midnight per range item", "observeOnce"),
+    "CheckBoxField": ("getBoolean", "boolean", "observeOnce"),
+    "ComboField": ("getString", "String stored value", "measured"),
+    "MulComboField": ("getString", "String of stored values", "observeOnce"),
+    "CheckBoxGroupField": ("getString", "String of stored values", "observeOnce"),
+    "MulBasedataField": ("getDynamicObjectCollection", "DynamicObjectCollection", "measured"),
+    "ItemClassTypeField": ("getValue", "Object", "observeOnce"),
+    "ItemClassField": ("getDynamicObject", "DynamicObject", "observeOnce"),
+    **{name: ("getDynamicObject", "DynamicObject", "measured") for name in (
+        "BasedataField", "OrgField", "UserField", "CurrencyField", "UnitField",
+        "MaterielField", "CustomerField", "SupplierField", "AssistantField",
+    )},
+}
+REPORT_FILTER_EDITOR_OUTCOME_VERSION = "app-build-report-filter-editors/v1"
+
 
 def _requests_unpersisted(item, key):
     """True only when the value differs from the platform default, i.e. a real request.
@@ -224,22 +327,167 @@ def _normalize_column(raw, path, seen):
     return item
 
 
-def normalize_report_columns_input(value):
+def _assert_report_precision_writable(columns):
+    """标量列不能证明精度引用已物化；写前拒绝，不做固定精度降级。"""
+    for column in _iter_leaf_columns(columns):
+        spec = column.get("presentation")
+        if not isinstance(spec, dict):
+            continue
+        key = _PRESENTATION_BINDING_KEY.get(str(spec.get("kind") or "").strip().lower())
+        if key:
+            _input_error(
+                f"REPORT_PRECISION_REFERENCE_UNVERIFIED: {column.get('fieldKey')!r} 的 "
+                f"presentation.{key}={spec.get(key)!r} 需要格式化前运行行上的 DynamicObject 引用；"
+                "隐藏 bigint 的 Long 主键、相同字段名和 getColumns() 工厂调用不能证明引用已物化。"
+                "先验证平台引用字段、旧字段迁移及批量物化链路，再开放技能契约；"
+                "不发送写入，不用固定精度或取消绑定代替需求。")
+
+
+def _normalize_report_columns_structure(value):
+    """共用形状校验；历史需求编译不构成写入授权。"""
     if not isinstance(value, list) or not value:
         _input_error("columns must be a non-empty array")
     seen = set()
     return [_normalize_column(item, f"columns[{index}]", seen) for index, item in enumerate(value)]
 
 
+def normalize_report_columns_input(value):
+    columns = _normalize_report_columns_structure(value)
+    _assert_report_precision_writable(columns)
+    return columns
+
+
+def _combo_value(raw, path):
+    """A stored dropdown value as text, keeping 0 and leading zeros exactly as declared."""
+    if raw is None or isinstance(raw, bool) or isinstance(raw, (dict, list)):
+        _input_error(f"{path} must be a non-empty string or number")
+    text = raw.strip() if isinstance(raw, str) else str(raw)
+    if not text:
+        _input_error(f"{path} must be non-empty")
+    return text
+
+
+def _normalize_filter_combo_items(value, path):
+    if not isinstance(value, list) or not value:
+        _input_error(f"{path} must be a non-empty array of {{value, caption}}")
+    items = []
+    seen = set()
+    for index, raw in enumerate(value):
+        item = _object(raw, f"{path}[{index}]", {"value", "caption"})
+        entry = {
+            "value": _combo_value(item.get("value"), f"{path}[{index}].value"),
+            "caption": _text(item.get("caption"), f"{path}[{index}].caption"),
+        }
+        if entry["value"] in seen:
+            _input_error(f"duplicate {path} value {entry['value']!r}")
+        seen.add(entry["value"])
+        items.append(entry)
+    return items
+
+
+def _normalize_item_class_types(value, path):
+    if not isinstance(value, list) or not value:
+        _input_error(f"{path} must be a non-empty array of {{basedataNumber, caption}}")
+    rows = []
+    seen = set()
+    for index, raw in enumerate(value):
+        item = _object(raw, f"{path}[{index}]", {"basedataNumber", "caption"})
+        row = {"basedataNumber": _text(item.get("basedataNumber"), f"{path}[{index}].basedataNumber")}
+        if row["basedataNumber"] in seen:
+            _input_error(f"duplicate {path} basedataNumber {row['basedataNumber']!r}")
+        seen.add(row["basedataNumber"])
+        if "caption" in item:
+            row["caption"] = _text(item["caption"], f"{path}[{index}].caption")
+        rows.append(row)
+    return rows
+
+
+def _normalize_filter_editor(item, path):
+    """Validate one filter's typed editor against the platform patch's own rules.
+
+    Every refusal here is one the patch would make too, so a request that passes is one the
+    patch accepts. A platform without the patch accepts it as well and ignores the editor part,
+    which the write reports as a degraded editor rather than failing on.
+    """
+    raw = item.get("fieldType")
+    if raw is None:
+        for name in _REPORT_FILTER_TYPE_PARAMS:
+            if name in item:
+                _input_error(f"{path}.{name} needs fieldType: it configures a typed filter editor")
+        return item
+    field_type = _REPORT_FILTER_TYPE_ALIASES.get(str(raw).strip().lower())
+    if not field_type:
+        _input_error(
+            f"{path}.fieldType {raw!r} is not a report filter editor type; use one of "
+            f"{list(REPORT_FILTER_FIELD_TYPES)!r}")
+    if item["compare"] == "between":
+        field_type = _REPORT_FILTER_RANGE_OF.get(field_type, field_type)
+        if field_type not in _REPORT_FILTER_RANGE_ITEM_SUFFIXES:
+            _input_error(
+                f"{path}: compare=between needs a range editor (DateRangeField or "
+                f"TimeRangeField), and {field_type} holds one value; declare a from/to pair of "
+                "filters instead")
+    elif field_type in _REPORT_FILTER_RANGE_ITEM_SUFFIXES:
+        _input_error(f"{path}.fieldType {field_type} is a range editor and needs compare=between")
+    item["fieldType"] = field_type
+    for name, owners in _REPORT_FILTER_TYPE_PARAMS.items():
+        if name in item and field_type not in owners:
+            _input_error(
+                f"{path}.{name} does not apply to fieldType {field_type}; it configures "
+                f"{sorted(owners)!r}")
+    required = _REPORT_FILTER_REQUIRED_PARAMS.get(field_type)
+    if required and item.get(required) in (None, "", []):
+        _input_error(f"{path}.{required} is required for fieldType {field_type}")
+    if "basedataNumber" in item:
+        item["basedataNumber"] = _text(item["basedataNumber"], f"{path}.basedataNumber")
+    if "comboItems" in item:
+        item["comboItems"] = _normalize_filter_combo_items(item["comboItems"], f"{path}.comboItems")
+    if "itemClassTypes" in item:
+        item["itemClassTypes"] = _normalize_item_class_types(
+            item["itemClassTypes"], f"{path}.itemClassTypes")
+    for name in ("typeFieldKey", "startDateFieldKey", "endDateFieldKey"):
+        if name in item:
+            item[name] = _text(item[name], f"{path}.{name}", identifier=True)
+    if "asstTypeId" in item:
+        item["asstTypeId"] = _text(item["asstTypeId"], f"{path}.asstTypeId")
+        if not item["asstTypeId"].isdigit():
+            _input_error(f"{path}.asstTypeId must be the numeric id of an assistant data group")
+    if "orgFuncs" in item:
+        item["orgFuncs"] = _text(item["orgFuncs"], f"{path}.orgFuncs")
+    if "showStyle" in item:
+        style = item["showStyle"]
+        if isinstance(style, bool) or not isinstance(style, int) or not 0 <= style <= 3:
+            _input_error(f"{path}.showStyle must be an integer from 0 to 3")
+    if item.get("defaultValue") not in (None, ""):
+        if field_type in _REPORT_FILTER_F7_TYPES:
+            _input_error(
+                f"{path}.defaultValue is not supported on {field_type}: the platform refuses a "
+                "default on an F7 filter editor")
+        if field_type == "CheckBoxField" and str(item["defaultValue"]).strip().lower() not in {
+                "true", "false", "1", "0"}:
+            _input_error(f"{path}.defaultValue on CheckBoxField must be true, false, 1 or 0")
+    return item
+
+
 def normalize_report_filters_input(value):
     if not isinstance(value, list) or not value:
         _input_error("filters must be a non-empty array")
     allowed = {
-        "fieldPath", "displayName", "compare", "defaultValue", "mustInput", "visible", "source",
+        "fieldPath", "displayName", "compare", "defaultValue", "mustInput", "visible",
+        "fieldType", *_REPORT_FILTER_TYPE_PARAMS,
     }
     result = []
     seen = set()
     for index, raw in enumerate(value):
+        if isinstance(raw, dict) and "source" in raw:
+            _input_error(
+                f"filters[{index}].source is retired: declare fieldType and its parameters "
+                "instead (an F7 filter is fieldType plus basedataNumber); read the source field's "
+                "type and reference from that form's getFormSchema")
+        if isinstance(raw, dict) and "baseEntityId" in raw:
+            _input_error(
+                f"filters[{index}].baseEntityId is not accepted: pass basedataNumber and let the "
+                "platform resolve it, because a supplied id cannot be proven to exist")
         item = _object(raw, f"filters[{index}]", allowed)
         item["fieldPath"] = _text(item.get("fieldPath"), f"filters[{index}].fieldPath", identifier=True)
         if item["fieldPath"] in seen:
@@ -250,14 +498,21 @@ def normalize_report_filters_input(value):
         if item["compare"] not in {"=", "in", "between"}:
             _input_error(
                 f"filters[{index}].compare is not in the verified set (=, in, between)")
-        if "source" in item:
-            source = _object(item["source"], f"filters[{index}].source", {"formNumber", "fieldKey"})
-            item["source"] = {key: _text(source.get(key), f"filters[{index}].source.{key}", identifier=True)
-                              for key in ("formNumber", "fieldKey")}
         for key in ("mustInput", "visible"):
             if key in item:
                 item[key] = _boolean(item[key], f"filters[{index}].{key}")
-        result.append(item)
+        if item.get("mustInput") is True and item.get("visible") is False:
+            _input_error(
+                f"filters[{index}] is mustInput and visible:false at once; a required filter the "
+                "user cannot see can never be filled, and the platform refuses it")
+        result.append(_normalize_filter_editor(item, f"filters[{index}]"))
+    editors = {item["fieldPath"]: item.get("fieldType") for item in result}
+    for index, item in enumerate(result):
+        target = item.get("typeFieldKey")
+        if target and editors.get(target) != "ItemClassTypeField":
+            _input_error(
+                f"filters[{index}].typeFieldKey {target!r} must name an ItemClassTypeField "
+                "filter in the same request")
     return result
 
 
@@ -325,8 +580,28 @@ def _get_schema(cfg, token, form_id):
     return result
 
 
+class ReportMutationError(RuntimeError):
+    """报表写入边界已越过；None 表示结果未知，True 仅表示已有成功回执。"""
+    def __init__(self, message, mutation_applied=None):
+        super().__init__(message)
+        self.mutation_applied = mutation_applied
+
+
+def _read_after_report_write(callback, *args, **kwargs):
+    """成功写入后的回读失败保留写入证据，不能诱导重放。"""
+    try:
+        return callback(*args, **kwargs)
+    except Exception as exc:
+        raise ReportMutationError(
+            str(exc) if isinstance(exc, ValueError) else
+            f"REPORT_READBACK_UNAVAILABLE: {type(exc).__name__}; re-read before retrying",
+            mutation_applied=True) from exc
+
+
 def _set_complex(cfg, token, form_number, complex_type, data, element_key=None):
     """Wrapper for setComplexProperty API call."""
+    if complex_type == "ReportSorts":
+        raise RuntimeError(REPORT_SORTS_API_UNSAFE)
     payload = {
         "formNumber": form_number,
         "complexType": complex_type,
@@ -334,7 +609,12 @@ def _set_complex(cfg, token, form_number, complex_type, data, element_key=None):
     }
     if element_key:
         payload["elementKey"] = element_key
-    return _api_call(cfg, token, "setComplexProperty", payload, method="POST")
+    try:
+        return _api_call(cfg, token, "setComplexProperty", payload, method="POST")
+    except Exception as exc:
+        raise ReportMutationError(
+            f"REPORT_WRITE_OUTCOME_UNKNOWN: {complex_type} request failed with {type(exc).__name__}; "
+            "re-read the report before retrying; do not replay the write") from exc
 
 
 def _extract_form_number(schema_result):
@@ -408,7 +688,8 @@ _REPORT_COLUMNS_ALREADY_SET = (
     "REPORT_COLUMNS_NOT_REPLACEABLE: report {form!r} already has report-entity fields for "
     "{existing}. Columns are create-time only, because this write would duplicate those fields "
     "and brick every later save. To add columns, send only the new ones to addReportColumns; to "
-    "remove, reorder or re-type one, plan the rebuild with planReportRecreate. Do not add the "
+    "remove one leaf column, use removeReportColumn (requires the backend deletion patch); to "
+    "reorder or re-type one, plan the rebuild with planReportRecreate. Do not add the "
     "column in the designer: the platform attaches a loose control to the report page and the "
     "column list stays unchanged."
 )
@@ -508,6 +789,7 @@ def set_report_columns(cfg, token, form_id, columns, dry_run=False, form_number=
     """
     if not columns:
         raise ValueError("columns array must not be empty")
+    _assert_report_precision_writable(columns)
 
     column_payload = {"columns": _build_columns_payload(columns)}
     col_ids = _collect_column_ids(columns)
@@ -522,7 +804,7 @@ def set_report_columns(cfg, token, form_id, columns, dry_run=False, form_number=
         requested_column_keys=_leaf_column_keys(columns),
     )
     result = _set_complex(cfg, token, form_number, "ReportColumns", column_payload)
-    _check_result(result, "setReportColumns")
+    _check_result(result, "setReportColumns", form_mutation_possible=True)
     return col_ids
 
 
@@ -557,6 +839,7 @@ def add_report_columns(cfg, token, form_id, columns, dry_run=False, form_number=
     """
     if not columns:
         raise ValueError("columns array must not be empty")
+    _assert_report_precision_writable(columns)
 
     column_payload = {"columns": _build_columns_payload(columns)}
     col_ids = _collect_column_ids(columns)
@@ -573,7 +856,139 @@ def add_report_columns(cfg, token, form_id, columns, dry_run=False, form_number=
     return col_ids
 
 
-def set_report_filters(cfg, token, form_id, filters, dry_run=False, form_number=None):
+def normalize_report_column_removal_input(value):
+    """单项删除只接受精确叶子列标识，不接受数组、路径或模糊名称。"""
+    item = _object(value, "columnRemoval", {"fieldKey"})
+    if not isinstance(item.get("fieldKey"), str):
+        _input_error("columnRemoval.fieldKey must be a string identifier")
+    item["fieldKey"] = _text(item["fieldKey"], "columnRemoval.fieldKey", identifier=True)
+    return item
+
+
+def _without_report_column(rows, field_key):
+    return [{**row, **({"children": _without_report_column(row["children"], field_key)}
+                      if row.get("kind") == "group" else {})}
+            for row in rows if row["fieldKey"] != field_key]
+
+
+def plan_report_column_removal(schema, field_key, app_root=None, form_number=None, form_id=None):
+    """写前验证唯一叶子与已知币别/单位依赖，不从回读猜测完整需求。"""
+    def nodes(rows):
+        if not isinstance(rows, list):
+            raise ValueError("REPORT_READBACK_UNAVAILABLE: report column tree must be an array")
+        result = []
+        for row in rows:
+            if not isinstance(row, dict) or row.get("kind") not in ("column", "group") or not row.get("fieldKey"):
+                raise ValueError("REPORT_READBACK_UNAVAILABLE: malformed report column tree")
+            result.append(row)
+            if row["kind"] == "group":
+                result.extend(nodes(row.get("children")))
+        return result
+    if not isinstance(schema, dict) or not schema.get("readBackAvailable") or "reportColumns" in (schema.get("unverifiableSections") or []):
+        raise ValueError("REPORT_READBACK_UNAVAILABLE: read the report before deleting a column")
+    if form_number and schema.get("formNumber") and schema["formNumber"] != form_number:
+        raise ValueError("REPORT_TARGET_MISMATCH: report read-back belongs to another form; no deletion submitted")
+    rows = nodes(schema.get("reportColumns"))
+    keys = [row["fieldKey"] for row in rows]
+    if len(keys) != len(set(keys)):
+        raise ValueError("REPORT_COLUMN_TARGET_AMBIGUOUS: duplicate column keys; reconcile before deletion")
+    target = next((row for row in rows if row["fieldKey"] == field_key), None)
+    if not target:
+        raise ValueError(f"REPORT_COLUMN_NOT_FOUND: {field_key!r}; no deletion submitted")
+    if target["kind"] != "column":
+        raise ValueError("REPORT_COLUMN_GROUP_NOT_REMOVABLE: only one leaf column can be removed; no deletion submitted")
+    if app_root:
+        path = report_authoring_path(app_root, form_number)
+        try:
+            previous = json.loads(path.read_text(encoding="utf-8")) if path.is_file() else {}
+        except (ValueError, UnicodeError):
+            previous = {}
+        if isinstance(previous, dict) and previous.get("formNumber") == form_number and previous.get("formId") == form_id:
+            authored = nodes((previous.get("artifact") or {}).get("reportColumns", []))
+            dependents = [row["fieldKey"] for row in authored if row["fieldKey"] != field_key
+                          and any((row.get("presentation") or {}).get(key) == field_key
+                                  for key in ("currencyField", "measureUnitField"))]
+            if dependents:
+                raise ValueError(f"REPORT_COLUMN_IN_USE: {field_key!r} is required by {dependents}; reconcile presentation before deleting")
+    return {"fieldKey": field_key, "before": schema}
+
+
+def _report_column_delete_unavailable(result):
+    """仅识别明确不支持删除分支/缺少路由的失败，保存、权限和目标错误不降级。"""
+    from _core.formatters import _is_api_success
+    if not isinstance(result, dict) or _is_api_success(result):
+        return False
+    layers = [layer for layer in (result, result.get("data")) if isinstance(layer, dict)]
+    if any(str(layer.get("errorCode") or "") not in ("", "0", "META_SAVE_FAIL", "404", "405", "501")
+           or layer.get("success") is True for layer in layers):
+        return False
+    # 内层 PropertyResult 是实际分支回执；外层文案不能覆盖其权限、保存或业务拒绝。
+    layer = layers[-1]
+    code = str(layer.get("errorCode") or "")
+    message = str(layer.get("message") or layer.get("msg") or "").strip()
+    if code in ("", "META_SAVE_FAIL") and re.fullmatch(
+            r"(?:不支持的复杂属性类型\s*[:：]\s*ReportColumns\.remove[。.]?"
+            r"|Unsupported complex property type\s*:\s*ReportColumns\.remove[.]?)", message, re.I):
+        return True
+    return code in ("404", "405", "501") and any(
+        marker in message.lower() for marker in ("cannot found openapi", "接口未注册", "接口不存在",
+                                                "endpoint not found", "no handler found"))
+
+
+def remove_report_column(cfg, token, form_id, field_key, dry_run=False, form_number=None):
+    """调用真实删除分支一次；旧后端明确不支持时保持本地基线，不自动隐藏或重建。"""
+    from _core.formatters import _is_api_success, _extract_error_message
+    field_key = normalize_report_column_removal_input({"fieldKey": field_key})["fieldKey"]
+    form_number = _text(form_number, "formNumber", identifier=True)
+    payload = {"formNumber": form_number, "complexType": "ReportColumns.remove", "data": {"fieldKey": field_key}}
+    if dry_run:
+        return {"dryRun": True, "payload": payload, "writeAttempted": False,
+                "capabilityVerified": False, "runtimeVerified": False}
+    _assert_report_entity_writable(cfg, token, form_id, form_number)
+    try:
+        result = _api_call(cfg, token, "setComplexProperty", payload, method="POST")
+    except urllib.error.HTTPError as exc:
+        # 网关 JSON 业务错误不能被 HTTP 404 包装吞掉；无业务体的缺路由状态才可兼容。
+        if exc.code not in (404, 405, 501):
+            raise ReportMutationError(f"REPORT_WRITE_OUTCOME_UNKNOWN: deletion HTTP {exc.code}; re-read before retrying; do not replay") from exc
+        try:
+            body = exc.read()
+        except Exception as read_error:
+            raise ReportMutationError("REPORT_WRITE_OUTCOME_UNKNOWN: deletion HTTP error body unavailable; re-read before retrying; do not replay") from read_error
+        try:
+            result = json.loads(body) if body else None
+        except (ValueError, UnicodeError):
+            result = None
+        if not isinstance(result, dict):
+            result = {"status": False, "errorCode": str(exc.code), "message": "endpoint not found"}
+        elif _is_api_success(result):
+            raise ReportMutationError("REPORT_WRITE_OUTCOME_UNKNOWN: deletion HTTP status contradicts response; re-read before retrying; do not replay") from exc
+    except Exception as exc:
+        raise ReportMutationError(f"REPORT_WRITE_OUTCOME_UNKNOWN: deletion request failed with {type(exc).__name__}; re-read before retrying; do not replay") from exc
+    if _report_column_delete_unavailable(result):
+        return {"status": False, "errorCode": "REPORT_COLUMN_DELETE_API_UNAVAILABLE",
+                "message": "Backend does not support ReportColumns.remove yet; upgrade the backend before deleting. No hide, rebuild or replay was attempted.",
+                "writeAttempted": True, "data": {"capability": "ReportColumns.remove", "capabilityAvailable": False,
+                "platformMutationApplied": False, "runtimeVerified": False, "platformResponse": result}}
+    inner = result.get("data") if isinstance(result, dict) else None
+    inner_error = isinstance(inner, dict) and str(inner.get("errorCode") or "0") != "0"
+    if not _is_api_success(result) or inner_error:
+        # 已核实这些内层错误在修改 context 前返回；通用 META_SAVE_FAIL 则不能这样断言。
+        rejection = inner if isinstance(inner, dict) and inner.get("success") is False else result
+        if isinstance(rejection, dict) and rejection.get("errorCode") in ("PARAM_INVALID", "PROPERTY_ELEMENT_NOT_FOUND", "ELEMENT_NOT_FOUND"):
+            raise RuntimeError(f"REPORT_COLUMN_DELETE_REJECTED: {_extract_error_message(result)}")
+        raise ReportMutationError(f"REPORT_COLUMN_DELETE_FAILED: {_extract_error_message(result)}; the report may already have changed; re-read before retrying; do not replay")
+    receipt = result.get("data") or {}
+    if isinstance(receipt, dict) and isinstance(receipt.get("data"), dict):
+        receipt = receipt["data"]
+    if not isinstance(receipt, dict) or receipt.get("fieldKey") != field_key or receipt.get("action") != "removed":
+        raise ReportMutationError("REPORT_COLUMN_DELETE_RECEIPT_INVALID: successful response did not identify the requested removal; re-read before retrying; do not replay", True)
+    return {"status": True, "data": {"formId": form_id, "formNumber": form_number,
+            "fieldKey": field_key, "fieldId": receipt.get("fieldId"), "action": "removed", "runtimeVerified": False}}
+
+
+def set_report_filters(cfg, token, form_id, filters, dry_run=False, form_number=None,
+                       outcome=None):
     """Set report filter fields.
 
     Args:
@@ -583,20 +998,24 @@ def set_report_filters(cfg, token, form_id, filters, dry_run=False, form_number=
         filters: reportFilters[] array from artifact.
         dry_run: If True, return payload without submitting.
         form_number: Optional form number.
+        outcome: Optional dict, filled with what the platform did with each filter's editor
+            (see build_filter_editor_outcome). The return value stays the list of filter ids.
 
     Returns:
         List of filter fieldPath ids.
 
-    Note: The platform's Java-side ``ReportPropertyService.setReportFilters``
-    has been fixed to auto-create ``CommonFilterColumnAp`` children in the
-    ``reportcommfilterpanelap`` layout panel, so this client does NOT need to
-    pass ``elementKey``; ReportFilters bound to the entity is enough to make
-    filter controls render at runtime.
+    Typed editors (``fieldType``) need the platform's typed report filter patch. A platform
+    without it accepts the same request, ignores the editor part and renders its legacy control
+    — a text box, or a date range for ``between`` — so the write is not refused for that: the
+    outcome reports the filter as degraded instead, and the read-back confirms which editor
+    rendered. A platform carrying an older patch refuses an editor type it does not offer before
+    saving anything; that filter is sent again without its editor and reported degraded too.
     """
     if not filters:
         raise ValueError("filters array must not be empty")
 
-    filter_payload = {"filters": _build_filters_payload(filters)}
+    payload_filters = _build_filters_payload(filters)
+    filter_payload = {"filters": payload_filters}
     filter_ids = [f.get("fieldPath", "") for f in filters]
     unpersisted = sorted({
         key for f in filters for key in _FILTER_UNPERSISTED_KEYS
@@ -609,6 +1028,11 @@ def set_report_filters(cfg, token, form_id, filters, dry_run=False, form_number=
             "payload": filter_payload,
             "filterIds": filter_ids,
             "unpersistedRequestedProperties": unpersisted,
+            "typedFilterEditors": [
+                {"fieldPath": f["fieldPath"], "fieldType": f["fieldType"],
+                 "legacyFieldType": legacy_filter_editor(f)}
+                for f in filters if f.get("fieldType")
+            ],
         }
 
     if unpersisted:
@@ -621,84 +1045,319 @@ def set_report_filters(cfg, token, form_id, filters, dry_run=False, form_number=
             file=sys.stderr, flush=True,
         )
 
-    # Comparison semantics remain a query requirement; editor shape depends on the
-    # deployed platform version and must be observed instead of assumed to be plain text.
+    # Comparison semantics remain a query requirement whatever editor renders the filter.
     print(
         "[setReportFilters] query comparisons: "
         + ", ".join(
             f"{f.get('fieldPath', '')}={f.get('compare', '')}" for f in filters
         )
-        + ". Verify actual filter editor types from report read-back; compare is not an "
-        "arbitrary control-type selector. Apply the requested query conditions in query().",
+        + ". 编辑器或比较配置回读不证明查询条件已下推；在所属 query() 中落实比较。",
         file=sys.stderr, flush=True,
     )
 
     form_number = _ensure_form_number(cfg, token, form_id, form_number)
-    if any(f.get("source") for f in filters):
-        report_filter_source_expectations(cfg, token, filters)
     _assert_report_entity_writable(
         cfg, token, form_id, form_number, requested_filter_keys=filter_ids)
-    # A separate route makes an old platform reject before mutation instead of silently
-    # ignoring source and creating TextField. Never fall back after an unsupported write.
-    complex_type = "ReportFilters.typed" if any(f.get("source") for f in filters) else "ReportFilters"
-    result = _set_complex(cfg, token, form_number, complex_type, filter_payload)
-    _check_result(result, "setReportFilters", form_mutation_possible=True)
+    typed_keys = [f["fieldPath"] for f in filters if f.get("fieldType")]
+    degraded = {}
+    platform_types = None
+    while True:
+        sent = [
+            _legacy_filter_payload(item) if item["fieldPath"] in degraded else item
+            for item in payload_filters
+        ]
+        result = _set_complex(cfg, token, form_number, "ReportFilters", {"filters": sent})
+        rejection = _unsupported_filter_type_rejection(result, sent)
+        newly = []
+        if rejection:
+            key, refused, offered = rejection
+            platform_types = offered or platform_types
+            for item in sent:
+                field_type = item.get("fieldType")
+                if not field_type or item["fieldPath"] in degraded:
+                    continue
+                if item["fieldPath"] == key or (offered and field_type not in offered):
+                    degraded[item["fieldPath"]] = (
+                        f"the platform's report filter API does not offer {field_type}"
+                        + (f" (it refused {refused})" if field_type != refused else ""))
+                    newly.append(item["fieldPath"])
+        if newly:
+            # The patch validates every filter before it saves anything, so the refused request
+            # changed nothing and resending without those editors is safe.
+            print(
+                f"[setReportFilters] the platform does not offer the editor of {newly}; "
+                "resending them as legacy filters",
+                file=sys.stderr, flush=True,
+            )
+            continue
+        _check_result(result, "setReportFilters", form_mutation_possible=True)
+        break
+    editor_outcome = build_filter_editor_outcome(
+        filters, _filter_receipt(result), degraded, platform_types, form_number)
+    if typed_keys and editor_outcome["typedFilterSupport"] != "available":
+        print(
+            f"[setReportFilters] typed filter editors: {editor_outcome['typedFilterSupport']}. "
+            + ("The platform returned no editor receipt, so it predates the typed report "
+               "filter patch and renders legacy controls; the read-back confirms which editor "
+               "each filter got. " if not editor_outcome["platformReceipt"] else "")
+            + "Re-apply these filters after the platform patch is installed.",
+            file=sys.stderr, flush=True,
+        )
+    if isinstance(outcome, dict):
+        outcome.update(editor_outcome)
     return filter_ids
 
 
-def report_filter_source_expectations(cfg, token, filters):
-    """Read only the selected source forms once; no inferred reference IDs or enum values."""
-    sources = {}
-    expected = {}
-    for item in filters:
-        source = item.get("source")
-        if not source:
+def legacy_filter_editor(item):
+    """The control a platform without the typed filter patch renders for this filter."""
+    return "DateRangeField" if (item or {}).get("compare") == "between" else "TextField"
+
+
+def _legacy_filter_payload(item):
+    """The same filter without its editor part, as a platform without the patch reads it."""
+    return {
+        key: value for key, value in item.items()
+        if key != "fieldType" and key not in _REPORT_FILTER_TYPE_PARAMS
+    }
+
+
+def _result_message(result):
+    if not isinstance(result, dict):
+        return ""
+    nested = result.get("data") if isinstance(result.get("data"), dict) else {}
+    return " ".join(
+        str(value) for value in (result.get("message"), nested.get("message")) if value)
+
+
+_FIELD_CLASS_TOKEN = re.compile(r"\b[A-Z][A-Za-z]*Field\b")
+
+
+def _unsupported_filter_type_rejection(result, sent):
+    """(filterKey, refusedType, offeredTypes) when the platform refused an editor type itself.
+
+    An older patch answers an editor type it does not offer with one message, before saving:
+    the filter key, the refused type and the list it does offer. The wording is localized, but
+    the key and the class names are not, so those are what this reads. Any other refusal — a
+    missing base data, a duplicated dropdown value — is not this, and returns None.
+    """
+    message = _result_message(result)
+    if "fieldType" not in message:
+        return None
+    for item in sent:
+        field_type = item.get("fieldType")
+        key = str(item.get("fieldPath") or "")
+        if not field_type or not key or key not in message:
             continue
-        number = source["formNumber"]
-        if number not in sources:
-            data = (_get_schema(cfg, token, number) or {}).get("data") or {}
-            sources[number] = data.get("fieldSchemas")
-        if not isinstance(sources[number], list):
-            raise RuntimeError("REPORT_TYPED_FILTER_PLATFORM_UNSUPPORTED: source field schema unavailable; install the typed filter platform extension")
-        matches = [row for row in sources[number] if row.get("fieldPath") == source["fieldKey"]]
-        if len(matches) != 1:
-            raise ValueError("REPORT_FILTER_SOURCE_FIELD_AMBIGUOUS_OR_MISSING: " + source["fieldKey"])
-        wanted = {key: value for key, value in matches[0].items() if key not in {"fieldPath", "displayName", "mustInput"}}
-        if item["compare"] == "between" and wanted.get("fieldType") != "DateRangeField":
-            if wanted.get("fieldType") not in {"DateField", "DateTimeField"}:
-                raise ValueError("REPORT_FILTER_RANGE_TYPE_UNSUPPORTED: " + str(wanted.get("fieldType")))
-            wanted["fieldType"] = "DateRangeField"
-        expected[item["fieldPath"]] = wanted
-    return expected
+        position = message.find(field_type, message.find(key))
+        if position < 0:
+            continue
+        offered = set(_FIELD_CLASS_TOKEN.findall(message[position + len(field_type):]))
+        if len(offered) < 2 or field_type in offered:
+            continue
+        return key, field_type, offered
+    return None
 
 
-def set_report_sorts(cfg, token, form_id, sorts, dry_run=False, form_number=None):
-    """Set report sort configuration.
+def _filter_receipt(result):
+    """The per-filter receipt a typed-filter platform returns, or None when there is none.
 
-    Args:
-        cfg: Config dict.
-        token: Access token.
-        form_id: Report form ID.
-        sorts: reportSorts[] array from artifact.
-        dry_run: If True, return payload without submitting.
-        form_number: Optional form number.
+    The patch answers every filter write with data.filters[] (fieldPath, the editor class it
+    actually built, fieldId, action) and data.removed[]. Older platforms answer with no such
+    list, which is how an unpatched platform is recognized without a separate probe.
+    """
+    data = result.get("data") if isinstance(result, dict) else None
+    inner = data.get("data") if isinstance(data, dict) else None
+    rows = inner.get("filters") if isinstance(inner, dict) else None
+    if not isinstance(rows, list):
+        return None
+    return {
+        "filters": [row for row in rows if isinstance(row, dict)],
+        "removed": [str(key) for key in (inner.get("removed") or [])],
+    }
 
-    Returns:
-        True on success.
+
+def _accepted_editor_types(requested):
+    return {requested, *_REPORT_FILTER_EQUIVALENT_TYPES.get(requested, ())}
+
+
+def build_filter_editor_outcome(filters, receipt=None, degraded=None, platform_types=None,
+                                form_number=""):
+    """What the platform did with each filter's editor, as far as the write can tell.
+
+    status per filter:
+      typed        the receipt shows the requested editor (or its documented equivalent);
+      degraded     the platform refused or ignored the editor and renders the legacy control;
+      unconfirmed  no receipt — the read-back decides between typed and degraded;
+      mismatch     the receipt shows an editor that is neither requested nor legacy;
+      legacy       the filter asked for no editor type.
     """
-    if not sorts:
-        raise ValueError("sorts array must not be empty")
+    degraded = degraded or {}
+    by_key = {
+        str(row.get("fieldPath") or ""): row for row in ((receipt or {}).get("filters") or [])
+    }
+    editors = []
+    for item in filters:
+        key = str(item.get("fieldPath") or "")
+        requested = item.get("fieldType") or None
+        legacy = legacy_filter_editor(item)
+        row = by_key.get(key) or {}
+        entry = {"fieldPath": key, "requestedFieldType": requested, "legacyFieldType": legacy}
+        platform_type = str(row.get("fieldType") or "").strip()
+        if platform_type:
+            entry["platformFieldType"] = platform_type
+        if row.get("action"):
+            entry["action"] = row["action"]
+        if not requested:
+            entry["status"] = "legacy"
+        elif key in degraded:
+            entry["status"] = "degraded"
+            entry["reason"] = degraded[key]
+        elif receipt is None:
+            entry["status"] = "unconfirmed"
+            entry["reason"] = (
+                "the platform returned no editor receipt; it renders the legacy control unless "
+                "the read-back shows the requested editor")
+        elif platform_type in _accepted_editor_types(requested):
+            entry["status"] = "typed"
+        elif platform_type == legacy:
+            entry["status"] = "degraded"
+            entry["reason"] = f"the platform built {legacy} instead of {requested}"
+        else:
+            entry["status"] = "mismatch"
+            entry["reason"] = (
+                f"the platform built {platform_type or 'no editor'} instead of {requested}")
+        editors.append(entry)
+    outcome = {
+        "schemaVersion": REPORT_FILTER_EDITOR_OUTCOME_VERSION,
+        "formNumber": str(form_number or ""),
+        "platformReceipt": receipt is not None,
+        "editors": editors,
+    }
+    if platform_types:
+        outcome["platformFieldTypes"] = sorted(platform_types)
+    if receipt and receipt.get("removed"):
+        outcome["removed"] = receipt["removed"]
+    return _summarize_filter_editors(outcome)
+
+
+def _summarize_filter_editors(outcome):
+    """typedFilterSupport from the per-filter statuses."""
+    statuses = [row["status"] for row in outcome["editors"] if row.get("requestedFieldType")]
+    if not statuses:
+        support = "notRequested"
+    elif "mismatch" in statuses:
+        support = "mismatch"
+    elif "unconfirmed" in statuses:
+        support = "unconfirmed"
+    elif all(status == "typed" for status in statuses):
+        support = "available"
+    elif all(status == "degraded" for status in statuses):
+        support = "unavailable"
+    else:
+        support = "partial"
+    outcome["typedFilterSupport"] = support
+    outcome["degradedFilters"] = [
+        row["fieldPath"] for row in outcome["editors"] if row["status"] == "degraded"]
+    return outcome
 
-    sort_payload = {"sorts": _build_sorts_payload(sorts)}
 
-    if dry_run:
-        return {"dryRun": True, "payload": sort_payload}
+def resolve_filter_editors(outcome, observed_rows):
+    """Settle each filter's editor against the read-back, and return the mismatches.
 
-    form_number = _ensure_form_number(cfg, token, form_id, form_number)
-    _assert_report_entity_writable(cfg, token, form_id, form_number)
-    result = _set_complex(cfg, token, form_number, "ReportSorts", sort_payload)
-    _check_result(result, "setReportSorts", form_mutation_possible=True)
-    return True
+    The read-back's schemaText names the editor class of every filter field, so an unconfirmed
+    editor becomes typed or degraded here, and a typed one is held to what the receipt claimed.
+    A filter whose row carries no type stays as it was: that source cannot see it. A receipt
+    that already showed a wrong editor is a mismatch whether or not the read-back can see it.
+    """
+    resolved = json.loads(json.dumps(outcome))
+    observed_by_key = {
+        str(row.get("fieldPath") or ""): row for row in (observed_rows or []) if isinstance(row, dict)
+    }
+    mismatches = []
+    unobserved = []
+    for index, entry in enumerate(resolved["editors"]):
+        requested = entry.get("requestedFieldType")
+        if not requested:
+            continue
+        accepted = _accepted_editor_types(requested)
+        observed = str((observed_by_key.get(entry["fieldPath"]) or {}).get("fieldType") or "")
+        if not observed:
+            unobserved.append(entry["fieldPath"])
+            if entry["status"] == "mismatch":
+                mismatches.append({
+                    "path": f"/reportFilters/{index}/fieldType",
+                    "expected": sorted(accepted),
+                    "actual": entry.get("platformFieldType") or "<none>",
+                })
+            continue
+        entry["observedFieldType"] = observed
+        if entry["status"] == "degraded":
+            wanted = {entry["legacyFieldType"]}
+        elif entry["status"] in ("typed", "mismatch"):
+            wanted = accepted
+        else:
+            wanted = accepted | {entry["legacyFieldType"]}
+        if observed not in wanted:
+            entry["status"] = "mismatch"
+            entry["reason"] = f"the report holds {observed} where {sorted(wanted)} was expected"
+            mismatches.append({
+                "path": f"/reportFilters/{index}/fieldType",
+                "expected": sorted(wanted),
+                "actual": observed,
+            })
+            continue
+        if entry["status"] in ("unconfirmed", "mismatch"):
+            entry["status"] = "typed" if observed in accepted else "degraded"
+            if entry["status"] == "degraded":
+                entry["reason"] = (
+                    f"the platform rendered {observed}: it predates the typed report filter patch")
+            else:
+                entry.pop("reason", None)
+    if unobserved:
+        resolved["unobservedFilters"] = unobserved
+    return _summarize_filter_editors(resolved), mismatches
+
+
+REPORT_SORTS_API_UNSAFE = (
+    "REPORT_SORTS_API_UNSAFE: 未验证原生元数据排序通道；旧 API 曾误写 InitField，"
+    "新 API 返回 REPORT_SORT_NOT_SUPPORTED。InitField 是默认列可见性，不是排序。"
+    "未发送请求。Keep reportSorts in the complete "
+    "artifact and implement reportContract.defaultSorts in the enabled Java reportlist "
+    "plugin's query(), with interactive sorting taking priority. Do not patch isvisible or "
+    "use generic metadata writes; a query-data-source-only report needs a verified sorting "
+    "channel before it can be delivered. Existing invalid InitField requires separate repair."
+)
+
+
+def set_report_sorts(cfg, token, form_id, sorts, dry_run=False, form_number=None):
+    """阻断有缺陷的元数据排序 API；dry-run 也不能暗示该写入受支持。"""
+    normalize_report_sorts_input(sorts)
+    raise RuntimeError(REPORT_SORTS_API_UNSAFE)
+
+
+def compile_report_default_sorts(artifact):
+    """保留排序业务要求并绑定真实叶子列；创建前确认 Java 取数插件能承接。"""
+    if not artifact.get("reportSorts"):
+        return []
+    sorts = normalize_report_sorts_input(artifact["reportSorts"], "reportSorts")
+    columns = {
+        col["fieldKey"]: col
+        for col in _iter_leaf_columns(_normalize_report_columns_structure(artifact.get("reportColumns") or []))
+    }
+    missing = [row["fieldKey"] for row in sorts if row["fieldKey"] not in columns]
+    if missing:
+        raise ValueError(f"REPORT_INPUT_INVALID: sort columns not found: {missing}")
+    plugins = artifact.get("reportPlugins") or []
+    if (len(plugins) != 1 or not isinstance(plugins[0], dict)
+            or str(plugins[0].get("type") or "Java").lower() != "java"
+            or plugins[0].get("enabled") is False or not plugins[0].get("className")):
+        raise ValueError(
+            "REPORT_DEFAULT_SORT_PLUGIN_REQUIRED: reportSorts requires exactly one enabled "
+            "Java reportlist data-fetch plugin; metadata ReportSorts is unsafe. Preserve the "
+            "sorting requirement and confirm a supported query implementation before creating "
+            "the report. Do not silently drop sorts or add/replace a plugin without authorization."
+        )
+    return [{**row, "dateIndex": columns[row["fieldKey"]]["dateIndex"]} for row in sorts]
 
 
 def register_report_plugin(cfg, token, form_id, plugin_spec, dry_run=False, form_number=None):
@@ -901,14 +1560,14 @@ def set_report_query_data_source(cfg, token, form_number, data_source_number=Non
         _set_complex(cfg, token, form_number, "ReportQueryDataSource", data),
         "setReportQueryDataSource", form_mutation_possible=True)
 
-    observed = read_report_query_data_source(cfg, token, form_number) or {}
+    observed = _read_after_report_write(read_report_query_data_source, cfg, token, form_number) or {}
     actual_id = str(observed.get("DataSourceId") or "")
     expected_id = "" if clear else resolved["dataSourceId"]
     if actual_id != expected_id:
-        raise RuntimeError(
+        raise ReportMutationError(
             f"REPORT_QUERY_DATA_SOURCE_MISMATCH: {form_number!r} reads back DataSourceId "
             f"{actual_id!r} after a write of {expected_id!r}; the platform reported success, so "
-            "re-read the report before retrying"
+            "re-read the report before retrying", mutation_applied=True
         )
     return {
         "formNumber": form_number,
@@ -953,63 +1612,114 @@ def get_report_schema(cfg, token, form_id):
         "reportPlugins": canonical.get("reportPlugins") or [],
         "readBackAvailable": bool(canonical.get("readBackAvailable")),
         "readBackSource": "canonical" if canonical.get("readBackAvailable") else "unavailable",
-        "unverifiableSections": [],
+        "unverifiableSections": sorted(set(canonical.get("unverifiableSections") or []) | {"reportSorts"} | {
+            name for name in ("reportColumns", "reportFilters", "reportSorts", "reportPlugins")
+            if not isinstance(canonical.get(name), list)}),
     }
 
-    typed = data.get("reportFilterSchema")
-    if isinstance(typed, dict) and typed.get("schemaVersion") == "app-build-typed-report-filters/v1":
-        report_schema["reportFilters"] = typed.get("reportFilters") or []
-        report_schema["typedFiltersReadBack"] = True
-
-    if report_schema["readBackAvailable"]:
-        return report_schema
-
-    if report_schema.get("typedFiltersReadBack"):
-        report_schema["readBackAvailable"] = True
-        report_schema["readBackSource"] = "typedFilters"
-        report_schema["unverifiableSections"] = ["reportColumns", "reportSorts", "reportPlugins"]
-        report_schema["undecidableFilterProperties"] = ["compare", "visible", "defaultValue"]
-
+    # 过滤的新投影独立于 reportSchema；不能因其他分区已可读而提前返回。
     # Derived read-back. The tested deployment exposes no data.reportSchema, but
     # data.formLayout is the same ControlAp tree that setReportColumns / setReportFilters
     # write, so the requested structure is provable from it. Returning empty arrays here used
     # to make every write look unverified; deriving the projection keeps verification real and
     # names exactly which properties the derived source cannot prove.
     layout = data.get("formLayout")
-    if isinstance(layout, dict):
+    if not report_schema["readBackAvailable"] and isinstance(layout, dict):
         report_schema["_raw_formLayout"] = layout
         report_schema["reportColumns"] = _columns_from_layout(layout)
         report_schema["reportFilters"] = _filters_from_layout(layout, data.get("schemaText") or "")
-        if report_schema.get("typedFiltersReadBack"):
-            report_schema["reportFilters"] = typed.get("reportFilters") or []
         report_schema["readBackAvailable"] = True
         report_schema["readBackSource"] = "formLayout"
-        # formLayout carries the control tree only. Default sort lives in the ReportListAp
-        # InitField property and the data-fetch plugin lives in ReportQueryPlugin; neither
-        # is part of the layout payload, so they stay explicitly unverifiable instead of
-        # being reported as passing.
+        # 布局不承载查询插件。InitField 是默认显示列，不是默认排序；排序保持不可验证。
         report_schema["unverifiableSections"] = ["reportSorts", "reportPlugins"]
         report_schema["derivedColumnProperties"] = ["fieldKey", "caption", "kind", "children"]
         report_schema["undecidableColumnProperties"] = [
             "dateIndex", "fieldType", "width", "headerBackColor", "hide", "freeze",
         ]
         report_schema["derivedFilterProperties"] = ["fieldPath", "displayName", "controlType"]
+        # schemaText names the class of every report-entity field, so a filter control backed
+        # by one also proves which editor it renders.
+        if data.get("schemaText"):
+            report_schema["derivedFilterProperties"].append("fieldType")
         # `compare` belongs here rather than being quietly absent: the tested deployment stores
         # `=`, `in` and `between` as the same CommonFilterColumnAp, so neither this projection
         # nor the design-state export can tell them apart. Naming it keeps the drop visible.
         report_schema["undecidableFilterProperties"] = [
             "compare", "mustInput", "visible", "defaultValue",
         ]
-        if report_schema.get("typedFiltersReadBack"):
-            report_schema["undecidableFilterProperties"].remove("mustInput")
 
     schema_text = data.get("schemaText") or ""
-    if schema_text:
+    if schema_text and report_schema["readBackSource"] != "canonical":
         report_schema["_raw_schemaText"] = schema_text
-
+    if "reportFilters" in data:
+        _attach_report_filter_projection(report_schema, data["reportFilters"], layout)
     return report_schema
 
 
+def _attach_report_filter_projection(schema, projection, layout):
+    """消费 bos1030 的真实过滤投影；来源缺失不能回退成旧布局中的肯定证据。"""
+    schema["reportFilterProjection"] = copy.deepcopy(projection)
+    schema.setdefault("readBackSources", {})["reportFilters"] = "reportFilterProjection"
+    unavailable = set(schema.get("unverifiableSections") or []) | {"reportFilters"}
+    schema["unverifiableSections"] = sorted(unavailable)
+    if not isinstance(projection, dict) or projection.get("available") is not True:
+        return
+    rows = projection.get("filters")
+    panel = projection.get("filterPanel")
+    if not isinstance(rows, list) or not all(isinstance(row, dict) for row in rows):
+        return
+    if not isinstance(panel, dict) or panel.get("commFilterPanelFound") is not True:
+        return
+    show = panel.get("showFilterFields")
+    if not isinstance(show, dict) or show.get("format") not in {"json-array", "empty"}:
+        return
+    parsed = show.get("parsed")
+    if (not isinstance(parsed, list) or not all(isinstance(key, str) and key for key in parsed)
+            or len(set(parsed)) != len(parsed)
+            or [row.get("fieldPath") for row in rows] != parsed):
+        return
+    # 新 API 会对坏 JSON 兼容拆分；必须核对原值，不能把兼容输出当正常空配置。
+    try:
+        raw = json.loads(show.get("raw")) if show.get("format") == "json-array" else []
+    except (TypeError, ValueError):
+        return
+    if raw != parsed or (show.get("format") == "empty" and show.get("raw") not in (None, "")):
+        return
+    nodes = list(_iter_layout_items(layout))
+    filters = []
+    for original in rows:
+        row = copy.deepcopy(original)
+        unknown = set(row.get("unknown") or [])
+        # compare 是配置对象，不是公开的比较运算符；完整保留，不猜 compareTypeId。
+        row["compareConfig"] = row.pop("compare", None)
+        for name in ("mustInput", "fieldType"):
+            if name in unknown or row.get(name) is None:
+                row.pop(name, None)
+        if not isinstance(row.get("mustInput"), bool):
+            row.pop("mustInput", None)
+        if "visibleEffective" not in unknown and isinstance(row.get("visibleEffective"), bool):
+            row["visible"] = row["visibleEffective"]
+        reference = row.get("reference")
+        if isinstance(reference, dict) and "reference" not in unknown:
+            if "baseEntityNumber" not in (reference.get("unknown") or []) and reference.get("baseEntityNumber"):
+                row["referenceNumber"] = reference["baseEntityNumber"]
+        # 新投影没有名称；只从同一响应的真实控件身份取名，不用请求值补齐。
+        matches = [node for node in nodes if row.get("controlId")
+                   and node.get("id") == row["controlId"]
+                   and node.get("fieldId") == row.get("fieldId")
+                   and node.get("key") == row.get("fieldPath")]
+        if len(matches) == 1 and isinstance(matches[0].get("name"), str):
+            row["displayName"] = matches[0]["name"]
+        filters.append(row)
+    schema["reportFilters"] = filters
+    schema["readBackAvailable"] = True
+    if schema.get("readBackSource") == "unavailable":
+        schema["readBackSource"] = "reportFilterProjection"
+    schema["unverifiableSections"] = sorted(unavailable - {"reportFilters"})
+    schema["derivedFilterProperties"] = ["fieldPath", "fieldId", "fieldType", "mustInput", "visible", "reference", "rangeKeys"]
+    schema["undecidableFilterProperties"] = ["compare", "defaultValue"]
+
+
 # Filter control types emitted under reportcommfilterpanelap, mapped back to the
 # semantic compare that produced them.
 _FILTER_CONTROL_COMPARE = {
@@ -1062,6 +1772,9 @@ def _filters_from_layout(layout, schema_text=""):
     entities = parse_schema_text(schema_text)
     fields = (entities[0].get("fields") or []) if entities else []
     field_types = {field["fieldKey"]: field["fieldType"] for field in fields if field.get("fieldType")}
+    # schemaText prints the referenced base data after every BasedataField-derived field, which
+    # is what proves an F7 filter points at the base data it was given.
+    references = {field["fieldKey"]: field["refEntity"] for field in fields if field.get("refEntity")}
     result = []
     for child in panel.get("children") or []:
         if not isinstance(child, dict):
@@ -1079,6 +1792,8 @@ def _filters_from_layout(layout, schema_text=""):
         }
         if item["fieldPath"] in field_types:
             item["fieldType"] = field_types[item["fieldPath"]]
+        if item["fieldPath"] in references:
+            item["referenceNumber"] = references[item["fieldPath"]]
         # The layout's own `visible` is a control-phase list ("init,new,edit,...") and is not
         # the filter contract's boolean `visible`. Exposing it under the same key would make a
         # dropped `visible: false` look persisted, so keep the names apart.
@@ -1089,11 +1804,7 @@ def _filters_from_layout(layout, schema_text=""):
 
 
 # ─── Design-state (.dym) evidence ─────────────────────────────────────────────
-# formLayout proves the control tree but carries neither the default sort nor the data-fetch
-# plugin, so on the tested deployment those two sections had no observable read-back at all.
-# syncDym exports the platform's own design-state metadata to the repository, and that
-# export does carry both: <InitField> holds the sort list and <ReportQueryPlugin> holds the
-# registered plugins. Parsing it turns "not carried by this source" into real evidence.
+# syncDym 的 ReportQueryPlugin 补充插件证据；InitField 只承载默认显示列，绝不作为排序证据。
 #
 # Freshness is the caller's responsibility: a .dym on disk only proves the platform state as
 # of the last syncDym. Callers must sync after their writes and before asking for this
@@ -1125,32 +1836,7 @@ def locate_report_dym(app_root, form_number):
     return max(matches, key=lambda path: os.path.getmtime(path))
 
 
-def _dym_sorts(root):
-    """Report default sorts from every <InitField> payload in the export."""
-    sorts = []
-    for node in root.iter("InitField"):
-        raw = (node.text or "").strip()
-        if not raw:
-            continue
-        try:
-            entries = json.loads(raw)
-        except (ValueError, TypeError):
-            continue
-        if not isinstance(entries, list):
-            continue
-        for entry in entries:
-            if not isinstance(entry, dict):
-                continue
-            if str(entry.get("purpose") or "").strip().lower() != "sort":
-                continue
-            field_key = str(entry.get("listname") or entry.get("freezelistkey") or "").strip()
-            if not field_key:
-                continue
-            sorts.append({
-                "fieldKey": field_key,
-                "direction": str(entry.get("direction") or "asc").strip().lower(),
-            })
-    return sorts
+# InitField 是默认显示列配置；purpose=sort 是旧 API 的污染，不能作为排序证据。
 
 
 def _dym_plugins(root):
@@ -1242,7 +1928,7 @@ def _dym_filters(root):
 # failure mode this list exists to prevent: an undecidable property is not evidence that the
 # write failed. Once the fixed platform is deployed, remove "description" here and let the
 # comparison run again — the value becomes real evidence at that point.
-_DYM_SECTIONS = ("reportSorts", "reportPlugins")
+_DYM_SECTIONS = ("reportPlugins",)
 _DYM_UNDECIDABLE_PLUGIN_PROPERTIES = ("type", "bizAppId", "fpk", "description")
 
 
@@ -1260,7 +1946,6 @@ def parse_report_dym(path):
         return {}
     evidence = {
         "path": path,
-        "reportSorts": _dym_sorts(root),
         "reportPlugins": _dym_plugins(root),
         "reportFilters": _dym_filters(root),
     }
@@ -1283,6 +1968,8 @@ def _merge_dym_filter_properties(report_schema, rows):
     is missing evidence, and filling some rows while leaving others bare would make an absent
     node look like a proven default.
     """
+    if "reportFilterProjection" in report_schema:
+        return []  # 导出只能补旧布局的缺口，不能覆盖新投影或将其 unknown 变成默认值。
     observed = [item for item in (report_schema.get("reportFilters") or []) if isinstance(item, dict)]
     if not observed or not rows:
         return []
@@ -1305,15 +1992,12 @@ def _merge_dym_filter_properties(report_schema, rows):
 def attach_dym_evidence(report_schema, evidence):
     """Promote what the .dym export proves onto a report schema that could not observe it.
 
-    Two kinds of promotion: a whole section the derived source does not carry at all
-    (reportSorts, reportPlugins), and individual filter properties the API projection cannot
-    decide (mustInput, visible). Only what the export actually carries is promoted.
+    仅提升 reportPlugins 及过滤属性 mustInput / visible。
+    InitField 的排序污染条目不被解析或提升为排序证据。
 
-    This is confined to the formLayout tier by construction: a canonical projection already
-    proves everything and must not be overwritten by a file that may predate the last write,
-    and an `unavailable` projection lists no sections at all, so promoting into it would flip
-    readBackAvailable to true while columns and filters remained unobserved — turning an
-    unverified write into a passing one.
+    仅补充 formLayout 档的缺失证据，不以可能陈旧的导出覆盖 canonical 数据。
+    canonical 排序投影也不证明排序生效。unavailable 档不能被提升：
+    否则列和过滤仍未观察到，却会把 readBackAvailable 置为 true，造成错误验收。
     """
     if not isinstance(report_schema, dict) or not isinstance(evidence, dict):
         return report_schema
@@ -1364,6 +2048,9 @@ _RECREATE_LOSSES = (
     "the old one has to be re-pointed",
     "anything adjusted by hand in the Cosmic designer on this report",
     "form-level permission configuration attached to the old formId",
+    "plugins registered on the report form itself (plugin type reportform, read back by "
+    "queryEditablePlugins as location BILL_FORM): deleteForm removes them with the form and "
+    "run registers only the data plugins",
 )
 
 
@@ -1406,12 +2093,80 @@ def _menu_bindings(menus, form_number, form_id):
     return found
 
 
-def plan_report_recreate(current_schema, target_artifact=None, menus=None):
+def _report_form_plugins(rows, data_plugins):
+    """This app's plugins on the report form's own plugin list, from queryEditablePlugins rows.
+
+    queryEditablePlugins returns a report's root form plugins as location BILL_FORM, and only
+    the ones this app owns, so template plugins are not listed. Its REPORT_QUERY_PLUGIN rows are
+    the data plugins the artifact carries, which run registers again by itself. A data plugin
+    found on the form list is split out: that slot casts it to a form plugin when the report
+    opens, so re-registering it there would recreate the failure. ``None`` means not read, and so
+    does a read-back that is not a row list.
+    """
+    if not isinstance(rows, list):
+        return None, []
+    plugins, misplaced, seen = [], [], set()
+    for row in rows:
+        if not isinstance(row, dict) or str(row.get("location") or "").strip() != "BILL_FORM":
+            continue
+        class_name = str(row.get("className") or "").strip()
+        if not class_name or class_name in seen:
+            continue
+        seen.add(class_name)
+        if class_name in data_plugins:
+            misplaced.append(class_name)
+            continue
+        plugins.append({
+            "className": class_name,
+            "pluginType": str(row.get("pluginType") or "JAVA").strip().upper(),
+            "enabled": row.get("enabled") is not False,
+        })
+    return plugins, misplaced
+
+
+def _form_plugin_step_detail(plugins, misplaced, form_number):
+    if plugins is None:
+        return (
+            "the report form's own plugin list was not read; before deleting, list it with "
+            f"queryEditablePlugins --formNumber {form_number or '<formNumber>'} (rows with "
+            "location BILL_FORM), because deleteForm removes those plugins and run does not "
+            "register them"
+        )
+    java = [item["className"] for item in plugins if item["pluginType"] == "JAVA"]
+    scripts = [item["className"] for item in plugins if item["pluginType"] != "JAVA"]
+    parts = []
+    if java:
+        parts.append(
+            f"{len(java)} Java plugin(s) on the report form itself: {', '.join(java)}; register "
+            "each again once step 3 has created the form, with targetType BILL_FORM, and check "
+            "that the read-back lists it at location BILL_FORM. A class that is not in "
+            "archive.json is registered with registerPlugin --formNumber instead"
+        )
+    if scripts:
+        parts.append(
+            f"script plugin(s) {', '.join(scripts)}: register_plugins.py registers Java classes "
+            "only, so register them with registerPlugin and targetType BILL_FORM once "
+            "queryAvailableScripts offers the script for the recreated form"
+        )
+    if misplaced:
+        parts.append(
+            f"{', '.join(misplaced)} is the report's data plugin but also sits on the form "
+            "plugin list, where it fails when the report opens; step 3 registers it in the "
+            "data-plugin slot, so do not register it on the form again"
+        )
+    return "; ".join(parts) or (
+        "no plugin of this app is registered on the report form itself, so nothing to "
+        "re-register"
+    )
+
+
+def plan_report_recreate(current_schema, target_artifact=None, menus=None, plugin_rows=None):
     """Plan the only supported way to change a report's column set.
 
     Read-only: it decides nothing and writes nothing. ``current_schema`` is a
     get_report_schema projection, ``target_artifact`` the intended report artifact (optional),
-    and ``menus`` a queryMenuTree menu list (optional).
+    ``menus`` a queryMenuTree menu list (optional) and ``plugin_rows`` the report's
+    queryEditablePlugins rows (optional; ``None`` means they were not read).
     """
     if not isinstance(current_schema, dict):
         raise ValueError("REPORT_INPUT_INVALID: current report schema is required")
@@ -1419,6 +2174,10 @@ def plan_report_recreate(current_schema, target_artifact=None, menus=None):
     form_id = str(current_schema.get("formId") or "").strip()
 
     current_columns = _column_index(current_schema.get("reportColumns") or [])
+    form_plugins, misplaced_plugins = _report_form_plugins(plugin_rows, {
+        str(item.get("className") or "").strip()
+        for item in current_schema.get("reportPlugins") or [] if isinstance(item, dict)
+    })
     plan = {
         "schemaVersion": REPORT_RECREATE_PLAN_VERSION,
         "formNumber": form_number,
@@ -1435,6 +2194,7 @@ def plan_report_recreate(current_schema, target_artifact=None, menus=None):
             "reportFilters": current_schema.get("reportFilters") or [],
             "reportSorts": current_schema.get("reportSorts") or [],
             "reportPlugins": current_schema.get("reportPlugins") or [],
+            "formPlugins": form_plugins,
             "unverifiableSections": current_schema.get("unverifiableSections") or [],
         },
         "lostOnRecreate": list(_RECREATE_LOSSES),
@@ -1501,13 +2261,23 @@ def plan_report_recreate(current_schema, target_artifact=None, menus=None):
             "command": 'run --app-root "<appRoot>" --artifact "<artifactPath>"',
             "detail": (
                 "the artifact keeps the same formNumber and carries the complete intended "
-                "columns, filters, sorts and plugins; the pipeline verifies the result"
+                "columns, filters, sorts and plugins; the pipeline verifies observable metadata, "
+                "while default sorts remain Java query requirements pending runtime verification"
             ),
         },
         {
-            # Last, not first: the recreated form only gets its new formId in step 3, so a
-            # menu cannot be re-pointed before then.
             "order": 4,
+            "action": "re-register the plugins listed in current.formPlugins on the report form",
+            "command": (
+                'register_plugins.py --app-root "<appRoot>" --class-name "<className>" --verify'
+            ),
+            "detail": _form_plugin_step_detail(form_plugins, misplaced_plugins, form_number),
+        },
+        {
+            # Last, not first: the recreated form only gets its new formId in step 3, so a
+            # menu cannot be re-pointed before then, and pointing it at a report whose own
+            # plugins are not back yet would hand users a report that misbehaves.
+            "order": 5,
             "action": "re-point the menu entries listed in menuBindings",
             "detail": (
                 f"{len(plan['menuBindings'])} menu entry(ies) point at this report"
@@ -1645,17 +2415,109 @@ def _iter_leaf_columns(columns):
             yield col
 
 
-def compile_report_plugin_contract(artifact, form_number=""):
+def _filter_value_shape(field_type, filter_key, range_keys=None):
+    """How query() reads one editor's value: accessor call, Java value and evidence level."""
+    method, java_type, evidence = _REPORT_FILTER_VALUE_SHAPES.get(
+        field_type, ("getValue", "Object", "observeOnce"))
+    if range_keys:
+        accessor = (
+            "ReportQueryParam.getFilter().getFilterItems(), matching "
+            f'"{range_keys["start"]}" and "{range_keys["end"]}"')
+    else:
+        accessor = f'ReportQueryParam.getFilter().{method}("{filter_key}")'
+    return {"valueAccessor": accessor, "valueJavaType": java_type, "valueEvidence": evidence}
+
+
+def _filter_range_keys(item, field_type):
+    """The two runtime item keys a range editor submits, or None for a single-value editor."""
+    suffixes = _REPORT_FILTER_RANGE_ITEM_SUFFIXES.get(field_type)
+    if not suffixes:
+        return None
+    key = str(item.get("fieldPath") or "")
+    return {
+        "start": str(item.get("startDateFieldKey") or key + suffixes[0]),
+        "end": str(item.get("endDateFieldKey") or key + suffixes[1]),
+    }
+
+
+def _filter_editor_contract(item, filter_key, editor_row=None):
+    """The editor half of one filterValueContracts entry.
+
+    A typed editor needs the platform's typed report filter patch, and the client can be newer
+    than the platform. So the entry names both the requested editor and the legacy one a
+    platform without the patch renders, each with the accessor that reads it: query() written
+    against both keeps working when the patch is installed later and the filters re-applied.
+    """
+    requested = item.get("fieldType") or None
+    legacy = legacy_filter_editor(item)
+    editor = requested or legacy
+    entry = {"editorFieldType": editor, "editorRequested": bool(requested)}
+    entry.update(_filter_value_shape(editor, filter_key, _filter_range_keys(item, editor)))
+    if requested and requested != legacy:
+        entry["legacyEditor"] = {
+            "fieldType": legacy,
+            **_filter_value_shape(legacy, filter_key, _filter_range_keys(item, legacy)),
+        }
+    for name in ("basedataNumber", "orgFuncs", "asstTypeId", "typeFieldKey"):
+        if item.get(name):
+            entry[name] = item[name]
+    if item.get("comboItems"):
+        entry["comboValues"] = [row["value"] for row in item["comboItems"]]
+    if item.get("itemClassTypes"):
+        entry["itemClassTypes"] = [row["basedataNumber"] for row in item["itemClassTypes"]]
+    if requested in REPORT_FILTER_MULTI_VALUE_TYPES:
+        entry["multiValue"] = True
+    if editor_row:
+        entry["editorStatus"] = editor_row.get("status")
+        rendered = editor_row.get("observedFieldType") or editor_row.get("platformFieldType")
+        if rendered:
+            entry["renderedFieldType"] = rendered
+    return entry
+
+
+def registered_report_plugin_types(artifact):
+    """Every Java class the artifact registers, mapped to the plugin type its slot runs.
+
+    The slot decides the base class. reportPlugins lands on the report list's ReportQueryPlugin,
+    which runs an AbstractReportListDataPlugin; reportProperties.tree.ReportPlugin is the left
+    tree's own data plugin on ReportTreeAp, which runs an AbstractReportTreeDataPlugin. Reading only
+    the first slot left a left-tree report's tree class outside the card gate, so it could reach
+    the cards with no source. A JS or KingScript entry has no Java source to deliver, so listing it
+    would make the gate demand a .java file that can never exist.
+    """
+    types = {}
+    if not isinstance(artifact, dict):
+        return types
+    for plugin in artifact.get("reportPlugins") or []:
+        if not isinstance(plugin, dict):
+            continue
+        if str(plugin.get("type") or "Java").strip().lower() != "java":
+            continue
+        name = str(plugin.get("className") or "").strip()
+        if name:
+            types.setdefault(name, "reportlist")
+    properties = artifact.get("reportProperties")
+    tree = properties.get("tree") if isinstance(properties, dict) else None
+    tree_plugin = str(tree.get("ReportPlugin") or "").strip() if isinstance(tree, dict) else ""
+    if tree_plugin:
+        types.setdefault(tree_plugin, "reporttreelist")
+    return types
+
+
+def compile_report_plugin_contract(artifact, form_number="", filter_editors=None):
     """Compile every requirement the report's plugin must implement.
 
     Returns None when the artifact asks nothing of the plugin beyond returning rows, so an
-    empty contract is never written just to have a file.
+    empty contract is never written just to have a file. ``filter_editors`` is the outcome the
+    filter write produced (build_filter_editor_outcome / resolve_filter_editors); when given, each
+    filter also says which editor this report actually renders.
     """
     if not isinstance(artifact, dict):
         return None
     columns = artifact.get("reportColumns") or []
     filters = artifact.get("reportFilters") or []
-    plugins = artifact.get("reportPlugins") or []
+    plugin_types = registered_report_plugin_types(artifact)
+    default_sorts = compile_report_default_sorts(artifact)
 
     data_set_columns = []
     column_types = []
@@ -1693,6 +2555,19 @@ def compile_report_plugin_contract(artifact, form_number=""):
         bound = str(spec.get(_PRESENTATION_BINDING_KEY.get(spec["kind"], "")) or "").strip()
         if bound:
             entry["bindsTo"] = bound
+            # 原始/历史 Artifact 仍保留需求，但工厂签名和 Long 主键不构成运行证明。
+            entry["precisionSource"] = {
+                "fieldKey": bound,
+                "requiredRuntimeValueType": "DynamicObject",
+                "runtimeVerified": False,
+                "rawIdIsReference": False,
+                "metadataWriteBlocked": True,
+                "requiredEvidence": [
+                    "persisted currency/unit reference property and old scalar field migration",
+                    "batch row reference materialization before NumberFormatProvider",
+                    "mixed precision, grouping, totals, paging and export runtime verification",
+                ],
+            }
             bindings.setdefault(bound, []).append(entry["fieldKey"])
         presentation.append(entry)
 
@@ -1706,6 +2581,10 @@ def compile_report_plugin_contract(artifact, form_number=""):
     enforcement = []
     value_contracts = []
     field_config = (artifact.get("reportProperties") or {}).get("filterFieldConfig") or []
+    editor_rows = {
+        str(row.get("fieldPath") or ""): row
+        for row in ((filter_editors or {}).get("editors") or []) if isinstance(row, dict)
+    }
     for item in filters:
         filter_key = str(item.get("fieldPath") or "")
         binding = next((row for row in field_config if row.get("key") == filter_key), {})
@@ -1717,19 +2596,22 @@ def compile_report_plugin_contract(artifact, form_number=""):
         between = item.get("compare") == "between"
         accessor = ('ReportQueryParam.getFilter().getFilterItems()' if between
                     else f'ReportQueryParam.getFilter().getValue("{filter_key}")')
-        value_contracts.append({
+        range_keys = _filter_range_keys(item, item.get("fieldType") or legacy_filter_editor(item))
+        contract_entry = {
             "filterKey": filter_key,
             "compare": item.get("compare"),
             "candidateValueKeys": candidates,
             "runtimeKeysVerified": False,
             "valueChannel": "getFilterItems" if between else "getValue",
-            "rangeItemKeys": {"start": filter_key + "_startdate", "end": filter_key + "_enddate"} if between else None,
-            "sourceBinding": item.get("source") or {key: binding[key] for key in ("dataSourceId", "fieldName") if binding.get(key)},
+            "rangeItemKeys": range_keys if between else None,
+            "sourceBinding": {key: binding[key] for key in ("dataSourceId", "fieldName") if binding.get(key)},
             "requiredEvidence": ["source field type and editor/reference/enum configuration",
                                  "actual runtime key mapping and comparison semantics",
                                  "query entity, field and value type",
                                  "F7 organization scope and number uniqueness when applicable"],
-        })
+        }
+        contract_entry.update(_filter_editor_contract(item, filter_key, editor_rows.get(filter_key)))
+        value_contracts.append(contract_entry)
         # Every filter carries its comparison here. The platform stores one plain control per
         # key whatever the compare is, so `between` / `in` / `=` exist only as a requirement on
         # query() — without this entry they reached Java delivery as nothing at all.
@@ -1740,8 +2622,8 @@ def compile_report_plugin_contract(artifact, form_number=""):
                 "requirement": _FILTER_UNPERSISTED_COMPARE,
                 "value": item.get(_FILTER_UNPERSISTED_COMPARE),
                 "reason": (
-                    "this deployment stores every comparison as the same filter control, so "
-                    "query() must apply the comparison itself"
+                    "编辑器或 ReportFilterFieldConfig 不证明用户条件已下推；"
+                    "query() 必须在所属数据源落实比较并保留权限条件"
                 ),
                 "java": accessor,
             })
@@ -1766,28 +2648,50 @@ def compile_report_plugin_contract(artifact, form_number=""):
     contract = {
         "schemaVersion": REPORT_PLUGIN_CONTRACT_VERSION,
         "formNumber": str(form_number or ""),
-        "pluginClasses": [
-            str(plugin.get("className") or "") for plugin in plugins
-            if str(plugin.get("className") or "")
-        ],
+        "pluginClasses": list(plugin_types),
+        "pluginTypes": plugin_types,
         "dataSetColumns": data_set_columns,
         "dataSetColumnTypes": column_types,
         "columnPresentation": presentation,
         "filterEnforcement": enforcement,
         "filterValueContracts": value_contracts,
+        "defaultSorts": default_sorts,
+        "defaultSortPolicy": {
+            "implementation": "reportlist.query",
+            "interactiveSortChannel": "ReportQueryParam.getSortInfo()",
+            "priority": "interactiveThenDefault",
+            "applyStage": "afterDataSetAssemblyBeforePagingOrExport",
+            "metadataWritten": False,
+            "runtimeVerified": False,
+        },
         "permissionFilterChannel": "getQFilters",
         "notes": [
+            "defaultSorts is a query() requirement, not persisted metadata. Map interactive sort "
+            "keys through declared fieldKey -> dateIndex bindings and honor that ordering first; "
+            "only when no interactive ordering is present apply defaultSorts in array order. "
+            "Apply ordering after joins, unions and aggregation, before paging/export; preserve "
+            "permission filters. Use target-SDK SortInfo and DataSet ordering APIs, never "
+            "concatenate unvalidated user sort keys into SQL. Contract/source existence is not "
+            "runtime evidence; test default and interactive ordering separately.",
+            "pluginClasses are the Java classes this report registers, and pluginTypes names the "
+            "plugin type each one's slot runs: reportlist for the report list's ReportQueryPlugin "
+            "(AbstractReportListDataPlugin), reporttreelist for the left tree's "
+            "ReportTreeAp.ReportPlugin (AbstractReportTreeDataPlugin). Deliver each class as "
+            "that type; the card gate refuses the cards while any of them has no source.",
             "dataSetColumns are the column names query() must return, case-sensitive, and "
             "dataSetColumnTypes is the Java type each one must carry. Nothing in metadata can "
             "check either. The report sets every value into a metadata field, so a wrong type "
             "fails at set time rather than at read time: read each column with its rowAccessor, "
             "and declare it as its algoDataType when building a DataSet by hand.",
-            "A column with requiredBy is the hidden id another column's presentation binds to "
-            "(bindsTo names it from the other side). It looks droppable and is not: without it "
-            "the formatted columns listed there lose their currency or unit.",
-            "Bind columnPresentation in getColumns() using each java call plus its "
-            "javaFollowUp setters; do not guess ReportColumn.TYPE_* names. Recurse into "
-            "ReportColumnGroup.getChildren(): a grouped column is not in the top-level list.",
+            "requiredBy and bindsTo retain dependencies, not runtime proof. A Long DataSet id "
+            "is not a DynamicObject precision reference. precisionSource marks dynamic bindings "
+            "unverified and blocked for metadata writes; preserve the business requirement until "
+            "reference properties, migration and batch materialization are verified. Neither "
+            "hide nor a factory call upgrades an existing BigInt property.",
+            "columnPresentation java and javaFollowUp describe documented signatures, not a "
+            "complete precision implementation. Do not execute dynamic bindings before satisfying "
+            "precisionSource. For supported presentation, recurse into "
+            "ReportColumnGroup.getChildren(); do not guess ReportColumn.TYPE_* names.",
             "Enforce filterEnforcement using filterValueContracts. candidateValueKeys are "
             "unverified candidates, not a universal prefix rule; confirm actual keys and reject "
             "conflicting values. Date ranges may use separate start/end FilterItemInfo values. "
@@ -1795,8 +2699,18 @@ def compile_report_plugin_contract(artifact, form_number=""):
             "getQFilters carries permissions and never substitutes for extracting user values. "
             "F7 number filters are String comparisons on field.number, while field/id comparisons "
             "require Long; preserve organization and permission scope.",
+            "Each filterValueContracts entry names its editor (editorFieldType) and the "
+            "FilterInfo call that reads it (valueAccessor). A typed editor needs the platform's "
+            "typed report filter patch; a platform without it renders legacyEditor instead, and "
+            "editorStatus says which one this report got when the write reported it. Read the "
+            "value of the editor that rendered; unless editorStatus is typed, accept the "
+            "legacyEditor shape as well, so installing the patch later and re-applying the "
+            "filters does not break query(). valueEvidence observeOnce means no value class has "
+            "been measured for that editor: confirm it with one request-scoped observation.",
         ],
     }
+    if filter_editors:
+        contract["filterEditorSupport"] = filter_editors.get("typedFilterSupport")
     return contract
 
 
@@ -1812,6 +2726,137 @@ def write_report_plugin_contract(app_root, form_number, contract):
     return path
 
 
+def report_authoring_path(app_root, form_number):
+    from pathlib import Path
+    if not re.fullmatch(r"[A-Za-z0-9_]+", str(form_number or "")):
+        raise ValueError("REPORT_INPUT_INVALID: exact formNumber required for local report state")
+    return Path(app_root).resolve() / "_runtime" / f"{form_number}.report-authoring.json"
+
+
+def _report_observation(schema):
+    """仅对比平台实际可观测的结构，不能从回读推造 presentation 或 compare。"""
+    def columns(rows):
+        return [{**{key: row[key] for key in ("kind", "fieldKey", "caption", "dateIndex", "fieldType") if key in row},
+                 **({"children": columns(row.get("children") or [])} if row.get("kind") == "group" else {})}
+                for row in rows]
+    return {"reportColumns": columns(schema.get("reportColumns") or []),
+            "reportFilters": [{key: row[key] for key in ("fieldPath", "displayName", "fieldType", "refId", "referenceNumber") if key in row}
+                              for row in schema.get("reportFilters") or []],
+            **{key: schema[key] for key in ("reportSorts", "reportPlugins", "reportProperties", "queryDataSource") if key in schema}}
+
+
+def write_report_authoring_state(app_root, form_number, form_id, artifact, schema, filter_editors=None):
+    """保存当前需求与独立回读证据；历史 run-result 不被改写成新的运行验证。"""
+    from pathlib import Path
+    import uuid
+    # 拒绝将未验证动态精度刷新为新成功基线；原始契约编译仍可保留全部历史需求。
+    _assert_report_precision_writable(artifact.get("reportColumns") or [])
+    state_path = report_authoring_path(app_root, form_number)
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    artifact_path = state_path.with_name(f"{form_number}.report-artifact.json")
+    # 先失效旧成功状态：中途失败时旧契约不能继续冒充当前。
+    state_path.write_text(json.dumps({"status": "incomplete", "formNumber": form_number,
+        "formId": form_id, "reason": "Local persistence pending; platform mutation must not be replayed"}), encoding="utf-8")
+    compile_report_default_sorts(artifact)
+    contract = (compile_report_plugin_contract(artifact, form_number, filter_editors)
+                if not artifact.get("queryDataSource") or artifact.get("reportPlugins") else None)
+    contract_path = state_path.with_name(f"{form_number}.report-plugin-contract.json")
+    for destination, value in ((artifact_path, artifact),
+            *(((contract_path, contract),) if contract else ()),
+            (state_path, {"status": "current", "formNumber": form_number, "formId": form_id,
+                "artifactPath": str(artifact_path), "artifact": artifact,
+                "observation": _report_observation(schema), "filterEditors": filter_editors,
+                "evidenceScope": "Authoring requirements and observable design state only; runtime unverified"})):
+        temporary = Path(str(destination) + "." + uuid.uuid4().hex + ".tmp")
+        try:
+            temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2), encoding="utf-8")
+            os.replace(temporary, destination)
+        finally:
+            temporary.unlink(missing_ok=True)
+    return {"status": "current", "path": str(state_path), "artifactPath": str(artifact_path),
+            "contractPath": str(contract_path) if contract else "",
+            "runtimeVerified": False}
+
+
+def sync_report_authoring_state(app_root, form_number, form_id, section, expected, before, after, verification, filter_editors=None):
+    """增量写入后刷新契约；缺基线、回读失败或设计器漂移均明确失效而非猜测。"""
+    import copy
+    path = report_authoring_path(app_root, form_number)
+    try:
+        previous = json.loads(path.read_text(encoding="utf-8")) if path.is_file() else {}
+    except (ValueError, UnicodeError):
+        previous = {}
+    reason = ("Unsupported mutation requires full artifact reconciliation" if section not in ("columnsAppend", "columnsRemove", "columns", "filters", "sorts", "plugin") else
+              "Independent read-back did not verify the write" if not verification.get("verified") else
+              "No matching complete authoring baseline; reconcile the full artifact against current getReportSchema"
+              if not isinstance(previous, dict) or previous.get("status") != "current" or previous.get("formId") != form_id or previous.get("formNumber") != form_number else
+              "Observable report state changed outside the authoring baseline; reconcile before coding"
+              if previous.get("observation") != _report_observation(before) else "")
+    if reason:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps({"status": "incomplete", "formNumber": form_number, "formId": form_id,
+            "reason": reason, "platformMutationApplied": True}), encoding="utf-8")
+        return {"status": "incomplete", "path": str(path), "reason": reason, "platformMutationApplied": True}
+    path.write_text(json.dumps({"status": "incomplete", "formNumber": form_number, "formId": form_id,
+        "reason": "Refreshing authoring state after platform mutation", "platformMutationApplied": True}), encoding="utf-8")
+    artifact = copy.deepcopy(previous["artifact"])
+    if section == "columnsAppend":
+        def nodes(rows):
+            return {item["fieldKey"]: item for row in rows for item in [row, *nodes(row.get("children") or []).values()]}
+        old = nodes(artifact.get("reportColumns") or [])
+        requested = nodes(expected["requested"])
+        def rebuild(rows):
+            result = []
+            for row in rows:
+                key = row["fieldKey"]
+                if key not in old and key not in requested:
+                    raise ValueError("REPORT_AUTHORING_STATE_INCOMPLETE: observed an unrequested column")
+                column = copy.deepcopy(old.get(key, requested.get(key)))
+                if column.get("kind") == "group":
+                    column["children"] = rebuild(row.get("children") or [])
+                result.append(column)
+            return result
+        artifact["reportColumns"] = rebuild(after.get("reportColumns") or [])
+    if section == "columnsRemove":
+        artifact["reportColumns"] = _without_report_column(artifact.get("reportColumns") or [], expected["fieldKey"])
+        try:
+            normalize_report_columns_input(artifact["reportColumns"])
+        except ValueError:
+            return invalidate_report_authoring_state(app_root, form_number,
+                "Remaining columns are empty or contain an empty group; reconcile the complete artifact before coding")
+        if "reportSorts" in artifact:
+            artifact["reportSorts"] = [row for row in artifact["reportSorts"] if row.get("fieldKey") != expected["fieldKey"]]
+            if not artifact["reportSorts"]:
+                artifact.pop("reportSorts")
+        properties = (artifact.get("reportProperties") or {}).get("columns")
+        if isinstance(properties, dict):
+            properties.pop(expected["fieldKey"], None)
+            if not properties:
+                artifact["reportProperties"].pop("columns")
+    if section in ("columns", "filters", "sorts"):
+        artifact[{"columns": "reportColumns", "filters": "reportFilters", "sorts": "reportSorts"}[section]] = expected
+    if section == "plugin":
+        # 注册槽位可能替换旧类，不能把回读中不存在的旧类保留在新契约。
+        previous_plugins = {row["className"]: row for row in artifact.get("reportPlugins") or []}
+        artifact["reportPlugins"] = [expected if row.get("className") == expected.get("className") else
+            previous_plugins.get(row.get("className"), row) for row in after.get("reportPlugins") or []]
+    return write_report_authoring_state(app_root, form_number, form_id, artifact, after,
+        filter_editors if section == "filters" else previous.get("filterEditors"))
+
+
+def invalidate_report_authoring_state(app_root, form_number, reason, mutation_applied=True):
+    """未合并或结果未知的写入使旧需求失效；未知不能冒充已成功。"""
+    path = report_authoring_path(app_root, form_number)
+    evidence = ({"platformMutationApplied": True} if mutation_applied is True else
+                {"platformMutationPossible": True})
+    if not path.is_file():
+        return {"status": "incomplete", "reason": "No local authoring baseline", **evidence, "runtimeVerified": False}
+    path.write_text(json.dumps({"status": "incomplete", "formNumber": form_number,
+        "reason": reason, **evidence}), encoding="utf-8")
+    return {"status": "incomplete", "path": str(path), "reason": reason,
+            **evidence, "runtimeVerified": False}
+
+
 def _subset_mismatches(expected, actual, path=""):
     """Compare every requested value while allowing extra read-back properties."""
     mismatches = []
@@ -1880,6 +2925,7 @@ def report_readback_verification(section, expected, schema):
         # Verify the pre-write tree and requested delta separately: comparing either against the
         # complete observed tree would mistake the other part for a mismatch.
         "columnsAppend": "reportColumns",
+        "columnsRemove": "reportColumns",
         "filters": "reportFilters",
         "sorts": "reportSorts",
         "plugin": "reportPlugins",
@@ -1899,13 +2945,19 @@ def report_readback_verification(section, expected, schema):
             }],
         }
 
-    source = schema.get("readBackSource") or "canonical"
+    source = (schema.get("readBackSources") or {}).get(key) or schema.get("readBackSource") or "canonical"
     derived = source != "canonical"
     result = {"section": key, "source": source}
+    if key == "reportFilters" and "reportFilterProjection" in schema:
+        result["projectionDiagnostics"] = schema["reportFilterProjection"]
 
-    if derived and key in (schema.get("unverifiableSections") or []):
-        # The derived source does not carry this section at all. Say so instead of
-        # comparing against an empty array and calling it a pass.
+    if section == "sorts":
+        return {**result, "verified": False, "errorCode": "REPORT_SORTS_API_UNSAFE",
+                "mismatches": [{"path": "/reportSorts", "expected": "runtime ordering evidence",
+                                "actual": "not carried by a verified native sorting contract; InitField is visibility"}]}
+
+    if key in (schema.get("unverifiableSections") or []):
+        # 任一回读来源缺少该分区时，都不能将归一化空数组作为验证通过的证据。
         result["verified"] = False
         result["mismatches"] = [{
             "path": f"/{key}",
@@ -1939,6 +2991,27 @@ def report_readback_verification(section, expected, schema):
         mismatches = _subset_mismatches(wanted, observed, f"/{key}")
         if derived:
             result["unverifiedProperties"] = list(schema.get("undecidableColumnProperties") or [])
+    elif section == "columnsRemove":
+        before = expected["before"]
+        field_key = expected["fieldKey"]
+        # 同级 index 会重排；比较树顺序和其余属性，不将 index 当成稳定身份。
+        def comparable(rows):
+            return [{**{name: value for name, value in row.items() if name not in ("index", "children")},
+                     **({"children": comparable(row["children"])} if row.get("kind") == "group" else {})}
+                    for row in rows]
+        wanted = comparable(_without_report_column(before["reportColumns"], field_key))
+        mismatches = _subset_mismatches(wanted, comparable(observed), "/reportColumns")
+        unverified = ["entityFieldCleanup"]
+        for name in ("reportSorts", "reportFilters", "reportPlugins"):
+            if name in before and name in schema and name not in (before.get("unverifiableSections") or []) and name not in (schema.get("unverifiableSections") or []):
+                values = ([row for row in before[name] if row.get("fieldKey") != field_key]
+                          if name == "reportSorts" else before[name])
+                mismatches.extend(_subset_mismatches(values, schema[name], f"/{name}"))
+            else:
+                unverified.append(name)
+        result["unverifiedProperties"] = sorted(set(unverified + (schema.get("undecidableColumnProperties") or [])))
+        result["entityFieldCleanup"] = {"verified": False,
+            "reason": "Compact report schema does not expose the field-id reference graph; orphan cleanup is backend receipt evidence only"}
     elif section == "columnsAppend":
         before = expected.get("before") or []
         requested = expected.get("requested") or []
@@ -2040,8 +3113,19 @@ def report_readback_verification(section, expected, schema):
     elif section == "filters":
         if derived:
             wanted = _expected_filter_structure(expected)
+            projection = source == "reportFilterProjection"
+            if projection and isinstance(observed, list):
+                # 未输出名称是缺证据，不是空名称；仍按有序注册键和实际控件核对结构。
+                wanted = [{name: value for name, value in item.items()
+                           if name != "displayName" or (index < len(observed) and "displayName" in observed[index])}
+                          for index, item in enumerate(wanted)]
             undecidable = set(schema.get("undecidableFilterProperties") or [])
             mismatches = _subset_mismatches(wanted, observed, f"/{key}")
+            if projection:
+                for index, row in enumerate(observed or []):
+                    if row.get("controlFound") is not True or row.get("duplicateControlCount") != 1:
+                        mismatches.append({"path": f"/{key}/{index}/control",
+                            "expected": "one resolved control", "actual": row})
             observed_by_key = {
                 str(row.get("fieldPath") or ""): row for row in (observed or []) if isinstance(row, dict)
             }
@@ -2053,10 +3137,12 @@ def report_readback_verification(section, expected, schema):
             unpersisted = set()
             for index, item in enumerate(expected):
                 row = observed_by_key.get(str(item.get("fieldPath") or ""), {})
+                if projection and "displayName" not in row:
+                    unverifiable_requested.add("displayName")
                 for name in _FILTER_UNPERSISTED_KEYS:
-                    if not _requests_unpersisted(item, name):
+                    if not (name in item if projection else _requests_unpersisted(item, name)):
                         continue
-                    if name in undecidable or name not in row:
+                    if name in undecidable or name not in row or row[name] is None:
                         unverifiable_requested.add(name)
                         continue
                     if row[name] != item[name]:
@@ -2072,18 +3158,14 @@ def report_readback_verification(section, expected, schema):
                 result["unverifiableRequestedProperties"] = sorted(unverifiable_requested)
             result["unverifiedProperties"] = sorted(undecidable)
         else:
-            mismatches = _subset_mismatches(_build_filters_payload([{k: v for k, v in item.items() if k != "source"} for item in expected]), observed, f"/{key}")
-        # Structure-only receipts cannot prove source-derived editor configuration.
-        by_key = {row.get("fieldPath"): row for row in observed or []}
-        for index, item in enumerate(expected):
-            if not item.get("source"):
-                continue
-            actual = by_key.get(item["fieldPath"], {})
-            wanted = (schema.get("filterSourceExpectations") or {}).get(item["fieldPath"])
-            if (not schema.get("typedFiltersReadBack") or not wanted
-                    or any(actual.get(name) != value for name, value in wanted.items())):
-                mismatches.append({"path": f"/{key}/{index}/source", "expected": item["source"],
-                                   "actual": actual.get("fieldType"), "reason": "typed-editor-source-not-proven"})
+            # The canonical projection is compared as written, minus the editor parameters: they
+            # configure the field the platform builds, and the receipt and fieldType prove it.
+            mismatches = _subset_mismatches([
+                {name: value for name, value in item.items() if name not in _REPORT_FILTER_TYPE_PARAMS}
+                for item in _build_filters_payload(expected)
+            ], observed, f"/{key}")
+        if any(item.get("fieldType") for item in expected):
+            mismatches.extend(_verify_filter_editors(expected, observed, schema, result))
     else:
         mismatches = _subset_mismatches(expected, observed, f"/{key}")
 
@@ -2092,6 +3174,57 @@ def report_readback_verification(section, expected, schema):
     return result
 
 
+def _verify_filter_editors(expected, observed, schema, result):
+    """Hold every typed filter to the editor the platform actually rendered.
+
+    The write's own outcome (attached as filterEditorOutcome) says what the receipt showed; the
+    read-back settles the rest. A degraded editor is not a mismatch — a platform without the
+    typed filter patch renders the legacy control, and that is reported, not failed. An editor
+    that is neither the requested one nor the legacy one is a mismatch.
+    """
+    outcome = schema.get("filterEditorOutcome") or build_filter_editor_outcome(expected)
+    editors, mismatches = resolve_filter_editors(outcome, observed)
+    result["filterEditors"] = editors
+    unverifiable = set(result.get("unverifiableRequestedProperties") or [])
+    if editors.get("unobservedFilters"):
+        unverifiable.add("fieldType")
+    observed_by_key = {
+        str(row.get("fieldPath") or ""): row for row in (observed or []) if isinstance(row, dict)
+    }
+    status_by_key = {row["fieldPath"]: row["status"] for row in editors["editors"]}
+    for index, item in enumerate(expected):
+        number = item.get("basedataNumber")
+        if not number or status_by_key.get(item["fieldPath"]) != "typed":
+            continue
+        # 旧 schemaText 不输出多选引用；新投影通过实际 baseEntityNumber 提供该证据。
+        reference = (observed_by_key.get(item["fieldPath"]) or {}).get("referenceNumber")
+        if not reference:
+            unverifiable.add("basedataNumber")
+        elif str(reference).strip().lower() != number.strip().lower():
+            mismatches.append({
+                "path": f"/reportFilters/{index}/basedataNumber",
+                "expected": number,
+                "actual": reference,
+            })
+    if result.get("source") == "reportFilterProjection":
+        for index, item in enumerate(expected):
+            row = observed_by_key.get(item["fieldPath"], {})
+            if status_by_key.get(item["fieldPath"]) != "typed":
+                continue
+            for name, wanted in (("rangeKeys", _filter_range_keys(item, row.get("fieldType"))),
+                                 ("comboItems", item.get("comboItems"))):
+                if wanted is None:
+                    continue
+                actual = row.get(name)
+                if name in (row.get("unknown") or []) or actual is None:
+                    unverifiable.add(name)
+                    continue
+                mismatches.extend(_subset_mismatches(wanted, actual, f"/reportFilters/{index}/{name}"))
+    if unverifiable:
+        result["unverifiableRequestedProperties"] = sorted(unverifiable)
+    return mismatches
+
+
 def validate_report_references(section, payload, schema):
     """Validate cross-section references that the read-back projection can decide.
 
@@ -2245,8 +3378,13 @@ def _build_filters_payload(filters):
             "displayName": f.get("displayName", ""),
             "compare": _map_compare_operator(f.get("compare", "=")),
         }
-        if f.get("source"):
-            item["source"] = f["source"]
+        # The editor part travels only with a declared fieldType: the patch refuses a type
+        # parameter sent without one, and a platform without the patch ignores both.
+        if f.get("fieldType"):
+            item["fieldType"] = f["fieldType"]
+            for name in _REPORT_FILTER_TYPE_PARAMS:
+                if f.get(name) is not None:
+                    item[name] = f[name]
         # Only forward keys the normalized contract accepts. The previous version also
         # emitted required / enableFuzzy / basedataFilter, which normalize_report_filters_input
         # already rejects — dead branches that could only reintroduce silent drift.
@@ -2257,18 +3395,6 @@ def _build_filters_payload(filters):
     return result
 
 
-def _build_sorts_payload(sorts):
-    """Build report sorts payload for setComplexProperty."""
-    result = []
-    for s in sorts:
-        item = {
-            "fieldKey": s.get("fieldKey", ""),
-            "direction": s.get("direction", "asc"),
-        }
-        result.append(item)
-    return result
-
-
 def _map_compare_operator(compare_str):
     """Map semantic compare operators to platform numeric codes.
 
@@ -2310,10 +3436,11 @@ def _check_result(result, operation_name, form_mutation_possible=False):
     )
 
     def fail(message):
-        raise RuntimeError(f"{operation_name} failed: {message}{suffix}")
+        error = ReportMutationError if form_mutation_possible else RuntimeError
+        raise error(f"{operation_name} failed: {message}{suffix}")
 
     if not isinstance(result, dict):
-        raise RuntimeError(f"{operation_name}: unexpected response type {type(result)}")
+        fail(f"unexpected response type {type(result)}")
     # Check common error patterns; errorCode may be string "0" for success
     _err = result.get("errorCode")
     if _err is not None and str(_err) not in ("", "0"):
@@ -2423,9 +3550,9 @@ _FILTER_PANEL_PROPERTIES = {
     "DirectExportExcel": _prop(_KIND_BOOL, _READ_BACK_GET_PROPERTIES),
     # Input is a list of filter keys. It is serialised to a JSON ARRAY string, which is the
     # form the runtime parses (ReportFilter.getShowFilterFieldList casts it with
-    # JSONUtils.cast(..., ArrayList.class, String.class)). setReportFilters writes the same
-    # property as a COMMA-JOINED string instead, which that cast cannot read — see
-    # _SHOW_FILTER_FIELDS_HAZARD.
+    # JSONUtils.cast(..., ArrayList.class, String.class)). A platform without the typed report
+    # filter patch has setReportFilters write the same property as a COMMA-JOINED string
+    # instead, which that cast cannot read — see _SHOW_FILTER_FIELDS_HAZARD.
     "ShowFilterFields": _prop(_KIND_IDENTIFIER_LIST, _READ_BACK_GET_PROPERTIES),
 }
 
@@ -2535,7 +3662,8 @@ _REPORT_PROPERTY_REFUSED = {
         "Columns are addReportColumns; a column set is not a scalar property."
     ),
     "InitField": (
-        "Default sorting is setReportSorts."
+        "InitField is default column visibility, not sorting. ReportSorts is blocked; "
+        "preserve default sorts in reportContract.defaultSorts for Java query()."
     ),
     "QueryDataSource": (
         "The query data source is setReportQueryDataSource --dataSourceNumber."
@@ -2543,11 +3671,12 @@ _REPORT_PROPERTY_REFUSED = {
 }
 
 _SHOW_FILTER_FIELDS_HAZARD = (
-    "setReportFilters also writes ShowFilterFields, as a comma-joined string "
-    "(observed live: \"flt_biztime,flt_supplier,flt_billstatus\"). The runtime parses that "
-    "property as a JSON array, so the comma form raises KDException when the user updates the "
-    "selected conditions. Re-apply this command after any setReportFilters call until the "
-    "platform's own join is fixed."
+    "On a platform without the typed report filter patch, setReportFilters also writes "
+    "ShowFilterFields, as a comma-joined string (observed live: "
+    "\"flt_biztime,flt_supplier,flt_billstatus\"). The runtime parses that property as a JSON "
+    "array, so the comma form raises KDException when the user updates the selected "
+    "conditions. Re-apply this command after any setReportFilters call on such a platform; a "
+    "patched platform writes the JSON array itself."
 )
 
 _REPORT_PROPERTY_TARGETS = {
@@ -2582,10 +3711,13 @@ _REPORT_PROPERTY_TARGETS = {
     },
     "tree": {
         "complexType": "ReportTree",
-        "elementKey": "reporttreeap",
+        # No public template presets a report tree: a user adds the control in the designer,
+        # under whatever key they give it, so the key is found by element type per call.
+        "elementKey": None,
         "hostType": "ReportTreeAp",
         "properties": _TREE_PROPERTIES,
         "requiresElement": False,
+        "resolveByType": True,
     },
     "column": {
         "complexType": "ReportColumnProps",
@@ -2690,6 +3822,16 @@ def resolve_report_property_target(target, form_number, element_key=None, elemen
         spec["hostType"] = host
         spec["properties"] = _COLUMN_PROPERTIES_BY_HOST[host]
         return spec
+    if spec.get("resolveByType"):
+        # The key is whatever the control was given; set_report_properties finds it by type.
+        if supplied and element_type != spec["hostType"]:
+            _report_property_error(
+                f"--element {supplied!r} is a {element_type or 'unknown'} element; target "
+                f"{name!r} writes a {spec['hostType']}"
+            )
+        spec["elementKey"] = supplied or None
+        spec["target"] = name
+        return spec
     if supplied and supplied != (spec["elementKey"] or form_number):
         _report_property_error(
             f"target {name!r} writes {spec['elementKey'] or 'the form root'} and takes no "
@@ -2739,18 +3881,23 @@ def _closest_property_name(given, allowed):
     return None
 
 
+def _report_controls(cfg, token, form_number):
+    """The form's control rows from its own element list."""
+    result = _api_call(cfg, token, "listElements",
+                       {"formNumber": form_number, "category": "control"}, method="POST")
+    _check_result(result, "listElements")
+    rows = result.get("data") if isinstance(result, dict) else None
+    return [row for row in (rows if isinstance(rows, list) else []) if isinstance(row, dict)]
+
+
 def resolve_report_element_type(cfg, token, form_number, element_key):
     """The element type of one exact key, from the form's own element list.
 
     Raises:
         ValueError: the key is not an element of this form.
     """
-    result = _api_call(cfg, token, "listElements",
-                       {"formNumber": form_number, "category": "control"}, method="POST")
-    _check_result(result, "listElements")
-    rows = result.get("data") if isinstance(result, dict) else None
-    for row in rows if isinstance(rows, list) else []:
-        if isinstance(row, dict) and str(row.get("key") or "") == element_key:
+    for row in _report_controls(cfg, token, form_number):
+        if str(row.get("key") or "") == element_key:
             return str(row.get("type") or "")
     _report_property_error(
         f"--element {element_key!r} is not a control of {form_number!r}; a report column key "
@@ -2758,6 +3905,39 @@ def resolve_report_element_type(cfg, token, form_number, element_key):
     )
 
 
+def resolve_report_element_by_type(cfg, token, form_number, host_type, element_key=None):
+    """The key of the form's one control of `host_type`, or of the named one after checking it.
+
+    A user-added control carries whatever key it was given, so a fixed key would refuse a tree
+    that is there and its read-back would prove nothing.
+
+    Raises:
+        ValueError: REPORT_PROPERTY_ELEMENT_MISMATCH when the form has no such control;
+            REPORT_PROPERTY_INPUT_INVALID when several exist and none is named, or the named
+            key is not one of them.
+    """
+    keys = [str(row.get("key")) for row in _report_controls(cfg, token, form_number)
+            if str(row.get("type") or "") == host_type and row.get("key")]
+    supplied = str(element_key or "").strip()
+    if supplied:
+        if supplied not in keys:
+            _report_property_error(
+                f"--element {supplied!r} is not a {host_type} of {form_number!r}; its "
+                f"{host_type} controls are {keys}"
+            )
+        return supplied
+    if not keys:
+        raise ValueError(
+            f"REPORT_PROPERTY_ELEMENT_MISMATCH: {form_number!r} has no {host_type} control, so "
+            "there is nothing to write to. No public report template presets one; a user adds "
+            "it in the designer first."
+        )
+    if len(keys) > 1:
+        _report_property_error(
+            f"{form_number!r} has several {host_type} controls {keys}; name one with --element")
+    return keys[0]
+
+
 def _read_back_request_name(name):
     """The name to ASK getProperties for, which is not always the name written."""
     return _READ_BACK_KEY_OVERRIDES.get(name, name)
@@ -2791,9 +3971,9 @@ def read_report_element_properties(cfg, token, form_number, element_key, names):
 def _identifier_list_value(value):
     """The key list behind either persisted form of ShowFilterFields, or None.
 
-    The runtime expects a JSON array. setReportFilters writes a comma-joined string instead,
-    so both have to be readable or a verification would fail on a report the platform itself
-    wrote.
+    The runtime expects a JSON array. A platform without the typed report filter patch has
+    setReportFilters write a comma-joined string instead, so both have to be readable or a
+    verification would fail on a report the platform itself wrote.
     """
     if isinstance(value, list):
         return [str(item) for item in value]
@@ -2838,12 +4018,17 @@ def set_report_properties(cfg, token, form_number, target, data,
         _report_property_error("formNumber is required")
 
     element_type = None
-    if _REPORT_PROPERTY_TARGETS.get(str(target or "").strip(), {}).get("requiresElement"):
+    target_spec = _REPORT_PROPERTY_TARGETS.get(str(target or "").strip(), {})
+    if target_spec.get("requiresElement"):
         if not str(element_key or "").strip():
             _report_property_error(
                 "target 'column' needs --element, the exact report column or column group key")
         element_type = resolve_report_element_type(
             cfg, token, form_number, str(element_key).strip())
+    elif target_spec.get("resolveByType"):
+        element_key = resolve_report_element_by_type(
+            cfg, token, form_number, target_spec["hostType"], element_key)
+        element_type = target_spec["hostType"]
     spec = resolve_report_property_target(target, form_number, element_key, element_type)
     payload = normalize_report_properties_input(spec, data)
 
@@ -2873,10 +4058,11 @@ def set_report_properties(cfg, token, form_number, target, data,
 
     _check_result(
         _set_complex(cfg, token, form_number, spec["complexType"], payload,
-                     element_key=spec["elementKey"] if spec["requiresElement"] else None),
+                     element_key=spec["elementKey"]
+                     if spec["requiresElement"] or spec.get("resolveByType") else None),
         f"setReportProperties[{spec.get('target') or 'column'}]", form_mutation_possible=True)
 
-    after = read_report_element_properties(
+    after = _read_after_report_write(read_report_element_properties,
         cfg, token, form_number, spec["elementKey"], readable) if readable else {}
 
     mismatches, indistinguishable, unverifiable = [], [], []
@@ -2901,9 +4087,10 @@ def set_report_properties(cfg, token, form_number, target, data,
             indistinguishable.append(name)
 
     if mismatches:
-        raise RuntimeError(
+        raise ReportMutationError(
             f"REPORT_PROPERTY_MISMATCH: {form_number!r} reads back {mismatches} after a "
-            "write the platform reported as successful; re-read the report before retrying."
+            "write the platform reported as successful; re-read the report before retrying.",
+            mutation_applied=True
         )
 
     result = {
@@ -3034,7 +4221,7 @@ def set_report_filter_field_config(cfg, token, form_number, fields, dry_run=Fals
     _check_result(
         _set_complex(cfg, token, form_number, "ReportFilterFieldConfig", payload),
         "setReportFilterFieldConfig", form_mutation_possible=True)
-    observed = read_report_element_properties(
+    observed = _read_after_report_write(read_report_element_properties,
         cfg, token, form_number, "reportfilterap", ["ReportFilterFieldConfig"])
     stored = observed.get("ReportFilterFieldConfig")
     # This one projects as a native object rather than as a JSON string, unlike
@@ -3045,9 +4232,10 @@ def set_report_filter_field_config(cfg, token, form_number, fields, dry_run=Fals
     actual_keys = [str(row.get("key") or row.get("Key") or "")
                    for row in rows if isinstance(row, dict)]
     if actual_keys and actual_keys != expected_keys:
-        raise RuntimeError(
+        raise ReportMutationError(
             f"REPORT_FILTER_FIELD_CONFIG_MISMATCH: {form_number!r} reads back {actual_keys} "
-            f"after a write of {expected_keys}; re-read the report before retrying."
+            f"after a write of {expected_keys}; re-read the report before retrying.",
+            mutation_applied=True
         )
     return {
         "formNumber": form_number,
@@ -3107,7 +4295,7 @@ def set_report_default_hidden_fields(cfg, token, form_number, fields, dry_run=Fa
     _check_result(
         _set_complex(cfg, token, form_number, "ReportDefaultHiddenFields", payload),
         "setReportDefaultHiddenFields", form_mutation_possible=True)
-    observed = read_report_element_properties(
+    observed = _read_after_report_write(read_report_element_properties,
         cfg, token, form_number, "reportfilterap", ["DefaultHiddenFields"])
     rows = _json_rows(observed.get("DefaultHiddenFields"))
     expected_keys = [entry["fieldKey"] for entry in stored_fields]
@@ -3117,9 +4305,10 @@ def set_report_default_hidden_fields(cfg, token, form_number, fields, dry_run=Fa
     # and both were measured preserving the authored order, so comparing sorted keys would
     # silently accept a reordering the caller did not ask for.
     if actual_keys and actual_keys != expected_keys:
-        raise RuntimeError(
+        raise ReportMutationError(
             f"REPORT_DEFAULT_HIDDEN_FIELDS_MISMATCH: {form_number!r} reads back {actual_keys} "
-            f"after a write of {expected_keys}; re-read the report before retrying."
+            f"after a write of {expected_keys}; re-read the report before retrying.",
+            mutation_applied=True
         )
     result = {
         "formNumber": form_number,
@@ -3200,11 +4389,12 @@ def register_report_plugin_ext(cfg, token, form_number, plugin_spec, dry_run=Fal
         _set_complex(cfg, token, form_number, "ReportPluginExt", payload),
         "registerReportPluginExt", form_mutation_possible=True)
     observed = [_plugin_class_name(item)
-                for item in _report_plugin_ext_entries(cfg, token, form_number)]
+                for item in _read_after_report_write(_report_plugin_ext_entries, cfg, token, form_number)]
     if not any(name.casefold() == class_name.casefold() for name in observed):
-        raise RuntimeError(
+        raise ReportMutationError(
             f"REPORT_PLUGIN_EXT_MISMATCH: {form_number!r} does not read back {class_name!r} "
-            f"after a write the platform reported as successful; it carries {observed}."
+            f"after a write the platform reported as successful; it carries {observed}.",
+            mutation_applied=True
         )
     return {
         "formNumber": form_number,
@@ -3363,7 +4553,8 @@ def attach_report_property_design_state(result, dym_path, host_type, expected):
 # Ordering matters and is fixed by the pipeline, not by this function: the property section is
 # applied LAST, after setReportFilters. That is what makes a single run leave ShowFilterFields
 # in the JSON-array form the runtime parses rather than the comma-joined form the filter write
-# produces.
+# produces on a platform without the typed report filter patch, and what lets a declared
+# FilterMustInput or initial field list outlast the patched filter write, which resets both.
 
 _ARTIFACT_SCALAR_TARGETS = ("list", "filterPanel", "moreFilterPanel", "form", "tree")
 _ARTIFACT_STRUCTURED_KEYS = ("rowBackColor", "filterFieldConfig", "defaultHiddenFields",