docs(api): the batch cap is embedder-only, not the deployment's to configure

[claude]

Fixes #16940

Clause-②: no — the whole diff is content/docs/**; no contract surface is touched.

What changed

One paragraph in content/docs/api/data-api.mdx, section Batch size.

Before:

Every bulk route above — batch, createMany, updateMany, deleteMany — caps how many records one request may carry. The limit is the deployment's batch.maxBatchSize (default 200, configurable 1–1000); over it the request is rejected with 400 BATCH_TOO_LARGE before anything is written

After:

Every bulk route above — batch, createMany, updateMany, deleteMany — caps how many records one request may carry. The limit is batch.maxBatchSize, and it is embedder-only (#15543): it is written only by a host that constructs the RestServerConfig itself, never by os serve or the dev plugin. A CLI-started deployment therefore always gets the default of 200, and no flag, config file or CLI option moves it; only the embedding host can set it, anywhere in 1–1000. Over the cap the request is rejected with 400 BATCH_TOO_LARGE before anything is written

The wording was copied, not invented

The claim that this cap is "the deployment's" and reader-configurable was ruled false on 2026-09-07 (director seat, summon #17, decision batch #2, maintainer verbatim 「同意」). Two carriers were already corrected under that ruling, and this page is the third and last one still saying it in public. Every load-bearing phrase above is lifted from them:

phrase	copied from
"embedder-only"	packages/spec/src/api/rest-server.zod.ts, the WHO CAN WRITE THIS CONFIG (#15543) header — "every OTHER key here is EMBEDDER-ONLY"
"written only by a host that constructs … never by os serve or the dev plugin"	content/docs/references/api/rest-server.mdx:287 (auto-generated from the batch block's .describe()), verbatim: "embedder-only: written by a host that constructs this config, never by os serve or the dev plugin"
"a CLI-started deployment always gets the default … no flag, config file or CLI option moves it"	packages/rest/src/rest-server.ts, the enforceBatchSize docblock as #16801 left it, and the maxBatchSize REACHABILITY row in packages/spec/liveness/batch_endpoints.json
the 1–1000 range, now bound to the embedder	enforceBatchSize docblock — "The cap is RestServerConfig.batch.maxBatchSize (1..1000, default 200)"

The range is kept rather than deleted because it is true for the embedder — the false part was addressing it to this page's reader, who is precisely the party that cannot reach it. It is now attached to the only party that can.

⭐ A FOURTH carrier was swept up — filed, not fixed here

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

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

Same defect in weaker form: it drops "the deployment's" and drops the range, but still tells the reader the cap is configurable and names the key, with no statement of who may write it. It is outside this PR's fenced landing surface (content/docs/api/data-api.mdx alone), so it is filed as #17183 and left untouched here.

⚠️ Worth recording why the census did not name it: this carrier spells the key bare (maxBatchSize), so it never appears in the batch.maxBatchSize positive row — only in the maxBatchSize control row, which was carried to prove the probe reaches the tree, not to enumerate carriers. ⇒ The control token, not the positive token, is what held it. That is the same shape as this card's own subject: a probe written over one spelling of a claim is not a probe over the claim.

Token census — re-measured on this branch's base

content/ only, git grep -o … | wc -l (hit counts, not file counts), on fd5cff209f:

token	card	triage	PM	this PR
deployment policy	0	0	0	0
enforceBatchSize	0	0	0	0
batch.maxBatchSize	9	8	8	8
maxBatchSize (control)	20	19	19	19
RestServerConfig (control)	14	13	13	13

Exact match with triage and with the PM's independent re-measurement. ⛔ The card-vs-triage offset of 1 on three tokens is not explained here and this seat was not asked to explain it; no explanation is invented.

Every other maxBatchSize hit in content/ was adjudicated and is not a carrier: record-view-auditing.mdx (3, the readAudit flush buffer), references/api/contract.mdx (3, the DataLoader key), references/system/tracing.mdx (1, the OTel span processor), references/api/{batch,protocol}.mdx (6, "server caps the count", asserting nothing about configurability, and auto-generated), references/api/rest-server.mdx (3, auto-generated and already correct).

⛔ The docs-drift tool's green was not used as evidence

scripts/docs-audit/affected-docs.mjs reports 4 docs for the code-side change, all reached through the single symbol anchor RestServer, and this page is in neither list. That is structural: the page states the rule by its inputs, and the emitter's carrier is a private method (enforceBatchSize) no anchor kind reaches. A tool-reported 0 for a page of this shape is not a clean bill, so the sweep above was done by hand.

Verification

• node scripts/pm/dispatch-gates.mjs --commands derived 39 commands; all 39 run green.
• node scripts/pm/dispatch-gates.mjs --ran reconciles: 39 derived, 39 run, 0 NOT-MEASURED, 0 UNRUN.
• Five of the 39 first returned PREREQUISITE NOT MET / not-built refusals (exit 3, and exit 1 for two that refuse rather than measure). Those were read as NOT MEASURED — not as failures — and re-run green after building @objectstack/lint, @objectstack/formula, @objectstack/spec, @objectstack/client and @objectstack/client-react through the shared verify lock.
• No test change: the diff is prose only, and the behaviour it now describes correctly is already pinned on the code side by [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 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.

No changeset — measured, not assumed

Nothing published moves. content/ sits in no package directory, so it cannot appear in any published package's files[]; its only consumer, apps/docs (@objectstack/docs), is private: true with no files[] at all. Precedent on the same class: PR #16938, a content/docs/**-only prose correction, merged with skip-changeset and no changeset file. ⇒ skip-changeset applied.

验收备注

• Filed as [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 #17183 — content/docs/protocol/kernel/http-protocol.mdx:851, the fourth carrier described above.
• noted, not filed: content/docs/releases/v17/17-0.mdx:1734 carries the claim once more ("stay under batch.maxBatchSize (default 200, raisable to 1000"). RELEASE-OWNED — AGENTS.md forbids editing it in a code PR, and it needs a docs-only PR or its own card. Successor: whoever writes the next release-notes correction pass; it is also recorded inside [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 #17183 so it does not depend on this PR being read.
• noted, not filed: a path correction for anyone working from the card text. Both the card and its dispatch name content/docs/releases/v17.mdx; no such file exists on fd5cff209f — the release page was split per minor (docs(releases): split the v17 page per minor, and draft the missing 17.4.0 section #17105) and the live path is content/docs/releases/v17/17-0.mdx. The claim is on one line there, not two as the card states — one sentence carrying both the key and the range. Successor: the same release-notes pass; recorded in [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 #17183.
• noted, not filed: content/docs/references/api/rest-server.mdx is auto-generated and already carries the corrected embedder-only wording at line 287, which is what made it usable as the copy source above. No action.

---

Generated by Claude Code