Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(subscription): bound request members and elements before parsing

Alfredo Lopez3175518de7c3
diff --git a/codex-llm-proxy/test/bodyStructure.test.ts b/codex-llm-proxy/test/bodyStructure.test.ts
index 45bd7e317..778b88bb8 100644
--- a/codex-llm-proxy/test/bodyStructure.test.ts
+++ b/codex-llm-proxy/test/bodyStructure.test.ts
@@ -22,8 +22,8 @@ import { type ProxyRuntimeDeps, createProxyApps } from '../src/server.js'
// A8: JSON.parse allocates one heap object per container, so a body that fits
// every byte limit can still exhaust the proxy heap. Every parser scans the raw
// body against BODY_STRUCTURE_LIMITS before JSON.parse runs. These tests pin
-// where each refusal happens (before the parse) and that the densest body the
-// handler accepts is never refused by the scan.
+// where each refusal happens (before the parse) and that a body at both the
+// element and byte bounds is never refused by the scan.
// Test seam: make the structure verify throw an error that carries no status,
// so body-parser wraps it as a 403 `entity.verify.failed` that the error
@@ -158,6 +158,7 @@ function measure(body: string) {
maxContainers: Number.MAX_SAFE_INTEGER,
maxDepth: Number.MAX_SAFE_INTEGER,
maxMembers: Number.MAX_SAFE_INTEGER,
+ maxElements: Number.MAX_SAFE_INTEGER,
})
}
@@ -182,6 +183,14 @@ function bodyWithMembers(schemaVersion: SchemaVersion, members: number): string
return body
}
+/** A body holding exactly `elements` JSON values, including its envelope. */
+function bodyWithElements(schemaVersion: SchemaVersion, elements: number): string {
+ const one = bodyWithFiller(schemaVersion, zeros(1))
+ const body = bodyWithFiller(schemaVersion, zeros(elements - measure(one).elements + 1))
+ expect(measure(body).elements).toBe(elements)
+ return body
+}
+
/** A body nesting exactly `depth` containers deep, the root included. */
function bodyWithDepth(depth: number): string {
// root and request hold the filler; filler adds depth - 2 arrays
@@ -195,19 +204,23 @@ function zeros(count: number): string {
return `[${new Array(count).fill('0').join(',')}]`
}
+function wideNumbers(count: number): string {
+ return `[${'10000000,'.repeat(count - 1)}10000000]`
+}
+
/**
- * The densest V2 body the handler accepts: its non-image measure equals the
- * handler's own bound, and nearly all of it is structural bytes.
+ * A V2 body at the element bound whose non-image measure also reaches the
+ * byte bound. The padding is string content and does not add elements.
*/
-function densestAcceptedV2(): string {
+function elementAndByteBoundV2(): string {
const bound = LIMITS.maxRequestBodyBytes + ENVELOPE_ALLOWANCE_BYTES
const one = JSON.parse(bodyWithFiller('codex-completion-request.v2', zeros(1), { pad: '' }))
- // Each further element adds two bytes ("0,"); `pad` takes the odd byte.
- const count = Math.floor((bound - measureNonImageCompletionBytes(one)) / 2) + 1
+ const count = BODY_STRUCTURE_LIMITS.maxElements - measure(JSON.stringify(one)).elements + 1
const draft = JSON.parse(bodyWithFiller('codex-completion-request.v2', zeros(count), { pad: '' }))
const pad = 'p'.repeat(bound - measureNonImageCompletionBytes(draft))
const body = bodyWithFiller('codex-completion-request.v2', zeros(count), { pad })
expect(measureNonImageCompletionBytes(JSON.parse(body))).toBe(bound)
+ expect(measure(body).elements).toBe(BODY_STRUCTURE_LIMITS.maxElements)
return body
}
@@ -406,6 +419,70 @@ describe('codex proxy raw-body structure bounds (A8)', () => {
expect(acquire).not.toHaveBeenCalled()
})
+ it('refuses a visual body over the element bound before JSON.parse and frees the slot', async () => {
+ const acquire = vi.spyOn(visualStreamGate, 'acquire')
+ const largeParses = spyLargeParses()
+ const port = listen(createProxyApps(config()))
+ const over = bodyWithElements('codex-completion-request.v2', BODY_STRUCTURE_LIMITS.maxElements + 1)
+ const refused = await post(port, over)
+ expect(refused.status).toBe(413)
+ expect(await refused.json()).toEqual({ error: 'payload_too_large' })
+ expect(largeParses()).not.toContain(over.length)
+ await waitFor(() => visualStreamGate.snapshot().running === 0, 'the visual slot was not released')
+
+ const atBound = bodyWithElements('codex-completion-request.v2', BODY_STRUCTURE_LIMITS.maxElements)
+ const admitted = await post(port, atBound)
+ expect(admitted.status).toBe(403)
+ expect(await admitted.json()).toEqual({ error: 'ticket_invalid' })
+ expect(acquire).toHaveBeenCalledTimes(2)
+ expect(largeParses()).toContain(atBound.length)
+ })
+
+ it('refuses an ordinary body over the element bound before JSON.parse', async () => {
+ const acquire = vi.spyOn(visualStreamGate, 'acquire')
+ const largeParses = spyLargeParses()
+ const maxBodyBytes = LIMITS.maxRequestBodyBytes + ENVELOPE_ALLOWANCE_BYTES
+ const port = listen(createProxyApps(config({ maxBodyBytes })))
+ const over = bodyWithElements('codex-completion-request.v1', BODY_STRUCTURE_LIMITS.maxElements + 1)
+ expect(over.length).toBeLessThan(maxBodyBytes)
+ const refused = await post(port, over)
+ expect(refused.status).toBe(413)
+ expect(await refused.json()).toEqual({ error: 'payload_too_large' })
+ expect(largeParses()).not.toContain(over.length)
+
+ const atBound = bodyWithElements('codex-completion-request.v1', BODY_STRUCTURE_LIMITS.maxElements)
+ const admitted = await post(port, atBound)
+ expect(admitted.status).toBe(403)
+ expect(await admitted.json()).toEqual({ error: 'ticket_invalid' })
+ expect(largeParses()).toContain(atBound.length)
+ expect(acquire).not.toHaveBeenCalled()
+ })
+
+ it('refuses an admin body over the element bound before JSON.parse', async () => {
+ const largeParses = spyLargeParses()
+ const maxBodyBytes = LIMITS.maxRequestBodyBytes + ENVELOPE_ALLOWANCE_BYTES
+ const port = listen(createProxyApps(config({ maxBodyBytes })), 'adminApp')
+ const adminBody = (elements: number): string => `{"filler":[${'0,'.repeat(elements - 3)}0]}`
+ const postAdmin = (body: string): Promise<Response> =>
+ fetch(`http://127.0.0.1:${port}/internal/admin/v1/codex/models`, {
+ method: 'POST',
+ headers: { Authorization: `Bearer ${adminPermit()}`, 'content-type': 'application/json' },
+ body,
+ })
+ const over = adminBody(BODY_STRUCTURE_LIMITS.maxElements + 1)
+ expect(measure(over).elements).toBe(BODY_STRUCTURE_LIMITS.maxElements + 1)
+ const refused = await postAdmin(over)
+ expect(refused.status).toBe(413)
+ expect(await refused.json()).toEqual({ error: 'payload_too_large' })
+ expect(largeParses()).not.toContain(over.length)
+
+ const atBound = adminBody(BODY_STRUCTURE_LIMITS.maxElements)
+ const admitted = await postAdmin(atBound)
+ expect(admitted.status).toBe(400)
+ expect(await admitted.json()).toEqual({ error: 'unknown_field' })
+ expect(largeParses()).toContain(atBound.length)
+ })
+
it('refuses an admin body with too many containers before JSON.parse', async () => {
const largeParses = spyLargeParses()
const port = listen(createProxyApps(config()), 'adminApp')
@@ -463,38 +540,39 @@ describe('codex proxy raw-body structure bounds (A8)', () => {
it('refuses a body denser than the structural bound before JSON.parse', async () => {
// Built before the spy: the builder parses strings of the same length.
- const densest = densestAcceptedV2()
+ const boundaryBody = elementAndByteBoundV2()
const largeParses = spyLargeParses()
const port = listen(createProxyApps(config({ maxBodyBytes: 4096 })))
- const base = measure(bodyWithFiller('codex-completion-request.v2', zeros(1))).structuralBytes
- const count = Math.ceil((BODY_STRUCTURE_LIMITS.maxStructuralBytes + 1 - base) / 2) + 1
- const over = bodyWithFiller('codex-completion-request.v2', zeros(count))
- const structural = base + 2 * (count - 1)
+ const base = measure(bodyWithFiller('codex-completion-request.v2', wideNumbers(1))).structuralBytes
+ const count = Math.ceil((BODY_STRUCTURE_LIMITS.maxStructuralBytes + 1 - base) / 9) + 1
+ const over = bodyWithFiller('codex-completion-request.v2', wideNumbers(count))
+ const structural = base + 9 * (count - 1)
expect(structural).toBeGreaterThan(BODY_STRUCTURE_LIMITS.maxStructuralBytes)
- expect(structural).toBeLessThanOrEqual(BODY_STRUCTURE_LIMITS.maxStructuralBytes + 2)
+ expect(structural).toBeLessThanOrEqual(BODY_STRUCTURE_LIMITS.maxStructuralBytes + 9)
+ expect(measure(over).elements).toBeLessThan(BODY_STRUCTURE_LIMITS.maxElements)
const refused = await post(port, over)
expect(refused.status).toBe(413)
expect(await refused.json()).toEqual({ error: 'payload_too_large' })
expect(largeParses()).not.toContain(over.length)
- // Witness: the densest body the handler itself accepts is parsed.
- const admitted = await post(port, densest)
+ // Witness: a body at both the element and byte bounds is parsed.
+ const admitted = await post(port, boundaryBody)
expect(admitted.status).toBe(403)
- expect(largeParses()).toContain(densest.length)
+ expect(largeParses()).toContain(boundaryBody.length)
})
- it('never refuses the densest accepted body, compact or whitespace-padded', async () => {
+ it('never refuses an element-bound body, compact or whitespace-padded', async () => {
const port = listen(createProxyApps(config({ maxBodyBytes: 4096 })))
- const densest = densestAcceptedV2()
- expect(measure(densest).structuralBytes).toBeLessThanOrEqual(BODY_STRUCTURE_LIMITS.maxStructuralBytes)
- // One tab after each comma: an indented copy would pass the 24 MiB visual
- // ceiling and be refused by its declared length before any scan.
- const padded = densest.replaceAll(',', ',\t')
- // The padding alone puts the raw body far past the structural bound.
+ const boundaryBody = elementAndByteBoundV2()
+ expect(measure(boundaryBody).structuralBytes).toBeLessThanOrEqual(BODY_STRUCTURE_LIMITS.maxStructuralBytes)
+ // Eight tabs after each comma keep the copy below the 24 MiB visual
+ // ceiling while testing that whitespace adds no elements.
+ const padded = boundaryBody.replaceAll(',', ',\t\t\t\t\t\t\t\t')
+ // The wire body grows while its structural-byte and element counts stay fixed.
expect(padded.length).toBeGreaterThan(1.4 * BODY_STRUCTURE_LIMITS.maxStructuralBytes)
expect(padded.length).toBeLessThanOrEqual(24 * 1024 * 1024)
- for (const body of [densest, padded]) {
+ for (const body of [boundaryBody, padded]) {
const res = await post(port, body)
expect(res.status).toBe(403)
expect(await res.json()).toEqual({ error: 'ticket_invalid' })
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index f95b80ddd..865f6235f 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.645",
+ "version": "0.1.646",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.645",
+ "version": "0.1.646",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index f86280923..5817feb3f 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.645",
+ "version": "0.1.646",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts b/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts
index 550c5631b..9750cf6e8 100644
--- a/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts
+++ b/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts
@@ -357,6 +357,7 @@ describe('authorize raw-body scan before JSON.parse (A8 D4)', () => {
maxContainers: Infinity,
maxDepth: Infinity,
maxMembers: Infinity,
+ maxElements: Infinity,
}
const LARGE_PARSE = 100_000
@@ -408,6 +409,8 @@ describe('authorize raw-body scan before JSON.parse (A8 D4)', () => {
* so structural bytes = 2k + tail + 7.
*/
const numbersBody = (k: number, tail: string) => `{"pad":[${'0,'.repeat(k)}${tail}]}`
+ /** Eight-digit numbers keep the structural-byte witness below the element bound. */
+ const wideNumbersBody = (k: number, tail: string) => `{"pad":[${'10000000,'.repeat(k)}${tail}]}`
/** A body `d` containers deep, the root included. */
const deepBody = (d: number) => `{"pad":${'['.repeat(d - 1)}${']'.repeat(d - 1)}}`
/** An authorize body with exactly `n` object members: `request` plus n - 1 `"mN":0` members. */
@@ -419,7 +422,8 @@ describe('authorize raw-body scan before JSON.parse (A8 D4)', () => {
maxStructuralBytes: 8404992,
maxContainers: 262160,
maxDepth: 70,
- maxMembers: 524352,
+ maxMembers: 262208,
+ maxElements: 1048640,
})
})
@@ -512,6 +516,34 @@ describe('authorize raw-body scan before JSON.parse (A8 D4)', () => {
})
}, 30_000)
+ it('refuses a body over the element bound before JSON.parse and admits the boundary', async () => {
+ const atBound = numbersBody(SCAN_LIMITS.maxElements - 3, '0')
+ const over = numbersBody(SCAN_LIMITS.maxElements - 2, '0')
+ expect(scanJsonStructure(Buffer.from(atBound), UNBOUNDED).elements).toBe(
+ SCAN_LIMITS.maxElements
+ )
+ expect(scanJsonStructure(Buffer.from(over), UNBOUNDED).elements).toBe(
+ SCAN_LIMITS.maxElements + 1
+ )
+ await withRoute(async url => {
+ const refusedParses = await largeParsesDuring(async () => {
+ const refused = await fetch(url, { method: 'POST', headers: headers(), body: over })
+ expect(refused.status).toBe(413)
+ expect(await refused.json()).toEqual({ error: 'payload_too_large' })
+ })
+ expect(refusedParses).not.toContain(over.length)
+ expect(authorizer.authorizeLlmProviderAttempt).not.toHaveBeenCalled()
+
+ fixtureAuthorizer()
+ const admittedParses = await largeParsesDuring(async () => {
+ const admitted = await fetch(url, { method: 'POST', headers: headers(), body: atBound })
+ expect(admitted.status).toBe(400)
+ })
+ expect(admittedParses).toContain(atBound.length)
+ expect(authorizer.authorizeLlmProviderAttempt).toHaveBeenCalledTimes(1)
+ })
+ }, 30_000)
+
it('bounds the authorize wrapper to the 64-member envelope allowance on a maximal request', () => {
// Every key AUTHORIZE_BODY_KEYS accepts, around a request already at
// LIMITS.maxRequestMembers: the wrapper's own members must fit the 64
@@ -542,12 +574,15 @@ describe('authorize raw-body scan before JSON.parse (A8 D4)', () => {
})
it('refuses a body denser than the structural bound before JSON.parse', async () => {
- const k = (SCAN_LIMITS.maxStructuralBytes - 10) / 2
- const atBound = numbersBody(k, '100')
- const over = numbersBody(k, '1000')
+ const k = (SCAN_LIMITS.maxStructuralBytes - 9) / 9
+ const atBound = wideNumbersBody(k, '10')
+ const over = wideNumbersBody(k, '100')
expect(scanJsonStructure(Buffer.from(atBound), UNBOUNDED).structuralBytes).toBe(
SCAN_LIMITS.maxStructuralBytes
)
+ expect(scanJsonStructure(Buffer.from(over), UNBOUNDED).elements).toBeLessThan(
+ SCAN_LIMITS.maxElements
+ )
await withRoute(async url => {
const refusedParses = await largeParsesDuring(async () => {
const refused = await fetch(url, { method: 'POST', headers: headers(), body: over })
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index af54d4f52..07867d8f0 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -242,18 +242,24 @@ raw body before parsing it.
- `LIMITS.maxRequestContainers` is 262144 objects and arrays per request, the
same in both contracts. `checkStructure` refuses one more with
`request exceeds maxRequestContainers` (`kind: 'size'`).
+- `LIMITS.maxRequestMembers` is 262144 object members and
+ `LIMITS.maxRequestElements` is 1048576 total JSON values, including the
+ root. `checkStructure` refuses one more of either with `kind: 'size'`.
- `bodyStructure.cjs`, byte-identical in both contract packages, scans the raw
bytes in one pass and tracks string and escape state. `BODY_STRUCTURE_LIMITS`
derives its bounds from `LIMITS`: 8404992 structural bytes
(`maxRequestBodyBytes` plus the 16 KiB envelope allowance; bytes inside
strings and whitespace are not counted), 262160 containers
- (`maxRequestContainers` plus 16 for the envelope) and depth 70
- (`maxNestingDepth + 6`, the control-api formula). A contract test runs the
- deepest and the largest request the contract accepts through the scan.
+ (`maxRequestContainers` plus 16 for the envelope), depth 70
+ (`maxNestingDepth + 6`, the control-api formula), 262208 members and
+ 1048640 elements (each request bound plus 64 for the envelope). For valid
+ JSON the element count is exactly one root, plus commas outside strings,
+ plus non-empty containers. Contract tests run accepted boundary requests
+ through the scan.
- The scan is the `verify` hook of every JSON parser in both proxies
(ordinary, visual and admin) and of the control-api authorize route, so it
runs after the body is read and before `JSON.parse`. A body that is too
- dense or has too many containers is answered 413 `payload_too_large`, a body
+ dense or over any count bound is answered 413 `payload_too_large`, a body
that is too deep 400 `invalid_request`, and a charset other than UTF-8 415
`unsupported_media_type`. A refused visual body frees its slot.
- body-parser attaches the raw body to these errors, so the proxies' error
@@ -286,7 +292,9 @@ refuses a history over the bound before authorize as `payload_too_large`, and
classifies it as `ContextLengthExceeded`, not retryable.
Follow-up: a refusal metric by type (`body.structure.*`) and a histogram of
-container counts per request, to check the bound against real use.
+structure counts per request, to check the bounds against real use. The
+262144-member and 1048576-element values are subject to the separate V5
+memory gate; the container measurements above do not validate them.
### Compatibility and deployment order
@@ -632,26 +640,23 @@ code the proxy constructs, and every code it refuses a request with
| -------------------------------------------------------- | --------------------------------- |
| `request exceeds maxRequestBodyBytes` | serialized UTF-8 byte cap |
| `request exceeds maxRequestBodyBytes outside image data` | non-image share of a V2 request |
- | `request exceeds maxRequestBodyBytes element bound` | element count in `checkStructure` |
+ | `request exceeds maxRequestElements` | element count in `checkStructure` |
| `messages exceed <maxMessages>` | message count |
| `messages[i].toolCalls exceed <maxToolCalls>` | tool calls on one message |
- All five mean the conversation is too long, but compaction does not reach
- them equally. The Host's context manager counts the serialized bytes and,
- for this provider, the message count against the contract's `maxMessages`,
- so it compacts before either bound. A single turn holding more than
- `maxMessages` messages stays unshrinkable, because the cut never lands
- inside a turn. `maxToolCalls` also bounds every response, so only history
- produced by another provider can carry an over-long `toolCalls` array.
-
- The element bound is named distinctly
- from the byte cap so that a user report can tell which guard fired, not
- because it is fixed differently: every element serializes to at least one
- byte, so a request of plain JSON data with more elements than the byte cap
- cannot fit under the byte cap either, and for such a request an
- element-bound refusal is always also a byte-bound one. A value that
- `JSON.stringify` drops (a function, a symbol) is still counted, so for other
- input the element bound can only refuse earlier.
+ All five are request-volume refusals mapped to context length, but
+ compaction does not reach them equally. The Host's context manager counts
+ serialized bytes and messages, but not JSON values. A single turn holding
+ more than `maxMessages` messages stays unshrinkable, because the cut never
+ lands inside a turn. `maxToolCalls` also bounds every response, so only
+ history produced by another provider can carry an over-long `toolCalls`
+ array.
+
+ The element bound is independent of the byte cap: a compact array can fit
+ in 8 MiB while holding more than 1048576 values. The distinct refusal
+ message identifies which guard fired. The Host reports it as a context
+ length failure without retry or provider failover. A large tool definition
+ can also hit this bound; conversation compaction cannot shrink definitions.
The byte cap covers the whole request, tool definitions included. A tool
catalog that alone exceeds it is refused with the same message and labelled
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 19345c7b9..2d83e26a6 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -57,11 +57,12 @@ data blanked in a temporary projection.
The contract checks a V2 request in this order:
1. the structure, before any byte is measured: nesting depth, refused as
- `request exceeds maximum nesting depth 64`, an element count bounded by
- `maxRequestBodyBytes`, refused as
- `request exceeds maxRequestBodyBytes element bound` (`kind: 'size'`), and
- the container count, refused as `request exceeds maxRequestContainers`
- (`kind: 'size'`, see "Body structure before parse" below);
+ `request exceeds maximum nesting depth 64`; at most 1048576 JSON values,
+ refused as `request exceeds maxRequestElements` (`kind: 'size'`); at most
+ 262144 object members, refused as `request exceeds maxRequestMembers`;
+ and at most 262144 containers, refused as
+ `request exceeds maxRequestContainers` (both `kind: 'size'`, see "Body
+ structure before parse" below);
2. the non-image share against `maxRequestBodyBytes`, refused as
`request exceeds maxRequestBodyBytes outside image data`;
3. the whole request against 35 MiB, refused as
@@ -439,19 +440,25 @@ parse" in `codex-subscription-transport-contract.md`. In short:
`checkStructure` refuses one more with `request exceeds maxRequestContainers`
(`kind: 'size'`). Like `maxVisualRequestBodyBytes`, it is a runtime limit and
is not published in the fixture (`RUNTIME_ONLY_LIMIT_KEYS`).
+- `LIMITS.maxRequestMembers` is 262144 object members and
+ `LIMITS.maxRequestElements` is 1048576 total JSON values, including the
+ root. Both are runtime-only limits shared with the Codex contract.
- The ordinary, visual and admin parsers run the contract's raw-body scan
(`bodyStructure.cjs`, `BODY_STRUCTURE_LIMITS`: 8404992 structural bytes,
- 262160 containers, depth 70) as their `verify` hook, before `JSON.parse`.
- Too dense or too many containers is answered 413 `payload_too_large`, too
- deep 400 `invalid_request`, a charset other than UTF-8 415
+ 262160 containers, depth 70, 262208 members and 1048640 elements) as their
+ `verify` hook, before `JSON.parse`. The element count is exactly one root,
+ plus commas outside strings, plus non-empty containers. Too dense or over
+ any count bound is answered 413 `payload_too_large`; too deep is answered
+ 400 `invalid_request`, and a charset other than UTF-8 415
`unsupported_media_type`; a refused visual body frees its slot, and the
error handler logs only the error type and status because the error carries
the raw body.
-The value was measured on the Codex proxy, which holds five bodies at once
-against this proxy's four. This proxy was measured at 524288 containers
-(three ordinary bodies and one visual body): 196.8 MiB resident. It has not
-been measured at 262144.
+The container value was measured on the Codex proxy, which holds five bodies
+at once against this proxy's four. Grok was also measured at 524288
+containers (three ordinary bodies and one visual body): 196.8 MiB resident.
+That is historical evidence for the container bound; the new member and
+element bounds require their separate V5 memory gate.
## Identity headers
@@ -676,27 +683,24 @@ code the proxy constructs, and every code it refuses a request with
| Refusal message | Guard |
| -------------------------------------------------------- | -------------------------------------- |
| `request exceeds maxRequestBodyBytes` | serialized UTF-8 byte cap |
- | `request exceeds maxRequestBodyBytes element bound` | element count in `checkStructure` |
+ | `request exceeds maxRequestElements` | element count in `checkStructure` |
| `request exceeds maxRequestBodyBytes outside image data` | non-image share of a V2 request (#784) |
| `messages exceed <maxMessages>` | message count |
| `messages[i].toolCalls exceed <maxToolCalls>` | tool calls on one message |
- All five mean the conversation is too long, but compaction does not reach
- them equally. The Host's context manager counts the serialized bytes and,
- for this provider, the message count against the contract's `maxMessages`,
- so it compacts before either bound. A single turn holding more than
- `maxMessages` messages stays unshrinkable, because the cut never lands
- inside a turn. `maxToolCalls` also bounds every response, so only history
- produced by another provider can carry an over-long `toolCalls` array.
-
- The element bound is named distinctly
- from the byte cap so that a user report can tell which guard fired, not
- because it is fixed differently: every element serializes to at least one
- byte, so a request of plain JSON data with more elements than the byte cap
- cannot fit under the byte cap either, and for such a request an
- element-bound refusal is always also a byte-bound one. A value that
- `JSON.stringify` drops (a function, a symbol) is still counted, so for other
- input the element bound can only refuse earlier.
+ All five are request-volume refusals mapped to context length, but
+ compaction does not reach them equally. The Host's context manager counts
+ serialized bytes and messages, but not JSON values. A single turn holding
+ more than `maxMessages` messages stays unshrinkable, because the cut never
+ lands inside a turn. `maxToolCalls` also bounds every response, so only
+ history produced by another provider can carry an over-long `toolCalls`
+ array.
+
+ The element bound is independent of the byte cap: a compact array can fit
+ in 8 MiB while holding more than 1048576 values. The distinct refusal
+ message identifies which guard fired. The Host reports it as a context
+ length failure without retry or provider failover. A large tool definition
+ can also hit this bound; conversation compaction cannot shrink definitions.
The byte cap covers the whole request, tool definitions included. A tool
catalog that alone exceeds it is refused with the same message and labelled
diff --git a/grok-llm-proxy/test/bodyStructure.test.ts b/grok-llm-proxy/test/bodyStructure.test.ts
index 351bb86c9..ed59c1330 100644
--- a/grok-llm-proxy/test/bodyStructure.test.ts
+++ b/grok-llm-proxy/test/bodyStructure.test.ts
@@ -22,8 +22,8 @@ import { type ProxyRuntimeDeps, createProxyApps } from '../src/server.js'
// A8: JSON.parse allocates one heap object per container, so a body that fits
// every byte limit can still exhaust the proxy heap. Every parser scans the raw
// body against BODY_STRUCTURE_LIMITS before JSON.parse runs. These tests pin
-// where each refusal happens (before the parse) and that the densest body the
-// handler accepts is never refused by the scan.
+// where each refusal happens (before the parse) and that a body at both the
+// element and byte bounds is never refused by the scan.
// Test seam: make the structure verify throw an error that carries no status,
// so body-parser wraps it as a 403 `entity.verify.failed` that the error
@@ -158,6 +158,7 @@ function measure(body: string) {
maxContainers: Number.MAX_SAFE_INTEGER,
maxDepth: Number.MAX_SAFE_INTEGER,
maxMembers: Number.MAX_SAFE_INTEGER,
+ maxElements: Number.MAX_SAFE_INTEGER,
})
}
@@ -182,6 +183,14 @@ function bodyWithMembers(schemaVersion: SchemaVersion, members: number): string
return body
}
+/** A body holding exactly `elements` JSON values, including its envelope. */
+function bodyWithElements(schemaVersion: SchemaVersion, elements: number): string {
+ const one = bodyWithFiller(schemaVersion, zeros(1))
+ const body = bodyWithFiller(schemaVersion, zeros(elements - measure(one).elements + 1))
+ expect(measure(body).elements).toBe(elements)
+ return body
+}
+
/** A body nesting exactly `depth` containers deep, the root included. */
function bodyWithDepth(depth: number): string {
// root and request hold the filler; filler adds depth - 2 arrays
@@ -195,19 +204,23 @@ function zeros(count: number): string {
return `[${new Array(count).fill('0').join(',')}]`
}
+function wideNumbers(count: number): string {
+ return `[${'10000000,'.repeat(count - 1)}10000000]`
+}
+
/**
- * The densest V2 body the handler accepts: its non-image measure equals the
- * handler's own bound, and nearly all of it is structural bytes.
+ * A V2 body at the element bound whose non-image measure also reaches the
+ * byte bound. The padding is string content and does not add elements.
*/
-function densestAcceptedV2(): string {
+function elementAndByteBoundV2(): string {
const bound = LIMITS.maxRequestBodyBytes + ENVELOPE_ALLOWANCE_BYTES
const one = JSON.parse(bodyWithFiller('grok-completion-request.v2', zeros(1), { pad: '' }))
- // Each further element adds two bytes ("0,"); `pad` takes the odd byte.
- const count = Math.floor((bound - measureNonImageCompletionBytes(one)) / 2) + 1
+ const count = BODY_STRUCTURE_LIMITS.maxElements - measure(JSON.stringify(one)).elements + 1
const draft = JSON.parse(bodyWithFiller('grok-completion-request.v2', zeros(count), { pad: '' }))
const pad = 'p'.repeat(bound - measureNonImageCompletionBytes(draft))
const body = bodyWithFiller('grok-completion-request.v2', zeros(count), { pad })
expect(measureNonImageCompletionBytes(JSON.parse(body))).toBe(bound)
+ expect(measure(body).elements).toBe(BODY_STRUCTURE_LIMITS.maxElements)
return body
}
@@ -406,6 +419,70 @@ describe('grok proxy raw-body structure bounds (A8)', () => {
expect(acquire).not.toHaveBeenCalled()
})
+ it('refuses a visual body over the element bound before JSON.parse and frees the slot', async () => {
+ const acquire = vi.spyOn(visualStreamGate, 'acquire')
+ const largeParses = spyLargeParses()
+ const port = listen(createProxyApps(config()))
+ const over = bodyWithElements('grok-completion-request.v2', BODY_STRUCTURE_LIMITS.maxElements + 1)
+ const refused = await post(port, over)
+ expect(refused.status).toBe(413)
+ expect(await refused.json()).toEqual({ error: 'payload_too_large' })
+ expect(largeParses()).not.toContain(over.length)
+ await waitFor(() => visualStreamGate.snapshot().running === 0, 'the visual slot was not released')
+
+ const atBound = bodyWithElements('grok-completion-request.v2', BODY_STRUCTURE_LIMITS.maxElements)
+ const admitted = await post(port, atBound)
+ expect(admitted.status).toBe(403)
+ expect(await admitted.json()).toEqual({ error: 'ticket_invalid' })
+ expect(acquire).toHaveBeenCalledTimes(2)
+ expect(largeParses()).toContain(atBound.length)
+ })
+
+ it('refuses an ordinary body over the element bound before JSON.parse', async () => {
+ const acquire = vi.spyOn(visualStreamGate, 'acquire')
+ const largeParses = spyLargeParses()
+ const maxBodyBytes = LIMITS.maxRequestBodyBytes + ENVELOPE_ALLOWANCE_BYTES
+ const port = listen(createProxyApps(config({ maxBodyBytes })))
+ const over = bodyWithElements('grok-completion-request.v1', BODY_STRUCTURE_LIMITS.maxElements + 1)
+ expect(over.length).toBeLessThan(maxBodyBytes)
+ const refused = await post(port, over)
+ expect(refused.status).toBe(413)
+ expect(await refused.json()).toEqual({ error: 'payload_too_large' })
+ expect(largeParses()).not.toContain(over.length)
+
+ const atBound = bodyWithElements('grok-completion-request.v1', BODY_STRUCTURE_LIMITS.maxElements)
+ const admitted = await post(port, atBound)
+ expect(admitted.status).toBe(403)
+ expect(await admitted.json()).toEqual({ error: 'ticket_invalid' })
+ expect(largeParses()).toContain(atBound.length)
+ expect(acquire).not.toHaveBeenCalled()
+ })
+
+ it('refuses an admin body over the element bound before JSON.parse', async () => {
+ const largeParses = spyLargeParses()
+ const maxBodyBytes = LIMITS.maxRequestBodyBytes + ENVELOPE_ALLOWANCE_BYTES
+ const port = listen(createProxyApps(config({ maxBodyBytes })), 'adminApp')
+ const adminBody = (elements: number): string => `{"filler":[${'0,'.repeat(elements - 3)}0]}`
+ const postAdmin = (body: string): Promise<Response> =>
+ fetch(`http://127.0.0.1:${port}/internal/admin/v1/grok/models`, {
+ method: 'POST',
+ headers: { Authorization: `Bearer ${adminPermit()}`, 'content-type': 'application/json' },
+ body,
+ })
+ const over = adminBody(BODY_STRUCTURE_LIMITS.maxElements + 1)
+ expect(measure(over).elements).toBe(BODY_STRUCTURE_LIMITS.maxElements + 1)
+ const refused = await postAdmin(over)
+ expect(refused.status).toBe(413)
+ expect(await refused.json()).toEqual({ error: 'payload_too_large' })
+ expect(largeParses()).not.toContain(over.length)
+
+ const atBound = adminBody(BODY_STRUCTURE_LIMITS.maxElements)
+ const admitted = await postAdmin(atBound)
+ expect(admitted.status).toBe(400)
+ expect(await admitted.json()).toEqual({ error: 'unknown_field' })
+ expect(largeParses()).toContain(atBound.length)
+ })
+
it('refuses an admin body with too many containers before JSON.parse', async () => {
const largeParses = spyLargeParses()
const port = listen(createProxyApps(config()), 'adminApp')
@@ -463,35 +540,36 @@ describe('grok proxy raw-body structure bounds (A8)', () => {
it('refuses a body denser than the structural bound before JSON.parse', async () => {
// Built before the spy: the builder parses strings of the same length.
- const densest = densestAcceptedV2()
+ const boundaryBody = elementAndByteBoundV2()
const largeParses = spyLargeParses()
const port = listen(createProxyApps(config({ maxBodyBytes: 4096 })))
- const base = measure(bodyWithFiller('grok-completion-request.v2', zeros(1))).structuralBytes
- const count = Math.ceil((BODY_STRUCTURE_LIMITS.maxStructuralBytes + 1 - base) / 2) + 1
- const over = bodyWithFiller('grok-completion-request.v2', zeros(count))
- const structural = base + 2 * (count - 1)
+ const base = measure(bodyWithFiller('grok-completion-request.v2', wideNumbers(1))).structuralBytes
+ const count = Math.ceil((BODY_STRUCTURE_LIMITS.maxStructuralBytes + 1 - base) / 9) + 1
+ const over = bodyWithFiller('grok-completion-request.v2', wideNumbers(count))
+ const structural = base + 9 * (count - 1)
expect(structural).toBeGreaterThan(BODY_STRUCTURE_LIMITS.maxStructuralBytes)
- expect(structural).toBeLessThanOrEqual(BODY_STRUCTURE_LIMITS.maxStructuralBytes + 2)
+ expect(structural).toBeLessThanOrEqual(BODY_STRUCTURE_LIMITS.maxStructuralBytes + 9)
+ expect(measure(over).elements).toBeLessThan(BODY_STRUCTURE_LIMITS.maxElements)
const refused = await post(port, over)
expect(refused.status).toBe(413)
expect(await refused.json()).toEqual({ error: 'payload_too_large' })
expect(largeParses()).not.toContain(over.length)
- // Witness: the densest body the handler itself accepts is parsed.
- const admitted = await post(port, densest)
+ // Witness: a body at both the element and byte bounds is parsed.
+ const admitted = await post(port, boundaryBody)
expect(admitted.status).toBe(403)
- expect(largeParses()).toContain(densest.length)
+ expect(largeParses()).toContain(boundaryBody.length)
})
- it('never refuses the densest accepted body, compact or whitespace-padded', async () => {
+ it('never refuses an element-bound body, compact or whitespace-padded', async () => {
const port = listen(createProxyApps(config({ maxBodyBytes: 4096 })))
- const densest = densestAcceptedV2()
- expect(measure(densest).structuralBytes).toBeLessThanOrEqual(BODY_STRUCTURE_LIMITS.maxStructuralBytes)
- const padded = JSON.stringify(JSON.parse(densest), null, 1)
- // The padding alone puts the raw body far past the structural bound.
- expect(padded.length).toBeGreaterThan(2 * BODY_STRUCTURE_LIMITS.maxStructuralBytes)
- for (const body of [densest, padded]) {
+ const boundaryBody = elementAndByteBoundV2()
+ expect(measure(boundaryBody).structuralBytes).toBeLessThanOrEqual(BODY_STRUCTURE_LIMITS.maxStructuralBytes)
+ const padded = JSON.stringify(JSON.parse(boundaryBody), null, 1)
+ // The padding increases wire bytes without changing structural bytes.
+ expect(padded.length).toBeGreaterThan(BODY_STRUCTURE_LIMITS.maxStructuralBytes)
+ for (const body of [boundaryBody, padded]) {
const res = await post(port, body)
expect(res.status).toBe(403)
expect(await res.json()).toEqual({ error: 'ticket_invalid' })
diff --git a/grok-llm-proxy/test/contractFreeze.test.ts b/grok-llm-proxy/test/contractFreeze.test.ts
index 3edebb5e4..f541ab539 100644
--- a/grok-llm-proxy/test/contractFreeze.test.ts
+++ b/grok-llm-proxy/test/contractFreeze.test.ts
@@ -70,6 +70,7 @@ const RUNTIME_ONLY_LIMIT_KEYS = [
'maxVisualRequestBodyBytes',
'maxRequestContainers',
'maxRequestMembers',
+ 'maxRequestElements',
] as const
type Fixture = {
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 3988e441b..5223dec4b 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.464",
+ "version": "0.1.465",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.464",
+ "version": "0.1.465",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 2a5711a66..3ba364fb1 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.464",
+ "version": "0.1.465",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/llm/__tests__/codexSubscription.test.ts b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
index 18a150cc1..21daed6f3 100644
--- a/mcp-host/src/llm/__tests__/codexSubscription.test.ts
+++ b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
@@ -293,12 +293,8 @@ describe('CodexSubscriptionProvider', () => {
it('T-C3 reports the element bound as request_limit_exceeded before authorize (#731)', async () => {
const wired = deps()
const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
- // `checkStructure` runs before `JSON.stringify`, so a structure with more
- // elements than the byte cap is refused by the element bound and never by
- // the byte measurement. Its message carries a suffix the byte bound does
- // not, which is why `CONTEXT_LENGTH_REFUSALS` matches the byte pattern as a
- // prefix: anchoring it at both ends would drop this refusal back to
- // `invalid_request` and no other test would notice.
+ // This body fits the byte cap. The independent element bound refuses it
+ // before authorize and must remain a non-retryable context-length error.
const history = [
{ role: 'user' as const, content: 'summarize the export' },
{
@@ -308,7 +304,7 @@ describe('CodexSubscriptionProvider', () => {
{
id: 'call_1',
name: 'export_rows',
- arguments: { ids: new Array<number>(LIMITS.maxRequestBodyBytes + 1).fill(0) },
+ arguments: { ids: new Array<number>(LIMITS.maxRequestElements + 1).fill(0) },
},
],
},
@@ -318,8 +314,7 @@ describe('CodexSubscriptionProvider', () => {
await expect(rejected).rejects.toBeInstanceOf(CodexAuthorizeError)
await expect(rejected).rejects.toMatchObject({
code: 'request_limit_exceeded',
- message:
- 'codex completion request rejected: request exceeds maxRequestBodyBytes element bound',
+ message: 'codex completion request rejected: request exceeds maxRequestElements',
})
expect(wired.authorize).not.toHaveBeenCalled()
expect(wired.stream).not.toHaveBeenCalled()
diff --git a/mcp-host/src/llm/__tests__/grokSubscription.test.ts b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
index 59e5d6e98..005587b16 100644
--- a/mcp-host/src/llm/__tests__/grokSubscription.test.ts
+++ b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
@@ -550,14 +550,8 @@ describe('GrokSubscriptionProvider', () => {
it('T-C3-grok reports the element bound as request_limit_exceeded before authorize (#731)', async () => {
const wired = deps()
const provider = new GrokSubscriptionProvider('grok-4.6', wired as never)
- // `checkStructure` runs before `JSON.stringify`, so a structure with more
- // elements than the byte cap is refused by the element bound
- // (`checkStructure` in `grok-provider-attempt-contract/index.cjs`) and never
- // by the byte measurement in `parseGrokCompletionRequestV1`. This test is the runtime consumer of that message
- // rename: without it nothing on the Grok path observes the difference
- // between the element bound and the byte bound. The suffix is also why the
- // byte pattern is matched as a prefix - anchoring it at both ends would drop
- // this refusal back to `invalid_request` unnoticed.
+ // This body fits the byte cap. The independent element bound refuses it
+ // before authorize and must remain a non-retryable context-length error.
const history = [
{ role: 'user' as const, content: 'summarize the export' },
{
@@ -567,7 +561,7 @@ describe('GrokSubscriptionProvider', () => {
{
id: 'call_1',
name: 'export_rows',
- arguments: { ids: new Array<number>(LIMITS.maxRequestBodyBytes + 1).fill(0) },
+ arguments: { ids: new Array<number>(LIMITS.maxRequestElements + 1).fill(0) },
},
],
},
@@ -577,7 +571,7 @@ describe('GrokSubscriptionProvider', () => {
await expect(rejected).rejects.toBeInstanceOf(CodexAuthorizeError)
await expect(rejected).rejects.toMatchObject({
code: 'request_limit_exceeded',
- message: 'request exceeds maxRequestBodyBytes element bound',
+ message: 'request exceeds maxRequestElements',
})
expect(wired.authorizer.authorize).not.toHaveBeenCalled()
expect(wired.proxy.stream).not.toHaveBeenCalled()
@@ -901,8 +895,9 @@ describe('GrokSubscriptionProvider', () => {
expect(classifyFailoverClass(limited.code, limited.retryable)).toBe('rate_limited')
expect(
- provider.classifyError(new GrokProxyError('canceled', 'aborted before authorize', false))
- .providerDispatched
+ provider.classifyError(
+ new GrokProxyError('canceled', 'aborted before authorize', { dispatched: false })
+ ).providerDispatched
).toBe(false)
expect(provider.classifyError(new Error('who knows')).providerDispatched).toBeUndefined()
})
diff --git a/mcp-host/src/llm/codexSubscription.ts b/mcp-host/src/llm/codexSubscription.ts
index 3fcadc453..cdeda771d 100644
--- a/mcp-host/src/llm/codexSubscription.ts
+++ b/mcp-host/src/llm/codexSubscription.ts
@@ -48,15 +48,15 @@ export type CodexAttemptContext = {
* Of the `fail('limit', …)` checks on a request, only these are about
* conversation volume, all in `llm-provider-attempt-contract/index.cjs`: the
* real byte bound and its non-image share on a V2 request (both in
- * `parseCodexCompletionRequestRoot`), the element bound that proxies it
+ * `parseCodexCompletionRequestRoot`), the independent element bound
* (`checkStructure`), and `maxMessages` and `messages[i].toolCalls` (both in
* `parseMessages`).
- * All five are "this conversation is too long", which is exactly what
- * `ContextLengthExceeded` — "Conversation Too Long" — promises the user.
- * Compaction reaches them unevenly. The context manager counts bytes and,
- * through the registry's `maxMessages`, the message count, so it compacts
- * before either bound; a single turn holding more than `maxMessages`
- * messages stays unshrinkable, because the cut never lands inside a turn.
+ * All five are request-volume refusals mapped to `ContextLengthExceeded` —
+ * "Conversation Too Long" in the UI. Compaction reaches them unevenly. The
+ * context manager counts bytes and, through the registry's `maxMessages`,
+ * the message count; it does not count JSON values. A single turn holding
+ * more than `maxMessages` messages stays unshrinkable, because the cut never
+ * lands inside a turn. A large tool definition is also not compactable.
* `maxToolCalls` also bounds every response, so only history produced by
* another provider can carry an over-long `toolCalls` array.
*
@@ -80,8 +80,8 @@ export type CodexAttemptContext = {
* dimension budgets alike, and `count` covers `maxMessages` and `maxImages`
* alike. A shorter conversation fixes the first of each pair and none of the
* second, so the message stays the discriminator at this boundary (#731). The
- * byte pattern is a prefix so it covers both the element bound and the
- * `outside image data` check of a V2 request.
+ * byte pattern is a prefix so it covers the `outside image data` check of a
+ * V2 request. The element bound has its own explicit pattern.
*
* `messages exceed` is defence in depth rather than a reachable branch: the
* guard below raises that exact message with this same classification before
@@ -90,6 +90,7 @@ export type CodexAttemptContext = {
*/
const CONTEXT_LENGTH_REFUSALS = [
/^request exceeds maxRequestBodyBytes/,
+ /^request exceeds maxRequestElements$/,
/^messages exceed \d+$/,
/^messages\[\d+\]\.toolCalls exceed \d+$/,
]
diff --git a/mcp-host/src/llm/grokSubscription.ts b/mcp-host/src/llm/grokSubscription.ts
index 103618e82..df4f5fa91 100644
--- a/mcp-host/src/llm/grokSubscription.ts
+++ b/mcp-host/src/llm/grokSubscription.ts
@@ -57,15 +57,15 @@ export type GrokAttemptContext = {
*
* Of the `fail('limit', …)` checks on a request, only these are about volume:
* the real byte bound and its non-image share on a V2 request (both in
- * `parseGrokCompletionRequestRoot`), the element bound that proxies it
+ * `parseGrokCompletionRequestRoot`), the independent element bound
* (`checkStructure`), and `maxMessages` and `messages[i].toolCalls` (both in
* `parseMessages`).
- * All five are "this conversation is too long", which is exactly what
- * `ContextLengthExceeded` — "Conversation Too Long" — promises the user.
- * Compaction reaches them unevenly. The context manager counts bytes and,
- * through the registry's `maxMessages`, the message count, so it compacts
- * before either bound; a single turn holding more than `maxMessages`
- * messages stays unshrinkable, because the cut never lands inside a turn.
+ * All five are request-volume refusals mapped to `ContextLengthExceeded` —
+ * "Conversation Too Long" in the UI. Compaction reaches them unevenly. The
+ * context manager counts bytes and, through the registry's `maxMessages`,
+ * the message count; it does not count JSON values. A single turn holding
+ * more than `maxMessages` messages stays unshrinkable, because the cut never
+ * lands inside a turn. A large tool definition is also not compactable.
* `maxToolCalls` also bounds every response, so only history produced by
* another provider can carry an over-long `toolCalls` array.
*
@@ -90,8 +90,8 @@ export type GrokAttemptContext = {
* byte budgets alike, and a shorter conversation fixes the first and not the
* second. `count` is only ever `maxImages`; the `maxMessages` and tool-call
* refusals carry no `kind`. So the message stays the discriminator at this
- * boundary (#731). The byte pattern is a prefix so it covers the element
- * bound's own wording and the `outside image data` check of a V2 request.
+ * boundary (#731). The byte pattern is a prefix so it covers the `outside
+ * image data` check of a V2 request. The element bound has its own pattern.
*
* `messages exceed` is defence in depth rather than a reachable branch: the
* guard in `execute` raises that exact message with this same classification
@@ -100,6 +100,7 @@ export type GrokAttemptContext = {
*/
const CONTEXT_LENGTH_REFUSALS = [
/^request exceeds maxRequestBodyBytes/,
+ /^request exceeds maxRequestElements$/,
/^messages exceed \d+$/,
/^messages\[\d+\]\.toolCalls exceed \d+$/,
]
diff --git a/packages/grok-provider-attempt-contract/bodyStructure.cjs b/packages/grok-provider-attempt-contract/bodyStructure.cjs
index 818104ce2..bfd12ecfb 100644
--- a/packages/grok-provider-attempt-contract/bodyStructure.cjs
+++ b/packages/grok-provider-attempt-contract/bodyStructure.cjs
@@ -22,6 +22,9 @@
* envelope level around it.
* - members: every `:` outside a string, i.e. one per object member, bounded
* by the contract's `maxRequestMembers` plus the envelope's own members.
+ * - elements: every JSON value, including the root, bounded by the contract's
+ * `maxRequestElements` plus the envelope's own values. For valid JSON this
+ * equals 1 + commas outside strings + non-empty containers.
*
* Only UTF-8 is scanned. In UTF-16 or UTF-32 a quote or backslash byte can
* be half of another character, so the scan would lose track of strings; any
@@ -73,19 +76,28 @@ function tooManyMembers(maxMembers) {
)
}
+function tooManyElements(maxElements) {
+ return new BodyStructureError(
+ 413,
+ 'body.structure.too.many.elements',
+ `request body exceeds ${maxElements} elements`
+ )
+}
+
/**
* Scans `buf` (a Buffer holding UTF-8 JSON) and throws a BodyStructureError
* on the first bound it crosses. Returns the counts it measured. It does not
* validate JSON syntax; JSON.parse still does that.
*/
function scanJsonStructure(buf, limits) {
- const { maxStructuralBytes, maxContainers, maxDepth, maxMembers } = limits
+ const { maxStructuralBytes, maxContainers, maxDepth, maxMembers, maxElements } = limits
const length = buf.length
let structuralBytes = 0
let containers = 0
let depth = 0
let deepest = 0
let members = 0
+ let elements = 1
let i = 0
while (i < length) {
const byte = buf[i]
@@ -119,15 +131,29 @@ function scanJsonStructure(buf, limits) {
)
}
if (depth > deepest) deepest = depth
+ // Empty containers add no child value. This lookahead visits whitespace
+ // at most once more than the main scan and does not parse JSON.
+ let next = i + 1
+ while (
+ next < length &&
+ (buf[next] === 0x20 || buf[next] === 0x09 || buf[next] === 0x0a || buf[next] === 0x0d)
+ ) next++
+ if (next < length && buf[next] !== (byte === 0x7b ? 0x7d : 0x5d)) {
+ elements++
+ if (elements > maxElements) throw tooManyElements(maxElements)
+ }
} else if (byte === 0x7d || byte === 0x5d) {
depth--
} else if (byte === 0x3a) {
members++
if (members > maxMembers) throw tooManyMembers(maxMembers)
+ } else if (byte === 0x2c) {
+ elements++
+ if (elements > maxElements) throw tooManyElements(maxElements)
}
i++
}
- return { structuralBytes, containers, deepest, members }
+ return { structuralBytes, containers, deepest, members, elements }
}
/**
@@ -137,7 +163,7 @@ function scanJsonStructure(buf, limits) {
* body attached as `err.body`, so a handler must never log the error object.
*/
function createBodyStructureVerify(limits) {
- for (const name of ['maxStructuralBytes', 'maxContainers', 'maxDepth', 'maxMembers']) {
+ for (const name of ['maxStructuralBytes', 'maxContainers', 'maxDepth', 'maxMembers', 'maxElements']) {
const value = limits[name]
if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
throw new TypeError(`body structure limit ${name} must be a positive safe integer`)
@@ -148,6 +174,7 @@ function createBodyStructureVerify(limits) {
maxContainers: limits.maxContainers,
maxDepth: limits.maxDepth,
maxMembers: limits.maxMembers,
+ maxElements: limits.maxElements,
})
return function verifyBodyStructure(_req, _res, buf, encoding) {
if (encoding !== 'utf-8') {
diff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjs
index 0eea4c28f..2bbaaa81c 100644
--- a/packages/grok-provider-attempt-contract/index.cjs
+++ b/packages/grok-provider-attempt-contract/index.cjs
@@ -24,15 +24,15 @@ const COMPLETIONS_ORIGIN = 'https://cli-chat-proxy.grok.com/v1/responses'
const CATALOG_ORIGIN = 'https://cli-chat-proxy.grok.com/v1/models'
const MAX_REQUEST_BODY_BYTES = 8388608
-const MAX_REQUEST_MEMBERS = 524288
+const MAX_REQUEST_MEMBERS = 262144
const MIB = 1024 * 1024
const LIMITS = Object.freeze({
// 8 MiB of serialized request (#731). A 1M-token window is about 4 MB of
// text, and escaped JSON tool results cost 1.3-1.5x that, so this covers the
// largest listed model window; past it the model refuses on tokens first.
- // It is a non-image cap, and the element bound in checkStructure follows
- // this value 1:1.
+ // It is a non-image cap. The separate element bound below prevents a
+ // compact body from allocating too many primitive values during JSON.parse.
maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
// V2 request/envelope ceiling: the whole image budget encoded as base64
// (27962028 bytes) plus the non-image share, rounded up to a whole MiB,
@@ -76,8 +76,12 @@ const LIMITS = Object.freeze({
// with tiny values fits the byte cap with millions of members and exhausts
// the proxy heap before the request is ever authorized. A realistic
// request is about 190k members (A9 model window), and this bound leaves
- // more than twice that headroom. Must equal the Codex contract's value.
+ // about 1.38 times that headroom. Must equal the Codex contract's value.
maxRequestMembers: MAX_REQUEST_MEMBERS,
+ // Total JSON values in one request, including the root. A compact array of
+ // zeros fits the byte cap while JSON.parse allocates an element per value.
+ // Must equal the Codex contract's value.
+ maxRequestElements: 1048576,
// How long an execution ticket stays redeemable after authorize. control-api
// signs Grok tickets with this TTL, and the proxy bounds its admission waits
// against the remaining ticket life, so both read it from here (#739).
@@ -119,6 +123,7 @@ const BODY_STRUCTURE_LIMITS = Object.freeze({
maxContainers: LIMITS.maxRequestContainers + ENVELOPE_CONTAINER_ALLOWANCE,
maxDepth: MAX_REQUEST_DEPTH + 1,
maxMembers: LIMITS.maxRequestMembers + ENVELOPE_MEMBER_ALLOWANCE,
+ maxElements: LIMITS.maxRequestElements + ENVELOPE_MEMBER_ALLOWANCE,
})
const ID_PATTERN = /^[A-Za-z0-9._:/-]{1,128}$/
@@ -370,11 +375,9 @@ function rejectUnknown(obj, allowed, label) {
/**
* Iterative structural pre-check, safe on arbitrarily deep or cyclic input.
* Returns a failure when containers nest deeper than `maxDepth`, when the
- * value holds more elements than a maxRequestBodyBytes JSON document can encode
- * (every encoded element takes at least one byte, so no acceptable request
- * reaches that count), or when it holds more than maxRequestContainers objects
- * and arrays. Shared references are counted per occurrence, as JSON would
- * serialize them.
+ * value holds more than maxRequestElements JSON values or more than
+ * maxRequestContainers objects and arrays. Shared references are counted per
+ * occurrence, as JSON would serialize them.
*/
function checkStructure(value, maxDepth) {
if (value === null || typeof value !== 'object') return null
@@ -392,18 +395,8 @@ function checkStructure(value, maxDepth) {
? node
: Object.values(node).filter(child => child !== undefined)
elements += children.length
- if (elements > LIMITS.maxRequestBodyBytes) {
- // Named distinctly from the byte measurement below, which refuses with
- // the bare `request exceeds maxRequestBodyBytes`. Both are `limit`
- // failures of `kind: 'size'`, so the wording is the only thing that
- // tells a user report which guard fired.
- // The remedy is the same for both - compaction - and the bound is reused
- // rather than given a constant of its own: every element serializes to
- // at least one byte, so a request of plain JSON data with more elements
- // than the byte cap cannot fit under it either (#731). A value that
- // JSON.stringify drops (a function, a symbol) is still counted here, so
- // for such input this bound can only refuse earlier, never later.
- return fail('limit', 'request exceeds maxRequestBodyBytes element bound', 'size')
+ if (elements > LIMITS.maxRequestElements) {
+ return fail('limit', 'request exceeds maxRequestElements', 'size')
}
if (!Array.isArray(node)) {
members += Object.keys(node).length
diff --git a/packages/grok-provider-attempt-contract/index.d.ts b/packages/grok-provider-attempt-contract/index.d.ts
index 251b02bd9..5b97f4685 100644
--- a/packages/grok-provider-attempt-contract/index.d.ts
+++ b/packages/grok-provider-attempt-contract/index.d.ts
@@ -34,7 +34,9 @@ export declare const LIMITS: {
/** Objects and arrays in one request, the root included; equal to the Codex contract's. */
readonly maxRequestContainers: 262144
/** Object members in one request, over every object in the tree; equal to the Codex contract's. */
- readonly maxRequestMembers: 524288
+ readonly maxRequestMembers: 262144
+ /** JSON values in one request, including the root; equal to the Codex contract's. */
+ readonly maxRequestElements: 1048576
/** Execution ticket TTL; control-api signs Grok tickets with it. */
readonly executionTicketTtlMs: 60000
}
@@ -54,7 +56,8 @@ export declare const BODY_STRUCTURE_LIMITS: {
readonly maxStructuralBytes: 8404992
readonly maxContainers: 262160
readonly maxDepth: 70
- readonly maxMembers: 524352
+ readonly maxMembers: 262208
+ readonly maxElements: 1048640
}
export interface BodyStructureLimits {
@@ -62,12 +65,14 @@ export interface BodyStructureLimits {
readonly maxContainers: number
readonly maxDepth: number
readonly maxMembers: number
+ readonly maxElements: number
}
/**
* Thrown by the scan. `type` is `body.structure.too.dense` (413),
* `body.structure.too.many.containers` (413), `body.structure.too.deep` (400),
- * `body.structure.too.many.members` (413) or, from the verify hook,
+ * `body.structure.too.many.members` (413),
+ * `body.structure.too.many.elements` (413) or, from the verify hook,
* `charset.unsupported` (415).
*/
export interface BodyStructureError extends Error {
@@ -80,7 +85,7 @@ export interface BodyStructureError extends Error {
export declare function scanJsonStructure(
buf: Uint8Array,
limits: BodyStructureLimits
-): { structuralBytes: number; containers: number; deepest: number; members: number }
+): { structuralBytes: number; containers: number; deepest: number; members: number; elements: number }
/**
* A body-parser `verify` hook running scanJsonStructure. The error it throws
diff --git a/packages/grok-provider-attempt-contract/index.test.cjs b/packages/grok-provider-attempt-contract/index.test.cjs
index 57c1e60ef..618671d64 100644
--- a/packages/grok-provider-attempt-contract/index.test.cjs
+++ b/packages/grok-provider-attempt-contract/index.test.cjs
@@ -415,21 +415,16 @@ test('T-E2 the element bound reports itself distinctly from the byte bound', ()
// not name the guard that fired. Compaction is the remedy either way; the
// distinct wording buys diagnosis, not a different fix (#731).
//
- // What makes the two guards separable here is ORDER, not size:
- // `checkStructure` runs before `JSON.stringify`, so the element count is
- // refused first. The payload below is also ~3x the byte cap once serialized
- // — by construction it has to be, since more elements than the byte cap
- // cannot encode under it — so without that ordering the byte bound would
- // claim it and this test would be pinning the wrong guard.
+ // The shape fits the byte bound; only the element count refuses it.
const refused = contract.parseGrokCompletionRequestV1({
...BASE,
- messages: new Array(contract.LIMITS.maxRequestBodyBytes + 1).fill({}),
+ messages: new Array(contract.LIMITS.maxRequestElements + 1).fill(0),
})
assert.deepEqual(refused, {
ok: false,
code: 'limit',
kind: 'size',
- message: 'request exceeds maxRequestBodyBytes element bound',
+ message: 'request exceeds maxRequestElements',
})
})
@@ -449,13 +444,13 @@ test("fail carries kind:'size' on the byte bound and the element bound", () => {
})
const elements = contract.hashCanonicalGrokRequest({
...BASE,
- messages: new Array(contract.LIMITS.maxRequestBodyBytes + 1).fill({}),
+ messages: new Array(contract.LIMITS.maxRequestElements + 1).fill(0),
})
assert.deepEqual(elements, {
ok: false,
code: 'limit',
kind: 'size',
- message: 'request exceeds maxRequestBodyBytes element bound',
+ message: 'request exceeds maxRequestElements',
})
// Witness: a failure that is not a size bound carries no kind.
const wrongProvider = contract.hashCanonicalGrokRequest({ ...BASE, provider: 'codex-subscription' })
@@ -1496,10 +1491,61 @@ function requestWithMembers(target) {
}
test('LIMITS.maxRequestMembers is pinned and equal to the Codex contract', () => {
- assert.equal(contract.LIMITS.maxRequestMembers, 524288)
+ assert.equal(contract.LIMITS.maxRequestMembers, 262144)
assert.equal(contract.LIMITS.maxRequestMembers, codexContract.LIMITS.maxRequestMembers)
})
+/** Count JSON values independently of the contract's structural pre-check. */
+function countElements(value) {
+ let elements = 1
+ const stack = [value]
+ while (stack.length > 0) {
+ const node = stack.pop()
+ if (node === null || typeof node !== 'object') continue
+ const children = Array.isArray(node) ? node : Object.values(node)
+ elements += children.length
+ for (const child of children) if (child !== null && typeof child === 'object') stack.push(child)
+ }
+ return elements
+}
+
+function requestWithElements(target) {
+ const filler = []
+ const request = {
+ ...BASE,
+ tools: [{ name: 'eventasks__read', description: 'd', parameters: { type: 'object', enum: filler } }],
+ }
+ filler.length = target - countElements(request)
+ filler.fill(0)
+ assert.equal(countElements(request), target)
+ return request
+}
+
+test('LIMITS.maxRequestElements is pinned and equal to the Codex contract', () => {
+ assert.equal(contract.LIMITS.maxRequestElements, 1048576)
+ assert.equal(contract.LIMITS.maxRequestElements, codexContract.LIMITS.maxRequestElements)
+})
+
+test("a request over maxRequestElements is refused with kind:'size'", () => {
+ const limit = contract.LIMITS.maxRequestElements
+ const at = requestWithElements(limit)
+ assert.equal(contract.parseGrokCompletionRequest(at).ok, true)
+ const over = requestWithElements(limit + 1)
+ assert.ok(Buffer.byteLength(JSON.stringify(over), 'utf8') < contract.LIMITS.maxRequestBodyBytes)
+ const expected = {
+ ok: false,
+ code: 'limit',
+ kind: 'size',
+ message: 'request exceeds maxRequestElements',
+ }
+ assert.deepEqual(refusalOf(contract.parseGrokCompletionRequest(over)), expected)
+ assert.deepEqual(refusalOf(contract.hashCanonicalGrokRequest(over)), expected)
+ assert.deepEqual(
+ refusalOf(contract.parseGrokCompletionRequest({ ...over, schemaVersion: 'grok-completion-request.v2' })),
+ expected
+ )
+})
+
test("a request over maxRequestMembers is refused with kind:'size'", () => {
const limit = contract.LIMITS.maxRequestMembers
const at = requestWithMembers(limit)
@@ -1536,12 +1582,14 @@ test('BODY_STRUCTURE_LIMITS derive from LIMITS and match the Codex contract', ()
maxContainers: contract.LIMITS.maxRequestContainers + 16,
maxDepth: contract.LIMITS.maxNestingDepth + 6,
maxMembers: contract.LIMITS.maxRequestMembers + 64,
+ maxElements: contract.LIMITS.maxRequestElements + 64,
})
assert.deepEqual(limits, {
maxStructuralBytes: 8404992,
maxContainers: 262160,
maxDepth: 70,
- maxMembers: 524352,
+ maxMembers: 262208,
+ maxElements: 1048640,
})
assert.deepEqual(limits, codexContract.BODY_STRUCTURE_LIMITS)
assert.equal(Object.isFrozen(limits), true)
@@ -1556,15 +1604,17 @@ function referenceStructure(text) {
for (const ch of stripped) if (ch === ':') members++
let containers = 0
let deepest = 0
+ let elements = 0
const stack = [[JSON.parse(text), 1]]
while (stack.length > 0) {
const [node, depth] = stack.pop()
+ elements++
if (node === null || typeof node !== 'object') continue
containers++
if (depth > deepest) deepest = depth
for (const child of Object.values(node)) stack.push([child, depth + 1])
}
- return { structuralBytes, containers, deepest, members }
+ return { structuralBytes, containers, deepest, members, elements }
}
test('the body scan matches a reference walk, escapes and whitespace included', () => {
@@ -1618,7 +1668,7 @@ test('the body scan refuses nesting past the request depth plus the envelope lev
})
test('the body scan bounds structural bytes and never counts whitespace or string contents', () => {
- const limits = contract.BODY_STRUCTURE_LIMITS
+ const limits = { ...contract.BODY_STRUCTURE_LIMITS, maxElements: Number.MAX_SAFE_INTEGER }
// `[` + `0,` x n + `00]` holds 2n + 4 structural bytes.
const count = (limits.maxStructuralBytes - 4) / 2
const atBound = Buffer.from(`[${'0,'.repeat(count)}00]`)
@@ -1655,6 +1705,26 @@ test('the body scan bounds object members and never counts string contents', ()
assert.equal(contract.scanJsonStructure(quoted, limits).members, 0)
})
+test('the body scan counts values exactly and bounds elements before JSON.parse', () => {
+ const limits = contract.BODY_STRUCTURE_LIMITS
+ for (const [json, elements] of [
+ ['{"a":0}', 2],
+ ['[{},{}]', 3],
+ ['[ 0 , "x,[{}]", {"a": [1, 2]} ]', 7],
+ ['{"a\\\"[,": "\\\\,]"}', 2],
+ ]) {
+ assert.equal(contract.scanJsonStructure(Buffer.from(json), limits).elements, elements, json)
+ }
+ const at = Buffer.from(`[${'0,'.repeat(limits.maxElements - 2)}0]`)
+ assert.equal(contract.scanJsonStructure(at, limits).elements, limits.maxElements)
+ const over = Buffer.from(`[${'0,'.repeat(limits.maxElements - 1)}0]`)
+ assert.throws(() => contract.scanJsonStructure(over, limits), {
+ name: 'BodyStructureError',
+ status: 413,
+ type: 'body.structure.too.many.elements',
+ })
+})
+
test('the body scan admits every request the contract admits, at each bound', () => {
const limits = contract.BODY_STRUCTURE_LIMITS
// Containers: the request at maxRequestContainers, inside a proxy envelope.
@@ -1694,7 +1764,7 @@ test('the verify hook refuses a charset other than UTF-8 and scans UTF-8 bodies'
test('the verify hook fails closed unless every bound is a positive safe integer', () => {
const good = contract.BODY_STRUCTURE_LIMITS
- for (const name of ['maxStructuralBytes', 'maxContainers', 'maxDepth', 'maxMembers']) {
+ for (const name of ['maxStructuralBytes', 'maxContainers', 'maxDepth', 'maxMembers', 'maxElements']) {
for (const value of [undefined, 0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1]) {
assert.throws(() => contract.createBodyStructureVerify({ ...good, [name]: value }), TypeError)
}
diff --git a/packages/llm-provider-attempt-contract/bodyStructure.cjs b/packages/llm-provider-attempt-contract/bodyStructure.cjs
index 818104ce2..bfd12ecfb 100644
--- a/packages/llm-provider-attempt-contract/bodyStructure.cjs
+++ b/packages/llm-provider-attempt-contract/bodyStructure.cjs
@@ -22,6 +22,9 @@
* envelope level around it.
* - members: every `:` outside a string, i.e. one per object member, bounded
* by the contract's `maxRequestMembers` plus the envelope's own members.
+ * - elements: every JSON value, including the root, bounded by the contract's
+ * `maxRequestElements` plus the envelope's own values. For valid JSON this
+ * equals 1 + commas outside strings + non-empty containers.
*
* Only UTF-8 is scanned. In UTF-16 or UTF-32 a quote or backslash byte can
* be half of another character, so the scan would lose track of strings; any
@@ -73,19 +76,28 @@ function tooManyMembers(maxMembers) {
)
}
+function tooManyElements(maxElements) {
+ return new BodyStructureError(
+ 413,
+ 'body.structure.too.many.elements',
+ `request body exceeds ${maxElements} elements`
+ )
+}
+
/**
* Scans `buf` (a Buffer holding UTF-8 JSON) and throws a BodyStructureError
* on the first bound it crosses. Returns the counts it measured. It does not
* validate JSON syntax; JSON.parse still does that.
*/
function scanJsonStructure(buf, limits) {
- const { maxStructuralBytes, maxContainers, maxDepth, maxMembers } = limits
+ const { maxStructuralBytes, maxContainers, maxDepth, maxMembers, maxElements } = limits
const length = buf.length
let structuralBytes = 0
let containers = 0
let depth = 0
let deepest = 0
let members = 0
+ let elements = 1
let i = 0
while (i < length) {
const byte = buf[i]
@@ -119,15 +131,29 @@ function scanJsonStructure(buf, limits) {
)
}
if (depth > deepest) deepest = depth
+ // Empty containers add no child value. This lookahead visits whitespace
+ // at most once more than the main scan and does not parse JSON.
+ let next = i + 1
+ while (
+ next < length &&
+ (buf[next] === 0x20 || buf[next] === 0x09 || buf[next] === 0x0a || buf[next] === 0x0d)
+ ) next++
+ if (next < length && buf[next] !== (byte === 0x7b ? 0x7d : 0x5d)) {
+ elements++
+ if (elements > maxElements) throw tooManyElements(maxElements)
+ }
} else if (byte === 0x7d || byte === 0x5d) {
depth--
} else if (byte === 0x3a) {
members++
if (members > maxMembers) throw tooManyMembers(maxMembers)
+ } else if (byte === 0x2c) {
+ elements++
+ if (elements > maxElements) throw tooManyElements(maxElements)
}
i++
}
- return { structuralBytes, containers, deepest, members }
+ return { structuralBytes, containers, deepest, members, elements }
}
/**
@@ -137,7 +163,7 @@ function scanJsonStructure(buf, limits) {
* body attached as `err.body`, so a handler must never log the error object.
*/
function createBodyStructureVerify(limits) {
- for (const name of ['maxStructuralBytes', 'maxContainers', 'maxDepth', 'maxMembers']) {
+ for (const name of ['maxStructuralBytes', 'maxContainers', 'maxDepth', 'maxMembers', 'maxElements']) {
const value = limits[name]
if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
throw new TypeError(`body structure limit ${name} must be a positive safe integer`)
@@ -148,6 +174,7 @@ function createBodyStructureVerify(limits) {
maxContainers: limits.maxContainers,
maxDepth: limits.maxDepth,
maxMembers: limits.maxMembers,
+ maxElements: limits.maxElements,
})
return function verifyBodyStructure(_req, _res, buf, encoding) {
if (encoding !== 'utf-8') {
diff --git a/packages/llm-provider-attempt-contract/index.cjs b/packages/llm-provider-attempt-contract/index.cjs
index 1bb2cdd3e..a3e704641 100644
--- a/packages/llm-provider-attempt-contract/index.cjs
+++ b/packages/llm-provider-attempt-contract/index.cjs
@@ -22,7 +22,7 @@ const LIMITS = Object.freeze({
// largest listed model window; past it the model refuses on tokens first.
// It is the V1 ceiling, and the V2 ceiling for everything that is not image
// data; `measureNonImageRequestBytes` below enforces the second half. The
- // element bound in checkStructure follows this value 1:1.
+ // separate element bound below limits compact arrays of primitive values.
maxRequestBodyBytes: 8388608,
/**
* V2 request/envelope ceiling. It is larger than `maxRequestBodyBytes`
@@ -62,8 +62,12 @@ const LIMITS = Object.freeze({
// with tiny values fits the byte cap with millions of members and exhausts
// the proxy heap before the request is ever authorized. A realistic
// request is about 190k members (A9 model window), and this bound leaves
- // more than twice that headroom. Must equal the Grok contract's value.
- maxRequestMembers: 524288,
+ // about 1.38 times that headroom. Must equal the Grok contract's value.
+ maxRequestMembers: 262144,
+ // Total JSON values in one request, including the root. A compact array of
+ // zeros fits the byte cap while JSON.parse allocates an element per value.
+ // Must equal the Grok contract's value.
+ maxRequestElements: 1048576,
// How long an execution ticket stays redeemable after authorize. control-api
// signs tickets with this TTL, and the proxy bounds its admission waits
// against the remaining ticket life, so both read it from here (#739).
@@ -106,6 +110,7 @@ const BODY_STRUCTURE_LIMITS = Object.freeze({
maxContainers: LIMITS.maxRequestContainers + ENVELOPE_CONTAINER_ALLOWANCE,
maxDepth: MAX_REQUEST_DEPTH + 1,
maxMembers: LIMITS.maxRequestMembers + ENVELOPE_MEMBER_ALLOWANCE,
+ maxElements: LIMITS.maxRequestElements + ENVELOPE_MEMBER_ALLOWANCE,
})
const ID_PATTERN = /^[A-Za-z0-9._:/-]{1,128}$/
@@ -349,11 +354,9 @@ function rejectUnknown(obj, allowed, label) {
/**
* Iterative structural pre-check, safe on arbitrarily deep or cyclic input.
* Returns a failure when containers nest deeper than `maxDepth`, when the
- * value holds more elements than a maxRequestBodyBytes JSON document can encode
- * (every encoded element takes at least one byte, so no acceptable request
- * reaches that count), or when it holds more than maxRequestContainers objects
- * and arrays. Shared references are counted per occurrence, as JSON would
- * serialize them.
+ * value holds more than maxRequestElements JSON values or more than
+ * maxRequestContainers objects and arrays. Shared references are counted per
+ * occurrence, as JSON would serialize them.
*/
function checkStructure(value, maxDepth) {
if (value === null || typeof value !== 'object') return null
@@ -373,18 +376,8 @@ function checkStructure(value, maxDepth) {
}
const children = Array.isArray(node) ? node : Object.values(node).filter(child => child !== undefined)
elements += children.length
- if (elements > LIMITS.maxRequestBodyBytes) {
- // Named distinctly from the byte measurement below, which refuses with
- // the bare `request exceeds maxRequestBodyBytes`. Both are `limit`
- // failures of kind `size`, so the wording is the only thing that tells a
- // user report which guard fired.
- // The remedy is the same for both - compaction - and the bound is reused
- // rather than given a constant of its own: every element serializes to
- // at least one byte, so a request of plain JSON data with more elements
- // than the byte cap cannot fit under it either (#731). A value that
- // JSON.stringify drops (a function, a symbol) is still counted here, so
- // for such input this bound can only refuse earlier, never later.
- return fail('limit', 'request exceeds maxRequestBodyBytes element bound', 'size')
+ if (elements > LIMITS.maxRequestElements) {
+ return fail('limit', 'request exceeds maxRequestElements', 'size')
}
if (!Array.isArray(node)) {
members += Object.keys(node).length
diff --git a/packages/llm-provider-attempt-contract/index.d.ts b/packages/llm-provider-attempt-contract/index.d.ts
index 83d846c9f..1feaecbac 100644
--- a/packages/llm-provider-attempt-contract/index.d.ts
+++ b/packages/llm-provider-attempt-contract/index.d.ts
@@ -41,7 +41,9 @@ export declare const LIMITS: {
/** Objects and arrays in one request, the root included; equal to the Grok contract's. */
readonly maxRequestContainers: 262144
/** Object members in one request, over every object in the tree; equal to the Grok contract's. */
- readonly maxRequestMembers: 524288
+ readonly maxRequestMembers: 262144
+ /** JSON values in one request, including the root; equal to the Grok contract's. */
+ readonly maxRequestElements: 1048576
/** Execution ticket TTL; control-api signs tickets with it. */
readonly executionTicketTtlMs: 60000
}
@@ -62,7 +64,8 @@ export declare const BODY_STRUCTURE_LIMITS: {
readonly maxStructuralBytes: 8404992
readonly maxContainers: 262160
readonly maxDepth: 70
- readonly maxMembers: 524352
+ readonly maxMembers: 262208
+ readonly maxElements: 1048640
}
export interface BodyStructureLimits {
@@ -70,12 +73,14 @@ export interface BodyStructureLimits {
readonly maxContainers: number
readonly maxDepth: number
readonly maxMembers: number
+ readonly maxElements: number
}
/**
* Thrown by the scan. `type` is `body.structure.too.dense` (413),
* `body.structure.too.many.containers` (413), `body.structure.too.deep` (400),
- * `body.structure.too.many.members` (413) or, from the verify hook,
+ * `body.structure.too.many.members` (413),
+ * `body.structure.too.many.elements` (413) or, from the verify hook,
* `charset.unsupported` (415).
*/
export interface BodyStructureError extends Error {
@@ -88,7 +93,7 @@ export interface BodyStructureError extends Error {
export declare function scanJsonStructure(
buf: Uint8Array,
limits: BodyStructureLimits
-): { structuralBytes: number; containers: number; deepest: number; members: number }
+): { structuralBytes: number; containers: number; deepest: number; members: number; elements: number }
/**
* A body-parser `verify` hook running scanJsonStructure. The error it throws
diff --git a/packages/llm-provider-attempt-contract/index.test.cjs b/packages/llm-provider-attempt-contract/index.test.cjs
index c11f48af9..3981dcd63 100644
--- a/packages/llm-provider-attempt-contract/index.test.cjs
+++ b/packages/llm-provider-attempt-contract/index.test.cjs
@@ -459,21 +459,16 @@ test('T-E2 the element bound reports itself distinctly from the byte bound', ()
// maxRequestBodyBytes` therefore could not say which one fired. Compaction is the remedy either way;
// the distinct wording buys diagnosis, not a different fix (#731).
//
- // What makes the two guards separable here is ORDER, not size:
- // `checkStructure` runs before `JSON.stringify`, so the element count is
- // refused first. The payload below is also ~3x the byte cap once serialized
- // — by construction it has to be, since more elements than the byte cap
- // cannot encode under it — so without that ordering the byte bound would
- // claim it and this test would be pinning the wrong guard.
+ // The shape fits the byte bound; only the element count refuses it.
const refused = contract.parseCodexCompletionRequestV1({
...BASE,
- messages: new Array(contract.LIMITS.maxRequestBodyBytes + 1).fill({}),
+ messages: new Array(contract.LIMITS.maxRequestElements + 1).fill(0),
})
assert.deepEqual(refused, {
ok: false,
code: 'limit',
kind: 'size',
- message: 'request exceeds maxRequestBodyBytes element bound',
+ message: 'request exceeds maxRequestElements',
})
})
@@ -1869,7 +1864,57 @@ function requestWithMembers(target) {
}
test('LIMITS.maxRequestMembers is pinned', () => {
- assert.equal(contract.LIMITS.maxRequestMembers, 524288)
+ assert.equal(contract.LIMITS.maxRequestMembers, 262144)
+})
+
+/** Count JSON values independently of the contract's structural pre-check. */
+function countElements(value) {
+ let elements = 1
+ const stack = [value]
+ while (stack.length > 0) {
+ const node = stack.pop()
+ if (node === null || typeof node !== 'object') continue
+ const children = Array.isArray(node) ? node : Object.values(node)
+ elements += children.length
+ for (const child of children) if (child !== null && typeof child === 'object') stack.push(child)
+ }
+ return elements
+}
+
+function requestWithElements(target) {
+ const filler = []
+ const request = {
+ ...BASE,
+ tools: [{ name: 'crm__export', description: 'd', parameters: { type: 'object', enum: filler } }],
+ }
+ filler.length = target - countElements(request)
+ filler.fill(0)
+ assert.equal(countElements(request), target)
+ return request
+}
+
+test('LIMITS.maxRequestElements is pinned', () => {
+ assert.equal(contract.LIMITS.maxRequestElements, 1048576)
+})
+
+test("a request over maxRequestElements is refused with kind:'size'", () => {
+ const limit = contract.LIMITS.maxRequestElements
+ const at = requestWithElements(limit)
+ assert.equal(contract.parseCodexCompletionRequest(at).ok, true)
+ const over = requestWithElements(limit + 1)
+ assert.ok(Buffer.byteLength(JSON.stringify(over), 'utf8') < contract.LIMITS.maxRequestBodyBytes)
+ const expected = {
+ ok: false,
+ code: 'limit',
+ kind: 'size',
+ message: 'request exceeds maxRequestElements',
+ }
+ assert.deepEqual(refusalOf(contract.parseCodexCompletionRequest(over)), expected)
+ assert.deepEqual(refusalOf(contract.hashCanonicalCodexRequest(over)), expected)
+ assert.deepEqual(
+ refusalOf(contract.parseCodexCompletionRequest({ ...over, schemaVersion: 'codex-completion-request.v2' })),
+ expected
+ )
})
test("a request over maxRequestMembers is refused with kind:'size'", () => {
@@ -1908,12 +1953,14 @@ test('BODY_STRUCTURE_LIMITS derive from LIMITS', () => {
maxContainers: contract.LIMITS.maxRequestContainers + 16,
maxDepth: contract.LIMITS.maxNestingDepth + 6,
maxMembers: contract.LIMITS.maxRequestMembers + 64,
+ maxElements: contract.LIMITS.maxRequestElements + 64,
})
assert.deepEqual(limits, {
maxStructuralBytes: 8404992,
maxContainers: 262160,
maxDepth: 70,
- maxMembers: 524352,
+ maxMembers: 262208,
+ maxElements: 1048640,
})
assert.equal(Object.isFrozen(limits), true)
})
@@ -1961,6 +2008,26 @@ test('the body scan bounds object members and never counts string contents', ()
assert.equal(contract.scanJsonStructure(quoted, limits).members, 0)
})
+test('the body scan counts values exactly and bounds elements before JSON.parse', () => {
+ const limits = contract.BODY_STRUCTURE_LIMITS
+ for (const [json, elements] of [
+ ['{"a":0}', 2],
+ ['[{},{}]', 3],
+ ['[ 0 , "x,[{}]", {"a": [1, 2]} ]', 7],
+ ['{"a\\\"[,": "\\\\,]"}', 2],
+ ]) {
+ assert.equal(contract.scanJsonStructure(Buffer.from(json), limits).elements, elements, json)
+ }
+ const at = Buffer.from(`[${'0,'.repeat(limits.maxElements - 2)}0]`)
+ assert.equal(contract.scanJsonStructure(at, limits).elements, limits.maxElements)
+ const over = Buffer.from(`[${'0,'.repeat(limits.maxElements - 1)}0]`)
+ assert.throws(() => contract.scanJsonStructure(over, limits), {
+ name: 'BodyStructureError',
+ status: 413,
+ type: 'body.structure.too.many.elements',
+ })
+})
+
test('the verify hook refuses a charset other than UTF-8 and scans UTF-8 bodies', () => {
const verify = contract.createBodyStructureVerify(contract.BODY_STRUCTURE_LIMITS)
const body = Buffer.from('{"a":[1]}')
@@ -1978,7 +2045,7 @@ test('the verify hook refuses a charset other than UTF-8 and scans UTF-8 bodies'
test('the verify hook fails closed unless every bound is a positive safe integer', () => {
const good = contract.BODY_STRUCTURE_LIMITS
- for (const name of ['maxStructuralBytes', 'maxContainers', 'maxDepth', 'maxMembers']) {
+ for (const name of ['maxStructuralBytes', 'maxContainers', 'maxDepth', 'maxMembers', 'maxElements']) {
for (const value of [undefined, 0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1]) {
assert.throws(() => contract.createBodyStructureVerify({ ...good, [name]: value }), TypeError)
}
diff --git a/tests/e2e/integration/codex-subscription-contract-freeze.test.ts b/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
index 45fb74dbb..fd26b6c1b 100644
--- a/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
+++ b/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
@@ -92,6 +92,7 @@ const RUNTIME_ONLY_LIMIT_KEYS = [
'maxNestingDepth',
'maxRequestContainers',
'maxRequestMembers',
+ 'maxRequestElements',
] as const
const SENSITIVE_VALUE_PATTERN =
diff --git a/tests/e2e/package-lock.json b/tests/e2e/package-lock.json
index 5a53b1c45..882564dd9 100644
--- a/tests/e2e/package-lock.json
+++ b/tests/e2e/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-e2e-tests",
- "version": "0.1.99",
+ "version": "0.1.100",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-e2e-tests",
- "version": "0.1.99",
+ "version": "0.1.100",
"devDependencies": {
"@clerum/llm-provider-attempt-contract": "file:../../packages/llm-provider-attempt-contract",
"@types/jsonwebtoken": "^9.0.10",
diff --git a/tests/e2e/package.json b/tests/e2e/package.json
index 8cdb46303..77b8a7ffd 100644
--- a/tests/e2e/package.json
+++ b/tests/e2e/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-e2e-tests",
- "version": "0.1.99",
+ "version": "0.1.100",
"private": true,
"type": "module",
"scripts": {