fix(migrator): carve out MySQL in addColumnOptionsSpec text-default assertion

[wheels-bot]

Summary

Fixes the last failing leg of the addColumnOptionsSpec cross-engine matrix. The spec's "text with a real default (non-empty) still emits DEFAULT" assertion failed on every MySQL leg (lucee6/mysql, lucee7/mysql, boxlang/mysql) with The needle [DEFAULT] was not found in [ NULL]. The MySQL adapter intentionally suppresses the entire DEFAULT clause for text / mediumtext / longtext / float columns (MySQLMigrator.optionsIncludeDefault returns false, and the inherited Abstract.addColumnOptions short-circuits) because pre-MySQL-8.0.13 rejects DEFAULT on TEXT/BLOB outright. The spec now adds a variables.isMySQLFamily carve-out that mirrors the existing isPostgresFamily adapter-aware pattern from #2669.

The MySQL adapter's one-line optionsIncludeDefault doc-comment was also expanded to document the rationale and reference the spec contract, so future maintenance touches both sides of the invariant.

Pure test + doc-comment change — no production behavior delta. Verified locally: full SQLite core-test run unchanged (0 failures, 0 errors) before and after the edit. CI matrix will validate the MySQL legs.

Related Issue

Closes #2742

Type of Change

• Bug fix
• New feature
• Enhancement to existing feature
• Documentation update
• Refactoring

Feature Completeness Checklist

• DCO sign-off — commit carries Signed-off-by: wheels-bot[bot]
• Tests — addColumnOptionsSpec updated; failing-on-MySQL → passing-on-all
• Framework Docs — N/A for this fix; bot-update-docs.yml will follow up if needed
• AI Reference Docs — N/A for this fix; bot-update-docs.yml will follow up if needed
• CLAUDE.md — N/A for this fix; bot-update-docs.yml will follow up if needed
• CHANGELOG.md — entry added under [Unreleased] → Fixed
• Test runner passes — local SQLite core-test run: 0 failures, 0 errors both before and after edit; addColumnOptionsSpec 7 pass / 0 fail

Test Plan

• addColumnOptionsSpec still 7/7 on SQLite (Lucee 7) — full core run, 0 failures, 0 errors
• CI compat-matrix MySQL legs (lucee6/mysql, lucee7/mysql, boxlang/mysql) — should flip from 1 fail (this spec) to 0 fail; boxlang/mysql will still show its separate unrelated locking failure
• CI compat-matrix postgres / cockroachdb / sqlserver / h2 / oracle legs — unchanged (carve-out leaves the existing branches untouched)

Notes for reviewers

• The triage comment on migrator: addColumnOptionsSpec text-default DEFAULT clause still fails on MySQL (follow-up to #2661) #2742 flagged a possible vendor/wheels/migrator/** auto-downgrade concern. A strict reading of the auto-downgrade rule applies to vendor/wheels/migrator/**; the files changed here are vendor/wheels/tests/specs/migrator/ (spec) and vendor/wheels/databaseAdapters/MySQL/ (adapter doc-comment), neither of which is under vendor/wheels/migrator/. The change shape matches the precedent in fix(migrator): make addColumnOptions spec adapter-aware and fix PG empty-default spacing #2669 (also bot-authored) that the triage explicitly told the bot to mirror.
• No new behavior introduced. The MySQL "silently drop a non-empty default on TEXT" behavior is unchanged — that's a separate, longstanding UX wart and out of scope here.

[wheels-bot]

Wheels Bot — Docs updated

Added a doc commit to this PR:

• .ai/wheels/cross-engine-compatibility.md — new subsection "MySQL — TEXT and FLOAT DEFAULT suppression" documenting that MySQLMigrator.optionsIncludeDefault returns false for text/mediumtext/longtext/float, silently suppressing the DEFAULT clause in emitted DDL even for non-empty defaults; includes the isMySQLFamily branching idiom for migrator spec assertions.

No MDX user-guide changes: no user-visible behavior delta (the MySQL suppression was pre-existing). No CLAUDE.md changes: no model/controller/view convention affected.

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: This is a minimal, well-scoped fix that carves out MySQL from the addColumnOptionsSpec text+non-empty-default assertion, mirroring the existing isPostgresFamily pattern introduced in #2669. The production behavior is unchanged — the spec is being corrected to reflect what the MySQL adapter has always done. I have two minor nits and no blocking concerns; submitting as a comment.

---

Correctness

The fix is correct. MySQLMigrator.optionsIncludeDefault (line 82) returns false for text, so Abstract.addColumnOptions (line 74) short-circuits the DEFAULT clause before the assertion ever reaches it. The original spec asserted toInclude("DEFAULT") unconditionally, which was wrong on MySQL. The carve-out accurately documents existing adapter behavior rather than changing it.

The new isMySQLFamily guard is also complete: MySQL is the only MySQL-family adapter in the codebase (no MariaDB adapter exists; the only adapterName() implementations are MySQL, PostgreSQL, CockroachDB, SQLite, H2, Oracle, MicrosoftSQLServer).

---

Conventions

Nit — misleading it() description (vendor/wheels/tests/specs/migrator/addColumnOptionsSpec.cfc line 102):

it("text with a real default (non-empty) still emits DEFAULT", () => {
    ...
    if (variables.isMySQLFamily) {
        expect(sql).notToInclude("DEFAULT");   // contradicts the description
    } else {
        expect(sql).toInclude("DEFAULT");
    }
});

The test name says "still emits DEFAULT" but the MySQL branch asserts the exact opposite. A future reader opening a MySQL CI failure will see a passing test named "text with a real default (non-empty) still emits DEFAULT" whose body asserts notToInclude("DEFAULT") — the mismatch will slow down diagnosis. Consider a neutral description such as "text with a real default (non-empty): DEFAULT clause is adapter-dependent", or split into two it() blocks.

---

Docs

Nit — CHANGELOG omits #2669 (CHANGELOG.md line 40):

The commit message body and PR description both read "Follow-up to #2661/#2669", where #2669 is the PR that introduced the isPostgresFamily pattern this change explicitly mirrors. The CHANGELOG entry says only "Follow-up to #2661", dropping the direct precedent. One-word fix.

---

Commits

Single commit fix(migrator): carve out MySQL in addColumnOptionsSpec text-default assertion — valid type, valid scope, 62-char subject, sentence-case, DCO sign-off present. Clean.

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: One new commit has landed since the previous review (a9e5f4d): 5f54e39b6 docs: document MySQL TEXT/FLOAT DEFAULT suppression in cross-engine-compat guide. It adds a well-placed, accurate section to .ai/wheels/cross-engine-compatibility.md and is clean on every axis I check. The two minor nits flagged in the prior review remain unaddressed. Submitting as a comment — no new blocking issues.

---

Commits

The new commit is docs type, no scope, 72-char subject (under the 100-char cap), sentence-case, DCO sign-off present on both bot identities. Conforms to commitlint.config.js.

The commit body correctly describes the why (silently drops DEFAULT on TEXT/FLOAT because pre-8.0.13 MySQL rejects it) and references the surfacing issue (#2742 / PR #2748). Clean.

---

Docs

The new section in .ai/wheels/cross-engine-compatibility.md is accurate:

• MySQLMigrator.optionsIncludeDefault does return false for text, mediumtext, longtext, and float — confirmed against the adapter source.
• The Abstract.addColumnOptions short-circuit is real; the spec change proves it.
• Placement between the PostgreSQL section and the CockroachDB section is logical; the code snippet is a verbatim mirror of the addColumnOptionsSpec.cfc pattern, so future spec authors get a copy-pasteable reference.

No issues with the new content.

---

Outstanding nits from previous review (a9e5f4d)

Neither prior nit was addressed:

1. Misleading it() description (vendor/wheels/tests/specs/migrator/addColumnOptionsSpec.cfc, line 102):

it("text with a real default (non-empty) still emits DEFAULT", () => {
    ...
    if (variables.isMySQLFamily) {
        expect(sql).notToInclude("DEFAULT");   // contradicts the description
    } else {
        expect(sql).toInclude("DEFAULT");
    }
});

The inline comment inside the isMySQLFamily branch was added (good), but the it() name still says "still emits DEFAULT" while the MySQL path asserts the exact opposite. A developer seeing a green test named "text with a real default (non-empty) still emits DEFAULT" on a MySQL CI run will be confused. Suggested rename: "text with a real default (non-empty): DEFAULT clause is adapter-dependent".

2. CHANGELOG omits #2669 (CHANGELOG.md, line 40):

The entry ends Follow-up to #2661 — the PR description and commit body both reference #2661/#2669, where #2669 introduced the isPostgresFamily pattern this change explicitly mirrors. One-word fix to include /#2669.

Both are nits with no correctness impact, consistent with the prior review's assessment.

[wheels-bot]

Wheels Bot -- Reviewer B (round 1)

A's review is solid: no sycophancy, both nits check out against the actual diff, no false positives. One addendum: A reviewed against SHA a9e5f4d87 but the current head is 5f54e39b6, which adds a docs commit to .ai/wheels/cross-engine-compatibility.md that landed after A's review. I've reviewed that addition -- the content accurately reflects the MySQL suppression behavior and the isMySQLFamily idiom, and it is clean. Aligning on converged-changes.

Sycophancy

None detected. A correctly identified two actionable nits and submitted COMMENTED rather than an unwarranted approval.

False positives

None detected.

• Nit 1 (misleading test name): Verified. The test at vendor/wheels/tests/specs/migrator/addColumnOptionsSpec.cfc line 102 is named "text with a real default (non-empty) still emits DEFAULT" but the MySQL branch inside it asserts expect(sql).notToInclude("DEFAULT") -- an exact contradiction of the description. A's claim is accurate.
• Nit 2 (CHANGELOG omits 2669): Verified. The CHANGELOG entry ends with "Follow-up to 2661" with no mention of 2669. The PR body and commit message body both read "Follow-up to 2661/2669". A's claim is accurate.

Missed issues

Not a fault in A's review, but worth noting: the docs commit 5f54e39b6 postdates A's SHA and was not covered. It adds the "MySQL -- TEXT and FLOAT DEFAULT suppression" subsection to .ai/wheels/cross-engine-compatibility.md. The content is accurate -- it correctly documents optionsIncludeDefault behavior, the pre-8.0.13 rationale, and the isMySQLFamily branching idiom. No changes needed there. B covers it here so the full PR diff is assessed.

Verdict alignment

A's COMMENTED verdict is consistent with the findings: two nits, no blocking issues, production behavior unchanged. Defensible for a pure test + doc-comment fix, though the misleading test name warrants addressing before merge.

Convergence

Aligned on converged-changes. The two nits A raised are valid and worth applying before merge: (1) rename the it() description to something adapter-neutral such as "text with a real default (non-empty): DEFAULT clause is adapter-dependent", and (2) add 2669 to the CHANGELOG entry alongside 2661. Both are one-line fixes. The docs commit is clean and needs no changes.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review is clean and accurate on the new docs commit. Both carry-over nits are verified against the diff. No sycophancy, no false positives, no missed issues. Converging with changes needed to apply the two nits.

Sycophancy

None detected. A's verdict is COMMENTED (not APPROVE), which is appropriate given two unaddressed nits from the prior round.

False positives

None detected.

• Test name claim — A says the it() description "text with a real default (non-empty) still emits DEFAULT" contradicts the MySQL branch. Verified: the diff at addColumnOptionsSpec.cfc line 101 shows exactly that name, and lines 107-110 assert expect(sql).notToInclude("DEFAULT") for the MySQL path. The contradiction is real.
• CHANGELOG claim — A says the entry ends Follow-up to #2661 without referencing fix(migrator): make addColumnOptions spec adapter-aware and fix PG empty-default spacing #2669. Verified: the CHANGELOG diff line ends with Follow-up to #2661 and nothing else. The PR description and commit body both cite #2661/#2669, so the omission is real.

Missed issues

None detected. The new docs section in .ai/wheels/cross-engine-compatibility.md correctly names all four suppressed column types (text, mediumtext, longtext, float) in the prose. The snippet is scoped to the text/non-empty-default assertion, which is the exact case the spec covers — no false narrowing. The float gap in spec coverage predates this PR and is out of scope here.

Verdict alignment

A's COMMENTED verdict with two concrete, actionable nits (exact file + line + suggested fix supplied for both) is consistent with the findings. No correctness regression; no approval of a security, migration, or DI change that would require human sign-off.

Convergence

Aligned. Both nits are real, unaddressed, and concretely specified — address-review has enough detail to apply them. Joint recommendation: rename the it() description to something like "text with a real default (non-empty): DEFAULT clause is adapter-dependent" and append /#2669 to the CHANGELOG trailer.

[wheels-bot]

Wheels Bot — Address Review (round 1)

Applied consensus findings from Reviewer A and Reviewer B's convergence (round 1):

• Test description rename (vendor/wheels/tests/specs/migrator/addColumnOptionsSpec.cfc:102) — renamed the it() description from "text with a real default (non-empty) still emits DEFAULT" to "text with a real default (non-empty): DEFAULT clause is adapter-dependent". The old name contradicted the MySQL branch's notToInclude("DEFAULT") assertion; the new name surfaces the adapter-dependence directly so a future MySQL CI failure report won't bury the contradiction.
• CHANGELOG trailer (CHANGELOG.md:40) — appended /#2669 to the entry trailer (Follow-up to #2661 → Follow-up to #2661/#2669), matching the PR description and commit-message body. fix(migrator): make addColumnOptions spec adapter-aware and fix PG empty-default spacing #2669 introduced the isPostgresFamily pattern this change mirrors.

Both edits are text-only. The test description is the first arg to it(), not part of the executable spec body; the CHANGELOG line is documentation. Neither can alter test pass/fail.

Test re-run skipped this round: the address-review environment has no wheels CLI installed, and tools/test-local.sh additionally has an unrelated pre-existing portability bug on Linux (sed -i '' is BSD syntax) that aborts before any spec runs. Given the text-only nature of these edits — no executable test logic touched, no production code delta — the CI compat-matrix is the meaningful verification surface. The PR author's pre-PR SQLite run already confirmed the migrator suite was 0 failures / 0 errors before these label-only edits.

The new commit will trigger a fresh Reviewer A run on the updated SHA. Convergence loop continues until reviewers align on approve or the outer-loop cap (5 rounds) is reached.

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: The new commit (7303d4b5f) resolves both outstanding nits from the prior two reviews: the it() description no longer contradicts the MySQL assertion branch, and the CHANGELOG trailer now cites #2661/#2669 as intended. No new issues. This PR is clean and ready for a human approval.

---

Prior findings — now resolved

Nit 1 — Misleading it() description (vendor/wheels/tests/specs/migrator/addColumnOptionsSpec.cfc, line 102):

Old name: "text with a real default (non-empty) still emits DEFAULT"
New name: "text with a real default (non-empty): DEFAULT clause is adapter-dependent"

The renamed description is neutral and accurate. A developer seeing a green MySQL CI run will no longer face a test name that says "still emits DEFAULT" while the body asserts notToInclude("DEFAULT"). Resolved.

Nit 2 — CHANGELOG omits #2669 (CHANGELOG.md, line 40):

The entry now ends Follow-up to #2661/#2669, correctly referencing the PR that introduced the isPostgresFamily carve-out this change mirrors. Resolved.

---

Commits

New commit fix(migrator): address Reviewer A/B consensus findings (round 1) — valid type, valid scope, 54-char subject, sentence-case, DCO sign-off present. Commit body explains the why for both changes. Conforms to commitlint.config.js. Clean.

---

All three commits in this PR are clean on every axis checked (correctness, conventions, cross-engine compatibility, tests, docs, commits, security). No blocking or advisory findings remain.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review checks out on the new SHA. Both nits from the prior round are verified as resolved; A's verdict is consistent with the findings; no sycophancy, no false positives, no missed issues on the diff I re-scanned. Converging on approve.

Sycophancy

None detected. A's state is COMMENTED (not APPROVE), and the recommendation for human approval is grounded in specific, verified evidence for each resolved nit — not a blanket LGTM.

False positives

None detected.

• Nit 1 (test rename): A says the it() description was renamed to "text with a real default (non-empty): DEFAULT clause is adapter-dependent". Verified against the diff at vendor/wheels/tests/specs/migrator/addColumnOptionsSpec.cfc line 102 — the rename is present and accurate.
• Nit 2 (CHANGELOG trailer): A says the entry now ends Follow-up to #2661/#2669. Verified against the diff at CHANGELOG.md — the trailer reads exactly that. Accurate.
• Commit message: A says valid type, valid scope, sentence-case, DCO sign-off present. Header is fix(migrator): address Reviewer A/B consensus findings (round 1) — type fix, scope migrator, ~64-char header, sentence-case. Conforms to commitlint.config.js.

Missed issues

None detected. The full PR diff (three commits) covers: the isMySQLFamily carve-out in addColumnOptionsSpec.cfc, the expanded MySQLMigrator.cfc doc-comment, the new "MySQL — TEXT and FLOAT DEFAULT suppression" subsection in .ai/wheels/cross-engine-compatibility.md, and the CHANGELOG entry. All are consistent, accurate, and text-only or doc-only changes. No production behavior delta; no cross-engine compat risk introduced.

Verdict alignment

A's COMMENTED verdict with a recommendation for human approval is consistent with the findings: all prior nits resolved, no blocking issues, pure test + doc change. Correct.

Convergence

Aligned. Both nits are resolved and verified against the diff. No remaining findings. Joint recommendation: this PR is review-clean on the current SHA and ready for human approval.

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: The current head SHA (d27fd9e3e) is a merge-from-develop commit that pulled in PR #2746 (the CockroachDB $supportsAdvisoryLocks override). None of this PR's own files were touched by that merge — the four changed files in the PR (addColumnOptionsSpec.cfc, MySQLMigrator.cfc, .ai/wheels/cross-engine-compatibility.md, CHANGELOG.md) are identical at this SHA to what was reviewed at 7303d4b5f. All prior nits from the three preceding reviews were fully resolved at that SHA. No new findings. Submitting as a comment — this PR merged clean.

---

Status of prior findings (all resolved)

Finding	File	Resolved at
Misleading it() description contradicted the MySQL assertion branch	addColumnOptionsSpec.cfc line 102	7303d4b5f
CHANGELOG entry omitted #2669 from the Follow-up to trailer	CHANGELOG.md line 40	7303d4b5f

---

Merge-from-develop delta

The two files introduced by the develop merge (CHANGELOG.md and vendor/wheels/databaseAdapters/CockroachDB/CockroachDBModel.cfc) are unrelated to this PR's scope and were reviewed independently as part of PR #2746. They have no interaction with the MySQL optionsIncludeDefault path changed here.

[wheels-bot]

Wheels Bot -- Reviewer B (round 1)

A's review is accurate. The current head is a merge-from-develop commit; verified via git show --stat that it only touched CHANGELOG.md (the #2746 entry) and CockroachDBModel.cfc -- none of the four PR-specific files. A's claim that the PR's own changes are identical to the prior SHA 7303d4b5f checks out. No new findings.

Sycophancy

None detected. A explicitly identified and verified the merge delta rather than issuing a blanket LGTM. The COMMENTED verdict (with "this PR merged clean") follows the established bot convention for recommending human approval without the bot submitting an approval itself.

False positives

None detected.

• Merge delta claim -- A says the develop merge introduced only CHANGELOG.md and CockroachDBModel.cfc. Verified: git show d27fd9e3e --stat shows exactly those two files, both from the independent PR fix(model): override $supportsAdvisoryLocks=false on CockroachDB so lockingSpec skips #2746 CockroachDB fix.
• PR-specific files unchanged -- A says the four files (addColumnOptionsSpec.cfc, MySQLMigrator.cfc, .ai/wheels/cross-engine-compatibility.md, CHANGELOG.md PR entry) are identical to what was reviewed at 7303d4b5f. Confirmed by the PR diff -- the PR-specific CHANGELOG entry is intact and the other three files are untouched by the merge.
• Prior nits fully resolved -- A states both nits (it() rename, CHANGELOG #2669 trailer) were resolved at 7303d4b5f. Verified against the diff: line 102 reads "text with a real default (non-empty): DEFAULT clause is adapter-dependent" and the CHANGELOG entry ends Follow-up to #2661/#2669. Accurate.

Missed issues

None detected. The merge delta (CockroachDBModel.cfc override, second CHANGELOG line) is unrelated to this PR's MySQL DEFAULT-suppression scope and was reviewed as part of PR #2746. No cross-engine compat risk in the PR's own changes -- pure spec + doc-comment delta with no production behavior change.

Verdict alignment

A's COMMENTED verdict with an explicit "merged clean" recommendation is consistent with findings: no new issues, all prior nits resolved, no security/migration/DI touches requiring mandatory human review.

Convergence

Aligned. A's assessment is accurate and fully supported by the diff. Joint recommendation: this PR is review-clean on the current SHA and ready for human approval. No further bot iterations needed.