@byline/db-mysql 4.8.0

package/dist/modules/storage/storage-store-manifest.d.ts

@@ -0,0 +1,77 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ *
+ * Generated UNION ALL column projections for the EAV store tables.
+ *
+ * Instead of maintaining 7 hand-synchronized SQL fragments with 41
+ * positional columns each, we generate the SELECT list for each store
+ * table from a single column manifest. Adding a column or a new store
+ * table is a one-line change in the manifest.
+ *
+ * The manifest data (`storeColumnManifest`, `storeTableNames`) is dialect
+ * independent and lives in `@byline/core` — the same manifest
+ * `@byline/db-postgres` consumes. This module owns everything
+ * MySQL-specific: the generated `SQL` fragments, and `mysqlNullCast()`,
+ * which renders the manifest's abstract `nullCast` type names (`'uuid'`,
+ * `'boolean'`, …) as MySQL `CAST(NULL AS <type>)` expressions — MySQL has
+ * no `NULL::<type>` shorthand.
+ *
+ * The adapter-agnostic pieces (`StoreType`, `ALL_STORE_TYPES`,
+ * `fieldTypeToStore`, `fieldTypeToStoreType`) also live in `@byline/core`
+ * so `@byline/client` can consume the same mapping without taking a
+ * dependency on either adapter. Mirrors
+ * `packages/db-postgres/src/modules/storage/storage-store-manifest.ts`.
+ */
+import { type StoreType } from '@byline/core';
+import { type SQL } from 'drizzle-orm';
+export { ALL_STORE_TYPES, fieldTypeToStore, fieldTypeToStoreType, type StoreType, storeTableNames, } from '@byline/core';
+/** Short-form alias used by adapter-internal call sites. */
+export declare const allStoreTypes: readonly StoreType[];
+/** The field_type literal emitted for each store table in the UNION ALL. */
+declare const fieldTypeLiterals: Record<StoreType, string>;
+/**
+ * Map the manifest's abstract `nullCast` type name to its MySQL `CAST(NULL
+ * AS <type>)` expression. MySQL has no `NULL::<type>` shorthand (that's
+ * Postgres-only syntax), so every branch of the UNION ALL that doesn't
+ * provide a given column emits an explicit `CAST`.
+ *
+ * Each mapping was verified against the live MySQL 9.7.1 container (not
+ * just read from the docs) by UNIONing a `CAST(NULL AS …)` branch against a
+ * branch selecting a real, populated column of the corresponding store type
+ * and confirming the driver returns the real value unmodified (no
+ * truncation, no precision loss) — see the Task 10A report for the
+ * transcript. Precision-bearing casts (`TIME(3)`, `DATETIME(6)`,
+ * `DECIMAL(10,2)`) mirror the schema's own column precision
+ * (`packages/db-mysql/src/database/schema/index.ts`) exactly, rather than
+ * relying on MySQL's default (whole-second time, `DECIMAL(10,0)`), so a
+ * NULL-cast branch can never be the one that silently narrows the unified
+ * column's type. `DATETIME(6)` here specifically must track
+ * `value_timestamp_tz`'s own `fsp` (Task 11 moved it from 3 to 6, matching
+ * pg's microsecond precision — see `common.ts`'s `auditTimestamp` docblock)
+ * — re-verified live post-move via `storage-queries.test.ts`'s
+ * `datetime`-field round-trip test, which exercises exactly this branch
+ * (a text-typed sibling row's UNION leg lands on this `CAST`) and confirmed
+ * full microsecond fidelity survives.
+ */
+export declare function mysqlNullCast(nullCast: string): string;
+/** Number of columns in the unified output (base + field_type + type-specific). */
+export declare const UNIFIED_COLUMN_COUNT: number;
+/**
+ * Build the SELECT column list for a given store table type.
+ *
+ * Base columns (id, document_version_id, etc.) are passed through directly.
+ * The `field_type` column is emitted as a string literal.
+ * Type-specific columns are either mapped to the source expression or
+ * emitted as a typed NULL.
+ */
+declare function buildSelectList(storeType: StoreType): string;
+/**
+ * Get the Drizzle SQL fragment for a store type's SELECT list.
+ * Results are cached — the generation runs once at module load.
+ */
+export declare function storeSelectList(storeType: StoreType): SQL;
+export { buildSelectList, fieldTypeLiterals };

package/dist/modules/storage/storage-store-manifest.js

@@ -0,0 +1,168 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ *
+ * Generated UNION ALL column projections for the EAV store tables.
+ *
+ * Instead of maintaining 7 hand-synchronized SQL fragments with 41
+ * positional columns each, we generate the SELECT list for each store
+ * table from a single column manifest. Adding a column or a new store
+ * table is a one-line change in the manifest.
+ *
+ * The manifest data (`storeColumnManifest`, `storeTableNames`) is dialect
+ * independent and lives in `@byline/core` — the same manifest
+ * `@byline/db-postgres` consumes. This module owns everything
+ * MySQL-specific: the generated `SQL` fragments, and `mysqlNullCast()`,
+ * which renders the manifest's abstract `nullCast` type names (`'uuid'`,
+ * `'boolean'`, …) as MySQL `CAST(NULL AS <type>)` expressions — MySQL has
+ * no `NULL::<type>` shorthand.
+ *
+ * The adapter-agnostic pieces (`StoreType`, `ALL_STORE_TYPES`,
+ * `fieldTypeToStore`, `fieldTypeToStoreType`) also live in `@byline/core`
+ * so `@byline/client` can consume the same mapping without taking a
+ * dependency on either adapter. Mirrors
+ * `packages/db-postgres/src/modules/storage/storage-store-manifest.ts`.
+ */
+import { ALL_STORE_TYPES, storeColumnManifest } from '@byline/core';
+import { sql } from 'drizzle-orm';
+// Re-export for adapter-internal consumers.
+export { ALL_STORE_TYPES, fieldTypeToStore, fieldTypeToStoreType, storeTableNames, } from '@byline/core';
+/** Short-form alias used by adapter-internal call sites. */
+export const allStoreTypes = ALL_STORE_TYPES;
+// ---------------------------------------------------------------------------
+// SQL generation
+// ---------------------------------------------------------------------------
+/** The field_type literal emitted for each store table in the UNION ALL. */
+const fieldTypeLiterals = {
+    text: 'text',
+    numeric: 'numeric',
+    boolean: 'boolean',
+    datetime: 'datetime',
+    json: 'richText',
+    relation: 'relation',
+    file: 'file',
+};
+/**
+ * Map the manifest's abstract `nullCast` type name to its MySQL `CAST(NULL
+ * AS <type>)` expression. MySQL has no `NULL::<type>` shorthand (that's
+ * Postgres-only syntax), so every branch of the UNION ALL that doesn't
+ * provide a given column emits an explicit `CAST`.
+ *
+ * Each mapping was verified against the live MySQL 9.7.1 container (not
+ * just read from the docs) by UNIONing a `CAST(NULL AS …)` branch against a
+ * branch selecting a real, populated column of the corresponding store type
+ * and confirming the driver returns the real value unmodified (no
+ * truncation, no precision loss) — see the Task 10A report for the
+ * transcript. Precision-bearing casts (`TIME(3)`, `DATETIME(6)`,
+ * `DECIMAL(10,2)`) mirror the schema's own column precision
+ * (`packages/db-mysql/src/database/schema/index.ts`) exactly, rather than
+ * relying on MySQL's default (whole-second time, `DECIMAL(10,0)`), so a
+ * NULL-cast branch can never be the one that silently narrows the unified
+ * column's type. `DATETIME(6)` here specifically must track
+ * `value_timestamp_tz`'s own `fsp` (Task 11 moved it from 3 to 6, matching
+ * pg's microsecond precision — see `common.ts`'s `auditTimestamp` docblock)
+ * — re-verified live post-move via `storage-queries.test.ts`'s
+ * `datetime`-field round-trip test, which exercises exactly this branch
+ * (a text-typed sibling row's UNION leg lands on this `CAST`) and confirmed
+ * full microsecond fidelity survives.
+ */
+export function mysqlNullCast(nullCast) {
+    switch (nullCast) {
+        case 'uuid':
+            return 'CAST(NULL AS CHAR(36))';
+        case 'boolean':
+            return 'CAST(NULL AS SIGNED)';
+        case 'timestamp':
+            // The manifest's abstract name for the `timestamptz`-shaped column
+            // (`value_timestamp_tz`); MySQL's storage-side type is `DATETIME(6)`
+            // (matching pg's microsecond precision — see `common.ts`'s
+            // `auditTimestamp` docblock), not a MySQL `TIMESTAMP` column.
+            return 'CAST(NULL AS DATETIME(6))';
+        case 'date':
+            return 'CAST(NULL AS DATE)';
+        case 'time':
+            return 'CAST(NULL AS TIME(3))';
+        case 'jsonb':
+            return 'CAST(NULL AS JSON)';
+        case 'text':
+        case 'varchar':
+            return 'CAST(NULL AS CHAR)';
+        case 'bigint':
+        case 'integer':
+            return 'CAST(NULL AS SIGNED)';
+        case 'decimal':
+            return 'CAST(NULL AS DECIMAL(10,2))';
+        case 'real':
+            return 'CAST(NULL AS FLOAT)';
+        case 'text[]':
+            // No MySQL array type — `object_keys` is stored as a JSON array of
+            // strings on this adapter (see the manifest's own comment at its
+            // `object_keys` entry), so the null cast matches that column's real
+            // MySQL type.
+            return 'CAST(NULL AS JSON)';
+        default:
+            throw new Error(`mysqlNullCast: unrecognised nullCast type '${nullCast}'`);
+    }
+}
+/** Number of columns in the unified output (base + field_type + type-specific). */
+export const UNIFIED_COLUMN_COUNT = storeColumnManifest.length + 1; // +1 for field_type
+/**
+ * Build the SELECT column list for a given store table type.
+ *
+ * Base columns (id, document_version_id, etc.) are passed through directly.
+ * The `field_type` column is emitted as a string literal.
+ * Type-specific columns are either mapped to the source expression or
+ * emitted as a typed NULL.
+ */
+function buildSelectList(storeType) {
+    const parts = [];
+    for (const col of storeColumnManifest) {
+        // Base columns (no sources) are always passed through from the table.
+        if (!col.sources) {
+            parts.push(col.name);
+            continue;
+        }
+        const sourceExpr = col.sources[storeType];
+        if (sourceExpr) {
+            // This store provides this column — use the source expression.
+            // If the source column name differs from the output alias, add AS.
+            if (sourceExpr === col.name) {
+                parts.push(col.name);
+            }
+            else {
+                parts.push(`${sourceExpr} as \`${col.name}\``);
+            }
+        }
+        else {
+            // This store doesn't provide this column — emit typed NULL.
+            parts.push(`${mysqlNullCast(col.nullCast)} as \`${col.name}\``);
+        }
+    }
+    // Insert field_type after the base columns. The base columns are the first
+    // 7 entries (id through parent_path). field_type goes at position 3
+    // (after collection_id, before field_path) to match the original layout.
+    const fieldTypeLiteral = `'${fieldTypeLiterals[storeType]}' as \`field_type\``;
+    parts.splice(3, 0, fieldTypeLiteral);
+    return parts.join(',\n  ');
+}
+// Pre-generate SQL fragments for each store type.
+const selectListCache = new Map();
+/**
+ * Get the Drizzle SQL fragment for a store type's SELECT list.
+ * Results are cached — the generation runs once at module load.
+ */
+export function storeSelectList(storeType) {
+    let cached = selectListCache.get(storeType);
+    if (!cached) {
+        cached = sql.raw(buildSelectList(storeType));
+        selectListCache.set(storeType, cached);
+    }
+    return cached;
+}
+// ---------------------------------------------------------------------------
+// Exported for testing
+// ---------------------------------------------------------------------------
+export { buildSelectList, fieldTypeLiterals };

package/dist/modules/storage/storage-utils.d.ts

@@ -0,0 +1,49 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export declare const getFirstOrThrow: <T>(message: string) => (values: T[]) => T;
+/**
+ * Coerce a raw driver `DATETIME`/`TIMESTAMP` value from a `db.execute(sql\`...\`)`
+ * call to a real `Date`. `drizzle-orm`'s mysql2 driver installs its own
+ * `typeCast` on every raw-execute call that has no schema-typed `fields`
+ * mapper — which every hand-written SQL read in this adapter is — that
+ * unconditionally returns those column types as **strings**
+ * (`'YYYY-MM-DD HH:MM:SS.ffffff'`, space-separated, no timezone marker),
+ * regardless of the pool's own `timezone` option. Confirmed live across
+ * three independent call sites in this adapter (Task 11's audit-log UNION,
+ * `normalizeRow`'s `value_timestamp_tz`, and `findDocuments`' main query —
+ * see the Task 11 report). Every `DATETIME`/`TIMESTAMP` column in this
+ * schema is UTC by convention, so appending `Z` after normalising the
+ * separator is the correct interpretation, not an assumed one. Tolerant of
+ * `null`/`undefined` and of the value already being a `Date` (defensive —
+ * not expected on this path, but cheap to allow and keeps callers simple).
+ *
+ * This is the sole gate between the raw driver row and three different
+ * public contract shapes (`normalizeRow`'s `value_timestamp_tz`,
+ * `findDocuments`'s `created_at`/`updated_at`, and the audit log's
+ * `occurredAt`), so a malformed value must not fall through as a silent
+ * `Invalid Date` — it throws instead (task 13b §M2; see
+ * `packages/db-postgres/src/modules/storage/normalize-row.ts`'s `toDate`
+ * for the pg-side equivalent of this guard). `context` is optional and
+ * purely cosmetic — it names which column the caller is coercing in the
+ * thrown message; omitted call sites still get a safe, if less specific,
+ * error instead of a silently wrong `Date`.
+ */
+export declare function toDate(value: string | Date | null | undefined, context?: string): Date | null;
+/**
+ * Read the affected-row count off a drizzle mysql2 `update()`/`delete()`
+ * result. MySQL has no `RETURNING`, so every guarded write in this adapter
+ * (optimistic-concurrency `UPDATE`/`DELETE` gates, bulk-mutation counts)
+ * uses this as its accept/reject or count signal instead. mysql2 resolves
+ * these to a `[ResultSetHeader, FieldPacket[]]` tuple — `affectedRows`
+ * lives on the first element, not `.rowCount` the way pg's driver shapes
+ * it (confirmed live against the test database; see
+ * `storage-commands.ts`'s `archivePublishedVersions` docblock for the
+ * original finding). Centralised here so the admin repositories (`../admin/
+ * *.ts`) share one cast instead of repeating it inline at every call site.
+ */
+export declare function affectedRowCount(result: unknown): number;

package/dist/modules/storage/storage-utils.js

@@ -0,0 +1,76 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { ERR_DATABASE, getLogger } from '@byline/core';
+// ------------------------------------------------------------------------------
+// Misc
+//
+// `resolveStoreTypes` lives in `@byline/core` (`packages/core/src/storage/
+// storage-utils.ts`) — it is dialect-independent. `getFirstOrThrow` stays
+// here: it's a result helper tied to this adapter. Mirrors
+// `packages/db-postgres/src/modules/storage/storage-utils.ts`.
+// ------------------------------------------------------------------------------
+export const getFirstOrThrow = (message) => (values) => {
+    const value = values[0];
+    if (value == null) {
+        throw ERR_DATABASE({ message }).log(getLogger());
+    }
+    return value;
+};
+/**
+ * Coerce a raw driver `DATETIME`/`TIMESTAMP` value from a `db.execute(sql\`...\`)`
+ * call to a real `Date`. `drizzle-orm`'s mysql2 driver installs its own
+ * `typeCast` on every raw-execute call that has no schema-typed `fields`
+ * mapper — which every hand-written SQL read in this adapter is — that
+ * unconditionally returns those column types as **strings**
+ * (`'YYYY-MM-DD HH:MM:SS.ffffff'`, space-separated, no timezone marker),
+ * regardless of the pool's own `timezone` option. Confirmed live across
+ * three independent call sites in this adapter (Task 11's audit-log UNION,
+ * `normalizeRow`'s `value_timestamp_tz`, and `findDocuments`' main query —
+ * see the Task 11 report). Every `DATETIME`/`TIMESTAMP` column in this
+ * schema is UTC by convention, so appending `Z` after normalising the
+ * separator is the correct interpretation, not an assumed one. Tolerant of
+ * `null`/`undefined` and of the value already being a `Date` (defensive —
+ * not expected on this path, but cheap to allow and keeps callers simple).
+ *
+ * This is the sole gate between the raw driver row and three different
+ * public contract shapes (`normalizeRow`'s `value_timestamp_tz`,
+ * `findDocuments`'s `created_at`/`updated_at`, and the audit log's
+ * `occurredAt`), so a malformed value must not fall through as a silent
+ * `Invalid Date` — it throws instead (task 13b §M2; see
+ * `packages/db-postgres/src/modules/storage/normalize-row.ts`'s `toDate`
+ * for the pg-side equivalent of this guard). `context` is optional and
+ * purely cosmetic — it names which column the caller is coercing in the
+ * thrown message; omitted call sites still get a safe, if less specific,
+ * error instead of a silently wrong `Date`.
+ */
+export function toDate(value, context) {
+    if (value == null)
+        return null;
+    if (value instanceof Date)
+        return value;
+    const date = new Date(`${value.replace(' ', 'T')}Z`);
+    if (Number.isNaN(date.getTime())) {
+        throw new Error(`toDate: ${context ?? 'value'} is not a parseable timestamp — got ${JSON.stringify(value)}`);
+    }
+    return date;
+}
+/**
+ * Read the affected-row count off a drizzle mysql2 `update()`/`delete()`
+ * result. MySQL has no `RETURNING`, so every guarded write in this adapter
+ * (optimistic-concurrency `UPDATE`/`DELETE` gates, bulk-mutation counts)
+ * uses this as its accept/reject or count signal instead. mysql2 resolves
+ * these to a `[ResultSetHeader, FieldPacket[]]` tuple — `affectedRows`
+ * lives on the first element, not `.rowCount` the way pg's driver shapes
+ * it (confirmed live against the test database; see
+ * `storage-commands.ts`'s `archivePublishedVersions` docblock for the
+ * original finding). Centralised here so the admin repositories (`../admin/
+ * *.ts`) share one cast instead of repeating it inline at every call site.
+ */
+export function affectedRowCount(result) {
+    return result[0]?.affectedRows ?? 0;
+}

package/dist/modules/storage/tests/dialect-pins.integration.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/modules/storage/tests/dialect-pins.integration.test.js

@@ -0,0 +1,266 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * MySQL-specific dialect properties the shared `@byline/db-conformance`
+ * suite cannot express, because they pin behaviour the Postgres adapter
+ * either doesn't have (collation choices) or expresses differently (its own
+ * `COLLATE "C"` / native `numeric` type). Each pin below exists because a
+ * real, live-server-verified property depends on a specific schema choice
+ * in `packages/db-mysql/src/database/schema/{index,common}.ts` — see each
+ * test's comment for the column/config it pins and why.
+ */
+import { generateKeyBetween, generateNKeysBetween } from '@byline/core';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { setupTestDB, teardownTestDB } from '../../../lib/test-helper.js';
+const timestamp = Date.now();
+function first(rows) {
+    const row = rows[0];
+    if (row == null)
+        throw new Error('expected at least one row, got none');
+    return row;
+}
+async function queryRows(pool, sql, params) {
+    const [rows] = await pool.query(sql, params);
+    return rows;
+}
+describe('MySQL dialect pins (live database)', () => {
+    let testDb;
+    let rawPool;
+    beforeAll(() => {
+        testDb = setupTestDB();
+        rawPool = testDb.pool;
+    });
+    afterAll(async () => {
+        await teardownTestDB();
+    });
+    describe('order_key sort parity', () => {
+        // `byline_documents.order_key` is `varcharByteSorted` (`ascii_bin`)
+        // specifically so `ORDER BY order_key` in SQL agrees with plain
+        // JavaScript string comparison — the fractional-index algorithm in
+        // `@byline/core` (`generateKeyBetween`) is designed against byte-wise
+        // ordering, and MySQL's database-default collation
+        // (`utf8mb4_0900_ai_ci`) does not agree with JS on every key (e.g.
+        // `'Zz'` vs `'a0'` sort oppositely under the two collations). This test
+        // builds a realistic, mixed-structure key spread — not just a single
+        // initial batch, but keys inserted "between" existing ones the way a
+        // real drag-and-drop reorder would generate them — shuffles the insert
+        // order, and asserts the database's own `ORDER BY` agrees with the JS
+        // sort of the exact same key strings.
+        it('DB ORDER BY order_key matches JS string sort over the generateKeyBetween alphabet', async () => {
+            const testCollection = {
+                path: `order-key-pin-${timestamp}`,
+                labels: { singular: 'OrderKeyThing', plural: 'OrderKeyThings' },
+                fields: [{ name: 'title', type: 'text' }],
+            };
+            const collectionId = first(await testDb.commandBuilders.collections.create(testCollection.path, testCollection)).id;
+            // An initial batch of 8 keys (generateNKeysBetween bisects
+            // recursively, so this alone already mixes integer-part lengths and
+            // fraction lengths — a richer structure than a flat sequential
+            // batch), then interleave 7 more by generating a key strictly
+            // between each already-adjacent pair, the shape a real "drop between
+            // these two rows" reorder produces.
+            const initial = generateNKeysBetween(null, null, 8);
+            const interleaved = initial.slice(0, -1).map((key, i) => {
+                const next = initial[i + 1];
+                return generateKeyBetween(key, next);
+            });
+            const cleanKeys = [...initial, ...interleaved];
+            // Create one document per key, in shuffled order, so insertion order
+            // carries no information about sort order.
+            const shuffled = [...cleanKeys];
+            for (let i = shuffled.length - 1; i > 0; i--) {
+                const j = Math.floor(Math.random() * (i + 1));
+                const tmp = shuffled[i];
+                shuffled[i] = shuffled[j];
+                shuffled[j] = tmp;
+            }
+            for (const key of shuffled) {
+                const created = await testDb.commandBuilders.documents.createDocumentVersion({
+                    collectionId,
+                    collectionVersion: 1,
+                    collectionConfig: testCollection,
+                    action: 'create',
+                    documentData: { title: key },
+                    locale: 'all',
+                    status: 'draft',
+                });
+                await testDb.commandBuilders.documents.setOrderKey({
+                    document_id: created.document.document_id,
+                    order_key: key,
+                });
+            }
+            const rows = await queryRows(rawPool, 'SELECT id, order_key FROM byline_documents WHERE collection_id = ? ORDER BY order_key ASC', [collectionId]);
+            const dbOrderedKeys = rows.map((r) => r.order_key);
+            const jsSortedKeys = [...cleanKeys].sort();
+            expect(dbOrderedKeys).toEqual(jsSortedKeys);
+            await testDb.commandBuilders.collections.delete(collectionId);
+        });
+    });
+    describe('ascii_bin id equality', () => {
+        // Every id/FK column uses `uuidChar` — `CHAR(36) CHARACTER SET ascii
+        // COLLATE ascii_bin` — precisely so id comparisons are byte-wise
+        // (case-sensitive), the MySQL analogue of Postgres's native `uuid`
+        // type (which has no notion of a case-insensitive collation at all).
+        // MySQL's database-default collation (`utf8mb4_0900_ai_ci`) folds
+        // case, so without `ascii_bin` a case-flipped id would wrongly compare
+        // equal.
+        it('a CHAR(36) id differing only in case does not match', async () => {
+            const testCollection = {
+                path: `ascii-bin-pin-${timestamp}`,
+                labels: { singular: 'AsciiBinThing', plural: 'AsciiBinThings' },
+                fields: [{ name: 'title', type: 'text' }],
+            };
+            const collectionId = first(await testDb.commandBuilders.collections.create(testCollection.path, testCollection)).id;
+            const created = await testDb.commandBuilders.documents.createDocumentVersion({
+                collectionId,
+                collectionVersion: 1,
+                collectionConfig: testCollection,
+                action: 'create',
+                documentData: { title: 'Ascii Bin' },
+                locale: 'all',
+                status: 'draft',
+            });
+            const documentId = created.document.document_id;
+            expect(documentId).not.toBe(documentId.toUpperCase());
+            const exactMatch = await queryRows(rawPool, 'SELECT id FROM byline_documents WHERE id = ?', [
+                documentId,
+            ]);
+            expect(exactMatch).toHaveLength(1);
+            const caseFlippedMatch = await queryRows(rawPool, 'SELECT id FROM byline_documents WHERE id = ?', [documentId.toUpperCase()]);
+            expect(caseFlippedMatch).toHaveLength(0);
+            await testDb.commandBuilders.collections.delete(collectionId);
+        });
+    });
+    describe('DATETIME(6) UTC round-trip', () => {
+        // The mysql2 pool opens with `timezone: 'Z'` (see `src/index.ts` and
+        // `test-helper.ts`) so `Date` values are sent and received as UTC,
+        // without local-timezone reinterpretation at the connection layer —
+        // MySQL's `DATETIME` has no timezone-aware storage the way Postgres's
+        // `TIMESTAMPTZ` does, so this pool option is the entire mechanism.
+        // `fsp: 6` on `value_timestamp_tz` (`common.ts`'s `auditTimestamp`
+        // discipline, mirrored on the store table) matches pg's `TIMESTAMPTZ(6)`
+        // resolution.
+        it('writes a Date and reads back the identical instant', async () => {
+            const testCollection = {
+                path: `datetime-utc-pin-${timestamp}`,
+                labels: { singular: 'DatetimeUtcThing', plural: 'DatetimeUtcThings' },
+                fields: [
+                    { name: 'title', type: 'text' },
+                    { name: 'atTime', type: 'datetime' },
+                ],
+            };
+            // `getDocumentById` resolves the collection definition from the set
+            // `queryBuilders` was constructed with — re-run `setupTestDB` with
+            // this test's collection so that lookup succeeds (mirrors the
+            // "Recreate queryBuilders when collections are provided" note in
+            // `test-helper.ts`).
+            testDb = setupTestDB([testCollection]);
+            const collectionId = first(await testDb.commandBuilders.collections.create(testCollection.path, testCollection)).id;
+            const expected = new Date('2026-05-04T03:02:01.456Z');
+            const created = await testDb.commandBuilders.documents.createDocumentVersion({
+                collectionId,
+                collectionVersion: 1,
+                collectionConfig: testCollection,
+                action: 'create',
+                documentData: { title: 'UTC round-trip', atTime: expected },
+                locale: 'all',
+                status: 'draft',
+            });
+            const doc = await testDb.queryBuilders.documents.getDocumentById({
+                collection_id: collectionId,
+                document_id: created.document.document_id,
+                locale: 'all',
+            });
+            const value = doc?.fields?.atTime;
+            expect(value).toBeInstanceOf(Date);
+            expect(value.getTime()).toBe(expected.getTime());
+            await testDb.commandBuilders.collections.delete(collectionId);
+        });
+    });
+    describe('DECIMAL precision preservation', () => {
+        // The pool opens with `decimalNumbers: false` (`src/index.ts`,
+        // `test-helper.ts`) so `DECIMAL` columns arrive as strings rather than
+        // JS `number`s — MySQL/JS float coercion would silently lose precision
+        // on money/decimal values otherwise, matching pg's `numeric` handling
+        // (node-postgres also returns `numeric` as a string by default).
+        it('returns a decimal field value as a string, not a JS number', async () => {
+            const testCollection = {
+                path: `decimal-pin-${timestamp}`,
+                labels: { singular: 'DecimalThing', plural: 'DecimalThings' },
+                fields: [
+                    { name: 'title', type: 'text' },
+                    { name: 'price', type: 'decimal' },
+                ],
+            };
+            testDb = setupTestDB([testCollection]);
+            const collectionId = first(await testDb.commandBuilders.collections.create(testCollection.path, testCollection)).id;
+            const created = await testDb.commandBuilders.documents.createDocumentVersion({
+                collectionId,
+                collectionVersion: 1,
+                collectionConfig: testCollection,
+                action: 'create',
+                documentData: { title: 'Decimal', price: '19.99' },
+                locale: 'all',
+                status: 'draft',
+            });
+            const doc = await testDb.queryBuilders.documents.getDocumentById({
+                collection_id: collectionId,
+                document_id: created.document.document_id,
+                locale: 'all',
+            });
+            expect(typeof doc?.fields?.price).toBe('string');
+            expect(doc?.fields?.price).toBe('19.99');
+            await testDb.commandBuilders.collections.delete(collectionId);
+        });
+    });
+    describe('LIKE case- and accent-insensitivity (elected divergence)', () => {
+        // The store `value` text columns keep the database's default
+        // `utf8mb4_0900_ai_ci` collation deliberately — unlike `order_key` /
+        // id columns, which are pinned to byte-wise collations for structural
+        // reasons, the *content* columns are left case- and accent-folding on
+        // purpose, so admin search (`LIKE`) matches more broadly than
+        // Postgres's `ILIKE` (case-only). This is an elected, spec-level
+        // divergence, not an oversight — do not "fix" it by pinning `value` to
+        // a binary collation. See `findDocuments`' query-search site and
+        // `packages/db-mysql/src/modules/storage/tests/storage-queries.test.ts`'s
+        // "query (LIKE admin search)" test for the full end-to-end behavioural
+        // pin through `findDocuments`.
+        //
+        // This test reads a real row through `byline_store_text.value` rather
+        // than comparing two SQL string literals — an earlier version of this
+        // test ran `SELECT ('Ünïcödé' LIKE ?) as matched`, which pins the
+        // *connection's* default collation (`collation_connection`, derived
+        // from the pool's `charset`), not the column's. Re-collating `value`
+        // to a binary collation would leave that version green while breaking
+        // the exact behaviour it claimed to pin — this version would catch it,
+        // because the comparison now happens against the actual indexed
+        // column.
+        it('LIKE matches a stored value in byline_store_text across case and accent variants', async () => {
+            const testCollection = {
+                path: `like-collation-pin-${timestamp}`,
+                labels: { singular: 'LikeCollationThing', plural: 'LikeCollationThings' },
+                fields: [{ name: 'title', type: 'text' }],
+            };
+            testDb = setupTestDB([testCollection]);
+            const collectionId = first(await testDb.commandBuilders.collections.create(testCollection.path, testCollection)).id;
+            await testDb.commandBuilders.documents.createDocumentVersion({
+                collectionId,
+                collectionVersion: 1,
+                collectionConfig: testCollection,
+                action: 'create',
+                documentData: { title: 'Ünïcödé Sample' },
+                locale: 'all',
+                status: 'draft',
+            });
+            const rows = await queryRows(rawPool, 'SELECT value FROM byline_store_text WHERE field_name = ? AND value LIKE ?', ['title', '%unicode sample%']);
+            expect(rows).toHaveLength(1);
+            expect(first(rows).value).toBe('Ünïcödé Sample');
+            await testDb.commandBuilders.collections.delete(collectionId);
+        });
+    });
+});

package/dist/modules/storage/tests/storage-commands.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};