@josephyan/qingflow-app-user-mcp 1.0.8 → 1.0.9

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@1.0.8
+npm install @josephyan/qingflow-app-user-mcp@1.0.9
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@1.0.8 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@1.0.9 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.0.8"
+version = "1.0.9"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-record-analysis/SKILL.md

@@ -17,6 +17,7 @@ If `app_get.accessible_views` marks a view with `analysis_supported=false`, do n
 This is the default execution order. Never skip `app_get` when the browse range is unclear. Never call `record_access` without a browse schema.
 
 Core tools: `app_get`, `record_browse_schema_get`, `record_access`, Python. Use field_id-based DSLs only for columns, filters, sort clauses, and any optional lightweight `record_analyze` helper. Use `record_list`/`record_get` only for browse samples. Use `record_analyze` only as a lightweight non-default statistics helper when a compact grouped result is enough. Task/comment work stays in [$qingflow-task-ops](../qingflow-task-ops/SKILL.md).
+For analysis-style tasks, prefer a concrete time range or business filter. If the user did not give one and the data could be large, ask for scope instead of trying an unbounded historical scan.
 
 ## Execution Modes
 
@@ -78,6 +79,8 @@ Then run Python against every `files[].local_path`. CSV columns are stable: `rec
 - Never ask for `page`, `page_size`, `limit`, or `max_rows`; `record_access` owns paging internally and follows the backend's native paging capability.
 - Never treat backend `searchQueIds` as column selection; it is only a full-text search scope.
 - If multiple CSV files are returned, read them all.
+- If `status=needs_scope`, no CSV was written; use `scope.suggested_time_fields` / `scope.recommended_where_examples` to ask for or apply a time/business range, then call `record_access` again.
+- If `status=partial`, read the returned files only as a limited subset; state the limitation and do not present a full-population final conclusion.
 - If `complete=false` or `safe_for_final_conclusion=false`, downgrade the answer and disclose the limitation.
 - `record_export_direct` is only for explicit export/download/Excel requests, not default analysis.
 - QingBI/report reads are only for user-provided report URLs or `chart_id`; do not create or use reports as the default analysis path.

package/skills/qingflow-record-analysis/references/analysis-gotchas.md

@@ -125,6 +125,8 @@ If the user asked for several outputs and only part of them is stable:
 - say which parts are still unresolved
 - do not present the answer as fully finished
 
+If `record_access.status=needs_scope`, stop and ask for a time/business range; no CSV was written. If `record_access.status=partial`, read the returned CSV only as a partial subset and name the limitation before any numbers.
+
 ## Do not send unsupported formula or div-style metrics into `record_analyze`.
 
 Examples to avoid:

package/skills/qingflow-record-analysis/references/analysis-patterns.md

@@ -25,13 +25,17 @@ Use this skill when the user asks for:
 
 Result reading order:
 
-1. `record_access.complete`
-2. `record_access.safe_for_final_conclusion`
-3. `record_access.files[].local_path`
-4. `record_access.metadata_files.schema`
-5. Python outputs
-6. `record_access.fields`
-7. `record_access.warnings`
+1. `record_access.status`
+2. `record_access.complete`
+3. `record_access.safe_for_final_conclusion`
+4. `record_access.files[].local_path`
+5. `record_access.metadata_files.schema`
+6. Python outputs
+7. `record_access.fields`
+8. `record_access.warnings`
+9. `record_access.scope`
+
+If `record_access.status=needs_scope`, no CSV was written; ask for a time/business range or retry with a user-provided period from `scope.suggested_time_fields`. If `status=partial`, use the CSV files only as a limited subset and do not make a full-population conclusion.
 
 Treat `record_browse_schema_get` as the browse-schema source of truth. It matches the selected Qingflow table view header and is the same schema source used by `record_access.fields` and `schema.json`. Missing fields are permission boundaries, not invitations to guess hidden ids.
 

package/skills/qingflow-record-analysis/references/confidence-reporting.md

@@ -27,6 +27,8 @@ Put evidence into `样本观察` when:
 - the tool reports `row_cap_hit`
 - the tool reports `sample_only`
 - the result is compact/capped and not complete
+- `record_access.status=needs_scope`
+- `record_access.status=partial`
 - `record_access.complete=false` or `record_access.truncated=true`
 
 ## Downgrade rule

package/src/qingflow_mcp/cli/formatters.py

@@ -194,6 +194,36 @@ def _format_record_list(result: dict[str, Any]) -> str:
     return "\n".join(lines) + "\n"
 
 
+def _format_record_access(result: dict[str, Any]) -> str:
+    status = result.get("status") or "-"
+    lines = [
+        f"Status: {status}",
+        f"Rows: {result.get('row_count')}",
+        f"Complete: {result.get('complete')}",
+        f"Safe for final conclusion: {result.get('safe_for_final_conclusion')}",
+    ]
+    if result.get("local_dir"):
+        lines.append(f"Local dir: {result.get('local_dir')}")
+    files = result.get("files") if isinstance(result.get("files"), list) else []
+    if files:
+        lines.append("Files:")
+        for item in files:
+            if isinstance(item, dict):
+                lines.append(f"- part {item.get('part')}: {item.get('local_path')} ({item.get('row_count')} rows)")
+    scope = result.get("scope") if isinstance(result.get("scope"), dict) else {}
+    if status == "needs_scope" and scope:
+        lines.append("Scope required:")
+        lines.append(f"- reported_total: {scope.get('reported_total')}")
+        lines.append(f"- estimated_pages: {scope.get('estimated_pages')}")
+        suggested = scope.get("suggested_time_fields") if isinstance(scope.get("suggested_time_fields"), list) else []
+        if suggested:
+            names = ", ".join(str(item.get("title") or item.get("field_id")) for item in suggested if isinstance(item, dict))
+            lines.append(f"- suggested_time_fields: {names}")
+    _append_warnings(lines, result.get("warnings"))
+    _append_verification(lines, result.get("verification"))
+    return "\n".join(lines) + "\n"
+
+
 def _format_task_list(result: dict[str, Any]) -> str:
     data = result.get("data") if isinstance(result.get("data"), dict) else {}
     items = data.get("items") if isinstance(data.get("items"), list) else []
@@ -693,6 +723,7 @@ _FORMATTERS = {
     "app_search": _format_app_items,
     "app_get": _format_app_get,
     "record_list": _format_record_list,
+    "record_access": _format_record_access,
     "task_list": _format_task_list,
     "task_workbench": _format_task_workbench,
     "task_get": _format_task_get,

package/src/qingflow_mcp/response_trim.py

@@ -465,6 +465,7 @@ def _trim_record_access(payload: JSONObject) -> None:
         "fields",
         "warnings",
         "verification",
+        "scope",
     ):
         value = payload.get(key)
         if value is not None:

package/src/qingflow_mcp/server_app_user.py

@@ -77,6 +77,7 @@ Inside `optional_fields`, any field with `may_become_required=true` is still wri
 Prefer `view_id` entries from `accessible_views` where `analysis_supported=true`.
 
 Use `record_access` to write local CSV shard files, then use Python to compute counts, rankings, ratios, trends, and final conclusions. `record_access` does not return bulk `items`; read `files[].local_path`. Use `fields[]` and the same-directory `metadata_files.schema` / `metadata_files.readme` to map stable `field_<id>` CSV columns back to titles and types.
+For analysis-style tasks, prefer an explicit time range or business filter. If `record_access.status == "needs_scope"`, do not treat it as a failure; ask for a time/business scope or retry with a user-provided period using `scope.suggested_time_fields` / `scope.recommended_where_examples`. If `record_access.status == "partial"`, read the returned files only as a limited subset and do not give a final full-population conclusion.
 Use `chart_get` only when the user provides a report URL / chart_id or explicitly asks to read an existing report. Do not use QingBI as the default analysis route.
 
 Use this data-access DSL shape:

package/src/qingflow_mcp/tools/record_tools.py

@@ -7,7 +7,7 @@ import re
 import time
 from copy import deepcopy
 from dataclasses import dataclass
-from datetime import UTC, datetime
+from datetime import UTC, datetime, timedelta
 from decimal import Decimal, InvalidOperation
 from pathlib import Path
 from typing import Any, cast
@@ -34,6 +34,9 @@ DEFAULT_QUERY_PAGE_SIZE = 50
 DEFAULT_LIST_PAGE_SIZE = 200
 BACKEND_RECORD_ACCESS_PAGE_SIZE = 1000
 DEFAULT_RECORD_ACCESS_SHARD_ROWS = 5000
+RECORD_ACCESS_UNBOUNDED_ROW_THRESHOLD = 20_000
+RECORD_ACCESS_TIME_BUDGET_SECONDS = 55.0
+RECORD_ACCESS_MIN_REMAINING_SECONDS = 8.0
 DEFAULT_ANALYSIS_PAGE_SIZE = 1000
 DEFAULT_SCAN_MAX_PAGES = 10
 DEFAULT_ANALYSIS_SCAN_MAX_PAGES = 100
@@ -1848,6 +1851,7 @@ class RecordTools(ToolBase):
         sorts = self._normalize_record_list_order_by(order_by)
 
         def runner(session_profile, context):
+            created_at = datetime.now(UTC).isoformat()
             browse_scope = self._build_browse_read_scope(
                 profile,
                 context,
@@ -1870,6 +1874,106 @@ class RecordTools(ToolBase):
                 if view_selection is not None or view_route.list_type is not None
                 else [DEFAULT_RECORD_LIST_TYPE, 14, 1, 2, 12]
             )
+            fields_payload = [_record_access_field_payload(field) for field in selected_fields]
+            scope_status = _record_access_scope_status(filters, view_route, index)
+
+            def fetch_page(page_num: int, page_size: int) -> JSONObject:
+                nonlocal used_list_type
+                if used_list_type is None:
+                    last_error: QingflowApiError | None = None
+                    page: JSONObject | None = None
+                    for candidate_list_type in fallback_list_types:
+                        try:
+                            page = self._search_page(
+                                context,
+                                app_key=app_key,
+                                view_selection=view_selection,
+                                page_num=page_num,
+                                page_size=page_size,
+                                query_key=None,
+                                match_rules=match_rules,
+                                sorts=sort_rules,
+                                search_que_ids=None,
+                                list_type=candidate_list_type,
+                            )
+                            used_list_type = None if view_selection is not None else candidate_list_type
+                            break
+                        except QingflowApiError as exc:
+                            last_error = exc
+                            if self._should_retry_list_type_fallback(exc) and candidate_list_type != fallback_list_types[-1]:
+                                continue
+                            raise
+                    if page is None:
+                        if last_error is not None:
+                            raise last_error
+                        raise_tool_error(QingflowApiError.config_error("record_access failed: no accessible listType"))
+                    return page
+                return self._search_page(
+                    context,
+                    app_key=app_key,
+                    view_selection=view_selection,
+                    page_num=page_num,
+                    page_size=page_size,
+                    query_key=None,
+                    match_rules=match_rules,
+                    sorts=sort_rules,
+                    search_que_ids=None,
+                    list_type=used_list_type,
+                )
+
+            probe_page_size = 1 if _record_access_light_probe_recommended(scope_status) else BACKEND_RECORD_ACCESS_PAGE_SIZE
+            probe_page = fetch_page(1, probe_page_size)
+            reported_total = _effective_total(probe_page, probe_page_size)
+            estimated_pages = _record_access_estimated_pages(probe_page, reported_total, page_size=probe_page_size)
+            scope_payload = _record_access_scope_payload(
+                scope_status=scope_status,
+                reported_total=reported_total,
+                estimated_pages=estimated_pages,
+                index=index,
+            )
+            warnings: list[JSONObject] = []
+            warnings.extend(legacy_warnings)
+            warnings.extend(compatibility_warnings)
+            warnings.extend(_view_filter_trust_warnings(view_route))
+            if used_list_type is not None and used_list_type != DEFAULT_RECORD_LIST_TYPE:
+                warnings.append(
+                    {
+                        "code": "LIST_TYPE_FALLBACK",
+                        "message": (
+                            f"record_access not accessible via listType={DEFAULT_RECORD_LIST_TYPE}; "
+                            f"fell back to listType={used_list_type} ({get_record_list_type_label(used_list_type)})."
+                        ),
+                    }
+                )
+            if _record_access_needs_scope(scope_status=scope_status, reported_total=reported_total):
+                warnings.append(_record_access_unbounded_scan_warning(reported_total=reported_total, estimated_pages=estimated_pages))
+                verification_payload: JSONObject = {
+                    **_view_filter_verification_payload(view_route),
+                    "reported_total": reported_total,
+                    "estimated_pages": estimated_pages,
+                    "fetched_pages": 1,
+                    "stopped_reason": "UNBOUNDED_SCAN_TOO_LARGE",
+                    "list_type_used": used_list_type,
+                }
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "ok": True,
+                    "status": "needs_scope",
+                    "app_key": app_key,
+                    "view_id": view_route.view_id,
+                    "format": "csv",
+                    "row_count": 0,
+                    "complete": False,
+                    "truncated": True,
+                    "safe_for_final_conclusion": False,
+                    "files": [],
+                    "fields": fields_payload,
+                    "warnings": warnings,
+                    "verification": verification_payload,
+                    "scope": scope_payload,
+                    "request_route": self._request_route_payload(context),
+                }
 
             run_dir = _record_access_run_dir()
             run_dir.mkdir(parents=True, exist_ok=True)
@@ -1926,58 +2030,14 @@ class RecordTools(ToolBase):
 
             current_page = 1
             has_more = False
-            reported_total: int | None = None
-            created_at = datetime.now(UTC).isoformat()
+            fetched_pages = 0
+            stopped_reason: str | None = None
+            deadline = time.monotonic() + RECORD_ACCESS_TIME_BUDGET_SECONDS
+            page = probe_page if probe_page_size == BACKEND_RECORD_ACCESS_PAGE_SIZE else fetch_page(1, BACKEND_RECORD_ACCESS_PAGE_SIZE)
             try:
                 while True:
-                    if used_list_type is None:
-                        last_error: QingflowApiError | None = None
-                        page: JSONObject | None = None
-                        for candidate_list_type in fallback_list_types:
-                            try:
-                                page = self._search_page(
-                                    context,
-                                    app_key=app_key,
-                                    view_selection=view_selection,
-                                    page_num=current_page,
-                                    page_size=BACKEND_RECORD_ACCESS_PAGE_SIZE,
-                                    query_key=None,
-                                    match_rules=match_rules,
-                                    sorts=sort_rules,
-                                    search_que_ids=None,
-                                    list_type=candidate_list_type,
-                                )
-                                used_list_type = None if view_selection is not None else candidate_list_type
-                                break
-                            except QingflowApiError as exc:
-                                last_error = exc
-                                if (
-                                    self._should_retry_list_type_fallback(exc)
-                                    and candidate_list_type != fallback_list_types[-1]
-                                ):
-                                    continue
-                                raise
-                        if page is None:
-                            if last_error is not None:
-                                raise last_error
-                            raise_tool_error(QingflowApiError.config_error("record_access failed: no accessible listType"))
-                    else:
-                        page = self._search_page(
-                            context,
-                            app_key=app_key,
-                            view_selection=view_selection,
-                            page_num=current_page,
-                            page_size=BACKEND_RECORD_ACCESS_PAGE_SIZE,
-                            query_key=None,
-                            match_rules=match_rules,
-                            sorts=sort_rules,
-                            search_que_ids=None,
-                            list_type=used_list_type,
-                        )
                     page_rows = page.get("list")
                     items = page_rows if isinstance(page_rows, list) else []
-                    if reported_total is None:
-                        reported_total = _effective_total(page, BACKEND_RECORD_ACCESS_PAGE_SIZE)
                     has_more = _page_has_more(page, current_page, BACKEND_RECORD_ACCESS_PAGE_SIZE, len(items))
                     page_apply_order: list[int] = []
                     page_answer_map: dict[int, list[JSONValue]] = {}
@@ -1993,34 +2053,33 @@ class RecordTools(ToolBase):
                         page_answer_map[apply_id] = cast(list[JSONValue], answer_list)
                     for apply_id in page_apply_order:
                         write_record(apply_id, page_answer_map.get(apply_id, []))
+                    fetched_pages += 1
                     if not has_more:
                         break
                     current_page += 1
+                    if _record_access_time_budget_exceeded(
+                        deadline,
+                        fetched_pages=fetched_pages,
+                        estimated_pages=estimated_pages,
+                    ):
+                        stopped_reason = "TIME_BUDGET_EXCEEDED"
+                        break
+                    page = fetch_page(current_page, BACKEND_RECORD_ACCESS_PAGE_SIZE)
             finally:
                 close_shard()
 
-            warnings: list[JSONObject] = []
-            warnings.extend(legacy_warnings)
-            warnings.extend(compatibility_warnings)
-            warnings.extend(_view_filter_trust_warnings(view_route))
-            if used_list_type is not None and used_list_type != DEFAULT_RECORD_LIST_TYPE:
-                warnings.append(
-                    {
-                        "code": "LIST_TYPE_FALLBACK",
-                        "message": (
-                            f"record_access not accessible via listType={DEFAULT_RECORD_LIST_TYPE}; "
-                            f"fell back to listType={used_list_type} ({get_record_list_type_label(used_list_type)})."
-                        ),
-                    }
-                )
-            complete = not has_more
+            if stopped_reason == "TIME_BUDGET_EXCEEDED":
+                warnings.append(_record_access_time_budget_warning(reported_total=reported_total, fetched_pages=fetched_pages))
+            complete = stopped_reason is None and not has_more
             safe_for_final_conclusion = complete and not any(
                 warning.get("code") == "CUSTOM_VIEW_FILTER_UNVERIFIED" for warning in warnings
             )
-            fields_payload = [_record_access_field_payload(field) for field in selected_fields]
             verification_payload: JSONObject = {
                 **_view_filter_verification_payload(view_route),
                 "reported_total": reported_total,
+                "estimated_pages": estimated_pages,
+                "fetched_pages": fetched_pages,
+                "stopped_reason": stopped_reason,
                 "list_type_used": used_list_type,
             }
             metadata_files = _write_record_access_metadata_files(
@@ -2035,6 +2094,7 @@ class RecordTools(ToolBase):
                 fields=fields_payload,
                 warnings=warnings,
                 verification=verification_payload,
+                scope=scope_payload,
             )
             return {
                 "profile": profile,
@@ -2054,6 +2114,7 @@ class RecordTools(ToolBase):
                 "fields": fields_payload,
                 "warnings": warnings,
                 "verification": verification_payload,
+                "scope": scope_payload,
                 "request_route": self._request_route_payload(context),
             }
 
@@ -11665,6 +11726,148 @@ def _record_access_field_payload(field: FormField) -> JSONObject:
     }
 
 
+def _record_access_scope_status(filters: list[JSONObject], view_route: AccessibleViewRoute, index: FieldIndex) -> JSONObject:
+    has_time_filter = False
+    has_explicit_business_filter = False
+    for item in filters:
+        if not isinstance(item, dict):
+            continue
+        field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
+        field = index.by_id.get(str(field_id)) if field_id is not None else None
+        if field is not None and field.que_type in DATE_QUE_TYPES:
+            has_time_filter = True
+        else:
+            has_explicit_business_filter = True
+    view_selection = view_route.view_selection
+    has_saved_view_filter = bool(view_selection is not None and view_selection.conditions)
+    return {
+        "filter_count": len(filters),
+        "has_explicit_where": bool(filters),
+        "has_time_filter": has_time_filter,
+        "has_business_filter": bool(has_explicit_business_filter or has_saved_view_filter),
+        "has_saved_view_filter": has_saved_view_filter,
+    }
+
+
+def _record_access_light_probe_recommended(scope_status: JSONObject) -> bool:
+    return not bool(scope_status.get("has_time_filter")) and not bool(scope_status.get("has_business_filter"))
+
+
+def _record_access_estimated_pages(page: JSONObject, reported_total: int | None, *, page_size: int) -> int | None:
+    page_amount = _coerce_count(page.get("pageAmount"))
+    if page_size == BACKEND_RECORD_ACCESS_PAGE_SIZE and page_amount is not None:
+        return page_amount
+    if reported_total is None or reported_total <= 0:
+        return page_amount
+    return (reported_total + BACKEND_RECORD_ACCESS_PAGE_SIZE - 1) // BACKEND_RECORD_ACCESS_PAGE_SIZE
+
+
+def _record_access_suggested_time_fields(index: FieldIndex) -> list[JSONObject]:
+    fields: list[JSONObject] = []
+    for field in index.by_id.values():
+        if field.que_type in DATE_QUE_TYPES:
+            fields.append(_record_access_field_payload(field))
+    return fields
+
+
+def _record_access_recommended_where_examples(suggested_time_fields: list[JSONObject]) -> list[JSONObject]:
+    if not suggested_time_fields:
+        return []
+    now = datetime.now(UTC)
+    month_start = now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+    if month_start.month == 12:
+        next_month = month_start.replace(year=month_start.year + 1, month=1)
+    else:
+        next_month = month_start.replace(month=month_start.month + 1)
+    month_end = next_month - timedelta(seconds=1)
+    examples: list[JSONObject] = []
+    for field in suggested_time_fields[:3]:
+        field_id = field.get("field_id")
+        examples.append(
+            {
+                "field_id": field_id,
+                "title": field.get("title"),
+                "where": [
+                    {
+                        "field_id": field_id,
+                        "op": "between",
+                        "value": [
+                            month_start.strftime("%Y-%m-%d"),
+                            month_end.strftime("%Y-%m-%d %H:%M:%S"),
+                        ],
+                    }
+                ],
+            }
+        )
+    return examples
+
+
+def _record_access_scope_payload(
+    *,
+    scope_status: JSONObject,
+    reported_total: int | None,
+    estimated_pages: int | None,
+    index: FieldIndex,
+) -> JSONObject:
+    suggested_time_fields = _record_access_suggested_time_fields(index)
+    return {
+        "reported_total": reported_total,
+        "estimated_pages": estimated_pages,
+        "has_time_filter": bool(scope_status.get("has_time_filter")),
+        "has_business_filter": bool(scope_status.get("has_business_filter")),
+        "suggested_time_fields": suggested_time_fields,
+        "recommended_where_examples": _record_access_recommended_where_examples(suggested_time_fields),
+    }
+
+
+def _record_access_needs_scope(*, scope_status: JSONObject, reported_total: int | None) -> bool:
+    if reported_total is None or reported_total <= RECORD_ACCESS_UNBOUNDED_ROW_THRESHOLD:
+        return False
+    return not bool(scope_status.get("has_time_filter")) and not bool(scope_status.get("has_business_filter"))
+
+
+def _record_access_unbounded_scan_warning(*, reported_total: int | None, estimated_pages: int | None) -> JSONObject:
+    page_text = f" across about {estimated_pages} pages" if estimated_pages else ""
+    return {
+        "code": "UNBOUNDED_SCAN_TOO_LARGE",
+        "message": (
+            "record_access stopped before writing CSV because this query has no time/business boundary "
+            f"and the backend reports {reported_total or 'unknown'} rows{page_text}. "
+            "Add a where filter, preferably on a time field, then retry."
+        ),
+        "row_threshold": RECORD_ACCESS_UNBOUNDED_ROW_THRESHOLD,
+        "reported_total": reported_total,
+        "estimated_pages": estimated_pages,
+    }
+
+
+def _record_access_time_budget_exceeded(
+    deadline: float,
+    *,
+    fetched_pages: int,
+    estimated_pages: int | None,
+) -> bool:
+    now = time.monotonic()
+    if now >= deadline:
+        return True
+    if estimated_pages is not None and estimated_pages - fetched_pages <= 1:
+        return False
+    return now + RECORD_ACCESS_MIN_REMAINING_SECONDS >= deadline
+
+
+def _record_access_time_budget_warning(*, reported_total: int | None, fetched_pages: int) -> JSONObject:
+    return {
+        "code": "TIME_BUDGET_EXCEEDED",
+        "message": (
+            "record_access stopped early to return partial CSV files before the caller timeout. "
+            "Narrow the query with a time or business filter for a complete result."
+        ),
+        "reported_total": reported_total,
+        "fetched_pages": fetched_pages,
+        "time_budget_seconds": RECORD_ACCESS_TIME_BUDGET_SECONDS,
+    }
+
+
 def _write_record_access_metadata_files(
     *,
     run_dir: Path,
@@ -11678,6 +11881,7 @@ def _write_record_access_metadata_files(
     fields: list[JSONObject],
     warnings: list[JSONObject],
     verification: JSONObject,
+    scope: JSONObject | None = None,
 ) -> JSONObject:
     schema_path = run_dir / "schema.json"
     readme_path = run_dir / "README.md"
@@ -11698,6 +11902,8 @@ def _write_record_access_metadata_files(
         "verification": verification,
         "csv_columns": ["record_id"] + [str(field["column_name"]) for field in fields if field.get("column_name")],
     }
+    if scope is not None:
+        schema_payload["scope"] = scope
     schema_path.write_text(json.dumps(schema_payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
     readme_path.write_text(
         _record_access_readme(
@@ -11710,6 +11916,7 @@ def _write_record_access_metadata_files(
             files=files,
             fields=fields,
             warnings=warnings,
+            scope=scope,
         ),
         encoding="utf-8",
     )
@@ -11730,6 +11937,7 @@ def _record_access_readme(
     files: list[JSONObject],
     fields: list[JSONObject],
     warnings: list[JSONObject],
+    scope: JSONObject | None = None,
 ) -> str:
     lines = [
         "# Qingflow Record Access",
@@ -11775,6 +11983,18 @@ def _record_access_readme(
             code = _normalize_optional_text(warning.get("code")) or "WARNING"
             message = _normalize_optional_text(warning.get("message")) or ""
             lines.append(f"- `{code}`: {message}")
+    if scope:
+        lines.extend(
+            [
+                "",
+                "## Scope",
+                "",
+                f"- Reported total: {scope.get('reported_total')}",
+                f"- Estimated pages: {scope.get('estimated_pages')}",
+                f"- Has time filter: {str(bool(scope.get('has_time_filter'))).lower()}",
+                f"- Has business filter: {str(bool(scope.get('has_business_filter'))).lower()}",
+            ]
+        )
     lines.extend(
         [
             "",