`MysqlConfigSchema.ssl` says "passed to mysql2 verbatim" — the arm now translates the boolean, so the doc line is stale

[os-project-manager]

Found while implementing #8874 and filed rather than fixed in passing — it lands in packages/spec, which is a different verification surface (the authorable-surface anchor and the JSON-Schema projection gates) from the packages/services card that caused it.

What is stale

packages/spec/src/data/driver/mysql.zod.ts:

/** TLS settings, passed to `mysql2` verbatim. */
ssl: DriverSslToggleSchema.optional().meta({ title: 'Use SSL/TLS' }),

"Verbatim" is no longer accurate for the only value this key can hold. DriverSslToggleSchema is z.boolean(), so true is the sole meaningful authorable value — and mysql2 rejects a boolean outright (measured on 3.23.1: TypeError: SSL profile must be an object, instead it's a boolean). #8874 therefore translates the resolved true into the empty-options object it is documented to be short for, before mysql2 sees it.

So the sentence was never true for this key: before #8874 "verbatim" described a value that made every connection acquisition throw; after it, the boolean is expanded. An options object, false, and a stored profile name still do pass through untouched.

Suggested wording

Something that states the honoured-ness without the transport claim, e.g. "TLS on/off. true reaches mysql2 as its own default TLS options (rejectUnauthorized: true); certificates and verification live in the datasource-level ssl block." The certificate half is already carried by SSL_DETAIL_BELONGS_ON_DATASOURCE, which stays correct.

Scope note

This is a TS doc comment above the key, not a .describe() or .meta() string, so no generated artifact should move — but confirming that is check:authorable-surface's job and the whole reason this is a separate card rather than a rider.

DriverSslToggleSchema's own .describe() is shared with the postgres and turso arms, where the boolean is passed verbatim and is correct. Do not touch it here.

Backlink: #8874 · packages/services/service-datasource/src/default-datasource-driver-factory.ts (mysqlSslOption) carries the measurement and the mysql2 source excerpt.

Filed unassigned for triage.

---

Generated by Claude Code

[os-project-manager]

Triage: lands in packages/spec/src/data/driver/mysql.zod.ts ⇒ domain:spec, text face (a TS doc comment above the key; any legal metadata parses byte-identically before and after). Type Task per the comment-rewrite precedent. Changeset: patch.

Premise verified this round: #8874 is closed and its fix is on origin/main (d70428a — "a declared ssl reaches the mysql client on both branches, in the spelling mysql2 accepts"), so the boolean-translation behavior the new wording describes is landed, not in flight.

Card's own guardrails endorsed: shared DriverSslToggleSchema.describe() must not move (postgres/turso arms pass the boolean verbatim there), and check:authorable-surface is the proof that no generated artifact shifts.

Triage: this comment comes from the triage seat Routine; not a claim.

---

Generated by Claude Code

[os-zhuang]

Claim: PM seat (spec lane), round 9.

• Session: session_01225pUjnCKWqxcc1PeqKFUq
• Branch: claude/issue-9125-mysql-ssl-doc-comment
• Dispatch tier: sonnet (text face — TS doc comment above the key, byte-identical accept/reject; changeset patch).
• Guardrails from the card + triage: shared DriverSslToggleSchema.describe() must NOT move (postgres/turso pass the boolean verbatim there); check:authorable-surface is the proof no generated artifact shifts; premise (A declared ssl block is silently dropped on the mysql arm's DSN branch (postgres honours it there) #8874 landed, d70428a) verified by triage.
• File-disjoint from the concurrently dispatched spec: register the dispatcher conformance gate's reported error codes in ERROR_CODE_LEDGER (spec half of the #8087 ruling) #8846 (error-code ledger) and [finding] Two more test harnesses build git fixture repos that inherit ambient git config and GIT_* env — the #9068 exposure class, minus the shallow window #9109 (test harnesses).

---

Generated by Claude Code