@@ -0,0 +1,13 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec): a plugin-driver datasource can declare its row cap, `external.rowCap`, up to a platform maximum of 10,000 (#29762)
+
+Clause-②: yes (widening) — one optional, bounded key joins the external datasource settings; the default keeps today's 1,000
+Metadata-protocol: added
+
+`ExternalDatasourceSettingsSchema` declares one optional key, `rowCap`: a whole number from 1 to `EXTERNAL_ROW_CAP_CEILING` (10,000). It is the most rows the engine reads from a plugin driver for one request, and so the most rows one read on such a datasource may match before it is refused with `EXTERNAL_ROW_CAP_EXCEEDED` (422). Absent, the cap is `EXTERNAL_ROW_CAP_DEFAULT` (1,000), today's fixed value, so no existing datasource changes. Both constants are exported from `@objectstack/spec/data`.
+
+- **Refused where it would do nothing.** On a built-in driver (which runs the whole query itself and is never capped) the key is refused at `external.rowCap`, naming the driver. On a managed datasource it is refused by the existing managed-block refusal, which names it among the keys to remove. A value above the ceiling, zero, a negative or a fraction is refused at parse. `maxRows` and `rowLimit` are folded onto `rowCap` in the refusal's suggestion.
+- **Not acted on yet.** This is the contract half. The engine's floor over a plugin driver reads the key in a following change; until then a datasource that sets it still reads at 1,000 rows. The liveness ledger grades it `planned` until that reader lands.
@@ -77,6 +77,7 @@ const result = DatasourceSchema.parse(data);
 | **credentialsRef** | `string` | optional | Reference into the secrets store; never inline credentials. Valid in every schemaMode — the one `external` key a managed datasource may carry. |
 | **connector** | `string` | optional | Name of a declared connector instance (a `connectors` entry with a `provider`) whose credential this API-backed datasource borrows — whichever kind the instance's `auth` declares (`bearer`, `api-key` or `basic`; ADR-0143 D2 adds the grant-bearing kinds), resolved the way the connector resolves it. One Connect serves both the connector's actions and this datasource's records. Exclusive with `credentialsRef`; refused on a built-in database driver and on a managed datasource. |
 | **queryTimeoutMs** | `number` | optional (default: `30000`) | Hard cap on per-query execution time. |
+| **rowCap** | `integer` | optional | Plugin-driver datasources only (a non-managed datasource whose `driver` is not a built-in id): the most rows the engine reads from the driver for one request, and so the most rows one read may match before it is refused with EXTERNAL_ROW_CAP_EXCEEDED (422). Absent: 1000. At most 10000. Each list page reads every match up to this cap from the remote, twice (the rows and the total), so raise it only as far as the widest read needs. |
 
 
 ---
@@ -119,6 +120,7 @@ External datasource settings: federation policy (schemaMode != "managed") plus t
 | **credentialsRef** | `string` | optional | Reference into the secrets store; never inline credentials. Valid in every schemaMode — the one `external` key a managed datasource may carry. |
 | **connector** | `string` | optional | Name of a declared connector instance (a `connectors` entry with a `provider`) whose credential this API-backed datasource borrows — whichever kind the instance's `auth` declares (`bearer`, `api-key` or `basic`; ADR-0143 D2 adds the grant-bearing kinds), resolved the way the connector resolves it. One Connect serves both the connector's actions and this datasource's records. Exclusive with `credentialsRef`; refused on a built-in database driver and on a managed datasource. |
 | **queryTimeoutMs** | `number` | optional (default: `30000`) | Hard cap on per-query execution time. |
+| **rowCap** | `integer` | optional | Plugin-driver datasources only (a non-managed datasource whose `driver` is not a built-in id): the most rows the engine reads from the driver for one request, and so the most rows one read may match before it is refused with EXTERNAL_ROW_CAP_EXCEEDED (422). Absent: 1000. At most 10000. Each list page reads every match up to this cap from the remote, twice (the rows and the total), so raise it only as far as the widest read needs. |
 
 ### Nested Shape: `ExternalDatasourceSettings.validation`
 
 
@@ -241,6 +241,8 @@
     "EMPTY_OPERATOR_ARMS (const)",
     "ENGINE_UPDATE_UPSERT_REMOVED (const)",
     "EXTENSION_FIELD_SUFFIX (const)",
+    "EXTERNAL_ROW_CAP_CEILING (const)",
+    "EXTERNAL_ROW_CAP_DEFAULT (const)",
     "EffectiveApiMethods (interface)",
     "EmptyOperatorArm (type)",
     "EmptyOperatorExpansion (interface)",
 
@@ -275,6 +275,7 @@
     "data/ExternalDatasourceSettings:connector",
     "data/ExternalDatasourceSettings:credentialsRef",
     "data/ExternalDatasourceSettings:queryTimeoutMs",
+    "data/ExternalDatasourceSettings:rowCap",
     "data/ExternalDatasourceSettings:validation",
     "data/ExternalTable:columns",
     "data/ExternalTable:indexes",
 
@@ -236,6 +236,8 @@
     "EMPTY_OPERATOR_ARMS": "src/data/filter-empty-operator.ts#EMPTY_OPERATOR_ARMS (const)",
     "ENGINE_UPDATE_UPSERT_REMOVED": "src/data/data-engine.zod.ts#ENGINE_UPDATE_UPSERT_REMOVED (const)",
     "EXTENSION_FIELD_SUFFIX": "src/data/field-customization.ts#EXTENSION_FIELD_SUFFIX (const)",
+    "EXTERNAL_ROW_CAP_CEILING": "src/data/datasource.zod.ts#EXTERNAL_ROW_CAP_CEILING (const)",
+    "EXTERNAL_ROW_CAP_DEFAULT": "src/data/datasource.zod.ts#EXTERNAL_ROW_CAP_DEFAULT (const)",
     "EffectiveApiMethods": "src/data/api-derivation.ts#EffectiveApiMethods (interface)",
     "EmptyOperatorArm": "src/data/filter-empty-operator.ts#EmptyOperatorArm (type)",
     "EmptyOperatorExpansion": "src/data/filter-empty-operator.ts#EmptyOperatorExpansion (interface)",
 
@@ -155,6 +155,11 @@
           "verifiedAt": "2026-08-28",
           "evidence": "packages/services/service-datasource/src/datasource-admin-service.ts#testConnection (`const queryTimeoutMs = (input.external as …)?.queryTimeoutMs`, spread onto the probe options as `timeoutMs` only when it is a number)",
           "note": "carried into the external-datasource probe options as `timeoutMs`. 2026-08-28: RE-ANCHORED (commit 9ee2dcfbd) and REPOINTED — `:220` had rotted onto a BLANK LINE, which is the most legible form of this rot: in range, resolvable, and pointing at nothing at all. Re-closed by hand against c459da6bc; DATED for the first time."
+        },
+        "rowCap": {
+          "status": "planned",
+          "verifiedAt": "2026-11-03",
+          "note": "PLANNED (#29762, maintainer ruling: a per-datasource cap bounded by a platform maximum of 10,000). The plugin-driver row cap: the most rows the engine's correctness floor reads from a plugin driver for one request, and so the most one read may match before EXTERNAL_ROW_CAP_EXCEEDED (422). Declared in the spec slice (packages/spec/src/data/datasource.zod.ts, beside `EXTERNAL_ROW_CAP_DEFAULT` and `EXTERNAL_ROW_CAP_CEILING`); refused at parse above the ceiling, on a built-in driver, and (through the managed-block refusal) on a managed datasource. ACTED ON by nothing yet: the reader is the floor in packages/objectql/src/external-driver-floor.ts, which lands in the card's second PR. Flip to `live` on the commit that lands that reader, citing it."
         }
       },
       "note": "5 of 7 live. The two dead ones are opposite in risk: `external.label` is cosmetic, `external.requirePermission` is security-shaped — it reads as an access gate and is not one."
 
@@ -12,4 +12,4 @@ committed anywhere: `check:liveness` sums the shards when it reads them.
 
 | Type | live | exp | elsewhere | dead | planned | classified |
 |---|---|---|---|---|---|---|
-| `datasource` | 31 | 0 | 0 | 0 | 0 | 31 |
+| `datasource` | 31 | 0 | 0 | 0 | 1 | 32 |
@@ -5,6 +5,8 @@ import {
   DriverType,
   SchemaModeSchema,
   ExternalDatasourceSettingsSchema,
+  EXTERNAL_ROW_CAP_CEILING,
+  EXTERNAL_ROW_CAP_DEFAULT,
   type Datasource,
 } from './datasource.zod';
 
@@ -958,3 +960,63 @@ describe('external.connector — an API-backed datasource borrows a connector in
     expect(result.success, JSON.stringify(result.error?.issues)).toBe(true);
   });
 });
+
+describe('[#29762] external.rowCap — a plugin-driver datasource\'s row cap, bounded by the platform maximum', () => {
+  const plugin = { name: 'plan', driver: 'production_plan', config: {}, schemaMode: 'external' } as const;
+
+  const issuesAt = (raw: unknown, path: string) => {
+    const result = DatasourceSchema.safeParse(raw);
+    return result.success ? [] : result.error.issues.filter((i) => i.path.join('.') === path);
+  };
+
+  it('the default and the ceiling are the ruled numbers', () => {
+    expect(EXTERNAL_ROW_CAP_DEFAULT).toBe(1000);
+    expect(EXTERNAL_ROW_CAP_CEILING).toBe(10_000);
+  });
+
+  it('accepts a whole number from 1 to the ceiling on a plugin driver, in external and validate-only modes', () => {
+    for (const schemaMode of ['external', 'validate-only'] as const) {
+      for (const rowCap of [1, 5000, EXTERNAL_ROW_CAP_CEILING]) {
+        const result = DatasourceSchema.safeParse({ ...plugin, schemaMode, external: { rowCap } });
+        expect(result.success, JSON.stringify(result.error?.issues)).toBe(true);
+        if (result.success) expect(result.data.external?.rowCap).toBe(rowCap);
+      }
+    }
+  });
+
+  it('is absent unless written — no default is stamped onto a parsed block', () => {
+    const parsed = ExternalDatasourceSettingsSchema.parse({});
+    expect(parsed).not.toHaveProperty('rowCap');
+  });
+
+  it('refuses a value above the ceiling, zero, a negative and a fraction', () => {
+    for (const rowCap of [EXTERNAL_ROW_CAP_CEILING + 1, 0, -1, 2500.5]) {
+      expect(issuesAt({ ...plugin, external: { rowCap } }, 'external.rowCap'), String(rowCap)).toHaveLength(1);
+    }
+  });
+
+  it('folds the near-miss spellings onto `rowCap`', () => {
+    for (const spelling of ['maxRows', 'rowLimit']) {
+      const result = DatasourceSchema.safeParse({ ...plugin, external: { [spelling]: 5000 } });
+      const messages = result.success ? [] : result.error.issues.map((i) => i.message);
+      expect(messages.join('\n'), spelling).toContain(`\`${spelling}\` → \`rowCap\``);
+    }
+  });
+
+  it('refuses the key on a built-in driver, which is never capped', () => {
+    const hits = issuesAt(
+      { name: 'warehouse', driver: 'sqlite', config: { filename: 'warehouse.db' }, schemaMode: 'external', external: { rowCap: 5000 } },
+      'external.rowCap',
+    );
+    expect(hits).toHaveLength(1);
+    expect(hits[0]!.code).toBe('custom');
+    expect(hits[0]!.message).toContain("'sqlite' driver is built in");
+  });
+
+  it('refuses the key on a managed datasource, through the managed-block refusal that names it', () => {
+    const result = DatasourceSchema.safeParse({ ...plugin, schemaMode: 'managed', external: { rowCap: 5000 } });
+    expect(result.success).toBe(false);
+    const messages = result.success ? [] : result.error.issues.map((i) => i.message).join('\n');
+    expect(messages).toContain('remove: rowCap');
+  });
+});
@@ -263,6 +263,26 @@ export const SchemaModeSchema = z
 
 export type SchemaMode = z.input<typeof SchemaModeSchema>;
 
+/**
+ * [#29762] How many rows the engine reads from a plugin driver for one request
+ * when the datasource sets no `external.rowCap`: the engine's correctness floor
+ * (`external-driver-floor.ts` in `@objectstack/objectql`) re-applies the whole
+ * query over the rows the driver returns, so a read matching more than this is
+ * refused (`EXTERNAL_ROW_CAP_EXCEEDED`, 422), never answered from a part.
+ */
+export const EXTERNAL_ROW_CAP_DEFAULT = 1000;
+
+/**
+ * [#29762] The platform maximum on `external.rowCap` (maintainer ruling on
+ * #29762: a per-datasource cap bounded by a platform maximum of 10,000).
+ * Refused above it at parse, as `LoopConfigSchema.maxIterations` is refused
+ * above `LOOP_MAX_ITERATIONS_CEILING`. Measured before it was set: the engine's
+ * own decode and re-application of 10,000 twelve-column rows is about 35 ms and
+ * 2 MiB per read; the remote's cost (every match, twice per list page: the rows
+ * and the total) is the operator's to judge below it.
+ */
+export const EXTERNAL_ROW_CAP_CEILING = 10_000;
+
 /**
  * External Datasource Settings (ADR-0015)
  *
@@ -301,6 +321,9 @@ export const ExternalDatasourceSettingsSchema = strictObject(
       connectorinstance: 'connector',
       timeoutms: 'queryTimeoutMs',
       querytimeout: 'queryTimeoutMs',
+      maxrows: 'rowCap',
+      rowlimit: 'rowCap',
+      maxrowcount: 'rowCap',
     },
     guidance: {
       label: RETIRED_DATASOURCE_BLOCKS.externalLabel,
@@ -373,6 +396,12 @@ export const ExternalDatasourceSettingsSchema = strictObject(
       + '`credentialsRef`; refused on a built-in database driver and on a managed datasource.'),
   queryTimeoutMs: z.number().default(30_000)
     .describe('Hard cap on per-query execution time.'),
+  rowCap: z.number().int().min(1).max(EXTERNAL_ROW_CAP_CEILING).optional()
+    .describe(`Plugin-driver datasources only (a non-managed datasource whose \`driver\` is not a built-in id): `
+      + `the most rows the engine reads from the driver for one request, and so the most rows one read may `
+      + `match before it is refused with EXTERNAL_ROW_CAP_EXCEEDED (422). Absent: ${EXTERNAL_ROW_CAP_DEFAULT}. `
+      + `At most ${EXTERNAL_ROW_CAP_CEILING}. Each list page reads every match up to this cap from the remote, `
+      + 'twice (the rows and the total), so raise it only as far as the widest read needs.'),
 })
   .describe('External datasource settings: federation policy (schemaMode != "managed") '
     + 'plus the secrets-store credentials reference (valid in every schemaMode) or the connector '
@@ -565,6 +594,19 @@ const CONNECTOR_ON_MANAGED_REFUSED =
   + "`'validate-only'` to warn on drift instead of failing) on this datasource. A managed "
   + "datasource's `external` block may carry only `credentialsRef`.";
 
+/**
+ * [#29762] `external.rowCap` on a built-in driver. The cap is read only by the
+ * engine's floor over a plugin driver; a built-in driver executes the whole
+ * query itself and is never floored, so the key would parse and do nothing.
+ * A managed datasource needs no refusal of its own: a non-default `rowCap` is
+ * a federation key, which the managed-block refusal already names.
+ */
+function rowCapOnBuiltinDriverRefusal(driverId: string): string {
+  return `\`external.rowCap\` caps the rows the engine reads from a plugin driver, which it holds behind `
+    + `its correctness floor; the '${driverId}' driver is built in, runs the whole query itself and is `
+    + 'never capped, so the key would do nothing here. Remove `rowCap`.';
+}
+
 /**
  * Replay a driver-config parse onto the datasource's own issue list (#4410).
  *
@@ -936,6 +978,18 @@ export const DatasourceSchema = lazySchema(() => strictObject(
     }
   }
 
+  // [#29762] `external.rowCap` is read only by the plugin-driver floor.
+  if (ds.external?.rowCap !== undefined) {
+    const builtinDriver = resolveDriverId(ds.driver);
+    if (builtinDriver !== undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['external', 'rowCap'],
+        message: rowCapOnBuiltinDriverRefusal(builtinDriver),
+      });
+    }
+  }
+
   if (ds.schemaMode !== 'managed' && !ds.external) {
     ctx.addIssue({
       code: 'custom',