@byline/db-mysql 4.8.0

package/dist/database/schema/auth.js

@@ -0,0 +1,226 @@
+/**
+ * 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
+ */
+/**
+ * Auth schema — admin identity, roles, role-user assignment, and per-role
+ * ability grants.
+ *
+ * All tables carry the `byline_` prefix so Byline can coexist with other
+ * schemas in a shared database. The TypeScript exports are unprefixed —
+ * the prefix is a DB-side concern.
+ *
+ * Shape mirrors the mature Modulus Learning implementation with minor
+ * Byline conventions:
+ *   - UUIDv7 primary keys (generated at insert time in the repository).
+ *   - `vid` integer version column for optimistic concurrency (defaults
+ *     to 1; bumped by write paths when needed).
+ *   - snake_case column names matching the rest of the Byline schema.
+ *
+ * See docs/06-auth-and-security/01-authn-authz.md for the full data model and present-state
+ * reference.
+ */
+import { relations, sql } from 'drizzle-orm';
+import { boolean, datetime, foreignKey, index, int, json, mysqlTable, primaryKey, text, unique, varchar, } from 'drizzle-orm/mysql-core';
+import { createdAt, timestamps, uuidChar } from './common.js';
+// Foreign keys below use the table-level `foreignKey()` builder with an
+// explicit, short `fk_<table>_<column>` name rather than the Postgres
+// schema's column-level `.references()` shorthand — MySQL enforces a hard
+// 64-character identifier cap that several of this schema's auto-generated
+// FK names exceed. See the longer explanation in `./index.ts`.
+// ---------------------------------------------------------------------------
+// byline_admin_users
+// ---------------------------------------------------------------------------
+export const adminUsers = mysqlTable('byline_admin_users', {
+    id: uuidChar('id').primaryKey(),
+    vid: int('vid').notNull().default(1),
+    given_name: varchar('given_name', { length: 100 }),
+    family_name: varchar('family_name', { length: 100 }),
+    /** Optional — email is the primary identifier. Unique when present. */
+    username: varchar('username', { length: 64 }).unique(),
+    email: varchar('email', { length: 254 }).notNull().unique(),
+    /** Full PHC string, e.g. `$argon2id$v=19$m=…$…$…`. */
+    password: varchar('password', { length: 255 }).notNull(),
+    remember_me: boolean('remember_me').notNull().default(false),
+    // fsp 6, matching pg's `timestamp('last_login', { precision: 6, withTimezone: true })` —
+    // see `common.ts`'s `auditTimestamp` docblock for why every temporal column
+    // in this schema moved from fsp 3 to fsp 6.
+    last_login: datetime('last_login', { fsp: 6 }),
+    last_login_ip: varchar('last_login_ip', { length: 45 }),
+    failed_login_attempts: int('failed_login_attempts').notNull().default(0),
+    /**
+     * Actor-level super-admin bypass. When true, `AdminAuth.isSuperAdmin`
+     * short-circuits every ability check. Set only via the seed script
+     * (or manually by a DB admin) — never via the admin UI.
+     */
+    is_super_admin: boolean('is_super_admin').notNull().default(false),
+    /**
+     * Account enablement. Defaults to `false` so accounts created through
+     * any future admin UI require a deliberate enable step. The super-admin
+     * seed sets this to `true`.
+     */
+    is_enabled: boolean('is_enabled').notNull().default(false),
+    is_email_verified: boolean('is_email_verified').notNull().default(false),
+    /**
+     * Per-user admin interface locale preference. Nullable — `null` means
+     * "use the detection cascade" (cookie → Accept-Language → defaultLocale).
+     * Stored as a BCP 47 code (`en`, `pt-BR`, `zh-Hans-CN`); validated at
+     * write time against the host's `i18n.interface.locales` set.
+     */
+    preferred_locale: varchar('preferred_locale', { length: 16 }),
+    ...timestamps,
+}, (table) => [index('idx_byline_admin_users_email').on(table.email)]);
+// ---------------------------------------------------------------------------
+// byline_admin_user_preferences
+// ---------------------------------------------------------------------------
+/**
+ * Scoped per-user key-value preferences (e.g. sticky list-view page
+ * size and sort). One row per (user, scope); `scope` is a dot-separated
+ * key like `collections.docs.list` and `value` is a JSON object whose
+ * shape belongs to the scope's feature. Composite natural PK — writes
+ * are `INSERT … ON DUPLICATE KEY UPDATE` with a per-key JSON merge.
+ * See `@byline/admin/admin-preferences`.
+ */
+export const adminUserPreferences = mysqlTable('byline_admin_user_preferences', {
+    user_id: uuidChar('user_id').notNull(),
+    scope: varchar('scope', { length: 255 }).notNull(),
+    value: json('value').notNull().$type(),
+    ...timestamps,
+}, (table) => [
+    foreignKey({
+        name: 'fk_admin_user_preferences_user_id',
+        columns: [table.user_id],
+        foreignColumns: [adminUsers.id],
+    }).onDelete('cascade'),
+    primaryKey({ columns: [table.user_id, table.scope] }),
+]);
+// ---------------------------------------------------------------------------
+// byline_admin_roles
+// ---------------------------------------------------------------------------
+export const adminRoles = mysqlTable('byline_admin_roles', {
+    id: uuidChar('id').primaryKey(),
+    vid: int('vid').notNull().default(1),
+    /** Human-readable label, e.g. `'Editor'`. */
+    name: varchar('name', { length: 128 }).notNull(),
+    /** Stable identifier used in code, e.g. `'editor'`, `'super-admin'`. */
+    machine_name: varchar('machine_name', { length: 128 }).notNull().unique(),
+    description: text('description'),
+    /** Display ordering in the role-editor UI. */
+    order: int('order').notNull().default(0),
+    ...timestamps,
+}, (table) => [index('idx_byline_admin_roles_machine_name').on(table.machine_name)]);
+// ---------------------------------------------------------------------------
+// byline_admin_role_admin_user — many-to-many join
+// ---------------------------------------------------------------------------
+export const adminRoleAdminUser = mysqlTable('byline_admin_role_admin_user', {
+    admin_role_id: uuidChar('admin_role_id').notNull(),
+    admin_user_id: uuidChar('admin_user_id').notNull(),
+    ...createdAt,
+}, (table) => [
+    foreignKey({
+        name: 'fk_admin_role_admin_user_admin_role_id',
+        columns: [table.admin_role_id],
+        foreignColumns: [adminRoles.id],
+    }).onDelete('cascade'),
+    foreignKey({
+        name: 'fk_admin_role_admin_user_admin_user_id',
+        columns: [table.admin_user_id],
+        foreignColumns: [adminUsers.id],
+    }).onDelete('cascade'),
+    primaryKey({ columns: [table.admin_role_id, table.admin_user_id] }),
+    index('idx_byline_admin_role_admin_user_user').on(table.admin_user_id),
+]);
+// ---------------------------------------------------------------------------
+// byline_admin_permissions — one row per (role, ability) grant
+// ---------------------------------------------------------------------------
+export const adminPermissions = mysqlTable('byline_admin_permissions', {
+    id: uuidChar('id').primaryKey(),
+    vid: int('vid').notNull().default(1),
+    admin_role_id: uuidChar('admin_role_id').notNull(),
+    /** Flat dotted ability key — see `@byline/auth` AbilityRegistry. */
+    ability: varchar('ability', { length: 128 }).notNull(),
+    ...timestamps,
+}, (table) => [
+    foreignKey({
+        name: 'fk_admin_permissions_admin_role_id',
+        columns: [table.admin_role_id],
+        foreignColumns: [adminRoles.id],
+    }).onDelete('cascade'),
+    unique('uq_byline_admin_permissions_role_ability').on(table.admin_role_id, table.ability),
+    index('idx_byline_admin_permissions_role').on(table.admin_role_id),
+]);
+// ---------------------------------------------------------------------------
+// byline_admin_refresh_tokens — JWT session provider's refresh-token store
+// ---------------------------------------------------------------------------
+/**
+ * Refresh tokens are opaque random strings minted by `JwtSessionProvider`.
+ * We never store the plaintext — only a SHA-256 hash (`token_hash`). When
+ * a token is rotated, `revoked_at` is stamped and `rotated_to_id` points
+ * at the replacement row; presenting a rotated token is treated as replay
+ * and revokes the whole chain.
+ */
+export const adminRefreshTokens = mysqlTable('byline_admin_refresh_tokens', {
+    id: uuidChar('id').primaryKey(),
+    admin_user_id: uuidChar('admin_user_id').notNull(),
+    /** SHA-256 hex digest of the raw refresh-token string. 64 chars. */
+    token_hash: varchar('token_hash', { length: 64 }).notNull().unique(),
+    // fsp 6 throughout this table, matching pg — see `common.ts`'s
+    // `auditTimestamp` docblock for why every temporal column in this
+    // schema moved from fsp 3 to fsp 6.
+    issued_at: datetime('issued_at', { fsp: 6 }).notNull().default(sql `CURRENT_TIMESTAMP(6)`),
+    expires_at: datetime('expires_at', { fsp: 6 }).notNull(),
+    revoked_at: datetime('revoked_at', { fsp: 6 }),
+    /**
+     * When this token was rotated, the id of the new token issued in its
+     * place. Self-referential; set atomically alongside `revoked_at`.
+     */
+    rotated_to_id: uuidChar('rotated_to_id'),
+    last_used_at: datetime('last_used_at', { fsp: 6 }),
+    user_agent: varchar('user_agent', { length: 512 }),
+    ip: varchar('ip', { length: 45 }),
+    ...timestamps,
+}, (table) => [
+    foreignKey({
+        name: 'fk_admin_refresh_tokens_admin_user_id',
+        columns: [table.admin_user_id],
+        foreignColumns: [adminUsers.id],
+    }).onDelete('cascade'),
+    index('idx_byline_admin_refresh_tokens_user').on(table.admin_user_id),
+    index('idx_byline_admin_refresh_tokens_token_hash').on(table.token_hash),
+]);
+// ---------------------------------------------------------------------------
+// Relations (drizzle query helpers)
+// ---------------------------------------------------------------------------
+export const adminUsersRelations = relations(adminUsers, ({ many }) => ({
+    roleAssignments: many(adminRoleAdminUser),
+    refreshTokens: many(adminRefreshTokens),
+}));
+export const adminRolesRelations = relations(adminRoles, ({ many }) => ({
+    userAssignments: many(adminRoleAdminUser),
+    permissions: many(adminPermissions),
+}));
+export const adminRoleAdminUserRelations = relations(adminRoleAdminUser, ({ one }) => ({
+    role: one(adminRoles, {
+        fields: [adminRoleAdminUser.admin_role_id],
+        references: [adminRoles.id],
+    }),
+    user: one(adminUsers, {
+        fields: [adminRoleAdminUser.admin_user_id],
+        references: [adminUsers.id],
+    }),
+}));
+export const adminPermissionsRelations = relations(adminPermissions, ({ one }) => ({
+    role: one(adminRoles, {
+        fields: [adminPermissions.admin_role_id],
+        references: [adminRoles.id],
+    }),
+}));
+export const adminRefreshTokensRelations = relations(adminRefreshTokens, ({ one }) => ({
+    user: one(adminUsers, {
+        fields: [adminRefreshTokens.admin_user_id],
+        references: [adminUsers.id],
+    }),
+}));

package/dist/database/schema/common.d.ts

@@ -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
+ */
+/**
+ * `CHAR(36) CHARACTER SET ascii COLLATE ascii_bin` — canonical UUID text.
+ *
+ * Every id / FK column in the schema uses this type. `ascii_bin` is a
+ * byte-wise (case-sensitive) collation, so id equality comparisons and
+ * joins compare bytes rather than applying a case- or accent-insensitive
+ * collation — the MySQL analogue of comparing `uuid` values in Postgres,
+ * which has no notion of collation for that type at all. UUIDs are
+ * app-generated UUIDv7 (the `uuid` package's `v7()`), never DB-generated.
+ */
+export declare const uuidChar: {
+    (): import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+        name: "";
+        dataType: 'custom';
+        columnType: 'MySqlCustomColumn';
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+    <TConfig extends Record<string, any> & unknown>(fieldConfig?: TConfig | undefined): import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+        name: "";
+        dataType: 'custom';
+        columnType: 'MySqlCustomColumn';
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+    <TName extends string>(dbName: TName, fieldConfig?: unknown): import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+        name: TName;
+        dataType: 'custom';
+        columnType: 'MySqlCustomColumn';
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+};
+/**
+ * `varchar(...)` with explicit byte-wise (`ascii_bin`) collation.
+ *
+ * Used for `byline_documents.order_key` (and `byline_document_relationships
+ * .order_key`) so the column sorts the same way JavaScript string
+ * comparison does. The fractional-index algorithm in `@byline/core`
+ * (`generateKeyBetween`, `generateNKeysBetween`) is designed against
+ * byte-wise ordering; MySQL's default collation (`utf8mb4_0900_ai_ci` on
+ * this database) is accent- and case-insensitive and disagrees with JS on
+ * cases like `'Zz' vs 'a0'` — which causes a refetch after a drag-reorder
+ * to "snap" the moved row back to its original position. Mirrors the
+ * Postgres adapter's `varcharByteSorted` (`COLLATE "C"`); see
+ * `packages/db-postgres/src/database/schema/index.ts`.
+ */
+export declare const varcharByteSorted: {
+    (): import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+        name: "";
+        dataType: 'custom';
+        columnType: 'MySqlCustomColumn';
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+    <TConfig extends Record<string, any> & {
+        length: number;
+    }>(fieldConfig?: TConfig | undefined): import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+        name: "";
+        dataType: 'custom';
+        columnType: 'MySqlCustomColumn';
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+    <TName extends string>(dbName: TName, fieldConfig?: {
+        length: number;
+    } | undefined): import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+        name: TName;
+        dataType: 'custom';
+        columnType: 'MySqlCustomColumn';
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+};
+/**
+ * `varchar(...)` with the `utf8mb4_bin` collation — full `utf8mb4` charset
+ * (unlike `uuidChar/varcharByteSorted`'s ascii-only columns, this one must
+ * carry arbitrary Unicode), but byte-wise, case- and accent-sensitive
+ * comparison instead of the database's default `utf8mb4_0900_ai_ci`.
+ *
+ * Used for `byline_document_paths.path`. MySQL's default collation is
+ * accent- *and* case-insensitive, so `/About` and `/about` collide as the
+ * same path on MySQL while remaining two distinct paths on Postgres (whose
+ * default collation carries no such folding). The project owner's initial
+ * instinct was that MySQL's default might be the *better* semantic for
+ * URLs — until testing against a live server showed `ai_ci` also collapses
+ * combining marks Byline's slugifier deliberately preserves for non-Latin
+ * scripts: `กา` = `ก่า` (a Thai tone mark), `कान` = `कानं` (a Devanagari
+ * anusvara), `שלום` = `שָׁלוֹם` (Hebrew niqqud) — see
+ * `packages/core/src/utils/slugify.ts`, which folds Latin diacritics but
+ * explicitly keeps non-Latin combining marks, because those marks are
+ * meaning-bearing in a way a Latin accent mark on a URL slug typically
+ * isn't. Two Thai (or Devanagari, or Hebrew) slugs Byline intended as
+ * distinct documents would silently collide as one path on MySQL only.
+ * Ruling: pin `utf8mb4_bin` so the two adapters agree exactly. This is
+ * `path` only — the store *value* columns keep the database's default
+ * `ai_ci` collation; the resulting accent-insensitive `LIKE` divergence
+ * there was elected deliberately by the plan and stands.
+ */
+export declare const varcharCaseSensitive: {
+    (): import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+        name: "";
+        dataType: 'custom';
+        columnType: 'MySqlCustomColumn';
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+    <TConfig extends Record<string, any> & {
+        length: number;
+    }>(fieldConfig?: TConfig | undefined): import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+        name: "";
+        dataType: 'custom';
+        columnType: 'MySqlCustomColumn';
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+    <TName extends string>(dbName: TName, fieldConfig?: {
+        length: number;
+    } | undefined): import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+        name: TName;
+        dataType: 'custom';
+        columnType: 'MySqlCustomColumn';
+        data: string;
+        driverParam: string;
+        enumValues: undefined;
+    }>;
+};
+/**
+ * Both `created_at` and `updated_at` for tables whose rows are
+ * mutated in place (most application tables — users, roles, documents,
+ * store rows, paths).
+ *
+ * Spread into a `mysqlTable` definition:
+ *
+ *   mysqlTable('byline_admin_users', {
+ *     id: uuidChar('id').primaryKey(),
+ *     ...timestamps,
+ *   })
+ */
+export declare const timestamps: {
+    created_at: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/mysql-core").MySqlDateTimeBuilderInitial<string>>>;
+    updated_at: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/mysql-core").MySqlDateTimeBuilderInitial<string>>>;
+};
+/**
+ * `created_at` only — for tables whose rows are immutable once
+ * inserted (junction tables like `byline_admin_role_admin_user`,
+ * registry rows like `byline_counter_groups`).
+ *
+ * Spread into a `mysqlTable` definition the same way as `timestamps`.
+ */
+export declare const createdAt: {
+    created_at: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/mysql-core").MySqlDateTimeBuilderInitial<string>>>;
+};

package/dist/database/schema/common.js

@@ -0,0 +1,130 @@
+/**
+ * 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 { sql } from 'drizzle-orm';
+import { customType, datetime } from 'drizzle-orm/mysql-core';
+/**
+ * `CHAR(36) CHARACTER SET ascii COLLATE ascii_bin` — canonical UUID text.
+ *
+ * Every id / FK column in the schema uses this type. `ascii_bin` is a
+ * byte-wise (case-sensitive) collation, so id equality comparisons and
+ * joins compare bytes rather than applying a case- or accent-insensitive
+ * collation — the MySQL analogue of comparing `uuid` values in Postgres,
+ * which has no notion of collation for that type at all. UUIDs are
+ * app-generated UUIDv7 (the `uuid` package's `v7()`), never DB-generated.
+ */
+export const uuidChar = customType({
+    dataType: () => 'char(36) CHARACTER SET ascii COLLATE ascii_bin',
+});
+/**
+ * `varchar(...)` with explicit byte-wise (`ascii_bin`) collation.
+ *
+ * Used for `byline_documents.order_key` (and `byline_document_relationships
+ * .order_key`) so the column sorts the same way JavaScript string
+ * comparison does. The fractional-index algorithm in `@byline/core`
+ * (`generateKeyBetween`, `generateNKeysBetween`) is designed against
+ * byte-wise ordering; MySQL's default collation (`utf8mb4_0900_ai_ci` on
+ * this database) is accent- and case-insensitive and disagrees with JS on
+ * cases like `'Zz' vs 'a0'` — which causes a refetch after a drag-reorder
+ * to "snap" the moved row back to its original position. Mirrors the
+ * Postgres adapter's `varcharByteSorted` (`COLLATE "C"`); see
+ * `packages/db-postgres/src/database/schema/index.ts`.
+ */
+export const varcharByteSorted = customType({
+    dataType: (config) => {
+        const len = config?.length ?? 255;
+        return `varchar(${len}) CHARACTER SET ascii COLLATE ascii_bin`;
+    },
+});
+/**
+ * `varchar(...)` with the `utf8mb4_bin` collation — full `utf8mb4` charset
+ * (unlike `uuidChar/varcharByteSorted`'s ascii-only columns, this one must
+ * carry arbitrary Unicode), but byte-wise, case- and accent-sensitive
+ * comparison instead of the database's default `utf8mb4_0900_ai_ci`.
+ *
+ * Used for `byline_document_paths.path`. MySQL's default collation is
+ * accent- *and* case-insensitive, so `/About` and `/about` collide as the
+ * same path on MySQL while remaining two distinct paths on Postgres (whose
+ * default collation carries no such folding). The project owner's initial
+ * instinct was that MySQL's default might be the *better* semantic for
+ * URLs — until testing against a live server showed `ai_ci` also collapses
+ * combining marks Byline's slugifier deliberately preserves for non-Latin
+ * scripts: `กา` = `ก่า` (a Thai tone mark), `कान` = `कानं` (a Devanagari
+ * anusvara), `שלום` = `שָׁלוֹם` (Hebrew niqqud) — see
+ * `packages/core/src/utils/slugify.ts`, which folds Latin diacritics but
+ * explicitly keeps non-Latin combining marks, because those marks are
+ * meaning-bearing in a way a Latin accent mark on a URL slug typically
+ * isn't. Two Thai (or Devanagari, or Hebrew) slugs Byline intended as
+ * distinct documents would silently collide as one path on MySQL only.
+ * Ruling: pin `utf8mb4_bin` so the two adapters agree exactly. This is
+ * `path` only — the store *value* columns keep the database's default
+ * `ai_ci` collation; the resulting accent-insensitive `LIKE` divergence
+ * there was elected deliberately by the plan and stands.
+ */
+export const varcharCaseSensitive = customType({
+    dataType: (config) => {
+        const len = config?.length ?? 255;
+        return `varchar(${len}) COLLATE utf8mb4_bin`;
+    },
+});
+/**
+ * Audit-timestamp column shape used across every Byline table.
+ * `DATETIME(6)` — microsecond precision, matching the Postgres adapter's
+ * `timestamp(name, { precision: 6, withTimezone: true })` exactly (see
+ * `packages/db-postgres/src/database/schema/common.ts`'s `auditTimestamp`).
+ * MySQL supports fractional seconds 0–6; picking 6 gives this adapter the
+ * same clock resolution as pg rather than a coarser one.
+ *
+ * This was `fsp: 3` (millisecond) originally, rejected only for
+ * `TIMESTAMP`'s 2038 range limit — with no stated rationale for choosing 3
+ * over 6. That turned out to matter: at millisecond resolution, two
+ * statements issued back-to-back on a fast local connection can land in the
+ * same tick and receive an *identical* `CURRENT_TIMESTAMP(3)` value, which
+ * is a real correctness gap for anything that orders or windows by these
+ * columns (found via `packages/db-conformance`'s audit activity-feed
+ * fixture — see docs/09-testing.md and the Task 11 report for the
+ * live-server evidence: four rapid statements produced 2 distinct values at
+ * fsp 3 versus 4 distinct values at fsp 6). Matching pg's precision closes
+ * that gap at the source instead of asking every fixture/consumer to work
+ * around a coarser clock.
+ *
+ * Stored and read as UTC by convention (the mysql2 pool is opened with
+ * `timezone: 'Z'` so values round-trip without local-timezone
+ * reinterpretation). MySQL's `DATETIME` has no timezone-aware storage the
+ * way Postgres's `TIMESTAMPTZ` does, so the UTC discipline is enforced
+ * entirely at the connection layer rather than the column type.
+ *
+ * Defined once here so adding a new column to every table — or changing
+ * the precision across the schema — is a one-line edit.
+ */
+const auditTimestamp = (name) => datetime(name, { fsp: 6 }).notNull().default(sql `CURRENT_TIMESTAMP(6)`);
+/**
+ * Both `created_at` and `updated_at` for tables whose rows are
+ * mutated in place (most application tables — users, roles, documents,
+ * store rows, paths).
+ *
+ * Spread into a `mysqlTable` definition:
+ *
+ *   mysqlTable('byline_admin_users', {
+ *     id: uuidChar('id').primaryKey(),
+ *     ...timestamps,
+ *   })
+ */
+export const timestamps = {
+    created_at: auditTimestamp('created_at'),
+    updated_at: auditTimestamp('updated_at'),
+};
+/**
+ * `created_at` only — for tables whose rows are immutable once
+ * inserted (junction tables like `byline_admin_role_admin_user`,
+ * registry rows like `byline_counter_groups`).
+ *
+ * Spread into a `mysqlTable` definition the same way as `timestamps`.
+ */
+export const createdAt = {
+    created_at: auditTimestamp('created_at'),
+};