@lenne.tech/nest-server 12.1.0 → 12.2.0

package/src/core/modules/better-auth/better-auth-sql.helper.ts

@@ -4,7 +4,7 @@ import { getMigrations } from 'better-auth/db/migration';
 import { DataSourceConfigError } from '../../common/persistence/data-source.config.js';
 import { generateId } from '../../common/persistence/id-format.js';
 import { type IamSqlStorage, registerForeignColumns } from '../../common/persistence/persistence-runtime.registry.js';
-import { columnName, quoteIdentifier } from '../../common/persistence/sql/sql-naming.js';
+import { columnName, quoteIdentifier, quoteMysqlIdentifier } from '../../common/persistence/sql/sql-naming.js';
 
 /** The table Better-Auth shares with the user model — created and owned by the framework */
 const USERS_TABLE = 'users';
@@ -15,15 +15,38 @@ const USERS_TABLE = 'users';
  */
 registerForeignColumns(USERS_TABLE, ['email_verified', 'image', 'name']);
 
-/** Postgres column type of a Better-Auth field, for a column the framework adds before Better-Auth's migration */
-const SQL_TYPES: Record<string, string> = {
-  boolean: 'boolean',
-  date: 'timestamptz',
-  json: 'jsonb',
-  number: 'integer',
-  'number[]': 'jsonb',
-  string: 'text',
-  'string[]': 'jsonb',
+/**
+ * Column type of a Better-Auth field per database, for a column the framework adds before Better-Auth's migration —
+ * the type Better-Auth's own migrator would choose, so it finds nothing to report about the column afterwards
+ */
+const SQL_TYPES: Record<IamSqlStorage['driver'], Record<string, string>> = {
+  mariadb: {
+    boolean: 'boolean',
+    date: 'timestamp(3)',
+    json: 'json',
+    number: 'integer',
+    'number[]': 'json',
+    string: 'text',
+    'string[]': 'json',
+  },
+  mysql: {
+    boolean: 'boolean',
+    date: 'timestamp(3)',
+    json: 'json',
+    number: 'integer',
+    'number[]': 'json',
+    string: 'text',
+    'string[]': 'json',
+  },
+  postgres: {
+    boolean: 'boolean',
+    date: 'timestamptz',
+    json: 'jsonb',
+    number: 'integer',
+    'number[]': 'jsonb',
+    string: 'text',
+    'string[]': 'jsonb',
+  },
 };
 
 /** The tables Better-Auth's own options name (models of plugins come from the plugins) */
@@ -32,8 +55,9 @@ const CORE_MODELS = ['user', 'session', 'account', 'verification'] as const;
 type Options = Record<string, any>;
 
 /**
- * Better-Auth on a SQL data source: its built-in Kysely adapter on the given `pg` pool (Better-Auth recognises the
- * pool and builds its own Kysely instance — the core imports no Kysely), ids in the framework's format, and every table
+ * Better-Auth on a SQL data source: its built-in Kysely adapter on the given pool — `pg`, or on MySQL / MariaDB the
+ * `mysql2` pool's promise wrapper (Better-Auth recognises the pool and builds its own Kysely instance — the core imports
+ * no Kysely), ids in the framework's format, and every table
  * and column named the way the framework names it.
  *
  * Naming is not cosmetic. Better-Auth and the user model share ONE row per user in `users`: the framework creates that
@@ -114,8 +138,10 @@ export function betterAuthOwnedTables(options: Options): string[] {
  * Without an owner connection it only checks, and a pending change stops the boot like a framework table would.
  */
 export async function applyBetterAuthSchema(options: Options, storage: IamSqlStorage): Promise<void> {
-  await storage.applySchema(async (pool, asOwner) => {
-    const nullable = asOwner ? await addRequiredUserColumnsAsNullable(options, pool as PgPool) : new Set<string>();
+  await storage.applySchema(async (pool, asOwner, query) => {
+    const nullable = asOwner
+      ? await addRequiredUserColumnsAsNullable(options, query, storage.driver)
+      : new Set<string>();
     const { runMigrations, toBeAdded, toBeCreated } = await getMigrations({
       ...options,
       database: pool,
@@ -135,10 +161,6 @@ export async function applyBetterAuthSchema(options: Options, storage: IamSqlSto
   }, betterAuthOwnedTables(options));
 }
 
-interface PgPool {
-  query(text: string, params?: unknown[]): Promise<{ rows: any[] }>;
-}
-
 /**
  * A field Better-Auth declares required without a default (`name`) becomes a NOT NULL column when Better-Auth adds it —
  * and every user the FRAMEWORK creates (legacy sign-up, user service, system setup) would then fail to insert, because the
@@ -146,10 +168,19 @@ interface PgPool {
  * first, nullable like every column it creates (the database does not enforce `required`, as on MongoDB); Better-Auth
  * then finds them and adds nothing. Returns every required user column that is nullable by the framework's design.
  */
-async function addRequiredUserColumnsAsNullable(options: Options, pool: PgPool): Promise<Set<string>> {
+export async function addRequiredUserColumnsAsNullable(
+  options: Options,
+  query: IamSqlStorage['query'],
+  driver: IamSqlStorage['driver'],
+): Promise<Set<string>> {
   const users = (getAuthTables(options as any) as Record<string, any>).user;
-  const { rows } = await pool.query(
-    'SELECT column_name FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = $1',
+  const postgres = driver === 'postgres';
+  const quote = postgres ? quoteIdentifier : quoteMysqlIdentifier;
+  const types = SQL_TYPES[driver];
+  const { rows } = await query(
+    postgres
+      ? 'SELECT column_name FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = $1'
+      : 'SELECT COLUMN_NAME AS column_name FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = $1',
     [users.modelName],
   );
   const existing = new Set(rows.map((row) => row.column_name as string));
@@ -161,9 +192,10 @@ async function addRequiredUserColumnsAsNullable(options: Options, pool: PgPool):
     }
     // Every column the framework created for a field is nullable — the user model's `email` and timestamps included
     nullable.add(column);
-    if (field.defaultValue === undefined && !existing.has(column) && SQL_TYPES[field.type]) {
-      await pool.query(
-        `ALTER TABLE ${quoteIdentifier(users.modelName)} ADD COLUMN IF NOT EXISTS ${quoteIdentifier(column)} ${SQL_TYPES[field.type]}`,
+    if (field.defaultValue === undefined && !existing.has(column) && types[field.type]) {
+      // MySQL has no ADD COLUMN IF NOT EXISTS; the catalog read above and the schema lock make it unnecessary
+      await query(
+        `ALTER TABLE ${quote(users.modelName)} ADD COLUMN ${postgres ? 'IF NOT EXISTS ' : ''}${quote(column)} ${types[field.type]}`,
       );
     }
   }

package/src/core/modules/better-auth/better-auth.config.ts

@@ -233,9 +233,10 @@ export interface CreateBetterAuthOptions {
   serverEnv?: string;
 
   /**
-   * The `pg` pool of the SQL data source the `users` table lives in (the application role's pool of the configured
-   * engine). Set, Better-Auth runs its built-in Kysely adapter on it instead of MongoDB, with the framework's ids and
-   * table and column names — see `withSqlStorage()`.
+   * The pool of the SQL data source the `users` table lives in, as `SqlDialect.foreignPool()` hands it out: the
+   * application role's `pg` pool, or on MySQL / MariaDB its `mysql2` pool's promise wrapper. Set, Better-Auth runs its
+   * built-in Kysely adapter on it instead of MongoDB, with the framework's ids and table and column names — see
+   * `withSqlStorage()`.
    */
   sqlPool?: unknown;
 }

package/src/core/modules/better-auth/core-better-auth-sql.store.ts

@@ -1,5 +1,6 @@
 import type { DataStore } from '../../common/persistence/data-store.interface.js';
-import { quoteIdentifier } from '../../common/persistence/sql/sql-naming.js';
+import type { IamSqlStorage } from '../../common/persistence/persistence-runtime.registry.js';
+import { quoteIdentifier, quoteMysqlIdentifier } from '../../common/persistence/sql/sql-naming.js';
 import { RequestContext } from '../../common/services/request-context.service.js';
 import type { BetterAuthInstance } from './better-auth.config.js';
 
@@ -28,10 +29,8 @@ export interface IamMigrationCounts {
   withIamId: number;
 }
 
-/** What the store needs of the `pg` pool Better-Auth runs on */
-export interface IamSqlQueryable {
-  query(text: string, values?: unknown[]): Promise<{ rows: any[] }>;
-}
+/** What the store needs to count in the database Better-Auth runs on: which one it is, and a statement runner */
+export type IamSqlQueryable = Pick<IamSqlStorage, 'driver' | 'query'>;
 
 /** A passkey challenge mapping as `CoreBetterAuthChallengeService` keeps it */
 export interface IamChallengeMapping {
@@ -60,7 +59,7 @@ export class BetterAuthSqlStore {
   constructor(
     readonly users: DataStore<any>,
     protected readonly auth: BetterAuthInstance,
-    protected readonly pool?: IamSqlQueryable,
+    protected readonly sql?: IamSqlQueryable,
   ) {}
 
   // ---------------------------------------------------------------------------------------------
@@ -144,39 +143,47 @@ export class BetterAuthSqlStore {
    * The IAM migration counts, computed in the database over every user and account — the definitions of the MongoDB
    * aggregation (`CoreBetterAuthUserMapper.getMigrationStatus()`). Never a page of rows: Better-Auth's `findMany()`
    * stops at 100 without a limit, which capped the status at 100 migrated users. Table and column names come from
-   * Better-Auth's own schema, so they follow what `withSqlStorage()` mapped.
+   * Better-Auth's own schema, so they follow what `withSqlStorage()` mapped. The same statements on every SQL database,
+   * only the identifier quotes differ; counts are converted here because MySQL answers them as strings.
    */
   async migrationCounts(pendingEmailLimit: number): Promise<IamMigrationCounts> {
-    if (!this.pool) {
-      throw new Error('BetterAuthSqlStore: migration counts need the pool Better-Auth runs on');
+    if (!this.sql) {
+      throw new Error('BetterAuthSqlStore: migration counts need the database Better-Auth runs on');
     }
+    const quote = this.sql.driver === 'postgres' ? quoteIdentifier : quoteMysqlIdentifier;
     const { tables } = await this.context();
-    const table = (model: string) => quoteIdentifier(tables[model].modelName);
-    const column = (model: string, field: string) => quoteIdentifier(tables[model].fields[field]?.fieldName ?? field);
+    const table = (model: string) => quote(tables[model].modelName);
+    const column = (model: string, field: string) => quote(tables[model].fields[field]?.fieldName ?? field);
     const users = table('user');
     const accounts = table('account');
     const iamId = column('user', 'iamId');
     const userId = column('account', 'userId');
     const providerId = column('account', 'providerId');
-    const migrated = `EXISTS (SELECT 1 FROM ${accounts} a WHERE a.${userId} = u."id" AND a.${providerId} = $1)`;
+    const migrated = `EXISTS (SELECT 1 FROM ${accounts} a WHERE a.${userId} = u.${quote('id')} AND a.${providerId} = $1)`;
     const {
       rows: [counts],
-    } = await this.pool.query(
-      `SELECT (SELECT count(*) FROM ${users})::int AS "total",
-              (SELECT count(*) FROM ${users} WHERE ${iamId} IS NOT NULL)::int AS "withIamId",
-              (SELECT count(DISTINCT ${userId}) FROM ${accounts} WHERE ${providerId} = $1)::int AS "withIamAccount",
-              (SELECT count(*) FROM ${users} u WHERE u.${iamId} IS NOT NULL AND ${migrated})::int AS "fullyMigrated"`,
+    } = await this.sql.query(
+      `SELECT (SELECT count(*) FROM ${users}) AS ${quote('total')},
+              (SELECT count(*) FROM ${users} WHERE ${iamId} IS NOT NULL) AS ${quote('withIamId')},
+              (SELECT count(DISTINCT ${userId}) FROM ${accounts} WHERE ${providerId} = $1) AS ${quote('withIamAccount')},
+              (SELECT count(*) FROM ${users} u WHERE u.${iamId} IS NOT NULL AND ${migrated}) AS ${quote('fullyMigrated')}`,
       ['credential'],
     );
     const pending =
       pendingEmailLimit > 0
-        ? await this.pool.query(
-            `SELECT u.${column('user', 'email')} AS "email" FROM ${users} u
-              WHERE u.${iamId} IS NULL OR NOT ${migrated} ORDER BY u."id" LIMIT $2`,
+        ? await this.sql.query(
+            `SELECT u.${column('user', 'email')} AS ${quote('email')} FROM ${users} u
+              WHERE u.${iamId} IS NULL OR NOT ${migrated} ORDER BY u.${quote('id')} LIMIT $2`,
             ['credential', pendingEmailLimit],
           )
         : { rows: [] };
-    return { ...counts, pendingEmails: pending.rows.map((row) => row.email).filter(Boolean) };
+    return {
+      fullyMigrated: Number(counts.fullyMigrated),
+      pendingEmails: pending.rows.map((row) => row.email).filter(Boolean),
+      total: Number(counts.total),
+      withIamAccount: Number(counts.withIamAccount),
+      withIamId: Number(counts.withIamId),
+    };
   }
 
   /** A session by its token with its user; `null` when unknown — expiry is the caller's check, as on MongoDB */

package/src/core/modules/better-auth/core-better-auth-user.mapper.ts

@@ -1,4 +1,4 @@
-import { Injectable, Logger, Optional } from '@nestjs/common';
+import { Injectable, Logger, OnApplicationBootstrap, OnModuleDestroy, Optional } from '@nestjs/common';
 import { InjectConnection } from '../../common/persistence/mongo/mongoose-compat.js';
 import * as bcrypt from 'bcrypt';
 import { randomBytes, scrypt, ScryptOptions } from 'crypto';
@@ -17,7 +17,9 @@ const scryptPromise = (password: string, salt: string, keylen: number, options:
 };
 
 import { RoleEnum } from '../../common/enums/role.enum.js';
+import { revalidateWsConnectionsOf } from '../../common/helpers/graphql-ws-connection.helper.js';
 import { maskEmail } from '../../common/helpers/logging.helper.js';
+import { CoreRedisService } from '../../common/services/core-redis.service.js';
 import { legacyCredentialAccountIssuer } from './core-better-auth-account-issuer.helper.js';
 import { getBetterAuthSqlStore } from './core-better-auth-sql.registry.js';
 import type { BetterAuthSqlStore } from './core-better-auth-sql.store.js';
@@ -139,13 +141,15 @@ function isClosedConnectionError(error: unknown): boolean {
 }
 
 @Injectable()
-export class CoreBetterAuthUserMapper {
+export class CoreBetterAuthUserMapper implements OnApplicationBootstrap, OnModuleDestroy {
   private readonly logger = new Logger(CoreBetterAuthUserMapper.name);
 
   /**
    * Lightweight TTL cache for user DB lookups.
    * Key: iamId (BetterAuth user ID), Value: minimal user data (id, roles, verified).
    * Only caches ~100 bytes per entry (no full documents). Max 500 entries = ~50KB.
+   *
+   * With `redis` configured, {@link invalidateUserCache} reaches the cache of every replica; without it, only this one.
    */
   private readonly userCache = new Map<string, CachedUserData>();
   private static readonly USER_CACHE_MAX = 500;
@@ -167,7 +171,64 @@ export class CoreBetterAuthUserMapper {
       ? 0
       : 15_000;
 
-  constructor(@Optional() @InjectConnection() private readonly connection?: Connection) {}
+  /**
+   * How long a user's roles and verification state are answered from the cache, in ms. `0` switches the cache off.
+   * Defaults to {@link USER_CACHE_TTL_MS}; a subclass may set another value.
+   */
+  protected userCacheTtlMs = CoreBetterAuthUserMapper.USER_CACHE_TTL_MS;
+
+  /** The listener on the shared subscriber connection, kept to detach it again in {@link onModuleDestroy}. */
+  private invalidationListener?: (channel: string, message: string) => void;
+
+  constructor(
+    @Optional() @InjectConnection() private readonly connection?: Connection,
+    @Optional() protected readonly redisService?: CoreRedisService,
+  ) {}
+
+  /**
+   * Subscribe to the cache invalidations of the other replicas. Runs after every `onModuleInit`, so the Redis service is
+   * connected. A no-op without `redis`.
+   */
+  async onApplicationBootstrap(): Promise<void> {
+    if (!this.redisService?.enabled) {
+      return;
+    }
+    const channel = this.invalidationChannel(this.redisService);
+    try {
+      // Held in a field: the subscriber connection is shared between features, so a listener that is never detached
+      // keeps clearing a destroyed mapper's cache for the life of the process.
+      this.invalidationListener = (incomingChannel: string, message: string) => {
+        if (incomingChannel === channel) {
+          this.applyInvalidation(message);
+        }
+      };
+      this.redisService.getSubscriber().on('message', this.invalidationListener);
+      // Registered with the Redis service, so the subscription is established again after every reconnect — also when
+      // this first attempt fails because Redis is down at boot.
+      await this.redisService.subscribeChannel(channel);
+    } catch (error) {
+      this.logger.warn(
+        `IAM user cache invalidation subscribe failed: ${(error as Error).message}. Retried when the Redis connection ` +
+          'is up; until then a role or verification change made on another replica reaches this one only when its ' +
+          'cache entry expires and at the next periodic WebSocket re-check.',
+      );
+    }
+  }
+
+  onModuleDestroy(): void {
+    if (!this.invalidationListener) {
+      return;
+    }
+    try {
+      if (this.redisService) {
+        this.redisService.getSubscriber().off('message', this.invalidationListener);
+        void this.redisService.releaseChannel(this.invalidationChannel(this.redisService)).catch(() => undefined);
+      }
+    } catch {
+      // Redis already gone — nothing to detach from
+    }
+    this.invalidationListener = undefined;
+  }
 
   /**
    * Maps a Better-Auth session user to a user with role capabilities
@@ -203,7 +264,7 @@ export class CoreBetterAuthUserMapper {
 
     try {
       // Check lightweight cache first (only stores id, roles, verified — ~100 bytes per entry)
-      const ttl = CoreBetterAuthUserMapper.USER_CACHE_TTL_MS;
+      const ttl = this.userCacheTtlMs;
       const now = Date.now();
       const cached = ttl > 0 ? this.userCache.get(sessionUser.id) : undefined;
       if (cached && now < cached.expiresAt) {
@@ -235,7 +296,7 @@ export class CoreBetterAuthUserMapper {
         const verified = dbUser.verified === true || sessionUser.emailVerified === true;
 
         // Cache only the minimal data needed (not the full document)
-        if (CoreBetterAuthUserMapper.USER_CACHE_TTL_MS > 0) {
+        if (this.userCacheTtlMs > 0) {
           this.cacheUserData(sessionUser.id, { id: String(dbUser._id ?? dbUser.id), roles, verified });
         }
 
@@ -316,7 +377,7 @@ export class CoreBetterAuthUserMapper {
     }
     this.userCache.set(iamId, {
       ...data,
-      expiresAt: Date.now() + CoreBetterAuthUserMapper.USER_CACHE_TTL_MS,
+      expiresAt: Date.now() + this.userCacheTtlMs,
     });
   }
 
@@ -324,10 +385,65 @@ export class CoreBetterAuthUserMapper {
    * Invalidate cached user data. Call when user roles or verified status change.
    * Called automatically from `CoreUserService.setRoles()` and `CoreUserService.update()`.
    *
+   * With `redis` configured, the invalidation is broadcast to every replica, which also re-checks the user's open
+   * GraphQL WebSockets — otherwise a withdrawn role would keep working there until the cache entry expires.
+   *
    * @param iamId - The BetterAuth user ID (from session/account, not MongoDB _id)
    */
   invalidateUserCache(iamId: string): void {
     this.userCache.delete(iamId);
+    this.publishInvalidation(iamId);
+  }
+
+  /**
+   * Apply an invalidation received from a replica (this one included — it is subscribed to its own broadcasts). Clears
+   * locally only: re-publishing would bounce the message around the cluster.
+   */
+  protected applyInvalidation(message: string): void {
+    let iamId: unknown;
+    try {
+      iamId = JSON.parse(message)?.iamId;
+    } catch {
+      iamId = undefined;
+    }
+    if (typeof iamId !== 'string' || !iamId) {
+      this.logger.debug(`Ignoring malformed IAM user cache invalidation message: ${message}`);
+      return;
+    }
+    this.userCache.delete(iamId);
+    // The replica that changed the user re-checks its own sockets; these are the ones on this replica. After the cache
+    // above, so the re-check reads the user as they are now.
+    revalidateWsConnectionsOf({ iamId });
+  }
+
+  /**
+   * Broadcast an invalidation to the other replicas (fire-and-forget). A no-op without `redis`.
+   *
+   * A failure is logged as a warning, not swallowed: until the entry expires on the other replicas, a withdrawn role
+   * keeps working there.
+   */
+  protected publishInvalidation(iamId: string): void {
+    const redisService = this.redisService;
+    if (!redisService?.enabled) {
+      return;
+    }
+    const warn = (error: Error) =>
+      this.logger.warn(
+        `IAM user cache invalidation could not be broadcast: ${error.message}. Other replicas keep the previous roles ` +
+          'until their cache entry expires, and their open WebSockets until the next periodic re-check.',
+      );
+    try {
+      void redisService
+        .getClient()
+        .publish(this.invalidationChannel(redisService), JSON.stringify({ iamId }))
+        .catch(warn);
+    } catch (error) {
+      warn(error as Error);
+    }
+  }
+
+  private invalidationChannel(redisService: CoreRedisService): string {
+    return redisService.key('iam-user-cache', 'invalidate');
   }
 
   // ===================================================================================================================

package/src/core/modules/better-auth/core-better-auth.module.ts

@@ -34,7 +34,7 @@ import {
 } from './better-auth.config.js';
 import { applyBetterAuthSchema } from './better-auth-sql.helper.js';
 import { getBetterAuthSqlStore, setBetterAuthSqlStore } from './core-better-auth-sql.registry.js';
-import { BetterAuthSqlStore, type IamSqlQueryable } from './core-better-auth-sql.store.js';
+import { BetterAuthSqlStore } from './core-better-auth-sql.store.js';
 import { DefaultBetterAuthResolver } from './better-auth.resolver.js';
 import { CoreBetterAuthApiMiddleware } from './core-better-auth-api.middleware.js';
 import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service.js';
@@ -490,7 +490,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     }
     const result = instantiateBetterAuth(built);
     if (storage) {
-      setBetterAuthSqlStore(new BetterAuthSqlStore(storage.users, result.instance, storage.pool as IamSqlQueryable));
+      setBetterAuthSqlStore(new BetterAuthSqlStore(storage.users, result.instance, storage));
     }
     return result;
   }

package/src/core/modules/error-code/error-codes.ts

@@ -22,6 +22,7 @@
  * - LTNS_0400-LTNS_0499: Resource errors
  * - LTNS_0500-LTNS_0599: File errors
  * - LTNS_0600-LTNS_0699: AI errors
+ * - LTNS_0700-LTNS_0799: Offline sync errors
  * - LTNS_0900-LTNS_0999: Internal errors
  *
  * @example
@@ -515,6 +516,15 @@ export const LtnsErrors = {
     },
   },
 
+  VERSION_CONFLICT: {
+    code: 'LTNS_0402',
+    message: 'Version conflict',
+    translations: {
+      de: 'Der Datensatz wurde inzwischen geändert.',
+      en: 'The record was changed in the meantime.',
+    },
+  },
+
   // =====================================================
   // File Errors (LTNS_0500-LTNS_0599)
   // =====================================================
@@ -702,6 +712,55 @@ export const LtnsErrors = {
       en: 'The AI connection has no valid base URL.',
     },
   },
+
+  // =====================================================
+  // Offline Sync Errors (LTNS_0700-LTNS_0799)
+  // =====================================================
+
+  SYNC_RESYNC_REQUIRED: {
+    code: 'LTNS_0700',
+    message: 'Resync required',
+    translations: {
+      de: 'Die lokalen Daten müssen vollständig neu geladen werden.',
+      en: 'The local data must be loaded again in full.',
+    },
+  },
+
+  SYNC_MODEL_NOT_FOUND: {
+    code: 'LTNS_0701',
+    message: 'Model is not available for sync',
+    translations: {
+      de: 'Diese Daten können nicht synchronisiert werden.',
+      en: 'This data cannot be synchronized.',
+    },
+  },
+
+  SYNC_INVALID_REQUEST: {
+    code: 'LTNS_0702',
+    message: 'Invalid sync request',
+    translations: {
+      de: 'Die Synchronisierungsanfrage ist ungültig.',
+      en: 'The synchronization request is invalid.',
+    },
+  },
+
+  SYNC_ORIGIN_REFUSED: {
+    code: 'LTNS_0703',
+    message: 'Origin not allowed for this request',
+    translations: {
+      de: 'Diese Anfrage ist von dieser Seite aus nicht erlaubt.',
+      en: 'This request is not allowed from this site.',
+    },
+  },
+
+  SYNC_STORE_UNAVAILABLE: {
+    code: 'LTNS_0704',
+    message: 'Sync store unavailable',
+    translations: {
+      de: 'Die Synchronisierung ist gerade nicht verfügbar. Bitte später erneut versuchen.',
+      en: 'Synchronization is unavailable right now. Please try again later.',
+    },
+  },
 } as const satisfies IErrorRegistry;
 
 // =====================================================

package/src/core/modules/hub/README.md

@@ -196,8 +196,11 @@ shows the merged cluster-wide view and "clear" clears it everywhere. Sequence nu
 from a shared counter, so the panels' cursor-based polling keeps working across replicas.
 
 Writes are fire-and-forget — the collectors sit in hot paths and their API stays synchronous.
-If Redis is unreachable a read silently falls back to the local buffer (a diagnostics panel
-must not be the thing that breaks), so a partial view during an outage is expected.
+If Redis is unreachable a read answers with the client's cursor and no entries (a diagnostics
+panel must not be the thing that breaks), so the panels show nothing new during an outage, and
+the first poll after it delivers what was missed. Until 12.1.0 the read fell back to the local
+buffer, whose sequence numbers count per replica: the next poll after the outage then repeated
+or skipped entries.
 
 #### Cost: Redis write volume scales with your traffic
 

package/src/core/modules/hub/hub-buffer.ts

@@ -48,7 +48,8 @@ const SHARED_READ_CHUNK = 64;
  *
  * **Writes are fire-and-forget.** The collectors sit in hot paths (every log line, every
  * request) and their API towards callers must stay synchronous. A Redis failure is logged at
- * debug level; reads then fall back to the local buffer rather than failing the panel.
+ * debug level; a read then answers with the client's cursor and no entries rather than failing
+ * the panel, and the next successful poll delivers what was missed.
  */
 export class HubBuffer<T extends HubBufferEntry> {
   protected readonly listKey: string;
@@ -116,11 +117,16 @@ export class HubBuffer<T extends HubBufferEntry> {
     }
   }
 
-  /** Entries oldest→newest, optionally only those newer than `since`. */
+  /**
+   * Entries oldest→newest, optionally only those newer than `since`.
+   *
+   * When the shared read fails, the answer keeps the client's cursor and carries no entries. The
+   * local buffer is no fallback there: its seq counts on this replica's own scale, and handing out
+   * its cursor made the next successful poll repeat or skip entries (DEV-3897).
+   */
   async read(since?: number, limit?: number): Promise<HubBufferData<T>> {
-    const shared = this.redis ? await this.readShared(since, limit) : undefined;
-    if (shared) {
-      return shared;
+    if (this.redis) {
+      return (await this.readShared(since, limit)) ?? { cursor: since ?? -1, dropped: -1, entries: [] };
     }
     return {
       cursor: this.local.lastSeq,
@@ -130,7 +136,7 @@ export class HubBuffer<T extends HubBufferEntry> {
   }
 
   /**
-   * Read the shared list, or undefined when Redis is unreachable (caller falls back to local).
+   * Read the shared list, or undefined when Redis is unreachable.
    *
    * The list is newest-first, so the entry with seq `s` sits at index `total - 1 - s` and the
    * entries a client with cursor `since` still needs are exactly the first `total - 1 - since`.
@@ -167,7 +173,7 @@ export class HubBuffer<T extends HubBufferEntry> {
       }
     } catch (err) {
       // console, NOT Logger — same re-entrancy as in mirror() above
-      console.debug(`Hub buffer read failed (${this.listKey}), using the local buffer: ${(err as Error).message}`);
+      console.debug(`Hub buffer read failed (${this.listKey}): ${(err as Error).message}`);
       return undefined;
     }
   }

package/src/core/modules/migrate/README.md

@@ -126,17 +126,21 @@ const migrationOptions = {
   migrationsDirectory: './migrations',
 };
 
-// Custom migration logic
+// Run all pending migrations: a MigrationRunner under the lock
+await synchronizedUp(migrationOptions);
+
+// Or custom logic under the same lock. `migrationSet` is the loaded state (`lastRun`, `migrations`), not something
+// that runs migrations
 await synchronizedMigration(migrationOptions, async (migrationSet) => {
   // Only one instance at a time will execute this code
-  console.log('Running migrations...');
-  await promisify(migrationSet.up).call(migrationSet);
+  // `migrations` is absent until the first migration was recorded
+  console.log(`${migrationSet.migrations?.length ?? 0} migration(s) recorded`);
 });
-
-// Or use the convenience function to run all pending migrations
-await synchronizedUp(migrationOptions);
 ```
 
+`synchronizedUp()` threw on every call until 12.1.0 (it called `up` on the loaded state, which has none). Since 12.1.1
+it runs the `MigrationRunner` — the same runner as `migrate up` — under the lock.
+
 ### SQL migrations (PostgreSQL data sources)
 
 On a PostgreSQL source the framework migrates the schema itself at boot (new tables, columns, declared renames,
@@ -257,10 +261,16 @@ async function synchronizedMigration(
 
 #### synchronizedUp
 
-Convenience function that executes all pending migrations in a synchronized manner.
+Executes all pending migrations in a synchronized manner: a `MigrationRunner` under the state store's lock. Refuses a
+`MongoStateStore` without `lockCollectionName` instead of running unsynchronized.
 
 ```typescript
-async function synchronizedUp(opts: MigrationOptions): Promise<void>;
+interface SynchronizedUpOptions extends MigrationOptions {
+  migrationsDirectory?: string; // default: `migrations` in the working directory, as for the `migrate` CLI
+  pattern?: RegExp; // default: `*.ts` and `*.js`, never `*.d.ts`
+}
+
+async function synchronizedUp(opts: SynchronizedUpOptions): Promise<void>;
 ```
 
 ## How It Works
@@ -589,9 +599,8 @@ are **not** re-run after the switch, and no state rewrite is needed. If both `fo
 `foo.js` are present in the migrations directory (e.g. an overlapping `outDir`), they count
 as ONE migration: only the `.js` file is loaded and executed, and a warning is emitted.
 
-Note: identity normalization applies to the `MigrationRunner`/CLI path only. The legacy
-`synchronizedUp()` helper drives the external `migrate` package's own state handling and
-keeps raw-filename identity.
+Identity normalization applies to every path that runs migrations: the `MigrationRunner`, the CLI and, since 12.1.1,
+`synchronizedUp()`, which runs the `MigrationRunner`.
 
 ### Missing migration files & strict mode
 

package/src/core/modules/migrate/index.ts

@@ -21,6 +21,7 @@
  *
  * // Using synchronized migration for clustered environments
  * await synchronizedUp({
+ *   migrationsDirectory: './migrations',
  *   stateStore: new MongoStateStore({
  *     uri: 'mongodb://localhost/mydb',
  *     lockCollectionName: 'migration_lock'