[finding] `content/docs/protocol/kernel/http-protocol.mdx` calls the batch cap "configurable via `maxBatchSize`" — a FOURTH carrier of the claim #15543 / #16801 / #16940 corrected elsewhere

[baozhoutao]

Filed by the domain:devx execution seat working #16940 (session session_012GKcPZbMoGq7WPzKLfRBTU), branch claude/issue-16940-data-api-batch-cap. ⛔ Not fixed there: #16940's dispatch fenced the landing surface to content/docs/api/data-api.mdx alone and said to report a fourth carrier in the PR body rather than widen. This card is that report, promoted so the finding is not lost with the PR. Routing and grading are the triage seat's.

The sentence

content/docs/protocol/kernel/http-protocol.mdx:851, in the batch endpoint's Behavior list, verbatim:

• Maximum batch size: 200 operations by default (configurable via maxBatchSize).

Why it is the same defect

The claim that a reader of a published page can configure batch.maxBatchSize was ruled false on 2026-09-07 (director seat, summon #17, decision batch #2, maintainer verbatim 「同意」). Three carriers have now been corrected under that ruling:

1. packages/spec — [finding] No shipped boot path authors RestServerConfig at all — os serve fixes it and the dev plugin passes none, so every live crud / metadata / batch key is embedder-only #15543 / PR docs(spec): RestServerConfig's crud / metadata / batch keys are embedder-only, and the schema now says so #16775. Reachability: EMBEDDER-ONLY, plus the per-key REACHABILITY row in packages/spec/liveness/batch_endpoints.json.
2. packages/rest — [finding] rest-server.ts#enforceBatchSize calls the batch cap "deployment policy", but no shipped boot path can set it — the same defect #15543 just closed in packages/spec, one package over #16801, in the enforceBatchSize docblock.
3. content/docs/api/data-api.mdx — [finding] content/docs/api/data-api.mdx tells operators the batch cap is "the deployment's" and "configurable 1-1000" — the third carrier of the claim #15543 and #16801 corrected in code #16940, in flight on the branch above.

This page is the fourth. It is a weaker form of the claim than #16940's — it does not say "the deployment's" and does not repeat the 1–1000 range — but it carries the load-bearing half: it tells the reader the cap is configurable and names the key, with no statement of who may write it. The declared contract it contradicts is the WHO CAN WRITE THIS CONFIG (#15543) header in packages/spec/src/api/rest-server.zod.ts, verbatim:

⇒ On a CLI-started deployment every OTHER key here is EMBEDDER-ONLY: the whole of crud, metadata and batch, and the rest of api. Its value is whatever the .default() below says, and no flag, config file or CLI option moves it.

How it was found — and why the token table did not name it

#16940's hand-sweep census uses batch.maxBatchSize as its positive token. This carrier spells the key bare (maxBatchSize, no batch. prefix), so it does not appear in that row at all. It is visible only in the control row — maxBatchSize, 19 hits — which the sweep carried to prove the probe reaches the tree, not to enumerate carriers.

⚠️ That is the same shape as the hazard #16940's triage seat recorded: a probe written over one spelling of a claim is not a probe over the claim. Here the control token, not the positive token, is what held the fourth carrier. ⇒ A census whose positive token is the more specific spelling under-counts by exactly the carriers that use the shorter one.

Measured on origin/main fd5cff209f, content/ only:

token	hits
deployment policy	0
enforceBatchSize	0
batch.maxBatchSize	8
maxBatchSize (control)	19
RestServerConfig (control)	13

Every other maxBatchSize hit in content/ was adjudicated and is not a carrier:

• content/docs/permissions/record-view-auditing.mdx (3 hits) — readAudit.maxBatchSize, a different key entirely (the read-audit flush buffer).
• content/docs/references/api/contract.mdx (3 hits) — the DataLoader maxBatchSize, a different key.
• content/docs/references/system/tracing.mdx (1 hit) — the OTel batch span processor, a different key.
• content/docs/references/api/{batch,protocol}.mdx (6 hits) — "server caps the count — see batch.maxBatchSize", which asserts nothing about who configures it. Also AUTO-GENERATED.
• content/docs/references/api/rest-server.mdx (3 hits) — AUTO-GENERATED from the Zod .describe(), and line 287 already carries the corrected wording: "embedder-only: written by a host that constructs this config, never by os serve or the dev plugin".

Out of scope for a code PR, noted here so the sweep is complete

content/docs/releases/v17/17-0.mdx:1734 carries the claim once more — "stay under batch.maxBatchSize (default 200, raisable to 1000". That tree is RELEASE-OWNED and AGENTS.md forbids editing it in a code PR, so it is a dedicated docs-only PR or its own card, not a rider.

⚠️ Path correction for anyone working from #16940's text: that card and its dispatch both name content/docs/releases/v17.mdx. No such file exists on fd5cff209f — the release page has been split per minor (#17105) and the live path is content/docs/releases/v17/17-0.mdx. The claim is on one line there, not two as #16940 states; it is one sentence carrying both the key and the range.

Suggested shape

⛔ Do not invent a fifth wording. The vocabulary landed three times already: the cap is embedder-only, written only by a host that constructs the RestServerConfig itself, never by os serve or the dev plugin, so a CLI-started deployment always gets the default of 200. Copy it.

⚠️ This page's register is a terse bullet list, not the running prose of data-api.mdx, so the copy is a compression rather than a paste — that is the one judgement the fixer has to make.

Duplicate check — method stated

Repository-scoped REST /search/issues is refused by this container's egress proxy (HTTP 403, "sessions are bound to their configured repositories"), so the channel was switched and the switch is declared: one targeted MCP search_issues call.

• Result: 4 items, total_count: 4 — [finding] content/docs/api/data-api.mdx tells operators the batch cap is "the deployment's" and "configurable 1-1000" — the third carrier of the claim #15543 and #16801 corrected in code #16940, [finding] rest-server.ts#enforceBatchSize calls the batch cap "deployment policy", but no shipped boot path can set it — the same defect #15543 just closed in packages/spec, one package over #16801, pm-dispatch SKILL.md arg table says batch defaults to 3 while the maintainer's cap has been 5 since 2026-09-03 — say which is default and which is ceiling #16272, pm-dispatch: concentrated-round batch parameter ruled ≤10 cards per batch (quality first) — update dispatch-runbook.md #11980. None is a card for content/docs/protocol/kernel/**.
• Live positive control, same call: [finding] content/docs/api/data-api.mdx tells operators the batch cap is "the deployment's" and "configurable 1-1000" — the third carrier of the claim #15543 and #16801 corrected in code #16940 and [finding] rest-server.ts#enforceBatchSize calls the batch cap "deployment policy", but no shipped boot path can set it — the same defect #15543 just closed in packages/spec, one package over #16801 both had to hit, and both did ⇒ the zero for this page is a reading, not a dead index.

Refs

#15543 · #16801 · #16940 · PR #16775 · the 2026-09-07 ruling (director seat, summon #17, decision batch #2, maintainer verbatim 「同意」)