driver-sql (MySQL): full-value UNIQUE on >768-char token columns is inexpressible on utf8mb4 — hash-shadow-key route for the four ruled cases (C half of the #11374 ruling)

[os-zhuang]

Blocked-by: #11374

Filed by the triage seat executing the maintainer's 2026-08-24 ruling on #11374 (batch acceptance, verbatim: 「四维分析一致的，接手你的建议。」 — adopting the aligned four-facet recommendation A + C(hash), B rejected). This card is the C half, split out and sequenced after A per that recommendation ("a hashed shadow key on identity tables is an architectural change that should not ride a mapping fix").

Scope (ruled)

The four cases measured past MySQL's 3072-byte key ceiling (768 utf8mb4 chars), where no declared bound can make a full-value unique index expressible:

• sys_oauth_access_token.token (maxLength: 1024, UNIQUE)
• sys_oauth_refresh_token.token (maxLength: 1024, UNIQUE)
• sys_oauth_resource.identifier (maxLength: 1024, UNIQUE)
• sys_metadata 4-column composite unique (type, name, organization_id, package_id — 3460 bytes fully bounded vs the 3072 ceiling; alternatively narrow its declared bounds if that is measurably safe)

Route (ruled)

Hash-shadow key, following the in-repo precedent _objectstack_sequences.key_hash in sql-driver.ts (its docblock names the same 3072-byte limit). The ascii-charset alternative was considered and not chosen (it silently forbids non-ASCII in those columns forever). ⛔ Prefix-unique indexes are rejected by the same ruling — measured on live MySQL 8.0.46 as stricter-and-different than the declared constraint (refuses distinct values sharing a 191-char prefix; a legitimate new sys_session.token colliding on prefix reads as a duplicate sign-in).

An OAuth access token may legitimately be a multi-KB JWT — this route is the only one that keeps full-value uniqueness on utf8mb4 InnoDB.

Sequencing

Dispatch after #11374's A half (declared bounds on the 12 unbounded columns) lands — the A PR decides the exact remaining population this card must cover; re-verify the four cases against that ref before cutting a branch. Measurement provenance: #11374's dev report (comment 5387700440) and the seat's re-entry analysis (comment 5387903086).

[os-warren]

Unblocked — pm:blocked → pm:queue. #11374's A half is complete.

This card's own sequencing clause said: "Dispatch after #11374's A half (declared bounds on the 12 unbounded columns) lands — the A PR decides the exact remaining population this card must cover; re-verify the four cases against that ref before cutting a branch."

A is now landed in full, and #11374 is closed:

• feat(platform-objects): declare sourced maxLength bounds on the unbounded keyed identity columns (#11374 route A) #11699 — 13 keyed identity columns.
• feat(platform-objects): declare a sourced maxLength on sys_import_job.created_by (#11374 route A, last column) #12058 (4805b5619d) — sys_import_job.created_by, the last one; it sat in audit/, outside feat(platform-objects): declare sourced maxLength bounds on the unbounded keyed identity columns (#11374 route A) #11699's declared file surface.

The ref to re-verify against, and the population it leaves you

origin/main at 4805b5619d or later. The A half's own physical measurement across all 44 exported platform objects on live MySQL 8.0.46:

	before A's last column	after
syncSchema failures	8 / 44 (7 ER_BLOB_KEY_WITHOUT_LENGTH + 1 ER_TOO_LONG_KEY)	7 / 44 (6 + 1)
Postgres 16.13 control	0 / 44	0 / 44

⇒ the 7 remaining failures are this card's population by construction — everything boundable is now bounded. ⛔ Re-measure them against that ref before cutting a branch rather than carrying this table forward; it is provenance, not a substitute for your own reading.

Also newly true and worth checking against your four ruled cases: the widened pin at packages/platform-objects/src/platform-keyed-text-bounds.test.ts now enumerates all 45 exported objects / 78 keyed text-family columns (was identity-only, 20+/30+), and its UNBOUNDABLE allowlist is where sys_verification.value is named with its reason. That is the surface a hash-shadow-key route has to satisfy or explicitly amend.

Route stays as ruled: hash-shadow key, precedent _objectstack_sequences.key_hash. ⛔ Prefix-unique indexes remain rejected by the same ruling. Sub-issue #11701 carries the re-measured population and is unblocked in the same stroke.

---

Generated by Claude Code

[os-warren]

Claim: PM loop (domain:engine seat)
Session: session_01W6HFzyH98W1YaQXhJUJt6o
Branch: claude/issue-11627-hash-shadow-key-utf8mb4
Worktree: objectstack-issue-11627
Domain: domain:engine
Container & model: M, mode:subagent, CONTRACT_REVIEW_TIER
Clause-②: yes. Two limbs, both real:

• Behaviour — schema creation that MySQL refuses today will succeed. That is an accept/reject door moving in the widening direction, on the published platform schema.
• Semantics — uniqueness enforcement moves from the value to a hash of the value. A hash collision would falsely reject a legitimate write. The collision probability must be stated and bounded, not assumed negligible.

Serial constraints cleared — measured just now, and the blocker cleared this round

packages/drivers/driver-sql/src/sql-driver.ts:

• YOUR band: 13215–13400 — MAX_KEYABLE_VARCHAR_CHARS (:13229), keyableTextLength (:13334), the refusal message at :13385 — plus the in-repo precedent at 5511–5620 (_objectstack_sequences's key_hash, t.string('key_hash', 64).notNullable().primary() at :5594), and wherever the unique-index emission lands.
• ✅ signature / qrcode have no maxLength enforcement anywhere, so they cannot join the TEXT family — a data-URI signature is refused at 255 chars and the declared bound binds nothing #11875's band 13275–13980 is now FREE — PR feat(data): signature and qrcode join the bounded-string family end to end #12119 landed as a11c1a57d6, verified by content. That was this card's real blocker beyond driver-sql: the platform-objects schema does not sync onto MySQL — unbounded string fields become TEXT, which MySQL refuses to index #11374.
• ⛔ 8628–9220 is held by driver-sql: a declared field named id / created_at / updated_at is silently discarded by initObjects — declared type, length and constraints all ignored with no diagnostic #12015 → PR fix(driver-sql): name the declared field a builtin column discards, on all three DDL paths (#12015) #12109, enqueued and unlanded. Do not touch it.
• ⚠️ 10155–10499 landed (fix(driver-sql): SQLite reconcile reports applied only for the ops the rebuild actually honoured #12127, f5a7f9c884) — free, but applyMigrationEntries' honoured/skipped partition is newly meaningful there. If a hash-shadow column implies a new drift op, it must report honestly through that partition rather than riding the SQLite rebuild's blanket.

The population is 7, and I verified the number independently

#11374's A half is complete and closed. Its physical measurement across all 44 exported platform objects on live MySQL 8.0.46 leaves 7 / 44 syncSchema failures (6 ER_BLOB_KEY_WITHOUT_LENGTH + 1 ER_TOO_LONG_KEY), Postgres 0/44 — and everything boundable is now bounded, so those 7 are this card's population by construction.

That matches #11627's four ruled cases plus #11701's three re-measured additions. ⛔ Re-measure against origin/main at a11c1a57d6 or later before cutting a branch — this table is provenance, not a substitute for your own reading, and #11701 is the sub-issue carrying the re-measured population.

Route is RULED — do not re-open it

Maintainer 2026-08-24 on #11374, verbatim 「四维分析一致的，接手你的建议。」 — A + C(hash), B rejected. This is the C half.

• Hash-shadow key, following the in-repo precedent _objectstack_sequences.key_hash (its docblock names the same 3072-byte limit).
• ⛔ Prefix-unique indexes are REJECTED by that same ruling, measured on live MySQL 8.0.46 as stricter-and-different than the declared constraint: they refuse distinct values sharing a 191-char prefix, so a legitimate new sys_session.token colliding on prefix reads as a duplicate sign-in.
• ⛔ The ascii-charset alternative was considered and not chosen — it silently forbids non-ASCII in those columns forever.

An OAuth access token may legitimately be a multi-KB JWT; this route is the only one keeping full-value uniqueness on utf8mb4 InnoDB.

---

Generated by Claude Code

[os-warren]

⚠️ Re-dispatch at opus — Fable 5 quota measured EXHAUSTED mid-run. needs:contract-review applied as the compensating control.

The first dispatch at CONTRACT_REVIEW_TIER died early with a hard API refusal:

You've reached your Fable 5 limit.

It had reached "Now I need live servers for the population re-measurement" — no branch, no worktree, nothing written. So this is a fresh dispatch, not a resume.

Why opus is the right call and not a throughput shortcut

Standing maintainer ruling, 2026-08-13, verbatim: 「fable 如果用完了,可以用 opus」. That covers exactly this case — the tier is unavailable, not merely expensive.

⛔ This is not the forbidden move. The rule that stands is never re-dispatch a clause ② card below CONTRACT_REVIEW_TIER for throughput. Dropping a tier because the quota is gone is the case the maintainer pre-ruled; dropping it because a card is in a hurry is the one that is banned. Recording the distinction so this comment cannot later be read as precedent for the second.

⚠️ Quota state this shift, for the record: measured recovered around 06:0xZ (#11782 dispatched successfully at the tier, then #11875 → PR #12119 landed at it), and measured exhausted again at ~11:3xZ here. So it is oscillating within a single shift. ⛔ Neither reading generalises — probe, never assume, and never read "no fable dispatch lately" as "quota recovered".

The compensating control

needs:contract-review applied. Both limbs of that label's definition are conditioned on "dispatched below the tier", and this card now is — so the label is genuinely owed here, where it would not have been owed had the first dispatch survived.

Concretely, the review burden moves to this seat, and these do not soften:

1. The collision bound is non-negotiable. Name the hash, the digest width actually stored, the expected row count, and the resulting probability bound. ⛔ "SHA-256 is fine" is not an answer. If the stored width is truncated below the full digest, that truncation is the number that matters.
2. State whether a write-time hash collision is distinguishable from a genuine uniqueness violation. If it is not, say so plainly — an operator seeing an unexplainable duplicate error is a user-visible wrong answer, not a crash.
3. Both accept/reject transitions measured on live servers, read from information_schema, boundary included, with Postgres as the 0/44 control.

Everything else in my claim comment stands unchanged — route, population of 7, and the band ledger.

---

Generated by Claude Code