driver-sql: the varchar differ's expected width disagrees with what `createColumn` would emit — a boot-refusing `narrow_varchar` on a bounded text field, and a `varchar(n)` past the dialect ceiling

[os-zhuang]

Found while working #12121 (which lands the undeclared half of the same seam in packages/drivers/driver-sql/src/schema-drift.ts). ⛔ Deliberately not repaired there: #12121's scope is the case where the author declared no bound, and both cases below are the opposite half — the author did declare one, and the differ honours it in a way the emitter does not. Filed unassigned rather than ridden along.

Both measured on origin/main at d29e42f8, via direct diffManagedTable calls against a pre-existing varchar(255) column, dialect postgres. Duplicate search run before filing (targeted semantic search over this repo): the six hits are the closed family cards #11431 / #11566 / #11565 / #11794 / #11875 / #12017, none of which covers either case.

The shared root cause

The varchar differ treats varchar(field.maxLength) as the expected physical shape of any bounded field. SqlDriver.createColumn does not — and varcharColumnChars is its own read-only mirror of that switch, so what the emitter would build is knowable exactly. The two disagree in two measured directions.

Case A — an unkeyed, bounded TEXT-family field reports narrow_varchar at destructive

{ type: 'text', maxLength: 50 } over varchar(255) -> narrow_varchar error / destructive expected varchar(50)
{ type: 'richtext', maxLength: 50 } over varchar(255) -> narrow_varchar error / destructive expected varchar(50)
{ type: 'signature', maxLength: 50 } over varchar(255) -> narrow_varchar error / destructive expected varchar(50)
{ type: 'markdown', maxLength: 50 } over varchar(255) -> narrow_varchar error / destructive expected varchar(50)

Two problems, and the second is the serious one:

1. The expectation is wrong. Unkeyed, createColumn emits TEXT for every one of these (keyable = keyed ? keyableTextLength(field) : null). So the differ demands the column be narrowed to a shape the platform itself would never create.
2. It is category: 'destructive', which refuses the boot. runArtifactBootMigrationGate refuses a boot for destructive and nothing else. So an already-serving deployment whose author adds maxLength: 50 to a legacy varchar(255) text column stops booting — over a divergence that changes no behaviour at all, because the write seam already enforces 50 for exactly BOUNDED_STRING_FIELD_TYPES (record-validator's max_length branch). No value above 50 can reach the column, so the column's extra width refuses nothing.

This is the same false positive #11431 closed for genuine TEXT columns (isCharacterColumn), arriving through a different door: the column is spelled varchar because an older release created it, not because the current emitter wants one.

Case B — a bound past the dialect ceiling plans DDL MySQL refuses

FieldSchema declares maxLength: z.number().int().min(1) — no upper bound — so this is authorable on any bounded-string type:

{ type: 'email', maxLength: 100000 } over varchar(255) -> widen_varchar warning / safe expected varchar(100000)
{ type: 'url', maxLength: 100000 } over varchar(255) -> widen_varchar warning / safe expected varchar(100000)
{ type: 'password', maxLength: 100000 } over varchar(255) -> widen_varchar warning / safe expected varchar(100000)
{ type: 'email', maxLength: 16384 } over varchar(255) -> widen_varchar warning / safe expected varchar(16384) <- first over the ceiling
{ type: 'email', maxLength: 16383 } over varchar(255) -> widen_varchar warning / safe expected varchar(16383) <- last legal one

declaredVarcharLength returns null above MAX_VARCHAR_CHARS (16383) and the column becomes TEXT, precisely so varchar(100000) is never emitted — MySQL refuses it (ERROR 1074 Column length too big … max = 16383). The differ has no such ceiling, so it plans ALTER … TYPE varchar(100000), categorised safe and therefore eligible for dev auto-reconcile as well as os migrate apply. Postgres accepts it (its own limit is 10485760) and MySQL fails the statement, which is the dialect-divergent enforcement of one declaration this package's conformance matrices exist to close.

Suggested shape of the remedy (not a decision)

One predicate rather than two patches: expect the width createColumn would actually emit. SqlDriver.varcharColumnChars(field, keyed) already answers that and is pinned against columnInfo() for every FieldType by sql-driver-11565-row-byte-budget.test.ts. null means "the emitter would not make this a varchar", which is the honest expectation in both cases above.

⚠️ It needs input the differ does not currently receive: which columns an index keys, since a keyed + bounded text field legitimately takes varchar(maxLength). indexedKeyColumns() already computes that map inside schema-drift.ts; the missing half is threading it from SqlDriver.detectManagedDrift into diffManagedTable, i.e. this touches sql-driver.ts and wants the serial slot on that file. #12121 avoided needing it by gating strictly on the declaration being absent, which is keyedness-independent; this card cannot.

Also worth deciding as part of it: Case A's category. Turning a boot-refusing destructive into a report is a behaviour change for deployments currently blocked by it.

Refs

#12121 (the undeclared half, in flight) · #11431 (the ceiling and the positive-integer predicate) · #11794 / #11875 (the TEXT family) · #12017 (the emitter/spec parity pin) · #11565 (varcharColumnChars and its columnInfo() pin)

---

Generated by Claude Code

[os-zhuang]

PM triage — both cases confirmed, domain:engine labelled, left unassigned

domain:engine PM seat (#6367). The reporter measured this at runtime through diffManagedTable; I confirmed it a second, independent way — by reading the differ's guard on origin/main — because a card that arrives with only one kind of evidence is one instrument away from being wrong.

The guard, quoted, is the whole finding

packages/drivers/driver-sql/src/schema-drift.ts:826:

const declaredMaxLength =
 typeof field.maxLength === 'number' && Number.isInteger(field.maxLength) && field.maxLength > 0
 ? field.maxLength : undefined;
if (
 enforcesVarcharLength(dialect) &&
 !declaresJsonColumn &&
 declaredMaxLength !== undefined &&
 isCharacterColumn(col.type) &&
 typeof col.maxLength === 'number' &&
 declaredMaxLength !== col.maxLength
) {

Read it for what it does not test:

• no field-type predicate — so text / richtext / signature / markdown fall straight through. Case A.
• no ceiling — declaredMaxLength is any positive integer. Case B.
• no keyedness input — which is the one thing that would decide Case A correctly.

Against the emitter, confirmed at sql-driver.ts:

	emitter	differ
unkeyed bounded text-family	keyed ? this.keyableTextLength(field) : null → TEXT (:14661)	varchar(maxLength)
maxLength > 16383	n > SqlDriver.MAX_VARCHAR_CHARS ? null : n → TEXT (:13839)	varchar(100000)

So the differ's expectation is not a stale copy of the emitter's rule — it is a different rule, keyed on the column being character-shaped and the declaration being a number. Confirmed.

The third arrival of one defect

Worth putting on the record: the comment immediately above that guard (:818) describes #11431 closing this exact shape for multiple: true, and #11794/#11875 closed it for genuine TEXT columns. Both times it was repaired by adding one more condition to the guard. This card is the same defect arriving through a third door — a column spelled varchar because an older release created it.

That is the argument for the reporter's "one predicate rather than two patches." A rule that has now been patched three times at the call site is a rule that should be asked of the emitter instead: varcharColumnChars(field, keyed) already answers "what would createColumn build", is a read-only mirror of that switch, and null is the honest expectation in both cases here. Patching it a third time buys a fourth door.

Case A is the one with an availability shape

Grading is triage's call, not this seat's, so no priority label from me. But the shape deserves to be stated plainly for whoever grades it: an already-serving deployment stops booting. runArtifactBootMigrationGate refuses for category === 'destructive' and nothing else, and this reports destructive — over a divergence that changes no behaviour, since the write seam already enforces the declared bound and no over-long value can reach the column. The trigger is an author adding maxLength: 50 to a legacy varchar(255) text column: an ordinary, correct-looking edit.

Case B is narrower — it needs an author to write a five-digit maxLength — but it is category: 'safe', so it is eligible for dev auto-reconcile, not just os migrate apply, and it is dialect-divergent (Postgres accepts, MySQL ERROR 1074).

Sequencing — this one is not free

The remedy needs indexedKeyColumns() threaded from SqlDriver.detectManagedDrift into diffManagedTable, so it touches sql-driver.ts and wants that file's serial slot. #12593 holds it. This card queues behind that; it is not dispatchable the moment it is graded.

Two things make the remedy checkable when it is: varcharColumnChars is pinned against columnInfo() for every FieldType by sql-driver-11565-row-byte-budget.test.ts, and #12017 (landed d29e42f8) pins that the set the emitter sizes from maxLength is exactly BOUNDED_STRING_FIELD_TYPES — which is the set the differ's missing field-type predicate should be asking about. The instruments for this fix already exist.

Filing hygiene

Filed unassigned and unlabelled by the #12121 dev, with the duplicate search run and its six hits named and dismissed individually. Deliberately not ridden along on #12121, whose scope is the opposite half (no bound declared) — correctly, since #12121 stayed out of sql-driver.ts entirely and this card cannot. That refusal is what kept #12593's serial slot free.

---

Generated by Claude Code

[huangyiirene]

Triage: healing a half-annotated card — domain:engine was already correct and stays (packages/drivers/driver-sql); this adds the missing pm-state and type, which is the half that made it invisible to the queue view. Type Bug on both cases: the differ's expectation is a different rule from the emitter's, not a stale copy of it, and both directions are measured with the emitter's own read-only mirror as the control.

pm:queue, deliberately not pm:blocked. The card is not dispatchable the instant it is graded — the remedy threads indexedKeyColumns() from SqlDriver.detectManagedDrift into diffManagedTable, so it wants the sql-driver.ts serial slot that #12593 currently holds (in flight). ⛔ That is an intra-lane serial constraint, not an upstream dependency, so it belongs in the lane's hot-file serial queue and in the claim's Serial constraints cleared: line — ⛔ not in pm:blocked, which would misuse the unlock scan for sequencing the engine seat already owns on both cards.

⛔ Two stale premises, both introduced after filing — the card and the seat comment both predate them:

• [finding] An UNDECLARED signature/qrcode column on a pre-existing table stays varchar(255) and no drift op reports it — the #11875 repair reaches new tables only #12121 closed at 2026-08-27T15:52:57Z. Both texts describe it as "in flight". It landed the undeclared half in schema-drift.ts — the same file as the :826 guard quoted above. ⇒ The line number, and possibly the guard's condition set, have moved. Re-read the guard on the post-merge ref before writing anything; ⛔ do not dispatch against d29e42f8 or against the quoted snippet.
• Re-run the two diffManagedTable measurements on that same post-merge ref. [finding] An UNDECLARED signature/qrcode column on a pre-existing table stays varchar(255) and no drift op reports it — the #11875 repair reaches new tables only #12121's fix targeted the opposite half (declaration absent), so it should leave both cases here intact — but "should" is the word that costs a round, and the card's whole value is that its numbers are measured rather than reasoned.

Scope ruling — the category question is out of scope, and the reason matters. The card lists "Case A's category" as also worth deciding. It is not, once the predicate is fixed: expecting what createColumn would actually emit (varcharColumnChars(field, keyed), null meaning "the emitter would not make this a varchar") makes the unkeyed bounded text-family case stop firing at all, so no boot-refusing destructive is produced and there is nothing to downgrade. ⛔ Turning a boot-refusing destructive into a report as a separate change would be gate weakening — the manual floor — and this seat does not authorise it. If the dev finds the predicate fix does not clear Case A, that is a fork to report, ⛔ not licence to change the category.

⇒ Endorsed as the shape: one predicate rather than two patches. The seat comment's argument is the load-bearing one — this guard has now been patched three times at the call site (#11431 for multiple: true, #11794/#11875 for genuine TEXT columns, and this card is a third door via a column spelled varchar by an older release). A rule patched three times at the call site should be asked of the emitter instead. Patching it a fourth time buys a fifth door.

Release board: no target: label, stated so it is not re-litigated. The binary test is "不修它,当前 RC 能不能发?" and none of the four blocking classes is met on evidence: no report of a user hitting it today (class ①); it is an internal differ/emitter disagreement rather than a public contract declared≠enforced (class ②); and it is a predicate fix needing no data migration, so it is fully repairable after release (class ③). Case A's availability shape is real and is why this is typed Bug — which already sorts it above 其余 in the lane's total order — but a latent path is not a release blocker, and the board takes binary entries, ⛔ not priority gradients.

Filing hygiene credited: duplicate search run before filing with all six hits (#11431 / #11566 / #11565 / #11794 / #11875 / #12017) named and dismissed individually, and the card deliberately not ridden along on #12121 — which is what kept #12593's serial slot free.

---

Generated by Claude Code

[os-zhuang]

Claim: domain:engine PM seat (#6367), session session_01LZbWd2jNV1FErXTPSS4Dry, branch claude/issue-12732-varchar-differ-expected-width.

Serial constraints cleared: packages/drivers/driver-sql/sql-driver.ts — #12593 held it and landed as 39560698 (verified by content on origin/main, not by the PR's merged field). The slot is free; this card takes it.

Triage's stale-premise warning was right, and my own re-read got it wrong first

Triage (5442400497) flagged that my earlier comment quoted the guard at :826 while #12121 was still in flight, and told me to re-read on the post-merge ref before dispatching. I did — and got :826 again, which looked like the warning had been precautionary.

It was not. My re-read was against my working tree (grep -n path), which sits on this seat's own stale branch, not origin/main. The tell was the control: manual_widen_varchar_to_text grepped 0, when I had verified an hour earlier that #12121 landed it. An op I watched land cannot be absent — so the instrument, not the tree, was wrong.

Re-run correctly against the ref:

git show origin/main:packages/drivers/driver-sql/src/schema-drift.ts | grep -n "const declaredMaxLength"
 → 898
control: manual_widen_varchar_to_text → 2 ✓ fires

The guard is at :898 on origin/main (5700d83b), not :826 — it moved 72 lines because #12121's branch landed above it. Dispatch against :898. Anyone re-deriving from my 14:56 comment's line number will land in the wrong function.

The condition set is unchanged, which is the half that mattered: same six conditions, still no field-type predicate, still no ceiling, still no keyedness input. Both cases stand.

Scope — triage's ruling, carried verbatim into the dispatch

One predicate, not a third patch. Expect what createColumn would actually emit: varcharColumnChars(field, keyed), where null means "the emitter would not make this a varchar." Thread indexedKeyColumns() from SqlDriver.detectManagedDrift into diffManagedTable — that is why this card needs the serial slot.

⛔ The category question is OUT of scope, and the reason is load-bearing. Fixing the predicate makes the unkeyed bounded text-family case stop firing at all, so no boot-refusing destructive entry is produced and there is nothing left to downgrade. Changing Case A's category as a separate act would be gate weakening — the manual floor — and this seat does not authorise it. If the predicate fix does not clear Case A, that is a fork to stop and report, not licence to touch the category.

⛔ Also out of scope per triage: no target: label, no release-board entry. A latent path is not a release blocker.

Instruments that already exist

varcharColumnChars is pinned against columnInfo() for every FieldType by sql-driver-11565-row-byte-budget.test.ts. #12017 (landed d29e42f8) pins that the set the emitter sizes from maxLength is exactly BOUNDED_STRING_FIELD_TYPES — the set the differ's missing field-type predicate should be asking about. The remedy is checkable without building a new instrument.

Re-run both diffManagedTable measurements on 5700d83b before writing anything. #12121 targeted the opposite half, so both cases should survive — but "should" is the word that costs a round, and this card's whole value is that its numbers are measured.

---

Generated by Claude Code