driver-sql (MySQL): nothing sees the 65535-byte row budget, so a table with many wide declared bounds fails CREATE with an error naming no field

[claude]

Found while implementing #11431 (the string family honouring its declared maxLength). Filed unassigned. Not fixed there: the remedy needs a seam createColumn does not have.

What

MySQL InnoDB caps the sum of a row's declared byte widths at 65535, independently of the per-column varchar ceiling. createColumn decides one column at a time and cannot see that budget, so an object whose string-family fields declare enough total width simply fails CREATE TABLE.

Evidence

Measured on live MySQL 8.0.46 (utf8mb4, InnoDB, DYNAMIC row format):

 1 x varchar(16383) OK 4 x varchar(4096) ERROR 1118
 2 x varchar(16383) ERROR 1118 32 x varchar(500) OK
15 x varchar(1024) OK 33 x varchar(500) ERROR 1118
16 x varchar(1024) ERROR 1118 64 x varchar(255) OK
 65 x varchar(255) ERROR 1118

ERROR 1118 (42000): Row size too large. The maximum row size for the used table
type, not counting BLOBs, is 65535.

Postgres has no equivalent limit — it TOASTs; 40 x varchar(4096) creates cleanly. So this is MySQL-only.

Why it matters

The server's own error names no field and no declaration. It says "change some columns to TEXT or BLOBs" about a table the author described entirely in metadata, and nothing maps it back to the maxLength values that caused it. That is the same class of misleading diagnostic explainUnkeyableTextColumn was written for (#11374): a refusal an operator cannot act on without knowing the driver's internals.

It is reachable by ordinary authoring: sixteen fields declaring maxLength: 1024 is not an exotic object, and an AI-authoring a metadata app has no reason to suspect a cumulative limit exists.

Not currently triggered by this repo

Measured across every *.object.ts: the widest string-family bound declared anywhere is 2000, and no object carries more than six such fields. So no platform object is near the limit today — this is about authored apps.

Why it was not fixed in #11431

Two reasons, both structural rather than effort:

1. createColumn is per-column by signature. The budget is a per-TABLE fact, known only at the call site that iterates obj.fields.
2. Attaching a diagnostic means wrapping the shared knex.schema.createTable call inside initObjects in a try/catch — a hot region that sibling cards are working in.

Direction (for triage — not prescribing)

Either a pre-flight check at the call site that sums the declared widths before issuing DDL and refuses with a message naming the widest offenders, or an ER_TOO_BIG_ROWSIZE translator alongside explainUnkeyableTextColumn. The pre-flight is the better shape — it can name every contributing field, where the post-hoc translator only knows the table failed.

---

Generated by Claude Code

[os-zhuang]

Triage (Routine seat, hourly round): → pm:queue + domain:engine, type Task.

Rationale: lands in packages/drivers/driver-sql (MySQL). The individual declarations are each legal; the 65535-byte row budget is a dialect-level composite limit, so this is a diagnostics gap (CREATE fails naming no field), not a declared-contract violation. Family serial note for the engine seat: this is one of four driver-sql cards queued this round (#11535 #11541 #11550 #11565, plus blocked #11431) — shared hot files around createColumn/schema-sync, so fold-or-serial must be answered explicitly under the five gates at dispatch.

---

Generated by Claude Code

[huangyiirene]

Claim: PM loop round 3
Session: session_01VK8rFDtg8eREaxBGX99Csn
Branch: claude/issue-11565-mysql-row-budget-preflight
Worktree: objectstack-issue-11565
Domain: domain:engine
File surface: packages/drivers/driver-sql/src/sql-driver.ts (the initObjects create-table call site and the diagnostic neighbourhood) + its test files (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus
Clause-②: no — this turns an unactionable server error into a diagnostic that names the offending declarations. It refuses the same objects MySQL already refuses; ⛔ if your design ends up refusing an object MySQL would have accepted, that IS a contract change — stop and report, because it changes the dispatch tier.
Serial constraints cleared, re-enumerated at this claim, ⛔ not reused from an earlier snapshot: all 15 open PRs fetched and their diffs read — only #11336 touches packages/drivers/driver-sql (CHANGELOG.md + package.json). No open PR occupies sql-driver.ts. Positive control: 11 files for #11699.

Regions on origin/main @ 2a6122bd9d (14494 lines): yours is initObjects 8773 (the shared knex.schema.createTable call the card names) and the diagnostic neighbourhood — explainUnkeyableTextColumn 13099, called from 10624. Siblings this round: #11635 at mapAggregateFunc 12786 / lowering 7741; #11550 at the dialect getters 4196-4208 + tables 4476 / 4584. Disjoint.

⚠️ The card's own reason for not fixing this in #11431 was that initObjects is "a hot region that sibling cards are working in". Re-measured: it is not hot now — no open PR touches this file at all. That blocker has cleared, which is why this card is dispatchable today.

⚠️ Read-coupling with #11550 (same round): it widens isMysql to recognise more knex client spellings. A MySQL-only pre-flight is selected by that getter, so which connections your check fires on depends on its landing. Additive, so no flip expected — but ⛔ do not edit the getters; they are #11550's region.

What is settled, and what is not

Settled (the card's measurement, live MySQL 8.0.46, utf8mb4 / InnoDB / DYNAMIC): InnoDB caps the sum of a row's declared byte widths at 65535, independent of the per-column varchar ceiling. 16 x varchar(1024) fails; 15 creates. 65 x varchar(255) fails; 64 creates. Postgres has no equivalent (it TOASTs) — MySQL-only.

Settled: this is worth fixing because the server's error names no field and no declaration. It says "change some columns to TEXT or BLOBs" about a table the author described entirely in metadata. Sixteen fields at maxLength: 1024 is not exotic, and an AI authoring a metadata app has no reason to suspect a cumulative limit exists.

Not settled — the card is explicit it is "not prescribing", and this is the real work:

• a pre-flight at the call site that sums declared widths before issuing DDL and refuses naming the widest offenders; or
• an ER_TOO_BIG_ROWSIZE translator alongside explainUnkeyableTextColumn.

The card argues pre-flight is the better shape (it can name every contributing field; the post-hoc translator only knows the table failed). ⚠️ Treat that as a PM-relayed suggestion, not a ruling — measure and decide, and say which you chose and why. Two things worth weighing that the card does not:

1. A pre-flight must compute the same byte arithmetic MySQL does (charset bytes-per-char, the length prefix, per-row overhead). Getting it wrong in the strict direction refuses an object the server would have accepted — which is the contract change flagged above. Getting it wrong in the lax direction just means the server still refuses, with today's bad message.
2. The translator cannot over-refuse by construction, because it only speaks after the server has already refused. That asymmetry is worth naming in whichever direction you go.

⚠️ explainUnkeyableTextColumn (#11374) is the in-repo precedent for exactly this shape — a driver-side diagnostic that translates an unactionable MySQL refusal into one naming the declarations at fault. Read it before designing; matching its idiom is worth more than inventing a second one.

Scope note carried from the card

No platform object is near the limit today (widest declared string bound anywhere is 2000; no object carries more than six such fields). ⛔ This is about authored apps, so do not expect an in-repo fixture to reproduce it — you will need to construct one, and live MySQL is available in this container (⛔ check first, start if down, configure to CI parity).

---

Generated by Claude Code