@@ -0,0 +1,33 @@
+---
+'@objectstack/types': patch
+'@objectstack/spec': patch
+'@objectstack/metadata-protocol': patch
+'@objectstack/service-analytics': patch
+---
+
+feat(data): a host-configured default and maximum page size for list, report and analytics reads, and a per-query row budget, refused with a code that names the limit
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+What Clause-② widens: the published error-code vocabulary. `ErrorCode` (the union `ApiErrorSchema.code` parses against) gains one registered member, `QUERY_ROW_BUDGET_EXCEEDED`. A page size over the maximum answers the existing standard `MAX_RECORDS_EXCEEDED` (400), which gains its first producer. No metadata an author writes changes, and no existing code, status or response shape moves.
+
+A deployment can now bound how many rows one data API read returns and walks. Three environment variables, each a positive integer; all three unset is today's behaviour exactly, so a self-hosted deployment that sets none of them answers as before:
+
+- **`OS_DATA_DEFAULT_PAGE_SIZE`** — the page a read gets when it names no `limit`. Unset with a maximum set, the maximum is the default.
+- **`OS_DATA_MAX_PAGE_SIZE`** — the largest `limit` a read may name.
+- **`OS_DATA_QUERY_ROW_BUDGET`** — the most rows one query may walk: its `offset` plus the rows it returns.
+
+**Over a limit is refused, never clamped.** A clamp answers a different page from the one asked for, and a caller paging by its own `limit` would skip the rows in between. So a `limit` over the maximum answers `400 MAX_RECORDS_EXCEEDED`, and an `offset` plus `limit` over the budget answers `400 QUERY_ROW_BUDGET_EXCEEDED`. Both messages name the configured number, and both are refused before the driver is asked. Each refusal writes one `warn` line with the surface, the object (or analytics cube), the row count and the limit, and never a row value.
+
+**A read that names no limit:**
+
+- A list read (`GET /data/:object`, `POST /data/:object/query`, grouped or not) runs with the default page size as its `limit`. Its answer already says when more rows exist (`hasMore`, `total`), so this is an ordinary first page.
+- An analytics read (`query()` behind `/analytics/query`, and `queryDataset()`, the dataset door reports and dashboards read through) has no `hasMore`, so it is never cut silently. It runs with one row more than the default page size, and an answer with more rows than the default is refused with `MAX_RECORDS_EXCEEDED`, telling the caller to name a `limit` and page with `offset`.
+- With a row budget and no page size, an unpaged read runs with one row more than the budget leaves after its `offset`; an answer over the budget is refused with `QUERY_ROW_BUDGET_EXCEEDED`, and one that fits is served whole.
+
+The budget counts the rows a query walks through its window. Rows a database scans inside an aggregate or behind an unindexed filter are not visible to the data API and are not what it counts. The analytics doors judge the caller's own window; the dataset executor's internal passes (totals, measure-scoped queries) are not judged separately.
+
+A value that is not a positive integer, or a default above the maximum, fails at construction of the protocol and of the analytics service, naming the variable, so a typo never leaves the guard silently off.
+
+`@objectstack/types` exports the rule (`resolveQueryReadLimits`, `planQueryReadWindow`, `assertQueryReadRows`, `QueryReadLimitError` with one subclass per code, `QueryPageSizeExceededError` and `QueryRowBudgetExceededError`, and the variable and code names). `QUERY_ROW_BUDGET_EXCEEDED` is registered in the error-code ledger, and the error catalog's `MAX_RECORDS_EXCEEDED` entry names the page-size cause.
@@ -212,6 +212,32 @@ raw rows** with nothing to say the aggregation never happened.
 }
 ```
 
+#### Read limits a deployment may set
+
+A deployment can bound how many rows one read returns and walks. Three host
+environment variables, each a positive integer; with none of them set, no read
+is limited:
+
+| Variable | Meaning |
+|:--|:--|
+| `OS_DATA_DEFAULT_PAGE_SIZE` | the page a read gets when it names no `top` / `limit` (unset with a maximum set: the maximum) |
+| `OS_DATA_MAX_PAGE_SIZE` | the largest `top` / `limit` a read may name |
+| `OS_DATA_QUERY_ROW_BUDGET` | the most rows one query may walk: its `skip` / `offset` plus the rows it returns |
+
+Over a limit is **refused, never clamped**, so a client paging by its own page
+size never skips rows. A page size over the maximum answers
+`400 MAX_RECORDS_EXCEEDED`; `offset` plus page size over the budget answers
+`400 QUERY_ROW_BUDGET_EXCEEDED`. Both messages name the configured number, and
+both are refused before the read runs. A list read that names no page size gets
+the default page, and `hasMore` / `total` say whether more rows exist. With a
+budget and no page size, a read that names no page size runs one row past what
+the budget leaves and is refused with `QUERY_ROW_BUDGET_EXCEEDED` if its answer
+holds more; that read does run first. The same limits apply to
+`POST /analytics/query` and the dataset query that reports and dashboards read
+through. An analytics answer carries no `hasMore`, so one that names no `limit`
+and would answer more rows than the default page runs one row past the default
+and is refused with `MAX_RECORDS_EXCEEDED` rather than cut.
+
 ### `GET /data/:object/:id`
 
 Get a single record by ID. Only `select` and `expand` query parameters are allowed; any other parameter is refused `400 VALIDATION_ERROR`, and the message names it and lists the two accepted ones.
 
@@ -4,7 +4,7 @@ navTitle: Error Code Catalog
 description: Complete reference for all ObjectStack error codes with causes, fixes, and retry strategies
 ---
 
-ObjectStack uses a structured error system of **error categories** and **56 error codes reachable on the wire**, catalogued in full below (that count is pinned by `packages/spec/src/api/error-catalog-docs.test.ts` against the wire face). Every error includes a machine-readable code, HTTP status mapping, and retry guidance.
+ObjectStack uses a structured error system of **error categories** and **57 error codes reachable on the wire**, catalogued in full below (that count is pinned by `packages/spec/src/api/error-catalog-docs.test.ts` against the wire face). Every error includes a machine-readable code, HTTP status mapping, and retry guidance.
 
 This catalog documents the **wire face** — the codes a client can actually receive. That is not quite the
 `StandardErrorCode` enum: the enum also carries in-process spellings the REST door translates at the
@@ -367,8 +367,24 @@ result set — a response indistinguishable from a successful query.
 **Retry:** `no_retry`
 
 ### `MAX_RECORDS_EXCEEDED`
-**Cause:** The request attempts to create or return more records than the system limit.  
-**Fix:** Use pagination (`limit`/`offset` or cursor-based) for large datasets. Batch operations for bulk creates.  
+**Cause:** The request asked for more records than a request may carry. The data
+API answers it when the deployment sets `OS_DATA_MAX_PAGE_SIZE` and a list or
+analytics read named a `limit` (`$top`, `top` or `limit`) above it, and when an
+analytics read that named no `limit` would answer more rows than
+`OS_DATA_DEFAULT_PAGE_SIZE`. The message names the maximum (or the default).  
+**Fix:** Name a `limit` within the maximum and page with `offset` (or a cursor).
+See [Read limits a deployment may set](/docs/api/data-api#read-limits-a-deployment-may-set).  
+**Why it is an error and not a shorter page:** a clamped page is a different
+page from the one asked for, so a caller paging by its own `limit` would skip
+rows, and an analytics answer has no `hasMore` to say it was cut.  
+**Retry:** `no_retry`
+
+### `QUERY_ROW_BUDGET_EXCEEDED`
+**Cause:** The deployment sets `OS_DATA_QUERY_ROW_BUDGET` and the read's
+`offset` plus its rows would walk more than that budget. The message names the
+budget.  
+**Fix:** Narrow the read with a filter, or use a smaller `offset` and `limit`.
+See [Read limits a deployment may set](/docs/api/data-api#read-limits-a-deployment-may-set).  
 **Retry:** `no_retry`
 
 ---
 
@@ -417,7 +417,7 @@ const result = AutomationApiErrorCode.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +356 more>` | ✅ | The inner refusal's code in its WIRE spelling - the ADR-0112 member a record save of the same write answers in `error.code` (e.g. `UNIQUE_VIOLATION`); the closed set `ApiErrorSchema.code` parses against |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +357 more>` | ✅ | The inner refusal's code in its WIRE spelling - the ADR-0112 member a record save of the same write answers in `error.code` (e.g. `UNIQUE_VIOLATION`); the closed set `ApiErrorSchema.code` parses against |
 | **message** | `string` | ✅ | The inner refusal's own diagnostic text, verbatim, without the node and operation prefixes the run's failure text adds |
 
 ### Allowed Values: `FlowInnerRefusal.code`
@@ -693,6 +693,7 @@ const result = AutomationApiErrorCode.parse(data);
 * `PROJECT_PROVISIONING`
 * `PROJECT_PROVISIONING_FAILED`
 * `QUERY_OBJECT_MISMATCH`
+* `QUERY_ROW_BUDGET_EXCEEDED`
 * `QUEUE_NOT_FOUND`
 * `RAW_SQL_UNSUPPORTED`
 * `READ_BACK_FAILED`
 
@@ -28,7 +28,7 @@ const result = ApiErrorSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +356 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +357 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
 | **declaredCode** | `string` | optional | The producer-declared code, verbatim, when it is not a member of the closed `code` vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
 | **message** | `string` | ✅ | Readable error message |
 | **userMessage** | `string` | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces `message`. |
@@ -311,6 +311,7 @@ const result = ApiErrorSchema.parse(data);
 * `PROJECT_PROVISIONING`
 * `PROJECT_PROVISIONING_FAILED`
 * `QUERY_OBJECT_MISMATCH`
+* `QUERY_ROW_BUDGET_EXCEEDED`
 * `QUEUE_NOT_FOUND`
 * `RAW_SQL_UNSUPPORTED`
 * `READ_BACK_FAILED`
 
@@ -478,6 +478,7 @@ const result = ErrorCode.parse(data);
 * `PROJECT_PROVISIONING`
 * `PROJECT_PROVISIONING_FAILED`
 * `QUERY_OBJECT_MISMATCH`
+* `QUERY_ROW_BUDGET_EXCEEDED`
 * `QUEUE_NOT_FOUND`
 * `RAW_SQL_UNSUPPORTED`
 * `READ_BACK_FAILED`
 
@@ -8,6 +8,7 @@ import type {
 } from '@objectstack/spec/api';
 import { IDataEngine, engineCanRollBack, recordNotFoundError } from '@objectstack/core';
 import { declaredUserMessage, resolveTenancyPosture, resolveThrownHttpError } from '@objectstack/types';
+import { assertQueryReadRows, planQueryReadWindow, resolveQueryReadLimits } from '@objectstack/types';
 import { type TenancyPosture } from '@objectstack/spec/security';
 // [commit 376c70f98] The derived `version` this file's `getDiscovery()` serves as the
 // `DiscoverySchema` "System Identity" field — never a literal again.
@@ -1269,6 +1270,10 @@ export class ObjectStackProtocolImplementation implements
         this.getServicesRegistry = getServicesRegistry;
         this.environmentId = environmentId;
         this.authoringChannel = authoringChannel;
+        // Fail at construction on a misconfigured read limit (`OS_DATA_*`), so a
+        // typo is a boot fault naming the variable rather than a 500 on every
+        // list read. `findData` reads the limits again per call.
+        resolveQueryReadLimits();
     }
 
     // [#25467 E1] The one place that can read this class's private members builds
@@ -6248,7 +6253,23 @@ export class ObjectStackProtocolImplementation implements
         // honor groupBy/aggregations in find().
         const hasGroupBy = Array.isArray(options.groupBy) && options.groupBy.length > 0;
         const hasAggregations = Array.isArray(options.aggregations) && options.aggregations.length > 0;
+        // The deployment's read limits (`OS_DATA_DEFAULT_PAGE_SIZE`,
+        // `OS_DATA_MAX_PAGE_SIZE`, `OS_DATA_QUERY_ROW_BUDGET`; the rule is
+        // `@objectstack/types`' `query-read-limits.ts`). Planned here, after
+        // every shape gate and before the engine, so a refusal leaves the
+        // driver unasked. All three unset returns the caller's own `limit`.
+        const readLimits = resolveQueryReadLimits();
         if (hasGroupBy || hasAggregations) {
+            // The grouped branch slices in memory and never reads `offset`, so
+            // the window it is judged on is the groups it returns.
+            const groupRead = {
+                surface: 'list' as const,
+                object: request.object,
+                limit: typeof options.limit === 'number' ? options.limit : undefined,
+                limitParam: slotParam('limit'),
+            };
+            const groupPlan = planQueryReadWindow(groupRead, readLimits, console);
+            if (!groupPlan.probe) options.limit = groupPlan.limit;
             const aggregateQuery: EngineAggregateOptions = {
                 where: options.where,
                 groupBy: options.groupBy,
@@ -6270,6 +6291,7 @@ export class ObjectStackProtocolImplementation implements
                 context: options.context,
             };
             const records = await this.engine.aggregate(request.object, aggregateQuery);
+            assertQueryReadRows(groupRead, groupPlan, records.length, console);
             // Apply limit client-side (EngineAggregateOptions doesn't carry limit).
             // `records` is the full grouped set, so its length IS the real total
             // and `hasMore` follows from whether the slice dropped any groups.
@@ -6338,6 +6360,21 @@ export class ObjectStackProtocolImplementation implements
         // projection named only the body, and taken back off before serving.
         const bodyProjection = storedMetadataBodyProjection(request.object, options.fields);
         if (bodyProjection.addedType) options.fields = bodyProjection.fields;
+        // A list read with no `limit` takes the default page size, and its
+        // answer says whether more rows exist (`hasMore` / `total` below). A
+        // PROBE limit (a row budget with no page size) is the server's, not the
+        // caller's: the answer is refused when it overruns, and otherwise it is
+        // the whole set, so the probe is taken back off before the page
+        // metadata below reads `limit`.
+        const listRead = {
+            surface: 'list' as const,
+            object: request.object,
+            limit: typeof options.limit === 'number' ? options.limit : undefined,
+            offset: typeof options.offset === 'number' ? options.offset : undefined,
+            limitParam: slotParam('limit'),
+        };
+        const listPlan = planQueryReadWindow(listRead, readLimits, console);
+        if (listPlan.limit !== undefined) options.limit = listPlan.limit;
         // [#29764] The bag `engine.find` receives is typed as the engine declares
         // it. `options` is the caller's normalized request bag, and by this line
         // every key the normalizer does not hand on has been folded, deleted or
@@ -6361,11 +6398,16 @@ export class ObjectStackProtocolImplementation implements
         // is served in keyed form — never the stored value, which beside the
         // projected body confirms a guess at the withheld material offline —
         // under the provider's key, or the process-scoped ephemeral one.
+        const found = await this.engine.find(request.object, findQuery);
+        if (listPlan.probe) {
+            assertQueryReadRows(listRead, listPlan, found.length, console);
+            delete options.limit;
+        }
         const records = await serveStoredMetadataHashColumnRows(
             request.object,
             redactStoredMetadataRows(
                 request.object,
-                await this.engine.find(request.object, findQuery),
+                found,
                 { dropType: bodyProjection.addedType },
             ),
             this.storedHashDigest(),