@byline/db-mysql 4.8.0

package/dist/modules/admin/admin-permissions-repository.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 { AdminPermissionsRepository } from '@byline/admin/admin-permissions';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+/**
+ * MySQL implementation of `AdminPermissionsRepository` — per-role ability
+ * grants and the distinct-abilities-for-user join that drives
+ * `resolveActor()`. Ported from
+ * `packages/db-postgres/src/modules/admin/admin-permissions-repository.ts`.
+ *
+ * `grantAbility` — pg's `onConflictDoNothing({ target: [admin_role_id,
+ * ability] })` targets the named `uq_byline_admin_permissions_role_ability`
+ * constraint specifically. `byline_admin_permissions` carries **two** unique
+ * keys — the `id` primary key and that named constraint — so, per the
+ * per-table rule this port follows throughout (see
+ * `admin-roles-repository.ts`'s `assignToUser` for the one-unique-key
+ * counter-case), a plain `.onDuplicateKeyUpdate()` is not safe here: MySQL
+ * has no per-constraint targeting, so it would fire — and silently rewrite
+ * an existing row — on *either* unique key, when only a collision on the
+ * role+ability pair should be swallowed. This uses the insert-then-catch
+ * pattern instead (mirrors `writeDocumentPath` in
+ * `storage-commands.ts`): try the insert; if it fails with `ER_DUP_ENTRY`
+ * on `uq_byline_admin_permissions_role_ability` specifically (detected via
+ * the shared `classifyError`), treat it as the idempotent no-op pg's
+ * `onConflictDoNothing` gives; any other error (in particular a duplicate
+ * on `id`, which — being a fresh UUIDv7 — should never happen in practice,
+ * but is structurally a different unique key) rethrows unchanged.
+ */
+export declare function createAdminPermissionsRepository(db: MySql2Database<typeof schema>): AdminPermissionsRepository;

package/dist/modules/admin/admin-permissions-repository.js

@@ -0,0 +1,101 @@
+/**
+ * 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';
+import { and, eq } from 'drizzle-orm';
+import { v7 as uuidv7 } from 'uuid';
+import { adminPermissions, adminRoleAdminUser } from '../../database/schema/auth.js';
+import { classifyError } from '../storage/classify-error.js';
+/**
+ * MySQL implementation of `AdminPermissionsRepository` — per-role ability
+ * grants and the distinct-abilities-for-user join that drives
+ * `resolveActor()`. Ported from
+ * `packages/db-postgres/src/modules/admin/admin-permissions-repository.ts`.
+ *
+ * `grantAbility` — pg's `onConflictDoNothing({ target: [admin_role_id,
+ * ability] })` targets the named `uq_byline_admin_permissions_role_ability`
+ * constraint specifically. `byline_admin_permissions` carries **two** unique
+ * keys — the `id` primary key and that named constraint — so, per the
+ * per-table rule this port follows throughout (see
+ * `admin-roles-repository.ts`'s `assignToUser` for the one-unique-key
+ * counter-case), a plain `.onDuplicateKeyUpdate()` is not safe here: MySQL
+ * has no per-constraint targeting, so it would fire — and silently rewrite
+ * an existing row — on *either* unique key, when only a collision on the
+ * role+ability pair should be swallowed. This uses the insert-then-catch
+ * pattern instead (mirrors `writeDocumentPath` in
+ * `storage-commands.ts`): try the insert; if it fails with `ER_DUP_ENTRY`
+ * on `uq_byline_admin_permissions_role_ability` specifically (detected via
+ * the shared `classifyError`), treat it as the idempotent no-op pg's
+ * `onConflictDoNothing` gives; any other error (in particular a duplicate
+ * on `id`, which — being a fresh UUIDv7 — should never happen in practice,
+ * but is structurally a different unique key) rethrows unchanged.
+ */
+export function createAdminPermissionsRepository(db) {
+    return {
+        async grantAbility(roleId, ability) {
+            try {
+                await db.insert(adminPermissions).values({ id: uuidv7(), admin_role_id: roleId, ability });
+            }
+            catch (err) {
+                const classification = classifyError(err);
+                const isRoleAbilityConflict = classification.code === DbErrorCodes.UNIQUE_VIOLATION &&
+                    classification.constraint === 'uq_byline_admin_permissions_role_ability';
+                if (!isRoleAbilityConflict)
+                    throw err;
+                // Already granted — idempotent no-op, matching pg's onConflictDoNothing.
+            }
+        },
+        async revokeAbility(roleId, ability) {
+            await db
+                .delete(adminPermissions)
+                .where(and(eq(adminPermissions.admin_role_id, roleId), eq(adminPermissions.ability, ability)));
+        },
+        async listAbilities(roleId) {
+            const rows = await db
+                .select({ ability: adminPermissions.ability })
+                .from(adminPermissions)
+                .where(eq(adminPermissions.admin_role_id, roleId));
+            return rows.map((r) => r.ability);
+        },
+        async setAbilities(roleId, abilities) {
+            await db.transaction(async (tx) => {
+                await tx.delete(adminPermissions).where(eq(adminPermissions.admin_role_id, roleId));
+                if (abilities.length === 0)
+                    return;
+                const rows = abilities.map((ability) => ({
+                    id: uuidv7(),
+                    admin_role_id: roleId,
+                    ability,
+                }));
+                await tx.insert(adminPermissions).values(rows);
+            });
+        },
+        async listAbilitiesForUser(userId) {
+            const rows = await db
+                .selectDistinct({ ability: adminPermissions.ability })
+                .from(adminPermissions)
+                .innerJoin(adminRoleAdminUser, eq(adminRoleAdminUser.admin_role_id, adminPermissions.admin_role_id))
+                .where(eq(adminRoleAdminUser.admin_user_id, userId));
+            return rows.map((r) => r.ability);
+        },
+        async listRolesForAbility(ability) {
+            const rows = await db
+                .select({ admin_role_id: adminPermissions.admin_role_id })
+                .from(adminPermissions)
+                .where(eq(adminPermissions.ability, ability));
+            return rows.map((r) => r.admin_role_id);
+        },
+        async listUsersForAbility(ability) {
+            const rows = await db
+                .selectDistinct({ admin_user_id: adminRoleAdminUser.admin_user_id })
+                .from(adminRoleAdminUser)
+                .innerJoin(adminPermissions, eq(adminPermissions.admin_role_id, adminRoleAdminUser.admin_role_id))
+                .where(eq(adminPermissions.ability, ability));
+            return rows.map((r) => r.admin_user_id);
+        },
+    };
+}

package/dist/modules/admin/admin-preferences-repository.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 { AdminPreferencesRepository } from '@byline/admin/admin-preferences';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+/**
+ * MySQL implementation of `AdminPreferencesRepository`. Ported from
+ * `packages/db-postgres/src/modules/admin/admin-preferences-repository.ts`.
+ *
+ * `jsonb` → `json`. pg's upsert merges the JSONB patch per key inside a
+ * single `ON CONFLICT DO UPDATE value = value || patch` statement, computed
+ * atomically at the database. MySQL's nearest built-in, `JSON_MERGE_PATCH`,
+ * implements RFC 7396 merge-patch semantics — which recurse into matching
+ * nested *object* values instead of replacing them wholesale. Confirmed
+ * live, not assumed: `JSON_MERGE_PATCH('{"filters":{"status":"draft",
+ * "author":"ada"}}', '{"filters":{"status":"published"}}')` returns
+ * `{"filters":{"author":"ada","status":"published"}}` — it keeps `author`.
+ * Postgres's `||` on the same two documents returns `{"filters":
+ * {"status":"published"}}` — it replaces the nested `filters` object
+ * wholesale, discarding `author`. `AdminUserPreferenceRow.value` is a
+ * `Record<string, unknown>` a caller could one day populate with a nested
+ * object, so this doesn't reach for `JSON_MERGE_PATCH` — it computes the
+ * merge in JS instead (`{ ...current, ...patch }`), an exact shallow-merge
+ * equivalent of `||` that matches pg's actual (not RFC 7396) semantics.
+ *
+ * Race safety: rather than a `SELECT` (locked or not) followed by a
+ * conditional `INSERT`/`UPDATE` — which leaves a window on the
+ * *first-ever* write for a (user, scope) pair, since two concurrent
+ * transactions can each observe "no row yet" before either commits — this
+ * tries the `INSERT` first. `byline_admin_user_preferences` has exactly one
+ * unique key, the composite `(user_id, scope)` primary key, so the SQL
+ * engine itself is the single arbiter of "does this row already exist":
+ * the loser of a genuine race gets `ER_DUP_ENTRY` back atomically and falls
+ * through to a `SELECT … FOR UPDATE` + merge + `UPDATE`, run inside a
+ * transaction so the lock is held across the read-modify-write. A
+ * duplicate-key error is only treated as "row exists, merge" when
+ * `classifyError` confirms it's the `PRIMARY` key specifically (verified
+ * live: a composite-PK collision on this table reports `for key
+ * '<table>.PRIMARY'`) — any other error (e.g. the `fk_admin_user_
+ * preferences_user_id` foreign key rejecting an unknown `userId`) rethrows
+ * unchanged rather than being misread as a pre-existing row.
+ *
+ * The conflict-fallback branch handles the row vanishing out from under it
+ * too: if a concurrent delete (e.g. cascading from the owning admin user)
+ * removes the row between the failed `INSERT` and the locked `SELECT`,
+ * `existing` comes back empty and this inserts fresh rather than merging
+ * onto — and reporting success for — a snapshot of a row that no longer
+ * exists. The subsequent `UPDATE`'s affected-row count is checked too,
+ * defensively, even though the `FOR UPDATE` lock held across the
+ * read-modify-write should make a mid-transaction disappearance there
+ * unreachable.
+ *
+ * `.returning()` has no MySQL equivalent; `created_at`/`updated_at` are
+ * captured once as `now` and reused for both the write and the returned
+ * row — no re-`SELECT` needed.
+ */
+export declare function createAdminPreferencesRepository(db: MySql2Database<typeof schema>): AdminPreferencesRepository;

package/dist/modules/admin/admin-preferences-repository.js

@@ -0,0 +1,156 @@
+/**
+ * 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, ERR_DATABASE, getLogger } from '@byline/core';
+import { and, eq } from 'drizzle-orm';
+import { adminUserPreferences } from '../../database/schema/auth.js';
+import { classifyError } from '../storage/classify-error.js';
+import { affectedRowCount } from '../storage/storage-utils.js';
+/**
+ * MySQL implementation of `AdminPreferencesRepository`. Ported from
+ * `packages/db-postgres/src/modules/admin/admin-preferences-repository.ts`.
+ *
+ * `jsonb` → `json`. pg's upsert merges the JSONB patch per key inside a
+ * single `ON CONFLICT DO UPDATE value = value || patch` statement, computed
+ * atomically at the database. MySQL's nearest built-in, `JSON_MERGE_PATCH`,
+ * implements RFC 7396 merge-patch semantics — which recurse into matching
+ * nested *object* values instead of replacing them wholesale. Confirmed
+ * live, not assumed: `JSON_MERGE_PATCH('{"filters":{"status":"draft",
+ * "author":"ada"}}', '{"filters":{"status":"published"}}')` returns
+ * `{"filters":{"author":"ada","status":"published"}}` — it keeps `author`.
+ * Postgres's `||` on the same two documents returns `{"filters":
+ * {"status":"published"}}` — it replaces the nested `filters` object
+ * wholesale, discarding `author`. `AdminUserPreferenceRow.value` is a
+ * `Record<string, unknown>` a caller could one day populate with a nested
+ * object, so this doesn't reach for `JSON_MERGE_PATCH` — it computes the
+ * merge in JS instead (`{ ...current, ...patch }`), an exact shallow-merge
+ * equivalent of `||` that matches pg's actual (not RFC 7396) semantics.
+ *
+ * Race safety: rather than a `SELECT` (locked or not) followed by a
+ * conditional `INSERT`/`UPDATE` — which leaves a window on the
+ * *first-ever* write for a (user, scope) pair, since two concurrent
+ * transactions can each observe "no row yet" before either commits — this
+ * tries the `INSERT` first. `byline_admin_user_preferences` has exactly one
+ * unique key, the composite `(user_id, scope)` primary key, so the SQL
+ * engine itself is the single arbiter of "does this row already exist":
+ * the loser of a genuine race gets `ER_DUP_ENTRY` back atomically and falls
+ * through to a `SELECT … FOR UPDATE` + merge + `UPDATE`, run inside a
+ * transaction so the lock is held across the read-modify-write. A
+ * duplicate-key error is only treated as "row exists, merge" when
+ * `classifyError` confirms it's the `PRIMARY` key specifically (verified
+ * live: a composite-PK collision on this table reports `for key
+ * '<table>.PRIMARY'`) — any other error (e.g. the `fk_admin_user_
+ * preferences_user_id` foreign key rejecting an unknown `userId`) rethrows
+ * unchanged rather than being misread as a pre-existing row.
+ *
+ * The conflict-fallback branch handles the row vanishing out from under it
+ * too: if a concurrent delete (e.g. cascading from the owning admin user)
+ * removes the row between the failed `INSERT` and the locked `SELECT`,
+ * `existing` comes back empty and this inserts fresh rather than merging
+ * onto — and reporting success for — a snapshot of a row that no longer
+ * exists. The subsequent `UPDATE`'s affected-row count is checked too,
+ * defensively, even though the `FOR UPDATE` lock held across the
+ * read-modify-write should make a mid-transaction disappearance there
+ * unreachable.
+ *
+ * `.returning()` has no MySQL equivalent; `created_at`/`updated_at` are
+ * captured once as `now` and reused for both the write and the returned
+ * row — no re-`SELECT` needed.
+ */
+export function createAdminPreferencesRepository(db) {
+    return {
+        async get(userId, scope) {
+            const [row] = await db
+                .select()
+                .from(adminUserPreferences)
+                .where(and(eq(adminUserPreferences.user_id, userId), eq(adminUserPreferences.scope, scope)));
+            return row ?? null;
+        },
+        async upsert(userId, scope, patch) {
+            const insertNow = new Date();
+            try {
+                await db.insert(adminUserPreferences).values({
+                    user_id: userId,
+                    scope,
+                    value: patch,
+                    created_at: insertNow,
+                    updated_at: insertNow,
+                });
+                return {
+                    user_id: userId,
+                    scope,
+                    value: { ...patch },
+                    created_at: insertNow,
+                    updated_at: insertNow,
+                };
+            }
+            catch (err) {
+                const classification = classifyError(err);
+                const isExistingRow = classification.code === DbErrorCodes.UNIQUE_VIOLATION &&
+                    classification.constraint === 'PRIMARY';
+                if (!isExistingRow)
+                    throw err;
+            }
+            // A row already exists for (userId, scope) — lock it, merge in JS, and
+            // write the merge back. Locked inside a transaction so a second
+            // concurrent upsert blocks on this row rather than racing it.
+            return db.transaction(async (tx) => {
+                const [existing] = await tx
+                    .select()
+                    .from(adminUserPreferences)
+                    .where(and(eq(adminUserPreferences.user_id, userId), eq(adminUserPreferences.scope, scope)))
+                    .for('update');
+                const now = new Date();
+                if (!existing) {
+                    // The row that made our INSERT fail is gone by the time we got
+                    // here — a concurrent delete (e.g. cascading from the owning
+                    // admin user) raced us between the failed INSERT and this locked
+                    // read. There is truly no row now, so insert fresh rather than
+                    // merging onto a snapshot that no longer exists.
+                    await tx.insert(adminUserPreferences).values({
+                        user_id: userId,
+                        scope,
+                        value: patch,
+                        created_at: now,
+                        updated_at: now,
+                    });
+                    return {
+                        user_id: userId,
+                        scope,
+                        value: { ...patch },
+                        created_at: now,
+                        updated_at: now,
+                    };
+                }
+                const merged = {
+                    ...existing.value,
+                    ...patch,
+                };
+                const result = await tx
+                    .update(adminUserPreferences)
+                    .set({ value: merged, updated_at: now })
+                    .where(and(eq(adminUserPreferences.user_id, userId), eq(adminUserPreferences.scope, scope)));
+                if (affectedRowCount(result) === 0) {
+                    // Unreachable in practice — `existing` was read via `FOR UPDATE`
+                    // inside this same transaction, so the row is locked and cannot
+                    // vanish before the `UPDATE` above. Guarded anyway so a write
+                    // that didn't happen is never reported as a success.
+                    throw ERR_DATABASE({
+                        message: 'admin preferences upsert: locked row vanished before UPDATE',
+                    }).log(getLogger());
+                }
+                return {
+                    user_id: userId,
+                    scope,
+                    value: merged,
+                    created_at: existing.created_at,
+                    updated_at: now,
+                };
+            });
+        },
+    };
+}

package/dist/modules/admin/admin-roles-repository.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 AdminRolesRepository } from '@byline/admin/admin-roles';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+export declare function createAdminRolesRepository(db: MySql2Database<typeof schema>): AdminRolesRepository;

package/dist/modules/admin/admin-roles-repository.js

@@ -0,0 +1,209 @@
+/**
+ * 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_ADMIN_ROLE_VERSION_CONFLICT, } from '@byline/admin/admin-roles';
+import { and, asc, eq, sql } from 'drizzle-orm';
+import { v7 as uuidv7 } from 'uuid';
+import { adminRoleAdminUser, adminRoles } from '../../database/schema/auth.js';
+import { affectedRowCount } from '../storage/storage-utils.js';
+/**
+ * MySQL implementation of `AdminRolesRepository` — role CRUD, reorder, and
+ * role ↔ user assignments. Ability grants live on `AdminPermissionsRepository`
+ * (see `admin-permissions-repository.ts`). Ported from
+ * `packages/db-postgres/src/modules/admin/admin-roles-repository.ts`.
+ *
+ * `create`/`update` follow the same `.returning()` → construct-in-JS
+ * approach as `admin-users-repository.ts` (see that file's docblock for the
+ * full rationale): `create`'s `created_at`/`updated_at` are captured once as
+ * `now` and used for both the `INSERT` and the returned row; `update` reads
+ * the current row first (values the patch didn't touch aren't otherwise
+ * knowable) and merges the patch onto it in JS, with the vid-guarded
+ * `UPDATE`'s affected-row count as the sole accept/reject authority.
+ *
+ * Unlike `admin-users-repository.ts`'s `update`/`setPasswordHash` (which
+ * re-`SELECT` post-`UPDATE` — see that file's docblock for why), `update`
+ * here safely returns the pre-read-merged row: every mutator of
+ * `byline_admin_roles` — `update` itself and `reorder` — bumps `vid`, so
+ * there is no vid-less mutator on this table analogous to admin-users'
+ * `recordLoginSuccess`/`recordLoginFailure` that could leave a pre-read
+ * snapshot stale while the guarded `UPDATE` still succeeds. If a future
+ * change adds a vid-less mutator to this table, revisit this.
+ *
+ * `assignToUser`'s upsert uses a plain `.onDuplicateKeyUpdate()` no-op
+ * idiom (`admin_role_id = admin_role_id`) rather than the insert-then-catch
+ * pattern `admin-permissions-repository.ts` needs: `byline_admin_role_
+ * admin_user` carries exactly one unique key — the composite primary key
+ * `(admin_role_id, admin_user_id)` targeted here — so a duplicate-key
+ * collision on this table can only be that one key, and MySQL's lack of
+ * per-constraint targeting is a non-issue.
+ */
+const PUBLIC_ROLE_COLUMNS = {
+    id: adminRoles.id,
+    vid: adminRoles.vid,
+    name: adminRoles.name,
+    machine_name: adminRoles.machine_name,
+    description: adminRoles.description,
+    order: adminRoles.order,
+    created_at: adminRoles.created_at,
+    updated_at: adminRoles.updated_at,
+};
+export function createAdminRolesRepository(db) {
+    return {
+        // -----------------------------------------------------------------
+        // Role CRUD
+        // -----------------------------------------------------------------
+        async create(input) {
+            const id = uuidv7();
+            const now = new Date();
+            const row = {
+                id,
+                vid: 1,
+                name: input.name,
+                machine_name: input.machine_name,
+                description: input.description ?? null,
+                order: input.order ?? 0,
+                created_at: now,
+                updated_at: now,
+            };
+            await db.insert(adminRoles).values({
+                id: row.id,
+                name: row.name,
+                machine_name: row.machine_name,
+                description: row.description,
+                order: row.order,
+                created_at: now,
+                updated_at: now,
+            });
+            return row;
+        },
+        async getById(id) {
+            const [row] = await db
+                .select(PUBLIC_ROLE_COLUMNS)
+                .from(adminRoles)
+                .where(eq(adminRoles.id, id));
+            return row ?? null;
+        },
+        async getByMachineName(machineName) {
+            const [row] = await db
+                .select(PUBLIC_ROLE_COLUMNS)
+                .from(adminRoles)
+                .where(eq(adminRoles.machine_name, machineName));
+            return row ?? null;
+        },
+        async list() {
+            return db
+                .select(PUBLIC_ROLE_COLUMNS)
+                .from(adminRoles)
+                .orderBy(asc(adminRoles.order), asc(adminRoles.created_at));
+        },
+        async update(id, expectedVid, patch) {
+            const [current] = await db
+                .select(PUBLIC_ROLE_COLUMNS)
+                .from(adminRoles)
+                .where(eq(adminRoles.id, id));
+            const now = new Date();
+            const updateSet = {
+                updated_at: now,
+                vid: sql `${adminRoles.vid} + 1`,
+            };
+            if (patch.name !== undefined)
+                updateSet.name = patch.name;
+            if (patch.description !== undefined)
+                updateSet.description = patch.description;
+            if (patch.order !== undefined)
+                updateSet.order = patch.order;
+            const result = await db
+                .update(adminRoles)
+                .set(updateSet)
+                .where(and(eq(adminRoles.id, id), eq(adminRoles.vid, expectedVid)));
+            if (affectedRowCount(result) === 0 || !current)
+                throw ERR_ADMIN_ROLE_VERSION_CONFLICT();
+            return {
+                ...current,
+                name: patch.name !== undefined ? patch.name : current.name,
+                description: patch.description !== undefined ? patch.description : current.description,
+                order: patch.order !== undefined ? patch.order : current.order,
+                vid: expectedVid + 1,
+                updated_at: now,
+            };
+        },
+        async delete(id, expectedVid) {
+            // Cascades remove role ↔ user assignments and per-role permissions
+            // (`ON DELETE CASCADE` on both FKs — see `database/schema/auth.ts`).
+            const result = await db
+                .delete(adminRoles)
+                .where(and(eq(adminRoles.id, id), eq(adminRoles.vid, expectedVid)));
+            if (affectedRowCount(result) === 0)
+                throw ERR_ADMIN_ROLE_VERSION_CONFLICT();
+        },
+        async reorder(ids) {
+            if (ids.length === 0)
+                return;
+            // Single transaction so the list is never observed half-reordered.
+            // No vid gate: see `AdminRolesRepository.reorder` contract docs.
+            await db.transaction(async (tx) => {
+                const now = new Date();
+                for (let i = 0; i < ids.length; i++) {
+                    await tx
+                        .update(adminRoles)
+                        .set({
+                        order: i,
+                        updated_at: now,
+                        vid: sql `${adminRoles.vid} + 1`,
+                    })
+                        .where(eq(adminRoles.id, ids[i]));
+                }
+            });
+        },
+        // -----------------------------------------------------------------
+        // Role ↔ user assignments
+        // -----------------------------------------------------------------
+        async assignToUser(roleId, userId) {
+            await db
+                .insert(adminRoleAdminUser)
+                .values({ admin_role_id: roleId, admin_user_id: userId })
+                .onDuplicateKeyUpdate({
+                set: { admin_role_id: sql `admin_role_id` },
+            });
+        },
+        async unassignFromUser(roleId, userId) {
+            await db
+                .delete(adminRoleAdminUser)
+                .where(and(eq(adminRoleAdminUser.admin_role_id, roleId), eq(adminRoleAdminUser.admin_user_id, userId)));
+        },
+        async listRolesForUser(userId) {
+            const rows = await db
+                .select(PUBLIC_ROLE_COLUMNS)
+                .from(adminRoles)
+                .innerJoin(adminRoleAdminUser, eq(adminRoleAdminUser.admin_role_id, adminRoles.id))
+                .where(eq(adminRoleAdminUser.admin_user_id, userId))
+                .orderBy(asc(adminRoles.order));
+            return rows;
+        },
+        async listUsersForRole(roleId) {
+            const rows = await db
+                .select({ admin_user_id: adminRoleAdminUser.admin_user_id })
+                .from(adminRoleAdminUser)
+                .where(eq(adminRoleAdminUser.admin_role_id, roleId));
+            return rows.map((r) => r.admin_user_id);
+        },
+        async setRolesForUser(userId, roleIds) {
+            // Single transaction — user assignments are never observed
+            // half-edited. Symmetric to AdminPermissionsRepository.setAbilities.
+            await db.transaction(async (tx) => {
+                await tx.delete(adminRoleAdminUser).where(eq(adminRoleAdminUser.admin_user_id, userId));
+                if (roleIds.length === 0)
+                    return;
+                const rows = roleIds.map((admin_role_id) => ({
+                    admin_role_id,
+                    admin_user_id: userId,
+                }));
+                await tx.insert(adminRoleAdminUser).values(rows);
+            });
+        },
+    };
+}

package/dist/modules/admin/admin-store.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 { AdminStore } from '@byline/admin';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+/**
+ * Wire the five admin repositories against a Drizzle handle and return the
+ * `AdminStore` bundle expected by `@byline/admin` — specifically by the
+ * built-in `JwtSessionProvider`, by `seedSuperAdmin`, and by the admin-user /
+ * admin-role commands. Mirrors
+ * `packages/db-postgres/src/modules/admin/admin-store.ts`.
+ *
+ * Construct once per process, alongside the `mysqlAdapter` call.
+ */
+export declare function createAdminStore(db: MySql2Database<typeof schema>): AdminStore;

package/dist/modules/admin/admin-store.js

@@ -0,0 +1,30 @@
+/**
+ * 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 { createAdminPermissionsRepository } from './admin-permissions-repository.js';
+import { createAdminPreferencesRepository } from './admin-preferences-repository.js';
+import { createAdminRolesRepository } from './admin-roles-repository.js';
+import { createAdminUsersRepository } from './admin-users-repository.js';
+import { createRefreshTokensRepository } from './refresh-tokens-repository.js';
+/**
+ * Wire the five admin repositories against a Drizzle handle and return the
+ * `AdminStore` bundle expected by `@byline/admin` — specifically by the
+ * built-in `JwtSessionProvider`, by `seedSuperAdmin`, and by the admin-user /
+ * admin-role commands. Mirrors
+ * `packages/db-postgres/src/modules/admin/admin-store.ts`.
+ *
+ * Construct once per process, alongside the `mysqlAdapter` call.
+ */
+export function createAdminStore(db) {
+    return {
+        adminUsers: createAdminUsersRepository(db),
+        adminRoles: createAdminRolesRepository(db),
+        adminPermissions: createAdminPermissionsRepository(db),
+        refreshTokens: createRefreshTokensRepository(db),
+        adminPreferences: createAdminPreferencesRepository(db),
+    };
+}

package/dist/modules/admin/admin-users-repository.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 AdminUsersRepository } from '@byline/admin/admin-users';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+export declare function createAdminUsersRepository(db: MySql2Database<typeof schema>): AdminUsersRepository;