@byline/db-mysql 4.8.0

package/dist/modules/audit/audit-queries.js

@@ -0,0 +1,169 @@
+/**
+ * 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 { desc, eq, sql } from 'drizzle-orm';
+import { auditLog, documentVersions } from '../../database/schema/index.js';
+import { toDate } from '../storage/storage-utils.js';
+function toEntry(row) {
+    return {
+        id: row.id,
+        documentId: row.document_id,
+        collectionId: row.collection_id,
+        actorId: row.actor_id,
+        actorRealm: row.actor_realm,
+        action: row.action,
+        field: row.field,
+        before: row.before,
+        after: row.after,
+        occurredAt: row.occurred_at,
+    };
+}
+export class AuditQueries {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getDocumentAuditLog(params) {
+        const page = params.page ?? 1;
+        const pageSize = params.page_size ?? 20;
+        const offset = (page - 1) * pageSize;
+        // `count(*)::int` (pg) → `CAST(COUNT(*) AS SIGNED)` (design spec §2).
+        const totalResult = await this.db
+            .select({ count: sql `CAST(COUNT(*) AS SIGNED)` })
+            .from(auditLog)
+            .where(eq(auditLog.document_id, params.document_id));
+        const total = Number(totalResult[0]?.count) || 0;
+        const totalPages = Math.ceil(total / pageSize);
+        const rows = await this.db
+            .select()
+            .from(auditLog)
+            .where(eq(auditLog.document_id, params.document_id))
+            // id is UUIDv7 — DESC is newest-first without a separate sort column.
+            .orderBy(desc(auditLog.id))
+            .limit(pageSize)
+            .offset(offset);
+        return {
+            entries: rows.map(toEntry),
+            meta: { total, page, pageSize, totalPages },
+        };
+    }
+    async findAuditLog(params) {
+        const page = params.page ?? 1;
+        const pageSize = params.page_size ?? 20;
+        const offset = (page - 1) * pageSize;
+        // The activity feed is the UNION of two disjoint event sources, normalised
+        // onto the audit-log column shape (see IAuditQueries.findAuditLog):
+        //
+        //   1. byline_document_versions — content saves. event_type maps to a
+        //      `document.created` / `document.updated` action; created_by/created_at
+        //      become actor_id/occurred_at; field/before/after are null. Restricted
+        //      to create+update so any legacy 'delete' version rows can't surface
+        //      (deletions live only in the audit log — the union double-counts
+        //      nothing).
+        //   2. byline_audit_log — path/locale/status changes, deletions, and
+        //      future admin-realm events, used as-is.
+        //
+        // Filters and ordering apply to the unioned result; occurred_at is the only
+        // cross-source sort key (the per-source UUIDv7 ids are separate sequences).
+        //
+        // MySQL divergences from the pg source (design spec §2, confirmed live):
+        //   - `NULL::varchar` / `NULL::jsonb` casts → `CAST(NULL AS CHAR(128))` /
+        //     `CAST(NULL AS JSON)`. An untyped bare `NULL` in one UNION leg while
+        //     the sibling leg has a real typed column is fine for MySQL's type
+        //     resolution, but an explicit CAST keeps the two legs' declared types
+        //     symmetric and self-documenting, matching the pg source's intent.
+        //   - `'document.' || event_type` → `CONCAT('document.', event_type)` —
+        //     MySQL's `||` is logical OR by default (PIPES_AS_CONCAT is not a
+        //     baseline assumption for this adapter), so string concatenation must
+        //     use `CONCAT`.
+        //   - `before` backtick-quoted throughout — confirmed live:
+        //     `BEFORE` is a reserved word in MySQL (trigger syntax, `CREATE
+        //     TRIGGER ... BEFORE INSERT`), so an unquoted `before` column alias
+        //     or bare column reference is a syntax error (`ER_PARSE_ERROR`) both
+        //     as an `AS before` alias declaration and as a bare `SELECT ...,
+        //     before, ...` reference in the outer wrapper. `after` is NOT
+        //     reserved (confirmed live) but is backtick-quoted alongside it for
+        //     symmetry.
+        const union = sql `
+      SELECT id, document_id, collection_id, actor_id, actor_realm, action, field, \`before\`, \`after\`, occurred_at FROM (
+        SELECT
+          ${documentVersions.id} AS id,
+          ${documentVersions.document_id} AS document_id,
+          ${documentVersions.collection_id} AS collection_id,
+          ${documentVersions.created_by} AS actor_id,
+          CASE WHEN ${documentVersions.created_by} IS NULL THEN 'system' ELSE 'admin' END AS actor_realm,
+          CASE ${documentVersions.event_type}
+            WHEN 'create' THEN 'document.created'
+            WHEN 'update' THEN 'document.updated'
+            ELSE CONCAT('document.', ${documentVersions.event_type})
+          END AS action,
+          CAST(NULL AS CHAR(128)) AS field,
+          CAST(NULL AS JSON) AS \`before\`,
+          CAST(NULL AS JSON) AS \`after\`,
+          ${documentVersions.created_at} AS occurred_at
+        FROM ${documentVersions}
+        WHERE ${documentVersions.event_type} IN ('create', 'update')
+        UNION ALL
+        SELECT
+          ${auditLog.id} AS id,
+          ${auditLog.document_id} AS document_id,
+          ${auditLog.collection_id} AS collection_id,
+          ${auditLog.actor_id} AS actor_id,
+          ${auditLog.actor_realm} AS actor_realm,
+          ${auditLog.action} AS action,
+          ${auditLog.field} AS field,
+          ${auditLog.before} AS \`before\`,
+          ${auditLog.after} AS \`after\`,
+          ${auditLog.occurred_at} AS occurred_at
+        FROM ${auditLog}
+      ) AS activity`;
+        const filters = [];
+        if (params.actorId)
+            filters.push(sql `actor_id = ${params.actorId}`);
+        if (params.collectionId)
+            filters.push(sql `collection_id = ${params.collectionId}`);
+        if (params.action)
+            filters.push(sql `action = ${params.action}`);
+        if (params.from)
+            filters.push(sql `occurred_at >= ${params.from}`);
+        if (params.to)
+            filters.push(sql `occurred_at <= ${params.to}`);
+        const whereClause = filters.length > 0 ? sql ` WHERE ${sql.join(filters, sql ` AND `)}` : sql ``;
+        // `db.execute()` on the mysql2 driver returns a `[rows, fields]` tuple
+        // (unlike pg's `{ rows }` result object) — see `storage-queries.ts` for
+        // the established pattern this mirrors.
+        const totalResult = (await this.db.execute(sql `SELECT CAST(COUNT(*) AS SIGNED) AS count FROM (${union}${whereClause}) AS filtered`));
+        const total = Number(totalResult[0][0]?.count) || 0;
+        const totalPages = Math.ceil(total / pageSize);
+        const result = (await this.db.execute(sql `${union}${whereClause} ORDER BY occurred_at DESC, id DESC LIMIT ${pageSize} OFFSET ${offset}`));
+        return {
+            entries: result[0].map((row) => toEntryFromActivityRow(row)),
+            meta: { total, page, pageSize, totalPages },
+        };
+    }
+}
+/** Like `toEntry`, but for a raw `ActivityRow` off the UNION — see `toDate` (`storage-utils.ts`). */
+function toEntryFromActivityRow(row) {
+    return {
+        id: row.id,
+        documentId: row.document_id,
+        collectionId: row.collection_id,
+        actorId: row.actor_id,
+        actorRealm: row.actor_realm,
+        action: row.action,
+        field: row.field,
+        before: row.before,
+        after: row.after,
+        // `occurred_at` is NOT NULL on both UNION legs (`documentVersions.created_at`,
+        // `auditLog.occurred_at`), so the shared `toDate`'s `null` branch is
+        // unreachable here — the cast reflects that, not an assumption.
+        occurredAt: toDate(row.occurred_at, 'occurred_at'),
+    };
+}
+export function createAuditQueries(db) {
+    return new AuditQueries(db);
+}

package/dist/modules/counters/counters-commands.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 type { ICounterCommands } from '@byline/core';
+import type { Pool } from 'mysql2/promise';
+/**
+ * Table-emulated counters (design spec §3 — "the one real design
+ * divergence"). MySQL has no `CREATE SEQUENCE`, so `byline_counter_groups`
+ * IS the allocator: `current_value` holds the counter's live state, advanced
+ * in place with the classic `LAST_INSERT_ID(expr)` idiom, which makes an
+ * atomic `UPDATE`/`INSERT ... ON DUPLICATE KEY UPDATE` return its own new
+ * value via a same-connection `SELECT LAST_INSERT_ID()` — no separate
+ * `SELECT ... FOR UPDATE` round trip needed.
+ *
+ * Static (`ensureCounterGroup` + `nextCounterValue`) and runtime-scoped
+ * (`nextScopedCounterValue`) counters deliberately share the one
+ * `byline_counter_groups` table, keyed by name — see the schema comment on
+ * `counterGroups` (`packages/db-mysql/src/database/schema/index.ts`) for why
+ * a second `byline_counter_scopes` table (as the plan's implementation note
+ * first sketched) cannot honour `ICounterCommands`'s documented contract
+ * that a scope self-registered via `nextScopedCounterValue` continues the
+ * very same count when subsequently read through `nextCounterValue` — two
+ * independently-incrementing tables cannot both be "the same sequence"
+ * without every scoped call also writing the static table to keep them in
+ * sync, at which point it is one table with extra steps.
+ *
+ * Every method here takes the raw mysql2 **pool**, not `DBManager` — counters
+ * must never run inside the ambient `withTransaction` (a long document-create
+ * transaction holding the counter row would serialise every other writer in
+ * that group; gaps on rollback are already contractual, see
+ * `ICounterCommands.nextCounterValue`'s docstring). `nextCounterValue` and
+ * `nextScopedCounterValue` additionally check out a single connection via
+ * `pool.getConnection()` for their two-statement bodies — `LAST_INSERT_ID()`
+ * is per-connection session state (confirmed live: a second, freshly-opened
+ * connection reads it back as `0` regardless of what a sibling connection
+ * just set it to), so issuing the two statements through `pool.execute()` /
+ * `pool.query()` directly would let the pool hand each one a different
+ * physical connection and silently return another session's value.
+ */
+export declare class CounterCommands implements ICounterCommands {
+    private pool;
+    constructor(pool: Pool);
+    ensureCounterGroup(groupName: string): Promise<{
+        groupName: string;
+        sequenceName: string;
+    }>;
+    nextCounterValue(groupName: string): Promise<number>;
+    nextScopedCounterValue(scopeName: string): Promise<number>;
+}
+export declare function createCounterCommands(pool: Pool): ICounterCommands;

package/dist/modules/counters/counters-commands.js

@@ -0,0 +1,121 @@
+/**
+ * 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
+ */
+/**
+ * Table-emulated counters (design spec §3 — "the one real design
+ * divergence"). MySQL has no `CREATE SEQUENCE`, so `byline_counter_groups`
+ * IS the allocator: `current_value` holds the counter's live state, advanced
+ * in place with the classic `LAST_INSERT_ID(expr)` idiom, which makes an
+ * atomic `UPDATE`/`INSERT ... ON DUPLICATE KEY UPDATE` return its own new
+ * value via a same-connection `SELECT LAST_INSERT_ID()` — no separate
+ * `SELECT ... FOR UPDATE` round trip needed.
+ *
+ * Static (`ensureCounterGroup` + `nextCounterValue`) and runtime-scoped
+ * (`nextScopedCounterValue`) counters deliberately share the one
+ * `byline_counter_groups` table, keyed by name — see the schema comment on
+ * `counterGroups` (`packages/db-mysql/src/database/schema/index.ts`) for why
+ * a second `byline_counter_scopes` table (as the plan's implementation note
+ * first sketched) cannot honour `ICounterCommands`'s documented contract
+ * that a scope self-registered via `nextScopedCounterValue` continues the
+ * very same count when subsequently read through `nextCounterValue` — two
+ * independently-incrementing tables cannot both be "the same sequence"
+ * without every scoped call also writing the static table to keep them in
+ * sync, at which point it is one table with extra steps.
+ *
+ * Every method here takes the raw mysql2 **pool**, not `DBManager` — counters
+ * must never run inside the ambient `withTransaction` (a long document-create
+ * transaction holding the counter row would serialise every other writer in
+ * that group; gaps on rollback are already contractual, see
+ * `ICounterCommands.nextCounterValue`'s docstring). `nextCounterValue` and
+ * `nextScopedCounterValue` additionally check out a single connection via
+ * `pool.getConnection()` for their two-statement bodies — `LAST_INSERT_ID()`
+ * is per-connection session state (confirmed live: a second, freshly-opened
+ * connection reads it back as `0` regardless of what a sibling connection
+ * just set it to), so issuing the two statements through `pool.execute()` /
+ * `pool.query()` directly would let the pool hand each one a different
+ * physical connection and silently return another session's value.
+ */
+export class CounterCommands {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async ensureCounterGroup(groupName) {
+        if (!groupName || typeof groupName !== 'string') {
+            throw new Error(`ensureCounterGroup: groupName must be a non-empty string`);
+        }
+        // No DB sequence object exists on this dialect — the emulation row's own
+        // identity stands in for the sequence name the Postgres adapter reports.
+        const sequenceName = `byline_counter_groups:${groupName}`;
+        // `ON DUPLICATE KEY UPDATE group_name = group_name` is a race-safe no-op
+        // on an existing row (confirmed live: reports `ROW_COUNT() = 0` and
+        // leaves `current_value` untouched) — unlike Postgres's `CREATE SEQUENCE
+        // IF NOT EXISTS`, this single statement has no two-phase check-then-act
+        // window for two booting processes to race through, so there is no
+        // unique-violation to absorb here.
+        await this.pool.execute('INSERT INTO byline_counter_groups (group_name, sequence_name, current_value) VALUES (?, ?, 0) ON DUPLICATE KEY UPDATE group_name = group_name', [groupName, sequenceName]);
+        return { groupName, sequenceName };
+    }
+    async nextCounterValue(groupName) {
+        if (!groupName || typeof groupName !== 'string') {
+            throw new Error(`nextCounterValue: groupName must be a non-empty string`);
+        }
+        // Never `this.pool.execute()` here — see the class docblock. Both
+        // statements below must land on the one checked-out connection.
+        const connection = await this.pool.getConnection();
+        try {
+            const [result] = await connection.execute('UPDATE byline_counter_groups SET current_value = LAST_INSERT_ID(current_value + 1) WHERE group_name = ?', [groupName]);
+            // Zero affected rows means the group was never registered — surface
+            // that immediately rather than silently seeding it (mirrors pg's
+            // "unregistered group is a configuration error" honesty).
+            if (result.affectedRows === 0) {
+                throw new Error(`nextCounterValue: counter group "${groupName}" is not registered. ` +
+                    `Call ensureCounterGroup at boot before any document create that uses it.`);
+            }
+            const [rows] = await connection.query('SELECT LAST_INSERT_ID() AS v');
+            const row = rows[0];
+            if (row === undefined) {
+                throw new Error(`nextCounterValue: LAST_INSERT_ID() returned no row for group "${groupName}"`);
+            }
+            return typeof row.v === 'number' ? row.v : Number(row.v);
+        }
+        finally {
+            connection.release();
+        }
+    }
+    async nextScopedCounterValue(scopeName) {
+        if (!scopeName || typeof scopeName !== 'string') {
+            throw new Error(`nextScopedCounterValue: scopeName must be a non-empty string`);
+        }
+        const sequenceName = `byline_counter_groups:${scopeName}`;
+        // One atomic ensure-then-allocate statement: the `VALUES` seed itself
+        // wraps `LAST_INSERT_ID(1)`, so the insert path (brand-new scope) also
+        // leaves `LAST_INSERT_ID()` reading `1` on this connection — confirmed
+        // live, including that a second concurrent insert attempt on the same
+        // scope_name correctly falls through to the `ON DUPLICATE KEY UPDATE`
+        // branch rather than erroring. Still needs the same-connection
+        // discipline as `nextCounterValue` — see the class docblock.
+        const connection = await this.pool.getConnection();
+        try {
+            await connection.execute('INSERT INTO byline_counter_groups (group_name, sequence_name, current_value) ' +
+                'VALUES (?, ?, LAST_INSERT_ID(1)) ' +
+                'ON DUPLICATE KEY UPDATE current_value = LAST_INSERT_ID(current_value + 1)', [scopeName, sequenceName]);
+            const [rows] = await connection.query('SELECT LAST_INSERT_ID() AS v');
+            const row = rows[0];
+            if (row === undefined) {
+                throw new Error(`nextScopedCounterValue: LAST_INSERT_ID() returned no row for scope "${scopeName}"`);
+            }
+            return typeof row.v === 'number' ? row.v : Number(row.v);
+        }
+        finally {
+            connection.release();
+        }
+    }
+}
+export function createCounterCommands(pool) {
+    return new CounterCommands(pool);
+}

package/dist/modules/counters/tests/counters-concurrency.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/counters/tests/counters-concurrency.test.js

@@ -0,0 +1,111 @@
+/**
+ * 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
+ */
+/**
+ * Guards the concurrency design brief §C calls "the whole task": the
+ * two-statement `UPDATE ... SET current_value = LAST_INSERT_ID(current_value
+ * + 1)` + `SELECT LAST_INSERT_ID()` body of `nextCounterValue` MUST run on
+ * one checked-out connection (`LAST_INSERT_ID()` is per-connection state —
+ * confirmed live during Task 11: a fresh connection reads back `0` regardless
+ * of what a sibling connection just set). Nothing in the shared
+ * `@byline/db-conformance` `countersSuite` exercises this specific risk
+ * surface: its only parallel test (`counters.ts:87-98`) is 8-way on
+ * `nextScopedCounterValue`, whose body is a single atomic
+ * `INSERT ... ON DUPLICATE KEY UPDATE` statement — no same-connection
+ * discipline to get wrong, because there is only ever one statement.
+ * `nextCounterValue`'s two-statement body is the one method where a refactor
+ * could silently swap `connection.execute`/`connection.query` for
+ * `pool.execute`/`pool.query` (dropping the checked-out connection and
+ * letting the pool hand each statement to a different physical connection)
+ * and still pass every other test in this adapter — 280/280 unit, 138/138
+ * integration — because the resulting duplicate/zero counter values only
+ * show up under real concurrent load, which nothing else in the suite
+ * generates against this specific method. This test is that guard, and it
+ * belongs here (a MySQL-specific emulation detail — the shared conformance
+ * suite exercises `ICounterCommands`' contract behaviour, not this
+ * adapter's own connection-checkout implementation).
+ *
+ * Uses its own dedicated pool (not the shared singleton `test-helper.ts`
+ * hands other integration test files in this same worker process — vitest
+ * runs this suite with `fileParallelism: false` / `maxWorkers: 1`, so a
+ * monkey-patched shared pool would leak into whichever file runs next) so
+ * `pool.getConnection` can be instrumented without any cross-file risk.
+ */
+import mysql from 'mysql2/promise';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { assertTestDatabase, resetTestDatabase } from '../../../lib/test-db.js';
+import { createCounterCommands } from '../counters-commands.js';
+describe('CounterCommands connection discipline under concurrency (mysql, live database)', () => {
+    let pool;
+    let counters;
+    beforeAll(async () => {
+        const connectionString = process.env.BYLINE_DB_MYSQL_CONNECTION_STRING;
+        assertTestDatabase(connectionString);
+        await resetTestDatabase(connectionString);
+        // connectionLimit: 4 mirrors the test harness's own pool sizing
+        // (test-helper.ts) — small enough that 20 concurrent nextCounterValue
+        // calls genuinely contend for connections, which is the point.
+        pool = mysql.createPool({
+            uri: connectionString,
+            connectionLimit: 4,
+            timezone: 'Z',
+            decimalNumbers: false,
+            charset: 'UTF8MB4_0900_AI_CI',
+        });
+        counters = createCounterCommands(pool);
+    });
+    afterAll(async () => {
+        await pool.end();
+    });
+    it('20 parallel nextCounterValue calls on one group yield the expected contiguous set, genuinely contending a 4-connection pool', async () => {
+        const groupName = `concurrency-test-${Date.now()}`;
+        await counters.ensureCounterGroup(groupName);
+        // Instrument connection checkout/release to prove the calls genuinely
+        // overlapped rather than serialized. Distinctness alone does not prove
+        // this: 20 calls run one at a time (each getting its own connection in
+        // turn, or even all 20 on the SAME connection sequentially) would also
+        // return 20 distinct, contiguous values — the two-statement
+        // same-connection defect this test exists to catch only shows up under
+        // real overlap, so the test must force and observe that overlap
+        // directly rather than infer it from the results.
+        let activeConnections = 0;
+        let maxObservedConcurrency = 0;
+        const originalGetConnection = pool.getConnection.bind(pool);
+        pool.getConnection = async (...args) => {
+            const conn = await originalGetConnection(...args);
+            activeConnections++;
+            maxObservedConcurrency = Math.max(maxObservedConcurrency, activeConnections);
+            const originalRelease = conn.release.bind(conn);
+            conn.release = (...releaseArgs) => {
+                activeConnections--;
+                return originalRelease(...releaseArgs);
+            };
+            return conn;
+        };
+        let results;
+        try {
+            results = await Promise.all(Array.from({ length: 20 }, () => counters.nextCounterValue(groupName)));
+        }
+        finally {
+            pool.getConnection = originalGetConnection;
+        }
+        // Distinct AND the exact expected contiguous set {1..20} — a silently
+        // duplicated or zero return (the actual failure mode of a connection-
+        // discipline regression, per LAST_INSERT_ID()'s per-connection scoping)
+        // fails this, not just a weaker "no two values are equal" check.
+        const sorted = [...results].sort((a, b) => a - b);
+        expect(new Set(results).size).toBe(20);
+        expect(sorted).toEqual(Array.from({ length: 20 }, (_, i) => i + 1));
+        // Genuine contention, not accidental interleaving: with
+        // connectionLimit: 4 and 20 concurrent callers, more than one
+        // connection must have been checked out simultaneously at some point.
+        // A fully-serialized run — the shape a same-connection-checkout
+        // regression's fix-by-coincidence could produce — would never exceed 1
+        // here.
+        expect(maxObservedConcurrency).toBeGreaterThan(1);
+    });
+});

package/dist/modules/storage/classify-error.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 { type DbErrorClassification } from '@byline/core';
+/**
+ * Classify a MySQL driver error. Walks a short `cause` chain (Drizzle's
+ * `DrizzleQueryError` → the underlying mysql2 error) looking for a
+ * duplicate-key error and returns the carried index name. Mirrors
+ * `packages/db-postgres/src/modules/storage/classify-error.ts`, whose
+ * pg-anatomy docblock this docblock intentionally parallels.
+ *
+ * MySQL error anatomy (verified against a live MySQL 9.7.1 server, not
+ * assumed): a duplicate-key violation raises `ERROR 1062 (23000)`, and
+ * mysql2 surfaces it as `{ code: 'ER_DUP_ENTRY', errno: 1062, sqlState:
+ * '23000', message: "Duplicate entry '…' for key '<table>.<index>'" }`.
+ * Unlike Postgres, there is no structural `constraint` property — the index
+ * name must be parsed out of the message, and MySQL 8.0+ qualifies it with
+ * the table name. Matching on the numeric `errno` (not the `code` string)
+ * because it is stable across mysql2 versions and locales; the message text
+ * is not guaranteed to be, though the `for key '…'` shape has held since
+ * MySQL 5.x and is what we parse.
+ *
+ * Carriage semantics (binding, from the #45 review carry-forward): strip the
+ * `<table>.` qualifier and carry the **bare index name**, so both adapters'
+ * `classifyError` report the same shape for the same logical failure — core
+ * never learns driver anatomy. `packages/core/src/services/document-lifecycle
+ * /internals.ts` only substring-matches the constraint, so the qualified
+ * form would also have worked, but a contract is uniform or it is not one.
+ */
+export declare function classifyError(err: unknown): DbErrorClassification;

package/dist/modules/storage/classify-error.js

@@ -0,0 +1,50 @@
+/**
+ * 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 { DbErrorCodes } from '@byline/core';
+/**
+ * Classify a MySQL driver error. Walks a short `cause` chain (Drizzle's
+ * `DrizzleQueryError` → the underlying mysql2 error) looking for a
+ * duplicate-key error and returns the carried index name. Mirrors
+ * `packages/db-postgres/src/modules/storage/classify-error.ts`, whose
+ * pg-anatomy docblock this docblock intentionally parallels.
+ *
+ * MySQL error anatomy (verified against a live MySQL 9.7.1 server, not
+ * assumed): a duplicate-key violation raises `ERROR 1062 (23000)`, and
+ * mysql2 surfaces it as `{ code: 'ER_DUP_ENTRY', errno: 1062, sqlState:
+ * '23000', message: "Duplicate entry '…' for key '<table>.<index>'" }`.
+ * Unlike Postgres, there is no structural `constraint` property — the index
+ * name must be parsed out of the message, and MySQL 8.0+ qualifies it with
+ * the table name. Matching on the numeric `errno` (not the `code` string)
+ * because it is stable across mysql2 versions and locales; the message text
+ * is not guaranteed to be, though the `for key '…'` shape has held since
+ * MySQL 5.x and is what we parse.
+ *
+ * Carriage semantics (binding, from the #45 review carry-forward): strip the
+ * `<table>.` qualifier and carry the **bare index name**, so both adapters'
+ * `classifyError` report the same shape for the same logical failure — core
+ * never learns driver anatomy. `packages/core/src/services/document-lifecycle
+ * /internals.ts` only substring-matches the constraint, so the qualified
+ * form would also have worked, but a contract is uniform or it is not one.
+ */
+export function classifyError(err) {
+    let e = err;
+    for (let i = 0; i < 3 && e != null && typeof e === 'object'; i++) {
+        if (e.errno === 1062) {
+            const match = typeof e.message === 'string' ? e.message.match(/for key '([^']+)'/) : null;
+            const qualifiedName = match?.[1];
+            // MySQL 8.0+ qualifies the index name as `<table>.<index>` — strip the
+            // table qualifier so the carried value is the bare index name only.
+            const constraint = qualifiedName?.includes('.')
+                ? qualifiedName.slice(qualifiedName.indexOf('.') + 1)
+                : qualifiedName;
+            return { code: DbErrorCodes.UNIQUE_VIOLATION, constraint };
+        }
+        e = e.cause;
+    }
+    return { code: DbErrorCodes.UNKNOWN };
+}

package/dist/modules/storage/classify-error.test.node.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/classify-error.test.node.js

@@ -0,0 +1,89 @@
+/**
+ * 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 { runClassifyErrorContract } from '@byline/db-conformance';
+import { describe, expect, it } from 'vitest';
+import { classifyError } from './classify-error.js';
+describe('classifyError (mysql)', () => {
+    it('classifies a raw ER_DUP_ENTRY (errno 1062) as DB_UNIQUE_VIOLATION with the bare index name', () => {
+        const err = {
+            code: 'ER_DUP_ENTRY',
+            errno: 1062,
+            sqlState: '23000',
+            message: "Duplicate entry '1' for key 't_dup.idx_document_paths_collection_locale_path'",
+        };
+        expect(classifyError(err)).toEqual({
+            code: 'DB_UNIQUE_VIOLATION',
+            constraint: 'idx_document_paths_collection_locale_path',
+        });
+    });
+    it('walks a Drizzle-style cause chain to the underlying mysql2 error', () => {
+        const err = {
+            name: 'DrizzleQueryError',
+            cause: {
+                code: 'ER_DUP_ENTRY',
+                errno: 1062,
+                sqlState: '23000',
+                message: "Duplicate entry '2' for key 'byline_document_paths.some_other_unique'",
+            },
+        };
+        expect(classifyError(err)).toEqual({
+            code: 'DB_UNIQUE_VIOLATION',
+            constraint: 'some_other_unique',
+        });
+    });
+    it('matches on the numeric errno, not the code string', () => {
+        // Same errno, a code string that would not stringwise-match anything —
+        // classification still succeeds because the match is on `errno`.
+        const err = {
+            code: 'SOME_OTHER_CODE',
+            errno: 1062,
+            message: "Duplicate entry '1' for key 't.idx_x'",
+        };
+        expect(classifyError(err).code).toBe('DB_UNIQUE_VIOLATION');
+    });
+    it('returns DB_UNKNOWN for a non-duplicate-key error', () => {
+        expect(classifyError({
+            code: 'ER_NO_REFERENCED_ROW_2',
+            errno: 1452,
+            sqlState: '23000',
+            message: 'Cannot add or update a child row: a foreign key constraint fails',
+        })).toEqual({ code: 'DB_UNKNOWN' });
+    });
+    it('returns DB_UNKNOWN for a non-error value', () => {
+        expect(classifyError(undefined)).toEqual({ code: 'DB_UNKNOWN' });
+        expect(classifyError('boom')).toEqual({ code: 'DB_UNKNOWN' });
+        expect(classifyError(null)).toEqual({ code: 'DB_UNKNOWN' });
+    });
+});
+runClassifyErrorContract([
+    {
+        adapterName: 'mysql',
+        classifyError,
+        uniqueViolationError: {
+            code: 'ER_DUP_ENTRY',
+            errno: 1062,
+            sqlState: '23000',
+            message: "Duplicate entry 'some-uuid' for key 'byline_document_paths.idx_document_paths_collection_locale_path'",
+        },
+        nestedUniqueViolationError: {
+            name: 'DrizzleQueryError',
+            cause: {
+                code: 'ER_DUP_ENTRY',
+                errno: 1062,
+                sqlState: '23000',
+                message: "Duplicate entry 'some-uuid' for key 'byline_document_paths.idx_document_paths_collection_locale_path'",
+            },
+        },
+        unrelatedError: {
+            code: 'ER_NO_REFERENCED_ROW_2',
+            errno: 1452,
+            sqlState: '23000',
+            message: 'Cannot add or update a child row: a foreign key constraint fails',
+        },
+    },
+]);