@josephyan/qingflow-app-user-mcp 0.2.0-beta.16 → 0.2.0-beta.18

package/src/qingflow_mcp/tools/record_tools.py

@@ -16,10 +16,11 @@ from .base import ToolBase
 
 
 DEFAULT_QUERY_PAGE_SIZE = 50
-DEFAULT_ANALYSIS_PAGE_SIZE = 100
+DEFAULT_LIST_PAGE_SIZE = 200
+DEFAULT_ANALYSIS_PAGE_SIZE = 1000
 DEFAULT_SCAN_MAX_PAGES = 10
-DEFAULT_ANALYSIS_SCAN_MAX_PAGES = 20
-DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP = 50
+DEFAULT_ANALYSIS_SCAN_MAX_PAGES = 100
+DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP = 100
 DEFAULT_ROW_LIMIT = 200
 DEFAULT_OUTPUT_PROFILE = "compact"
 MAX_LIST_COLUMN_LIMIT = 20
@@ -139,36 +140,55 @@ class RecordTools(ToolBase):
 
     def register(self, mcp: FastMCP) -> None:
         @mcp.tool()
-        def record_field_resolve(
+        def record_schema_get(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            query: str | int | None = None,
-            queries: list[str | int] | None = None,
-            top_k: int = 3,
-            fuzzy: bool = True,
+            view_key: str | None = None,
+            view_name: str | None = None,
+            output_profile: str = "normal",
         ) -> JSONObject:
-            return self.record_field_resolve(
+            return self.record_schema_get(
                 profile=profile,
                 app_key=app_key,
-                query=query,
-                queries=queries,
-                top_k=top_k,
-                fuzzy=fuzzy,
+                view_key=view_key,
+                view_name=view_name,
+                output_profile=output_profile,
             )
 
         @mcp.tool(
             description=(
-                "Preflight complex read requests before actual execution. Resolves field selectors, validates required arguments, "
-                "and estimates scan scope. Use this first for grouped analysis, final statistics, or whenever scan completeness matters."
+                "Run schema-first analytics on a Qingflow app using a restricted DSL. "
+                "Use record_schema_get first, then let the model build a DSL with field_id references only. "
+                "dimensions=[] means whole-table summary; dimensions!=[] means grouped analysis. "
+                "This route hides paging and scan-budget controls from callers."
             )
         )
-        def record_query_plan(
+        def record_analyze(
             profile: str = DEFAULT_PROFILE,
-            tool: str = "record_query",
-            arguments: JSONObject | None = None,
-            resolve_fields: bool = True,
+            app_key: str = "",
+            dimensions: list[JSONObject] | None = None,
+            metrics: list[JSONObject] | None = None,
+            filters: list[JSONObject] | None = None,
+            sort: list[JSONObject] | None = None,
+            limit: int = 50,
+            strict_full: bool = True,
+            view_key: str | None = None,
+            view_name: str | None = None,
+            output_profile: str = "normal",
         ) -> JSONObject:
-            return self.record_query_plan(profile=profile, tool=tool, arguments=arguments or {}, resolve_fields=resolve_fields)
+            return self.record_analyze(
+                profile=profile,
+                app_key=app_key,
+                dimensions=dimensions or [],
+                metrics=metrics or [],
+                filters=filters or [],
+                sort=sort or [],
+                limit=limit,
+                strict_full=strict_full,
+                view_key=view_key,
+                view_name=view_name,
+                output_profile=output_profile,
+            )
 
         @mcp.tool(
             description=(
@@ -197,10 +217,9 @@ class RecordTools(ToolBase):
 
         @mcp.tool(
             description=(
-                "Unified read entry for record list / record detail / summary analysis. "
-                "List mode returns flattened wide-table rows only. Use query_mode=auto to route: "
-                "apply_id -> record, amount_column/time_range/stat_policy -> summary, otherwise -> list. "
-                "List mode is for browsing, export, and sample inspection; do not use it alone for final statistical conclusions."
+                "Unified read entry for record list / record detail. "
+                "Use query_mode=auto to route: apply_id -> record, otherwise -> list. "
+                "For statistical analysis use record_schema_get and record_analyze instead of query_mode=summary."
             )
         )
         def record_query(
@@ -209,98 +228,45 @@ class RecordTools(ToolBase):
             app_key: str = "",
             apply_id: int | None = None,
             page_num: int = 1,
-            page_size: int = DEFAULT_QUERY_PAGE_SIZE,
-            requested_pages: int = 1,
-            scan_max_pages: int = DEFAULT_SCAN_MAX_PAGES,
-            auto_expand_pages: bool = False,
             query_key: str | None = None,
             filters: list[JSONObject] | None = None,
             sorts: list[JSONObject] | None = None,
             max_rows: int = DEFAULT_ROW_LIMIT,
             max_columns: int | None = None,
             select_columns: list[str | int] | None = None,
-            amount_column: str | int | None = None,
-            time_range: JSONObject | None = None,
-            stat_policy: JSONObject | None = None,
-            strict_full: bool = False,
             output_profile: str = DEFAULT_OUTPUT_PROFILE,
             list_type: int = DEFAULT_RECORD_LIST_TYPE,
             view_key: str | None = None,
             view_name: str | None = None,
         ) -> JSONObject:
+            resolved_mode = _resolve_query_mode(
+                query_mode,
+                apply_id=apply_id,
+                amount_column=None,
+                time_range={},
+                stat_policy={},
+            )
+            paging = _fixed_analysis_scan_policy() if resolved_mode == "summary" else _fixed_list_scan_policy()
             return self.record_query(
                 profile=profile,
                 query_mode=query_mode,
                 app_key=app_key,
                 apply_id=apply_id,
                 page_num=page_num,
-                page_size=page_size,
-                requested_pages=requested_pages,
-                scan_max_pages=scan_max_pages,
-                auto_expand_pages=auto_expand_pages,
+                page_size=int(paging["page_size"]),
+                requested_pages=int(paging["requested_pages"]),
+                scan_max_pages=int(paging["scan_max_pages"]),
+                auto_expand_pages=bool(paging["auto_expand_pages"]),
                 query_key=query_key,
                 filters=filters or [],
                 sorts=sorts or [],
                 max_rows=max_rows,
                 max_columns=max_columns,
                 select_columns=select_columns or [],
-                amount_column=amount_column,
-                time_range=time_range or {},
-                stat_policy=stat_policy or {},
-                strict_full=strict_full,
-                output_profile=output_profile,
-                list_type=list_type,
-                view_key=view_key,
-                view_name=view_name,
-            )
-
-        @mcp.tool(
-            description=(
-                "Grouped record analysis endpoint. Aggregates record counts and numeric metrics by selected dimensions. "
-                "Use strict_full=true when the result will be used as a final conclusion."
-            )
-        )
-        def record_aggregate(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            group_by: list[str | int] | None = None,
-            amount_column: str | int | None = None,
-            metrics: list[str] | None = None,
-            page_num: int = 1,
-            page_size: int = DEFAULT_ANALYSIS_PAGE_SIZE,
-            requested_pages: int = 1,
-            scan_max_pages: int = DEFAULT_ANALYSIS_SCAN_MAX_PAGES,
-            auto_expand_pages: bool = False,
-            query_key: str | None = None,
-            filters: list[JSONObject] | None = None,
-            sorts: list[JSONObject] | None = None,
-            time_range: JSONObject | None = None,
-            time_bucket: str | None = None,
-            max_groups: int = 200,
-            strict_full: bool = False,
-            output_profile: str = DEFAULT_OUTPUT_PROFILE,
-            list_type: int = DEFAULT_RECORD_LIST_TYPE,
-            view_key: str | None = None,
-            view_name: str | None = None,
-        ) -> JSONObject:
-            return self.record_aggregate(
-                profile=profile,
-                app_key=app_key,
-                group_by=group_by or [],
-                amount_column=amount_column,
-                metrics=metrics or [],
-                page_num=page_num,
-                page_size=page_size,
-                requested_pages=requested_pages,
-                scan_max_pages=scan_max_pages,
-                auto_expand_pages=auto_expand_pages,
-                query_key=query_key,
-                filters=filters or [],
-                sorts=sorts or [],
-                time_range=time_range or {},
-                time_bucket=time_bucket,
-                max_groups=max_groups,
-                strict_full=strict_full,
+                amount_column=None,
+                time_range={},
+                stat_policy={},
+                strict_full=False,
                 output_profile=output_profile,
                 list_type=list_type,
                 view_key=view_key,
@@ -381,6 +347,601 @@ class RecordTools(ToolBase):
         ) -> JSONObject:
             return self.record_delete(profile=profile, app_key=app_key, apply_id=apply_id, list_type=list_type)
 
+    def record_schema_get(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        view_key: str | None,
+        view_name: str | None,
+        output_profile: str,
+    ) -> JSONObject:
+        if not app_key:
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+
+        def runner(session_profile, context):
+            index = self._get_field_index(profile, context, app_key, force_refresh=False)
+            view_selection = self._resolve_view_selection(profile, context, app_key, view_key=view_key, view_name=view_name)
+            fields = [self._schema_field_payload(field) for field in index.by_id.values()]
+            suggested_dimensions = [
+                {"field_id": item["field_id"], "title": item["title"]}
+                for item in fields
+                if bool(cast(JSONObject, item["role_hints"]).get("dimension_candidate"))
+            ]
+            suggested_metrics = [
+                {"field_id": item["field_id"], "title": item["title"]}
+                for item in fields
+                if bool(cast(JSONObject, item["role_hints"]).get("metric_candidate"))
+            ]
+            suggested_time_fields = [
+                {"field_id": item["field_id"], "title": item["title"]}
+                for item in fields
+                if bool(cast(JSONObject, item["role_hints"]).get("time_candidate"))
+            ]
+            response: JSONObject = {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "ok": True,
+                "status": "success",
+                "request_route": self._request_route_payload(context),
+                "data": {
+                    "app_key": app_key,
+                    "view_resolution": _view_selection_payload(view_selection),
+                    "fields": fields,
+                    "suggested_dimensions": suggested_dimensions,
+                    "suggested_metrics": suggested_metrics,
+                    "suggested_time_fields": suggested_time_fields,
+                },
+            }
+            if output_profile == "verbose":
+                response["data"]["field_count"] = len(fields)
+            return response
+
+        return self._run_record_tool(profile, runner)
+
+    def record_analyze(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        dimensions: list[JSONObject],
+        metrics: list[JSONObject],
+        filters: list[JSONObject],
+        sort: list[JSONObject],
+        limit: int,
+        strict_full: bool,
+        view_key: str | None,
+        view_name: str | None,
+        output_profile: str,
+    ) -> JSONObject:
+        if not app_key:
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+        if limit <= 0:
+            raise_tool_error(QingflowApiError.config_error("limit must be positive"))
+
+        def runner(session_profile, context):
+            index = self._get_field_index(profile, context, app_key, force_refresh=False)
+            view_selection = self._resolve_view_selection(profile, context, app_key, view_key=view_key, view_name=view_name)
+            compiled_dimensions = self._compile_analyze_dimensions(index, dimensions)
+            compiled_metrics = self._compile_analyze_metrics(index, metrics)
+            duplicate_aliases = {str(item["alias"]) for item in compiled_dimensions} & {str(item["alias"]) for item in compiled_metrics}
+            if duplicate_aliases:
+                raise RecordInputError(
+                    message=f"dimensions and metrics cannot share aliases: {sorted(duplicate_aliases)}",
+                    error_code="DUPLICATE_ANALYZE_ALIAS",
+                    fix_hint="Use distinct aliases across dimensions and metrics.",
+                )
+            compiled_filters = self._compile_analyze_filters(index, filters)
+            compiled_sort = self._compile_analyze_sort(sort, compiled_dimensions, compiled_metrics)
+            return self._execute_record_analyze(
+                profile=profile,
+                session_profile=session_profile,
+                context=context,
+                app_key=app_key,
+                index=index,
+                view_selection=view_selection,
+                dimensions=compiled_dimensions,
+                metrics=compiled_metrics,
+                filters=compiled_filters,
+                sort=compiled_sort,
+                limit=limit,
+                strict_full=strict_full,
+                output_profile=output_profile,
+            )
+
+        return self._run_record_tool(profile, runner)
+
+    def _schema_field_payload(self, field: FormField) -> JSONObject:
+        return {
+            "field_id": field.que_id,
+            "title": field.que_title,
+            "que_type": field.que_type,
+            "system": field.system,
+            "readonly": field.readonly,
+            "options": field.options,
+            "aliases": field.aliases,
+            "role_hints": self._schema_role_hints(field),
+        }
+
+    def _schema_role_hints(self, field: FormField) -> JSONObject:
+        time_candidate = field.que_type in DATE_QUE_TYPES
+        metric_candidate = bool(field.que_type == 8 and not field.system and not field.readonly)
+        dimension_candidate = bool(
+            field.que_type not in ATTACHMENT_QUE_TYPES | RELATION_QUE_TYPES | SUBTABLE_QUE_TYPES | VERIFY_UNSUPPORTED_WRITE_QUE_TYPES
+            and not field.system
+        )
+        return {
+            "dimension_candidate": dimension_candidate,
+            "metric_candidate": metric_candidate,
+            "time_candidate": time_candidate,
+        }
+
+    def _resolve_field_by_id(self, field_id: int | None, index: FieldIndex, *, location: str) -> FormField:
+        if field_id is None:
+            raise RecordInputError(
+                message=f"{location} requires field_id",
+                error_code="MISSING_FIELD_ID",
+                fix_hint="Use record_schema_get and pass a valid field_id from the schema response.",
+            )
+        field = index.by_id.get(str(field_id))
+        if field is None:
+            raise RecordInputError(
+                message=f"{location} references unknown field_id '{field_id}'",
+                error_code="FIELD_NOT_FOUND",
+                fix_hint="Use record_schema_get to confirm the exact field_id before calling record_analyze.",
+                details={"location": location, "field_id": field_id},
+            )
+        return field
+
+    def _compile_analyze_dimensions(self, index: FieldIndex, dimensions: list[JSONObject]) -> list[JSONObject]:
+        supported_buckets = {None, "day", "week", "month", "quarter", "year"}
+        compiled: list[JSONObject] = []
+        used_aliases: set[str] = set()
+        for idx, item in enumerate(dimensions):
+            if not isinstance(item, dict):
+                raise RecordInputError(
+                    message=f"dimensions[{idx}] must be an object",
+                    error_code="INVALID_ANALYZE_DIMENSION",
+                    fix_hint="Pass dimensions like {'field_id': 2, 'alias': '状态'}",
+                )
+            field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
+            field = self._resolve_field_by_id(field_id, index, location=f"dimensions[{idx}]")
+            bucket = _normalize_optional_text(item.get("bucket"))
+            if bucket not in supported_buckets:
+                raise RecordInputError(
+                    message=f"dimensions[{idx}] uses unsupported bucket '{bucket}'",
+                    error_code="UNSUPPORTED_TIME_BUCKET",
+                    fix_hint="Use one of day/week/month/quarter/year, or omit bucket.",
+                )
+            if bucket is not None and field.que_type not in DATE_QUE_TYPES:
+                raise RecordInputError(
+                    message=f"dimensions[{idx}] bucket requires a date/time field",
+                    error_code="INVALID_TIME_BUCKET_FIELD",
+                    fix_hint="Use bucket only on fields returned in suggested_time_fields by record_schema_get.",
+                    details={"field": _field_ref_payload(field), "bucket": bucket},
+                )
+            alias = _normalize_optional_text(item.get("alias")) or field.que_title
+            if alias in used_aliases:
+                raise RecordInputError(
+                    message=f"dimensions[{idx}] alias '{alias}' is duplicated",
+                    error_code="DUPLICATE_ANALYZE_ALIAS",
+                    fix_hint="Use unique aliases across dimensions and metrics.",
+                )
+            used_aliases.add(alias)
+            compiled.append({"field": field, "alias": alias, "bucket": bucket})
+        return compiled
+
+    def _compile_analyze_metrics(self, index: FieldIndex, metrics: list[JSONObject]) -> list[JSONObject]:
+        requested_metrics = metrics or [{"op": "count", "alias": "记录数"}]
+        supported_ops = {"count", "sum", "avg", "min", "max", "distinct_count"}
+        compiled: list[JSONObject] = []
+        used_aliases: set[str] = set()
+        for idx, item in enumerate(requested_metrics):
+            if not isinstance(item, dict):
+                raise RecordInputError(
+                    message=f"metrics[{idx}] must be an object",
+                    error_code="INVALID_ANALYZE_METRIC",
+                    fix_hint="Pass metrics like {'op': 'count', 'alias': '记录数'}",
+                )
+            op = _normalize_optional_text(item.get("op"))
+            if op not in supported_ops:
+                raise RecordInputError(
+                    message=f"metrics[{idx}] uses unsupported op '{op}'",
+                    error_code="UNSUPPORTED_ANALYZE_METRIC",
+                    fix_hint="Use one of count/sum/avg/min/max/distinct_count.",
+                )
+            field: FormField | None = None
+            if op != "count":
+                field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
+                field = self._resolve_field_by_id(field_id, index, location=f"metrics[{idx}]")
+            alias = _normalize_optional_text(item.get("alias"))
+            if alias is None:
+                if op == "count":
+                    alias = "count"
+                elif field is not None:
+                    alias = f"{field.que_title}_{op}"
+                else:
+                    alias = op
+            if alias in used_aliases:
+                raise RecordInputError(
+                    message=f"metrics[{idx}] alias '{alias}' is duplicated",
+                    error_code="DUPLICATE_ANALYZE_ALIAS",
+                    fix_hint="Use unique aliases across dimensions and metrics.",
+                )
+            used_aliases.add(alias)
+            compiled.append({"op": op, "field": field, "alias": alias})
+        return compiled
+
+    def _compile_analyze_filters(self, index: FieldIndex, filters: list[JSONObject]) -> list[JSONObject]:
+        supported_ops = {"eq", "neq", "in", "not_in", "gt", "gte", "lt", "lte", "between", "contains", "is_null", "not_null"}
+        compiled: list[JSONObject] = []
+        for idx, item in enumerate(filters):
+            if not isinstance(item, dict):
+                raise RecordInputError(
+                    message=f"filters[{idx}] must be an object",
+                    error_code="INVALID_ANALYZE_FILTER",
+                    fix_hint="Pass filters like {'field_id': 2, 'op': 'eq', 'value': '进行中'}.",
+                )
+            field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
+            op = _normalize_optional_text(item.get("op", item.get("operator"))) or "eq"
+            if op not in supported_ops:
+                raise RecordInputError(
+                    message=f"filters[{idx}] uses unsupported op '{op}'",
+                    error_code="UNSUPPORTED_ANALYZE_FILTER_OP",
+                    fix_hint="Use one of eq/neq/in/not_in/gt/gte/lt/lte/between/contains/is_null/not_null.",
+                )
+            field = self._resolve_field_by_id(field_id, index, location=f"filters[{idx}]")
+            compiled.append({"field": field, "field_id": field_id, "op": op, "value": item.get("value", item.get("values"))})
+        return compiled
+
+    def _compile_analyze_sort(self, sort: list[JSONObject], dimensions: list[JSONObject], metrics: list[JSONObject]) -> list[JSONObject]:
+        dimension_aliases = {str(item["alias"]) for item in dimensions}
+        metric_aliases = {str(item["alias"]) for item in metrics}
+        compiled: list[JSONObject] = []
+        for idx, item in enumerate(sort):
+            if not isinstance(item, dict):
+                raise RecordInputError(
+                    message=f"sort[{idx}] must be an object",
+                    error_code="INVALID_ANALYZE_SORT",
+                    fix_hint="Pass sort like {'by': '记录数', 'order': 'desc'}.",
+                )
+            by = _normalize_optional_text(item.get("by"))
+            if by is None:
+                raise RecordInputError(
+                    message=f"sort[{idx}] requires by",
+                    error_code="MISSING_SORT_KEY",
+                    fix_hint="Use a dimension alias or metric alias in sort.by.",
+                )
+            order = (_normalize_optional_text(item.get("order")) or "asc").lower()
+            if order not in {"asc", "desc"}:
+                raise RecordInputError(
+                    message=f"sort[{idx}] uses unsupported order '{order}'",
+                    error_code="INVALID_SORT_ORDER",
+                    fix_hint="Use asc or desc.",
+                )
+            if by in dimension_aliases:
+                compiled.append({"by": by, "order": order, "kind": "dimension"})
+                continue
+            if by in metric_aliases:
+                compiled.append({"by": by, "order": order, "kind": "metric"})
+                continue
+            raise RecordInputError(
+                message=f"sort[{idx}] references unknown alias '{by}'",
+                error_code="UNKNOWN_ANALYZE_SORT_KEY",
+                fix_hint="Use a dimension alias or metric alias defined in the same record_analyze request.",
+            )
+        return compiled
+
+    def _execute_record_analyze(
+        self,
+        *,
+        profile: str,
+        session_profile,
+        context,  # type: ignore[no-untyped-def]
+        app_key: str,
+        index: FieldIndex,
+        view_selection: ViewSelection | None,
+        dimensions: list[JSONObject],
+        metrics: list[JSONObject],
+        filters: list[JSONObject],
+        sort: list[JSONObject],
+        limit: int,
+        strict_full: bool,
+        output_profile: str,
+    ) -> JSONObject:
+        analysis_paging = _fixed_analysis_scan_policy()
+        page_size = int(analysis_paging["page_size"])
+        requested_pages = int(analysis_paging["requested_pages"])
+        scan_max_pages = int(analysis_paging["scan_max_pages"])
+        auto_expand_pages = bool(analysis_paging["auto_expand_pages"])
+        query_id = _query_id()
+        pages_to_scan = min(max(requested_pages, 1), max(scan_max_pages, 1))
+        current_page = 1
+        scanned_pages = 0
+        source_pages: list[int] = []
+        result_amount: int | None = None
+        has_more = False
+        dept_member_cache: dict[int, set[int]] = {}
+        local_filtering = bool(filters) or bool(view_selection is not None and view_selection.conditions)
+        group_stats: dict[str, JSONObject] = {}
+        overall_metrics = self._initialize_metric_states(metrics)
+        matched_rows = 0
+        scan_control: JSONObject = {
+            "requested_pages": max(requested_pages, 1),
+            "scan_max_pages": max(scan_max_pages, 1),
+            "auto_expand_pages": auto_expand_pages,
+            "auto_expand_applied": False,
+            "auto_expand_target_pages": pages_to_scan,
+            "auto_expand_page_cap": DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP,
+        }
+
+        while scanned_pages < pages_to_scan:
+            page = self._search_page(
+                context,
+                app_key=app_key,
+                page_num=current_page,
+                page_size=page_size,
+                query_key=None,
+                match_rules=[],
+                sorts=[],
+                search_que_ids=None,
+                list_type=DEFAULT_RECORD_LIST_TYPE,
+            )
+            scanned_pages += 1
+            source_pages.append(current_page)
+            items = page.get("list") if isinstance(page.get("list"), list) else []
+            if result_amount is None:
+                result_amount = _effective_total(page, page_size)
+                pages_to_scan, scan_control = _compute_scan_limit(
+                    requested_pages=requested_pages,
+                    scan_max_pages=scan_max_pages,
+                    auto_expand_pages=auto_expand_pages,
+                    page=page,
+                    page_size=page_size,
+                )
+            has_more = _page_has_more(page, current_page, page_size, len(items))
+            for item in items:
+                if not isinstance(item, dict):
+                    continue
+                answers = item.get("answers")
+                answer_list = answers if isinstance(answers, list) else []
+                if not self._matches_view_selection(
+                    context,
+                    answer_list,
+                    view_selection=view_selection,
+                    dept_member_cache=dept_member_cache,
+                ):
+                    continue
+                if not self._matches_analyze_filters(answer_list, filters):
+                    continue
+                matched_rows += 1
+                group_payload = self._build_analyze_group_payload(answer_list, dimensions)
+                group_key = json.dumps(group_payload, ensure_ascii=False, sort_keys=True)
+                bucket = group_stats.get(group_key)
+                if bucket is None:
+                    bucket = {
+                        "dimensions": group_payload,
+                        "metrics_state": self._initialize_metric_states(metrics),
+                    }
+                    group_stats[group_key] = bucket
+                bucket_metrics = cast(dict[str, JSONObject], bucket["metrics_state"])
+                self._apply_metric_states(bucket_metrics, metrics, answer_list)
+                self._apply_metric_states(overall_metrics, metrics, answer_list)
+            if not has_more:
+                break
+            current_page += 1
+
+        all_rows = [
+            {
+                "dimensions": cast(JSONObject, bucket["dimensions"]),
+                "metrics": self._render_metric_values(cast(dict[str, JSONObject], bucket["metrics_state"]), metrics),
+            }
+            for bucket in group_stats.values()
+        ]
+        all_rows = self._sort_analyze_rows(all_rows, sort, dimensions, metrics)
+        rows_truncated = len(all_rows) > limit
+        limited_rows = all_rows[:limit]
+        raw_scan_complete = not has_more
+        completeness_status = "complete" if raw_scan_complete else "incomplete"
+        reason_code = "LOCAL_VIEW_FILTERING" if local_filtering and raw_scan_complete else ("SOURCE_EXHAUSTED" if raw_scan_complete else "SCAN_LIMIT_HIT")
+        totals_backend_count = None if local_filtering else result_amount
+        totals = {
+            "backend_total_count": totals_backend_count,
+            "scanned_count": matched_rows,
+            "group_count": len(all_rows) if dimensions else 1,
+            "metric_totals": self._render_metric_values(overall_metrics, metrics),
+        }
+        data: JSONObject = {
+            "query": {
+                "app_key": app_key,
+                "dimensions": [
+                    {
+                        "field_id": cast(FormField, item["field"]).que_id,
+                        "title": cast(FormField, item["field"]).que_title,
+                        "alias": item["alias"],
+                        "bucket": item["bucket"],
+                    }
+                    for item in dimensions
+                ],
+                "metrics": [
+                    {
+                        "op": item["op"],
+                        "field_id": cast(FormField | None, item["field"]).que_id if item["field"] is not None else None,
+                        "title": cast(FormField | None, item["field"]).que_title if item["field"] is not None else None,
+                        "alias": item["alias"],
+                    }
+                    for item in metrics
+                ],
+                "filters": [
+                    {
+                        "field_id": cast(FormField, item["field"]).que_id,
+                        "title": cast(FormField, item["field"]).que_title,
+                        "op": item["op"],
+                        "value": item.get("value"),
+                    }
+                    for item in filters
+                ],
+                "sort": [{"by": item["by"], "order": item["order"]} for item in sort],
+                "view": _view_selection_payload(view_selection),
+            },
+            "rows": limited_rows if dimensions else [{"dimensions": {}, "metrics": totals["metric_totals"]}],
+            "totals": totals,
+            "completeness": {
+                "status": completeness_status,
+                "reason_code": reason_code,
+                "safe_for_final_conclusion": completeness_status == "complete",
+            },
+            "presentation": {
+                "row_limit": limit,
+                "rows_returned": 1 if not dimensions else len(limited_rows),
+                "rows_truncated": rows_truncated if dimensions else False,
+            },
+            "warnings": self._build_analyze_warnings(local_filtering=local_filtering, rows_truncated=rows_truncated),
+        }
+        response: JSONObject = {
+            "profile": profile,
+            "ws_id": session_profile.selected_ws_id,
+            "ok": True,
+            "status": "success" if raw_scan_complete else "partial",
+            "query_id": query_id,
+            "request_route": self._request_route_payload(context),
+            "data": data,
+        }
+        if strict_full and not raw_scan_complete:
+            response["ok"] = False
+            response["status"] = "error"
+            response["error"] = {
+                "code": "INCOMPLETE_SCAN",
+                "message": "record_analyze could not complete the scan within the fixed internal analysis budget.",
+                "fix_hint": "Narrow the scope with view/filter constraints, or retry after reducing the dataset size.",
+            }
+        if output_profile == "verbose":
+            response["data"]["debug"] = {
+                "source_pages": source_pages,
+                "raw_scan_complete": raw_scan_complete,
+                "scan_control": scan_control,
+            }
+        return response
+
+    def _build_analyze_group_payload(self, answer_list: list[JSONValue], dimensions: list[JSONObject]) -> JSONObject:
+        if not dimensions:
+            return {}
+        payload: JSONObject = {}
+        for item in dimensions:
+            field = cast(FormField, item["field"])
+            alias = cast(str, item["alias"])
+            bucket = cast(str | None, item["bucket"])
+            value = _extract_field_value(answer_list, field)
+            if bucket is not None:
+                value = _to_time_bucket(value, bucket)
+            payload[alias] = value
+        return payload
+
+    def _initialize_metric_states(self, metrics: list[JSONObject]) -> dict[str, JSONObject]:
+        states: dict[str, JSONObject] = {}
+        for item in metrics:
+            states[str(item["alias"])] = {
+                "count": 0,
+                "sum": 0.0,
+                "min": None,
+                "max": None,
+                "seen": set(),
+            }
+        return states
+
+    def _apply_metric_states(self, states: dict[str, JSONObject], metrics: list[JSONObject], answer_list: list[JSONValue]) -> None:
+        for item in metrics:
+            alias = cast(str, item["alias"])
+            op = cast(str, item["op"])
+            field = cast(FormField | None, item["field"])
+            state = states[alias]
+            if op == "count":
+                state["count"] = int(state["count"]) + 1
+                continue
+            value = _extract_field_value(answer_list, field)
+            if op == "distinct_count":
+                for entry in _flatten_distinct_values(value):
+                    cast(set[str], state["seen"]).add(entry)
+                continue
+            amount = _coerce_amount(value)
+            if amount is None:
+                continue
+            state["count"] = int(state["count"]) + 1
+            state["sum"] = float(state["sum"]) + amount
+            state["min"] = amount if state["min"] is None else min(float(state["min"]), amount)
+            state["max"] = amount if state["max"] is None else max(float(state["max"]), amount)
+
+    def _render_metric_values(self, states: dict[str, JSONObject], metrics: list[JSONObject]) -> JSONObject:
+        rendered: JSONObject = {}
+        for item in metrics:
+            alias = cast(str, item["alias"])
+            op = cast(str, item["op"])
+            state = states[alias]
+            count = int(state["count"] or 0)
+            amount_sum = float(state["sum"] or 0.0)
+            if op == "count":
+                rendered[alias] = count
+            elif op == "sum":
+                rendered[alias] = amount_sum
+            elif op == "avg":
+                rendered[alias] = (amount_sum / count) if count else None
+            elif op == "min":
+                rendered[alias] = state["min"]
+            elif op == "max":
+                rendered[alias] = state["max"]
+            elif op == "distinct_count":
+                rendered[alias] = len(cast(set[str], state["seen"]))
+        return rendered
+
+    def _matches_analyze_filters(self, answer_list: list[JSONValue], filters: list[JSONObject]) -> bool:
+        for item in filters:
+            field = cast(FormField, item["field"])
+            if not _match_analyze_filter(_extract_field_value(answer_list, field), cast(str, item["op"]), item.get("value")):
+                return False
+        return True
+
+    def _sort_analyze_rows(
+        self,
+        rows: list[JSONObject],
+        sort: list[JSONObject],
+        dimensions: list[JSONObject],
+        metrics: list[JSONObject],
+    ) -> list[JSONObject]:
+        if not rows or not sort:
+            if dimensions and any(item.get("bucket") for item in dimensions):
+                return sorted(rows, key=lambda item: json.dumps(item.get("dimensions", {}), ensure_ascii=False, sort_keys=True))
+            return rows
+        sorted_rows = list(rows)
+        for sort_item in reversed(sort):
+            by = cast(str, sort_item["by"])
+            reverse = cast(str, sort_item["order"]) == "desc"
+            kind = cast(str, sort_item["kind"])
+            sorted_rows.sort(
+                key=lambda item: _sortable_value(
+                    cast(JSONObject, item["metrics" if kind == "metric" else "dimensions"]).get(by)
+                ),
+                reverse=reverse,
+            )
+        return sorted_rows
+
+    def _build_analyze_warnings(self, *, local_filtering: bool, rows_truncated: bool) -> list[JSONObject]:
+        warnings: list[JSONObject] = []
+        if local_filtering:
+            warnings.append(
+                {
+                    "code": "LOCAL_FILTERING_APPLIED",
+                    "message": "Current analysis applies local filtering after scanning source pages.",
+                }
+            )
+        if rows_truncated:
+            warnings.append(
+                {
+                    "code": "ROWS_TRUNCATED",
+                    "message": "Result rows were truncated by limit; totals remain based on the full analyzed result set.",
+                }
+            )
+        return warnings
+
     def record_field_resolve(
         self,
         *,
@@ -597,7 +1158,7 @@ class RecordTools(ToolBase):
                 blockers.append("payload writes readonly or system-managed fields")
             if question_relations:
                 validation["warnings"].append("form contains questionRelations; linked visibility and runtime required rules may differ at submit time.")
-            actions = ["Use record_field_resolve when field titles are ambiguous."]
+            actions = ["Use record_schema_get when field titles or field ids are ambiguous."]
             if support_matrix["restricted"]:
                 actions.append("Review write_format.required_presteps for restricted fields before submit.")
             if invalid_fields:
@@ -662,6 +1223,23 @@ class RecordTools(ToolBase):
         view_name: str | None = None,
     ) -> JSONObject:
         resolved_mode = _resolve_query_mode(query_mode, apply_id=apply_id, amount_column=amount_column, time_range=time_range, stat_policy=stat_policy)
+        if resolved_mode == "summary":
+            raise_tool_error(
+                QingflowApiError(
+                    category="config",
+                    message="record_query(query_mode='summary') is no longer supported",
+                    details={
+                        "error_code": "ANALYSIS_MOVED",
+                        "fix_hint": "Use record_schema_get to fetch field metadata, then call record_analyze with field_id-based DSL.",
+                    },
+                )
+            )
+        if resolved_mode == "list":
+            list_paging = _fixed_list_scan_policy()
+            page_size = int(list_paging["page_size"])
+            requested_pages = int(list_paging["requested_pages"])
+            scan_max_pages = int(list_paging["scan_max_pages"])
+            auto_expand_pages = bool(list_paging["auto_expand_pages"])
         if resolved_mode == "record":
             return self._record_query_record(
                 profile=profile,
@@ -672,30 +1250,6 @@ class RecordTools(ToolBase):
                 output_profile=output_profile,
                 list_type=list_type,
             )
-        if resolved_mode == "summary":
-            return self._record_query_summary(
-                profile=profile,
-                app_key=app_key,
-                page_num=page_num,
-                page_size=page_size,
-                requested_pages=requested_pages,
-                scan_max_pages=scan_max_pages,
-                auto_expand_pages=auto_expand_pages,
-                query_key=query_key,
-                filters=filters,
-                sorts=sorts,
-                max_rows=max_rows,
-                max_columns=max_columns,
-                select_columns=select_columns,
-                amount_column=amount_column,
-                time_range=time_range,
-                stat_policy=stat_policy,
-                strict_full=strict_full,
-                output_profile=output_profile,
-                list_type=list_type,
-                view_key=view_key,
-                view_name=view_name,
-            )
         return self._record_query_list(
             profile=profile,
             app_key=app_key,
@@ -745,6 +1299,11 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if max_groups <= 0:
             raise_tool_error(QingflowApiError.config_error("max_groups must be positive"))
+        analysis_paging = _fixed_analysis_scan_policy()
+        page_size = int(analysis_paging["page_size"])
+        requested_pages = int(analysis_paging["requested_pages"])
+        scan_max_pages = int(analysis_paging["scan_max_pages"])
+        auto_expand_pages = bool(analysis_paging["auto_expand_pages"])
 
         def runner(session_profile, context):
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
@@ -933,10 +1492,6 @@ class RecordTools(ToolBase):
                         "app_key": app_key,
                         "group_by": [field.que_title for field in group_fields],
                         "page_num": max(page_num, 1),
-                        "page_size": page_size,
-                        "requested_pages": max(requested_pages, 1),
-                        "scan_max_pages": max(scan_max_pages, 1),
-                        "auto_expand_pages": auto_expand_pages,
                         "query_key": query_key,
                         "filters": filters,
                         "sorts": sorts,
@@ -1721,10 +2276,6 @@ class RecordTools(ToolBase):
                         "query_mode": "summary",
                         "app_key": app_key,
                         "page_num": max(page_num, 1),
-                        "page_size": page_size,
-                        "requested_pages": max(requested_pages, 1),
-                        "scan_max_pages": max(scan_max_pages, 1),
-                        "auto_expand_pages": auto_expand_pages,
                         "query_key": query_key,
                         "filters": filters,
                         "sorts": sorts,
@@ -1934,7 +2485,15 @@ class RecordTools(ToolBase):
         arguments: JSONObject,
         view_selection: ViewSelection | None,
     ) -> JSONObject:
-        page_size = max(_coerce_count(arguments.get("page_size")) or DEFAULT_QUERY_PAGE_SIZE, 1)
+        routed_mode = _resolve_query_mode(
+            str(arguments.get("query_mode", "auto")),
+            apply_id=_coerce_count(arguments.get("apply_id")),
+            amount_column=arguments.get("amount_column"),
+            time_range=cast(JSONObject, arguments.get("time_range") if isinstance(arguments.get("time_range"), dict) else {}),
+            stat_policy=cast(JSONObject, arguments.get("stat_policy") if isinstance(arguments.get("stat_policy"), dict) else {}),
+        )
+        fixed_policy = _fixed_analysis_scan_policy() if routed_mode == "summary" else _fixed_list_scan_policy()
+        page_size = int(fixed_policy["page_size"])
         query_key = _normalize_optional_text(arguments.get("query_key"))
         filters = _as_object_list(arguments.get("filters"))
         sorts = _as_object_list(arguments.get("sorts"))
@@ -1960,10 +2519,7 @@ class RecordTools(ToolBase):
         estimated_full_scan_pages = page_amount
         if estimated_full_scan_pages is None and backend_total_count > 0:
             estimated_full_scan_pages = (backend_total_count + page_size - 1) // page_size
-        current_budget = min(
-            max(_coerce_count(arguments.get("requested_pages")) or 1, 1),
-            max(_coerce_count(arguments.get("scan_max_pages")) or 1, 1),
-        )
+        current_budget = min(int(fixed_policy["requested_pages"]), int(fixed_policy["scan_max_pages"]))
         return {
             "page_size": page_size,
             "backend_total_count": backend_total_count,
@@ -2374,7 +2930,7 @@ class RecordTools(ToolBase):
             raise RecordInputError(
                 message=f"{location} references unknown queId '{requested}'",
                 error_code="FIELD_NOT_FOUND",
-                fix_hint="Use record_field_resolve to confirm the exact field id.",
+                fix_hint="Use record_schema_get to confirm the exact field_id.",
                 details={"location": location, "requested": requested, "requested_key": requested_key},
             )
         matches = index.by_title.get(requested_key, [])
@@ -2384,7 +2940,7 @@ class RecordTools(ToolBase):
             raise RecordInputError(
                 message=f"{location} field '{requested}' is ambiguous",
                 error_code="AMBIGUOUS_FIELD",
-                fix_hint="Use numeric queId, or resolve the field first with record_field_resolve.",
+                fix_hint="Use numeric queId, or inspect record_schema_get output to disambiguate the field.",
                 details={
                     "location": location,
                     "requested": requested,
@@ -2400,7 +2956,7 @@ class RecordTools(ToolBase):
             raise RecordInputError(
                 message=f"{location} field '{requested}' is ambiguous",
                 error_code="AMBIGUOUS_FIELD",
-                fix_hint="Use a more specific field title, or run record_field_resolve to inspect the alias candidates.",
+                fix_hint="Use a more specific field title, or inspect record_schema_get aliases to disambiguate the field.",
                 details={
                     "location": location,
                     "requested": requested,
@@ -2412,7 +2968,7 @@ class RecordTools(ToolBase):
         raise RecordInputError(
             message=f"{location} cannot resolve field '{requested}'",
             error_code="FIELD_NOT_FOUND",
-            fix_hint="Use record_field_resolve to confirm the exact field title.",
+            fix_hint="Use record_schema_get to confirm the exact field title or field_id.",
             details={
                 "location": location,
                 "requested": requested,
@@ -3194,11 +3750,34 @@ def _normalize_plan_arguments(tool: str, arguments: JSONObject) -> JSONObject:
     for alias, canonical in alias_map.items():
         if alias in result and canonical not in result:
             result[canonical] = result[alias]
+    if tool in {"record_query", "record_aggregate"}:
+        for key in ("page_size", "requested_pages", "scan_max_pages", "auto_expand_pages"):
+            result.pop(key, None)
     if tool == "record_get" and "query_mode" not in result:
         result["query_mode"] = "record"
     return result
 
 
+def _fixed_list_scan_policy() -> JSONObject:
+    return {
+        "page_size": DEFAULT_LIST_PAGE_SIZE,
+        "requested_pages": 1,
+        "scan_max_pages": 1,
+        "auto_expand_pages": False,
+        "public_inputs_exposed": False,
+    }
+
+
+def _fixed_analysis_scan_policy() -> JSONObject:
+    return {
+        "page_size": DEFAULT_ANALYSIS_PAGE_SIZE,
+        "requested_pages": DEFAULT_ANALYSIS_SCAN_MAX_PAGES,
+        "scan_max_pages": DEFAULT_ANALYSIS_SCAN_MAX_PAGES,
+        "auto_expand_pages": True,
+        "public_inputs_exposed": False,
+    }
+
+
 def _collect_plan_field_candidates(tool: str, arguments: JSONObject) -> list[JSONObject]:
     candidates: list[JSONObject] = []
     if tool in {"record_query", "record_get"}:
@@ -3231,15 +3810,10 @@ def _collect_plan_field_candidates(tool: str, arguments: JSONObject) -> list[JSO
 
 
 def _build_plan_estimate(tool: str, arguments: JSONObject, *, probe: JSONObject | None = None) -> JSONObject:
-    page_size = _coerce_count(arguments.get("page_size")) or DEFAULT_QUERY_PAGE_SIZE
-    requested_pages = _coerce_count(arguments.get("requested_pages")) or 1
-    scan_max_pages = _coerce_count(arguments.get("scan_max_pages")) or requested_pages
-    estimated_scan_pages = min(requested_pages, scan_max_pages)
-    may_hit_limits = estimated_scan_pages > DEFAULT_SCAN_MAX_PAGES
-    reasons = []
-    if may_hit_limits:
-        reasons.append("requested scan pages exceed the default analysis budget")
-    if tool == "record_query":
+    if tool == "record_aggregate":
+        fixed_policy = _fixed_analysis_scan_policy()
+        routed_mode = "summary"
+    elif tool == "record_query":
         routed_mode = _resolve_query_mode(
             str(arguments.get("query_mode", "auto")),
             apply_id=_coerce_count(arguments.get("apply_id")),
@@ -3247,8 +3821,18 @@ def _build_plan_estimate(tool: str, arguments: JSONObject, *, probe: JSONObject
             time_range=cast(JSONObject, arguments.get("time_range") if isinstance(arguments.get("time_range"), dict) else {}),
             stat_policy=cast(JSONObject, arguments.get("stat_policy") if isinstance(arguments.get("stat_policy"), dict) else {}),
         )
-        if routed_mode == "list":
-            reasons.append("list mode is not a safe final-analysis endpoint")
+        fixed_policy = _fixed_analysis_scan_policy() if routed_mode == "summary" else _fixed_list_scan_policy()
+    else:
+        routed_mode = "summary"
+        fixed_policy = _fixed_list_scan_policy()
+    page_size = int(fixed_policy["page_size"])
+    requested_pages = int(fixed_policy["requested_pages"])
+    scan_max_pages = int(fixed_policy["scan_max_pages"])
+    estimated_scan_pages = min(requested_pages, scan_max_pages)
+    may_hit_limits = False
+    reasons = []
+    if tool == "record_query" and routed_mode == "list":
+        reasons.append("list mode is not a safe final-analysis endpoint")
     recommended_arguments = _recommended_analysis_arguments(
         tool=tool,
         arguments=arguments,
@@ -3259,7 +3843,7 @@ def _build_plan_estimate(tool: str, arguments: JSONObject, *, probe: JSONObject
         estimated_scan_pages = max(estimated_scan_pages, min(int(probe["estimated_full_scan_pages"]), _coerce_count(recommended_arguments.get("scan_max_pages")) or estimated_scan_pages))
         if bool(probe.get("would_exceed_current_budget")):
             may_hit_limits = True
-            reasons.append("matching rows appear to exceed the current scan budget")
+            reasons.append("matching rows appear to exceed the fixed internal analysis scan budget")
     return {
         "page_size": page_size,
         "requested_pages": requested_pages,
@@ -3270,6 +3854,7 @@ def _build_plan_estimate(tool: str, arguments: JSONObject, *, probe: JSONObject
         "reasons": reasons,
         "probe": probe,
         "recommended_arguments": recommended_arguments,
+        "fixed_scan_policy": fixed_policy,
     }
 
 
@@ -3280,37 +3865,37 @@ def _recommended_analysis_arguments(
     probe: JSONObject | None,
     routed_mode: str,
 ) -> JSONObject:
-    base_page_size = _coerce_count(arguments.get("page_size")) or DEFAULT_QUERY_PAGE_SIZE
-    base_requested_pages = _coerce_count(arguments.get("requested_pages")) or 1
-    base_scan_max_pages = _coerce_count(arguments.get("scan_max_pages")) or base_requested_pages
-    if tool == "record_aggregate" or routed_mode == "summary":
-        recommended_page_size = max(base_page_size, DEFAULT_ANALYSIS_PAGE_SIZE)
-        recommended_scan_max_pages = max(base_scan_max_pages, DEFAULT_ANALYSIS_SCAN_MAX_PAGES)
-    else:
-        recommended_page_size = base_page_size
-        recommended_scan_max_pages = base_scan_max_pages
+    fixed_policy = _fixed_analysis_scan_policy() if tool == "record_aggregate" or routed_mode == "summary" else _fixed_list_scan_policy()
+    recommended_page_size = int(fixed_policy["page_size"])
+    recommended_scan_max_pages = int(fixed_policy["scan_max_pages"])
     backend_total_count = _coerce_count(probe.get("backend_total_count") if isinstance(probe, dict) else None)
     if backend_total_count is not None and backend_total_count > 0:
         estimated_full_scan_pages = (backend_total_count + recommended_page_size - 1) // recommended_page_size
-        recommended_requested_pages = max(base_requested_pages, estimated_full_scan_pages)
-        recommended_scan_max_pages = max(recommended_scan_max_pages, estimated_full_scan_pages)
+        recommended_requested_pages = min(max(estimated_full_scan_pages, 1), recommended_scan_max_pages)
     else:
-        recommended_requested_pages = base_requested_pages
+        recommended_requested_pages = int(fixed_policy["requested_pages"])
         estimated_full_scan_pages = None
     return {
-        "page_size": recommended_page_size,
-        "requested_pages": recommended_requested_pages,
-        "scan_max_pages": recommended_scan_max_pages,
         "strict_full": True,
-        "auto_expand_pages": True,
         "estimated_full_scan_pages": estimated_full_scan_pages,
+        "fixed_scan_policy": {
+            "page_size": recommended_page_size,
+            "requested_pages": recommended_requested_pages,
+            "scan_max_pages": recommended_scan_max_pages,
+            "auto_expand_pages": bool(fixed_policy["auto_expand_pages"]),
+            "public_inputs_exposed": False,
+        },
     }
 
 
 def _callable_analysis_arguments(arguments: JSONObject) -> JSONObject:
     if not isinstance(arguments, dict):
         return {}
-    return {key: value for key, value in arguments.items() if key not in {"estimated_full_scan_pages"}}
+    return {
+        key: value
+        for key, value in arguments.items()
+        if key not in {"estimated_full_scan_pages", "fixed_scan_policy"}
+    }
 
 
 def _build_recommended_analysis_chain(tool: str, arguments: JSONObject, estimate: JSONObject) -> list[JSONObject]:
@@ -3332,13 +3917,10 @@ def _build_recommended_analysis_chain(tool: str, arguments: JSONObject, estimate
     recommended = _callable_analysis_arguments(
         cast(JSONObject, estimate.get("recommended_arguments") if isinstance(estimate.get("recommended_arguments"), dict) else {})
     )
+    fixed_scan_policy = cast(JSONObject, estimate.get("fixed_scan_policy") if isinstance(estimate.get("fixed_scan_policy"), dict) else {})
     common_args: JSONObject = {
         "app_key": app_key,
         "page_num": max(_coerce_count(arguments.get("page_num")) or 1, 1),
-        "page_size": _coerce_count(arguments.get("page_size")) or DEFAULT_QUERY_PAGE_SIZE,
-        "requested_pages": _coerce_count(arguments.get("requested_pages")) or 1,
-        "scan_max_pages": _coerce_count(arguments.get("scan_max_pages")) or 1,
-        "auto_expand_pages": bool(arguments.get("auto_expand_pages")),
         "query_key": arguments.get("query_key"),
         "filters": _as_object_list(arguments.get("filters")),
         "sorts": _as_object_list(arguments.get("sorts")),
@@ -3370,6 +3952,8 @@ def _build_recommended_analysis_chain(tool: str, arguments: JSONObject, estimate
             "tool_name": "record_query",
             "purpose": "Confirm the full scope before presenting conclusions.",
             "safe_for_final_conclusion": True,
+            "note": "Summary uses fixed internal scan settings; do not pass manual paging controls.",
+            "scan_policy": fixed_scan_policy,
             "arguments": summary_args,
         }
     ]
@@ -3393,6 +3977,8 @@ def _build_recommended_analysis_chain(tool: str, arguments: JSONObject, estimate
                 "tool_name": "record_aggregate",
                 "purpose": "Use grouped aggregation for distribution, ratio, ranking, or top-N conclusions.",
                 "safe_for_final_conclusion": True,
+                "note": "Aggregate uses fixed internal scan settings; do not pass manual paging controls.",
+                "scan_policy": fixed_scan_policy,
                 "arguments": aggregate_arguments,
             }
         )
@@ -3422,6 +4008,7 @@ def _build_recommended_analysis_chain(tool: str, arguments: JSONObject, estimate
             "purpose": "Browse representative sample rows only after the full-scan analysis steps.",
             "safe_for_final_conclusion": False,
             "note": "List mode is sample-only evidence when capped; do not use it as the final statistical basis.",
+            "scan_policy": _fixed_list_scan_policy(),
             "arguments": list_arguments,
         }
     )
@@ -3488,8 +4075,8 @@ def _assess_plan_readiness(
         actions.append("Set strict_full=true so incomplete scans block final conclusions.")
     probe = estimate.get("probe") if isinstance(estimate.get("probe"), dict) else None
     if isinstance(probe, dict) and bool(probe.get("would_exceed_current_budget")):
-        blockers.append("current scan budget is smaller than the estimated matching dataset")
-        actions.append("Use estimate.recommended_arguments or enable auto_expand_pages before trusting aggregate or summary results.")
+        blockers.append("the estimated matching dataset exceeds the fixed internal analysis scan budget")
+        actions.append("Reuse suggested_next_call; do not try to hand-tune paging controls for analysis.")
     actions.append("After execution, verify completeness before using the result as a final conclusion.")
     return {
         "ready_for_final_conclusion": not blockers,
@@ -3791,6 +4378,11 @@ def _to_time_bucket(value: JSONValue, bucket: str) -> str:
     if bucket == "week":
         iso_year, iso_week, _ = parsed.isocalendar()
         return f"{iso_year}-W{iso_week:02d}"
+    if bucket == "quarter":
+        quarter = ((parsed.month - 1) // 3) + 1
+        return f"{parsed.year}-Q{quarter}"
+    if bucket == "year":
+        return parsed.strftime("%Y")
     return parsed.strftime("%Y-%m-%d")
 
 
@@ -3804,6 +4396,106 @@ def _parse_datetime_like(text: str) -> datetime | None:
     return None
 
 
+def _flatten_distinct_values(value: JSONValue) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        items = value
+    else:
+        items = [value]
+    flattened: list[str] = []
+    for item in items:
+        if item is None:
+            continue
+        if isinstance(item, (dict, list)):
+            flattened.append(json.dumps(item, ensure_ascii=False, sort_keys=True))
+        else:
+            flattened.append(_stringify_json(item))
+    return flattened
+
+
+def _coerce_comparable(value: JSONValue) -> JSONValue:
+    amount = _coerce_amount(value)
+    if amount is not None:
+        return amount
+    text = _normalize_optional_text(value)
+    if text is None:
+        return None
+    parsed = _parse_datetime_like(text)
+    if parsed is not None:
+        return parsed
+    return text
+
+
+def _match_analyze_filter(field_value: JSONValue, op: str, expected: JSONValue) -> bool:
+    if op == "is_null":
+        return field_value is None or field_value == [] or field_value == ""
+    if op == "not_null":
+        return not _match_analyze_filter(field_value, "is_null", expected)
+
+    values = field_value if isinstance(field_value, list) else [field_value]
+    normalized_values = [_coerce_comparable(item) for item in values if item is not None]
+
+    if op == "contains":
+        needle = _normalize_optional_text(expected)
+        if needle is None:
+            return False
+        return any(needle in _stringify_json(item) for item in values if item is not None)
+
+    if op in {"in", "not_in"}:
+        expected_values = expected if isinstance(expected, list) else [expected]
+        expected_set = {_stringify_json(item) for item in expected_values if item is not None}
+        actual_set = {_stringify_json(item) for item in values if item is not None}
+        matched = bool(actual_set & expected_set)
+        return matched if op == "in" else not matched
+
+    if op in {"eq", "neq"}:
+        expected_text = _stringify_json(expected)
+        matched = any(_stringify_json(item) == expected_text for item in values if item is not None)
+        return matched if op == "eq" else not matched
+
+    if op == "between":
+        lower, upper = _coerce_filter_range(expected)
+        lower_value = _coerce_comparable(lower)
+        upper_value = _coerce_comparable(upper)
+        for item in normalized_values:
+            if item is None:
+                continue
+            try:
+                if lower_value is not None and item < lower_value:
+                    continue
+                if upper_value is not None and item > upper_value:
+                    continue
+                return True
+            except TypeError:
+                continue
+        return False
+
+    target = _coerce_comparable(expected)
+    for item in normalized_values:
+        if item is None or target is None:
+            continue
+        try:
+            if op == "gt" and item > target:
+                return True
+            if op == "gte" and item >= target:
+                return True
+            if op == "lt" and item < target:
+                return True
+            if op == "lte" and item <= target:
+                return True
+        except TypeError:
+            continue
+    return False
+
+
+def _sortable_value(value: JSONValue) -> tuple[int, JSONValue]:
+    if value is None:
+        return (1, "")
+    comparable = _coerce_comparable(value)
+    return (0, comparable if comparable is not None else "")
+
+
 def _echo_filters(filters: list[JSONObject]) -> list[JSONObject]:
     return [dict(item) for item in filters]
 
@@ -4364,7 +5056,7 @@ def _option_value(raw_value: JSONValue, field: FormField) -> JSONObject:
         raise RecordInputError(
             message=f"field '{field.que_title}' uses unknown option '{text}'",
             error_code="OPTION_NOT_FOUND",
-            fix_hint="Use record_field_resolve or inspect the form to confirm allowed option values.",
+            fix_hint="Use record_schema_get or inspect the form to confirm allowed option values.",
             details={"field": _field_ref_payload(field), "expected_format": _write_format_for_field(field), "received_value": raw_value},
         )
     return {"value": text}