service-messaging: 15 keyed text columns declare no maxLength — five sys_notification_* objects land registered-but-broken on MySQL

[os-elon]

Found by the class-level gate built for #12147 (node scripts/check-keyed-text-bounds.mjs), on fa5d137ab0. This is a live member set of the #11374 route-A class, in a package that no existing pin covers — packages/services/service-messaging has no keyed-text-bounds pin, and the three that exist are scoped to platform-objects, plugin-audit and plugin-security.

The mechanism, restated once

A text-family column a declared index keys on must declare a maxLength, because a bound is what lets the column be a key at all. Without one, driver-sql's keyableTextLength returns null and createColumn emits table.text(name). MySQL then refuses ALTER TABLE … ADD [UNIQUE] INDEX on a TEXT column with no prefix length (ER_BLOB_KEY_WITHOUT_LENGTH), so CREATE TABLE succeeds, the index does not, and the object lands registered-but-broken with its declared index silently absent. Measured live on MySQL 8.0.46 in PR #12058.

The severity is not uniform across the 15. sys_notification_delivery declares

{ fields: ['notification_id', 'recipient_id', 'channel'], unique: true }

over three unbounded text columns. That index is the outbox's dedup constraint ("one delivery per (event, recipient, channel)"). On MySQL it does not exist, so the constraint the comment describes is not enforced and duplicate deliveries are admitted.

The 15 columns

column	type	index kind	plausible referent for the bound
sys_notification_delivery.notification_id	text	UNIQUE (composite) + plain	FK to sys_notification.id
sys_notification_delivery.recipient_id	text	UNIQUE (composite)	FK to sys_user.id
sys_notification_delivery.channel	text	UNIQUE (composite)	channel id vocabulary
sys_notification_delivery.digest_key	text	plain (composite)	derived `recipient
sys_notification_preference.user_id	text	plain	FK to sys_user.id, or the literal *
sys_notification_preference.topic	text	plain	topic vocabulary, or *
sys_notification_preference.channel	text	plain	channel id vocabulary, or *
sys_notification_receipt.notification_id	text	plain	FK to sys_notification.id
sys_notification_receipt.user_id	text	plain	FK to sys_user.id
sys_notification_receipt.channel	text	plain	channel id vocabulary
sys_notification_subscription.topic	text	plain	topic vocabulary
sys_notification_subscription.principal	text	plain	RecipientResolver.resolveOne() accepts an email-shaped value as well as a bare user id (#9807)
sys_notification_template.topic	text	plain	topic vocabulary
sys_notification_template.channel	text	plain	channel id vocabulary
sys_notification_template.locale	text	plain	BCP-47 tag; sys_email_template.locale is bounded at 16

Reproduce the list with node scripts/check-keyed-text-bounds.mjs --list once the #12147 gate lands.

Why this is filed rather than fixed on #12147's PR

#12147 is a domain:devx card whose deliverable is the gate. Bounding these columns is not a mechanical drive-by:

1. Each bound needs a sourced producer. Route A's shape is a NAMED producer stated in the declaration so it is vetoable in review. topic, channel and principal have no bound that can be read off a sibling declaration — channel and topic are open string vocabularies here, and principal deliberately accepts an email-shaped value. Picking a number without sourcing it is the failure route A exists to prevent.
2. It is a schema migration, not just a declaration. These columns are emitted TEXT today. Declaring a bound moves them to varchar(n), which is a drift op against every existing deployment, and the narrowing direction is categorised destructive in schema-drift.ts. That disposition belongs to the services/engine lane with a changeset, not to a devx gate PR.
3. The two id-family columns are the easy half and the rest are not, so a partial fix would leave the object's composite UNIQUE index still inexpressible while reading as addressed.

Until it is fixed, all 15 are recorded in the gate's per-package ALLOWLIST as kind: 'pending' rows citing this issue. That ledger is enumerated, not a wildcard: a new unbounded keyed text column anywhere in the tree still fails the gate, a row whose column gets bounded fails as stale, and a row whose column stops being keyed text fails as stale. Nothing here goes quiet.

Not in scope of this one

The separate >768-character key class (#11627 for the UNIQUE half, #11701 for the non-unique half) is a different predicate with a different disposition and is not folded in. None of the 15 declares a bound at all, so they are all route-A members first.

[os-elon]

p0 by maintainer instruction, and dispatched — ⚠️ from a seat that does not own this surface

Claim: domain:devx @ objectstack PM seat (issue #6023), session session_01CPrUz21stTFhJRUirdc4yw, round R25.

⚠️ Disclosed rather than glossed: packages/services/service-messaging is not this seat's lane. This is a domain:devx seat dispatching a services/engine surface, and it is doing so on a direct maintainer instruction (2026-08-28, escalate to p0 and dispatch a fix), not on its own authority. Another seat finding a devx session on this card should read that as the reason. If the services or engine lane wants it back, take it — this seat will stand down on request and hand over the brief.

⛔ No domain:* label written. That field is triage's, single-producer, decided by reading the code. This seat produces pm:* state and nothing else, and guessing domain:services from the path is exactly the failure that would mis-route it.

• Branch claude/issue-12978-notification-keyed-text-bounds · dedicated worktree off origin/main
• File surface packages/services/service-messaging/src/objects/*.object.ts, the pending rows in scripts/check-keyed-text-bounds.mjs's allowlist, and a changeset
• Container & model claude-fable-5 — see Clause ② below
• Clause-②: YES — --tier returns no path-derived mandate on this surface, so it is judged from card content, and the content is decisive: declaring maxLength on a field changes what the schema accepts, which is contract accept/reject behaviour. needs:contract-review applied.
• Serial constraints ⚠️ PR #12991 (Class-level keyed-text-bounds coverage needs a source-scanning gate — lifting the platform-objects pin is blocked by dependency direction (measured on #12059) #12147) is open and unlanded and it creates scripts/check-keyed-text-bounds.mjs including the 15 pending rows this card must retire. ⇒ this work is serialised behind it; the dev branches off a main that carries it, and ⛔ must not recreate the gate or edit rows that do not exist yet.

⚠️ Two things the escalation does not change, and a reviewer must not lose

1. Fixing this refuses boot on existing deployments. Verified at source rather than taken from the card: the TEXT → varchar(n) narrowing is category destructive in schema-drift.ts, and runArtifactBootMigrationGate refuses the boot for category = destructive — an operator must run os migrate apply --allow-destructive. So the fix trades "the dedup constraint silently does not exist on MySQL" for "existing deployments do not boot until an operator acts". Both are real; the second is louder, which is the right direction, but it is an operational consequence a p0 label does not dissolve. It must be disclosed in the PR body and in the changeset.

2. The card's own reason for not fixing it inline still binds. ⛔ "Picking a number without sourcing it is the failure route A exists to prevent." topic, channel and principal have no bound readable off a sibling declaration — channel and topic are open string vocabularies, and principal deliberately accepts an email-shaped value as well as a bare user id (#9807). p0 is a schedule, ⛔ not a licence to invent numbers.

Scope ruling

The p0 is the dedup constraint, and its unit of correctness is the whole composite index. sys_notification_delivery's { fields: ['notification_id','recipient_id','channel'], unique: true } must be bounded on all three columns together, or not at all — the card is explicit that the two id-family columns are the easy half and that a partial fix "would leave the object's composite UNIQUE index still inexpressible while reading as addressed." ⛔ That outcome is refused.

The remaining 11 columns are the same class but not the p0. Bound the ones whose producer can be honestly sourced; leave the rest pending with their citation intact and say which and why.

---

Generated by Claude Code

[os-elon]

Measurement: is the dedup constraint actually unenforced on MySQL today? (#11627 hash shadow vs. this card's headline)

Requested by the PM before the #12978 fix proceeds. Three questions, each with the instrument shown to return both answers; verdict at the end. Container has no MySQL server and no docker daemon, so the live-MySQL legs cite the tree's own pinned opt-in suites (run on live MySQL 8.0.46 per their headers) plus the source predicate chain; everything runnable here was run.

Q1 — does the #11627 hash shadow cover sys_notification_delivery's composite UNIQUE as declared today (three unbounded TEXT columns)?

Yes. The chain, each link cited:

1. Trigger matches the unbounded-TEXT refusal, not only the too-wide one. explainUnkeyableTextColumn fires for BOTH ER_BLOB_KEY_WITHOUT_LENGTH (the code an unbounded TEXT key part raises) and ER_TOO_LONG_KEY (packages/drivers/driver-sql/src/sql-driver.ts, the code check in explainUnkeyableTextColumn). The shadow fallback sits behind that match and behind if (unique) only, and is reactive — attempted only AFTER the server refused the direct index.
2. createHashShadowUniqueIndex has exactly one precondition: isMysql. Nothing conditions on the column being bounded; a composite is handled via CONCAT(col1, 0x1f, col2, ...) into UNHEX(SHA2(..., 256)) on a VARBINARY(32) STORED GENERATED column carrying the UNIQUE key.
3. Pinned live evidence, this exact shape. sql-driver-keyed-text-mysql.test.ts — "carries the UNIQUE cases on a hash shadow, still never a prefix index" — drives an object whose field is { type: 'text' } with NO maxLength and a unique: true index through initObjects on live MySQL, then reads information_schema.STATISTICS: the UNIQUE index exists, keys a __hash column, NON_UNIQUE = 0, SUB_PART null. The file states in words: "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) #11627 made a UNIQUE index over an unkeyable column expressible — it is now carried on a hash-shadow column instead of being refused. That is a ruled behaviour change (maintainer, 2026-08-24 on driver-sql: the platform-objects schema does not sync onto MySQL — unbounded string fields become TEXT, which MySQL refuses to index #11374)." Composite tuple semantics (separator injectivity, any-NULL tuples non-conflicting, real duplicates rejected) are pinned in sql-driver-11627-hash-shadow-key.test.ts.
4. Both directions in-container: I ran the two suites here: 5 passed (naming contract x2, the SQLite keeps-direct-index-no-shadow control, the emission rule x2), 3 skipped — the skips being precisely the live MySQL/Postgres cells, gated on OS_TEST_MYSQL_URL / OS_TEST_POSTGRES_URL. Exit 0, vitest summary "Test Files 2 passed (2), Tests 5 passed, 3 skipped (8)".

One data-dependent exception. On a database that accumulated real duplicate triples while nothing was enforced (pre-#11627 window), the shadow ALTER itself hits ER_DUP_ENTRY; the driver logs the failed shadow attempt and falls through to the named refusal (sql-driver.ts, the shadowErr catch). Dedup then stays UNENFORCED for that deployment until the rows are deduplicated. So "enforced via shadow" is the steady state, not a retroactive repair.

Q2 — is it live for this object specifically, or conditional on something it does not satisfy?

Conditions, checked against sys_notification_delivery as declared:

• MySQL-only by design (Postgres/SQLite take the direct index over TEXT; the SQLite no-shadow control ran green here). On Postgres the dedup index has always existed — the whole defect is MySQL-only.
• UNIQUE-only: the dedup index declares unique: true — covered. Global scope (bare composite, no organization key part), all three columns required: true — none of the org-scope or NULL caveats below apply to it.
• Order: the dedup UNIQUE is indexes[0], and syncDeclaredIndexes processes entries sequentially and throws at the first failing entry (syncTableIndexes passes field-level uniques then declared indexes in declaration order). So the dedup shadow lands BEFORE the later plain-index throw aborts the remainder — the shadow is not lost to the throw.
• Freshness: the table must have been synced at least once by a post-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) #11627 build. The alter path re-attempts missing declared indexes on EVERY boot of an existing table (initObjects alter branch always reaches syncTableIndexes), so an older MySQL database gains the shadow on its first boot under the current tree — subject to the duplicate-rows exception in Q1.
• ⚠️ Adjacent but not this index: the two org-scoped UNIQUEs in the same family (sys_notification_preference, sys_notification_subscription) also reach the shadow today, but the shadow hashes the RAW columns — the declared NULL-safe COALESCE(organization_id, '__global__') key part is not represented — so NULL-organization rows are NOT constrained under the shadow where the declared ADR-0120 D3 semantics say they collide in the global bucket. Pre-existing, unaffected by this card's fix, will be filed separately.

Q3 — what do the plain (non-unique) text-keyed composites do?

• Non-unique unkeyable indexes are deliberately NOT shadowed — pinned: "leaves a non-unique unkeyable index refused rather than shadowing it" (initObjects rejects; a digest index serves no lookup the planner can reach).
• The throw does not take the boot down. @objectstack/objectql's plugin catches per object (reportSyncFailure, packages/objectql/src/plugin.ts) and logs at error level — "Schema sync finished with N FAILED object(s) — those objects are registered and served ..." — and boot continues. So the outcome is a loud per-boot error line plus missing access-path indexes, not a refused boot. (Measured drift harness below confirms the artifact boot-migration gate also does not refuse: the missing-index finding is create_index at category safe, and the gate refuses destructive only.)
• Net state per object on a fresh MySQL boot under the current tree (declaration order decides what lands before the throw):
  • sys_notification_delivery: dedup UNIQUE — shadow, ENFORCED; (status, partition_key, next_attempt_at) ok; (status, claimed_at) ok; (notification_id) REFUSED (throw); (digest_key, status, next_attempt_at) never attempted. Two access-path indexes missing (event-cascade lookup, digest collapse claim).
  • sys_notification_receipt: UNIQUE — shadow, enforced; (user_id, state) refused/missing.
  • sys_notification_preference: org-UNIQUE — shadow (NULL-org caveat above); (topic) refused/missing.
  • sys_notification_subscription: org-UNIQUE — shadow (same caveat); (topic) refused/missing.
  • sys_notification_template: (topic, channel, locale) is FIRST and plain — refused immediately; (topic) never attempted; no unique declared. All declared indexes missing.

Supporting measurement: the migration/boot-gate half (pure functions, run here against built driver-sql)

Harness over exported diffManagedTable / diffManagedIndexes, each zero paired with a non-zero dual in the same run:

PASS A1 mysql: bounded keyed text field over physical TEXT -> NO drift entry [empty]
PASS A2 dual: over physical varchar(65535) -> narrow_varchar @ destructive
PASS A3 postgres: bounded keyed text field over physical text -> NO drift entry [empty]
PASS B1: missing declared UNIQUE -> create_index @ safe (boot gate refuses destructive ONLY)
PASS B2 dual: same-name non-unique physical -> recreate_index @ destructive

So the earlier brief's boot-refusal-via-narrow_varchar mechanism does not apply to this change (that op requires a physical varchar; #11431 deliberately excludes TEXT), and runArtifactBootMigrationGate (refuses category destructive only, packages/cli/src/utils/artifact-boot-migration.ts) does not refuse over this fix. The PM has withdrawn that ruling; disclosure will carry the measured story above.

Verdict: (b), with stated conditions

The dedup constraint is enforced on MySQL under the current tree — carried by the #11627 hash shadow rather than by the declared index — for any database a post-#11627 build has synced, EXCEPT deployments that already hold duplicate triples from the pre-#11627 window (shadow creation fails loudly there; dedup stays off until deduplicated). The card's headline sentence — the index "does not exist" so "duplicate deliveries are admitted" — describes the pre-#11627 tree; the cited measurement (PR #12058, live MySQL) predates the 2026-08-24 shadow ruling.

What remains true and worth fixing, independent of the p0's stated basis: the declared indexes are not expressible AS DECLARED on MySQL — five plain access-path indexes are missing with a loud error every boot, the dedup UNIQUE rides a shadow instead of its declared form, and the two org-scoped UNIQUEs ride it with weakened NULL-org semantics. Bounding the 15 columns (all 15 source cleanly — sourcing table on the PR) makes the dedup UNIQUE a direct index on new MySQL databases (255+255+64 = 574 chars = 2296 utf8mb4 bytes, inside InnoDB's 3072-byte key budget, measured boundary in-tree: varchar(768) keys, varchar(769) refuses), makes every plain index creatable, and gives existing MySQL databases a real operator path.

Not softening the card and not proceeding on the p0 basis as filed — the maintainer owns the label. Holding the fix behind #12991's landing as briefed; the declaration work is otherwise ready.

Generated by Claude Code · session_01CPrUz21stTFhJRUirdc4yw

---

Generated by Claude Code