@lenne.tech/nest-server 12.1.0 → 12.2.0

package/src/core/modules/migrate/migration-runner.ts

@@ -3,7 +3,7 @@ import * as path from 'path';
 
 import { _endMigration, _startMigration } from './migration.helper.js';
 import type { MigrationStateStore } from './migration-state-store.interface.js';
-import { withMigrationLock } from './mongo-state-store.js';
+import { type MigrationOptions, MongoStateStore, withMigrationLock } from './mongo-state-store.js';
 import { createRequire } from 'node:module';
 
 /**
@@ -94,7 +94,7 @@ export function parseStrictEnv(value: string | undefined = process.env.NSC__MIGR
  * Migration runner configuration
  */
 export interface MigrationRunnerOptions {
-  /** Directory containing migration files */
+  /** Directory containing migration files, absolute or relative to the working directory */
   migrationsDirectory: string;
   /** Pattern to match migration files (default: {@link DEFAULT_MIGRATION_FILE_PATTERN}) */
   pattern?: RegExp;
@@ -148,7 +148,13 @@ export class MigrationRunner {
   constructor(options: MigrationRunnerOptions) {
     // Resolve the strict default from the environment so NSC__MIGRATE__STRICT works
     // identically for programmatic runners and the CLI (which parses it itself).
-    this.options = { ...options, strict: options.strict ?? parseStrictEnv() };
+    // A relative directory is resolved against the working directory, as by the CLI: the files are
+    // loaded with require(), which reads `migrations/<file>` as a package name (DEV-3897).
+    this.options = {
+      ...options,
+      migrationsDirectory: path.resolve(options.migrationsDirectory),
+      strict: options.strict ?? parseStrictEnv(),
+    };
     this.pattern = options.pattern || DEFAULT_MIGRATION_FILE_PATTERN;
   }
 
@@ -413,3 +419,62 @@ export const down = async () => {
     return filePath;
   }
 }
+
+/**
+ * Options of {@link synchronizedUp}
+ */
+export interface SynchronizedUpOptions extends MigrationOptions {
+  /** Directory containing migration files (default: `migrations` in the working directory, as for the `migrate` CLI) */
+  migrationsDirectory?: string;
+  /** Pattern to match migration files (default: {@link DEFAULT_MIGRATION_FILE_PATTERN}) */
+  pattern?: RegExp;
+}
+
+/**
+ * Executes all pending migrations in a synchronized manner (for clustered environments)
+ *
+ * Runs a {@link MigrationRunner} under the state store's lock. Unlike `MigrationRunner.up()`, it refuses a store that
+ * cannot be locked — a `MongoStateStore` without `lockCollectionName` — instead of running unsynchronized. Until
+ * 12.1.0 it called `up` on the loaded migration state, which has none, and threw on every call (DEV-3897).
+ *
+ * @param opts - State store, plus the migrations directory and file pattern of the runner
+ * @throws Error if the state store cannot be locked
+ *
+ * @example
+ * ```typescript
+ * await synchronizedUp({
+ *   migrationsDirectory: './migrations',
+ *   stateStore: new MongoStateStore({
+ *     uri: 'mongodb://localhost/db',
+ *     lockCollectionName: 'migrationlock'
+ *   })
+ * });
+ * ```
+ */
+export async function synchronizedUp(opts: SynchronizedUpOptions): Promise<void> {
+  assertLockableStore(opts?.stateStore);
+  await new MigrationRunner({
+    migrationsDirectory: opts.migrationsDirectory ?? 'migrations',
+    pattern: opts.pattern,
+    stateStore: opts.stateStore,
+  }).up();
+}
+
+/**
+ * The checks of `synchronizedMigration()`: a store that brings its own lock, or a `MongoStateStore` with a lock
+ * collection
+ */
+function assertLockableStore(stateStore: MigrationStateStore | undefined): void {
+  if (!stateStore) {
+    throw new Error('No `stateStore` in migration options');
+  }
+  if (!(stateStore instanceof MongoStateStore)) {
+    if (typeof stateStore.withLock !== 'function') {
+      throw new Error('Given `stateStore` is not `MongoStateStore`');
+    }
+    return;
+  }
+  if (typeof stateStore.lockCollectionName !== 'string') {
+    throw new Error('`lockCollectionName` in MongoStateStore is not set');
+  }
+}

package/src/core/modules/migrate/mongo-state-store.ts

@@ -30,9 +30,8 @@ export interface MongoStateStoreOptions {
   /**
    * Optionally specify a collection to use for locking. This is intended for
    * clusters with multiple nodes to ensure that not more than one migration
-   * can run at any given time. You must use the `synchronizedMigration` or
-   * `synchronizedUp` function, instead of triggering the migration via
-   * `migrate` directly.
+   * can run at any given time. The `migrate` CLI, `MigrationRunner`,
+   * `synchronizedUp()` and `synchronizedMigration()` all hold this lock.
    */
   lockCollectionName?: string;
   /** MongoDB connection URI */
@@ -158,8 +157,11 @@ export class MongoStateStore implements MigrationStateStore {
  *     lockCollectionName: 'migrationlock'
  *   })
  * }, async (migrationSet) => {
- *   // Only one instance at a time will execute this
- *   await promisify(migrationSet.up).call(migrationSet);
+ *   // Only one instance at a time will execute this. `migrationSet` is the loaded state
+ *   // (`lastRun`, `migrations`); to run the pending migrations use `synchronizedUp()`.
+ *   if (!migrationSet.migrations?.some((m) => m.title === 'seed-defaults')) {
+ *     await seedDefaults();
+ *   }
  * });
  * ```
  */
@@ -206,31 +208,6 @@ export async function synchronizedMigration(
   }
 }
 
-/**
- * Executes all pending migrations in a synchronized manner (for clustered environments)
- *
- * This is a convenience function that wraps `synchronizedMigration` and automatically
- * calls the `up` method on the migration set.
- *
- * @param opts - Migration options including state store
- * @throws Error if state store is not configured correctly
- *
- * @example
- * ```typescript
- * await synchronizedUp({
- *   stateStore: new MongoStateStore({
- *     uri: 'mongodb://localhost/db',
- *     lockCollectionName: 'migrationlock'
- *   })
- * });
- * ```
- */
-export async function synchronizedUp(opts: MigrationOptions): Promise<void> {
-  await synchronizedMigration(opts, async (loadedSet) => {
-    await promisify(loadedSet.up).call(loadedSet);
-  });
-}
-
 /**
  * Runs `fn` while holding the migration lock of the given state store
  *

package/src/core/modules/migrate/sql-migration.helper.ts

@@ -1,13 +1,44 @@
 import type { DatabaseSqlEngine } from '../../common/interfaces/server-options.interface.js';
 import { withMysqlSchemaLock } from '../../common/persistence/sql/mysql/mysql-schema.migrator.js';
+import { MYSQL_SYNC_COUNTERS } from '../../common/persistence/sql/mysql/mysql-schema.compiler.js';
+import { syncSequenceName } from '../../common/persistence/sql/postgres/postgres-schema.compiler.js';
 import { SCHEMA_LOCK_SQL } from '../../common/persistence/sql/postgres/postgres-schema.migrator.js';
 import { createSqlExecutor } from '../../common/persistence/sql/sql-executor.factory.js';
+import { quoteIdentifier, quoteMysqlIdentifier } from '../../common/persistence/sql/sql-naming.js';
+
+/**
+ * A data migration's multi-row write on the table of a synchronized model, numbered the way the store numbers it (plan
+ * §3.4, C1d): the rows are locked first (`SELECT … FOR UPDATE`), then the change numbers taken, then the rows written
+ * with their numbers set and their `version` incremented. "Rows first, counter last" is what keeps the migration from
+ * deadlocking with a running application's writes on MySQL and MariaDB, whose row locks also lock index gaps; the
+ * incremented version turns the change into a conflict for a client that edited the old one, never a silent overwrite.
+ * Clients receive the rows at their next pull, like any change.
+ *
+ * `set` and `where` are SQL, reviewed like every statement of the migration — never built from request data.
+ */
+export interface SqlSyncUpdate {
+  syncUpdate: {
+    /** Assignments without `SET`, e.g. `"status" = 'archived'` (never `version` or `sync_seq`, both set here) */
+    set: string;
+    /** The table of the synchronized model, e.g. `sync_notes` */
+    table: string;
+    /** The rows to write, a condition without `WHERE` */
+    where: string;
+  };
+}
+
+/** How a migration statement runs: on the migration's connection, inside its transaction where there is one */
+export type SqlMigrationRun = (statement: { params: unknown[]; text: string }) => Promise<{ rows: any[] }>;
+
+/** Rows written per statement */
+const SYNC_UPDATE_CHUNK = 500;
 
 /**
  * Run the reviewed statements of a SQL migration (`migrate create <name> --sql`) as the table OWNER, under the lock the
  * boot's schema migration takes, so a replica booting meanwhile waits and then sees the result. On PostgreSQL in one
  * transaction: either every statement applies or none does. MySQL and MariaDB commit every DDL statement on its own, so
- * there a failure leaves the statements before it applied — write such a migration so it can run again.
+ * there a failure leaves the statements before it applied — write such a migration so it can run again. A `syncUpdate`
+ * runs in a transaction of its own there, because a DDL statement before it has ended the migration's.
  *
  * The statements are the ones a refused boot suggested (`SchemaMigrationRequiredError`) — after review: a narrowed
  * type, a new unique index or a rename collision can reject or rewrite stored rows, which is why the framework never
@@ -15,7 +46,7 @@ import { createSqlExecutor } from '../../common/persistence/sql/sql-executor.fac
  */
 export async function runSqlMigration(
   ownerUrl: string,
-  statements: readonly string[],
+  statements: readonly (SqlSyncUpdate | string)[],
   options: { engine?: DatabaseSqlEngine } = {},
 ): Promise<void> {
   if (!ownerUrl) {
@@ -30,19 +61,122 @@ export async function runSqlMigration(
   try {
     if (/^(mysql|mariadb):/i.test(ownerUrl)) {
       await withMysqlSchemaLock(executor, async (run) => {
-        for (const text of statements) {
-          await run({ params: [], text });
+        for (const statement of statements) {
+          await (typeof statement === 'string'
+            ? run({ params: [], text: statement })
+            : applySqlSyncUpdate(run, 'mysql', statement.syncUpdate));
         }
       });
       return;
     }
     await executor.transaction(async (tx) => {
-      await tx.run({ params: [], text: SCHEMA_LOCK_SQL }, { kind: 'system' });
-      for (const text of statements) {
-        await tx.run({ params: [], text }, { kind: 'system' });
+      const run: SqlMigrationRun = (statement) => tx.run(statement, { kind: 'system' });
+      await run({ params: [], text: SCHEMA_LOCK_SQL });
+      for (const statement of statements) {
+        await (typeof statement === 'string'
+          ? run({ params: [], text: statement })
+          : applySqlSyncUpdate(run, 'postgres', statement.syncUpdate));
       }
     });
   } finally {
     await executor.close();
   }
 }
+
+/**
+ * One `syncUpdate` of a migration: rows locked, numbers taken, rows written, in one transaction — the migration's on
+ * PostgreSQL. On MySQL / MariaDB in a transaction of its own: a DDL statement earlier in the migration committed the
+ * migration's transaction implicitly, and in autocommit every statement would release its locks at once — a running
+ * application could then commit a higher number before these rows (a client's cursor passes them for good) or read the
+ * counter between the increment and the read here (one number twice). Answers the number of rows written.
+ */
+export async function applySqlSyncUpdate(
+  run: SqlMigrationRun,
+  dialect: 'mysql' | 'postgres',
+  update: SqlSyncUpdate['syncUpdate'],
+): Promise<number> {
+  if (dialect === 'postgres') {
+    return writeSyncUpdate(run, dialect, update);
+  }
+  await run({ params: [], text: 'START TRANSACTION' });
+  try {
+    const written = await writeSyncUpdate(run, dialect, update);
+    await run({ params: [], text: 'COMMIT' });
+    return written;
+  } catch (error) {
+    await run({ params: [], text: 'ROLLBACK' }).catch(() => undefined);
+    throw error;
+  }
+}
+
+async function writeSyncUpdate(
+  run: SqlMigrationRun,
+  dialect: 'mysql' | 'postgres',
+  update: SqlSyncUpdate['syncUpdate'],
+): Promise<number> {
+  const quote = dialect === 'mysql' ? quoteMysqlIdentifier : quoteIdentifier;
+  const table = quote(update.table);
+  const id = quote('id');
+  const { rows } = await run({
+    params: [],
+    text: `SELECT ${id} AS id FROM ${table} WHERE ${update.where} ORDER BY ${id} FOR UPDATE`,
+  });
+  const ids = rows.map((row) => String(row.id));
+  if (!ids.length) {
+    return 0;
+  }
+  const numbers =
+    dialect === 'mysql'
+      ? await mysqlNumbers(run, update.table, ids.length)
+      : await postgresNumbers(run, update.table, ids.length);
+  const bigint = dialect === 'mysql' ? '' : '::bigint';
+  for (let start = 0; start < ids.length; start += SYNC_UPDATE_CHUNK) {
+    const chunk = ids.slice(start, start + SYNC_UPDATE_CHUNK);
+    const params: unknown[] = [];
+    const param = (value: unknown) => {
+      params.push(value);
+      return `$${params.length}`;
+    };
+    const cases = chunk
+      .map((row, index) => `WHEN ${param(row)} THEN ${param(numbers[start + index])}${bigint}`)
+      .join(' ');
+    const list = chunk.map((row) => param(row)).join(', ');
+    await run({
+      params,
+      text:
+        `UPDATE ${table} SET ${update.set}, ${quote('version')} = ${quote('version')} + 1, ` +
+        `${quote('sync_seq')} = CASE ${id} ${cases} END WHERE ${id} IN (${list})`,
+    });
+  }
+  return ids.length;
+}
+
+/** The next change numbers of a table on PostgreSQL, as the store takes them (advisory lock, then the sequence) */
+async function postgresNumbers(run: SqlMigrationRun, table: string, count: number): Promise<string[]> {
+  await run({
+    params: [table],
+    text: `SELECT pg_advisory_xact_lock(hashtext('lenne.tech:sync:' || current_schema() || '.' || $1))`,
+  });
+  const { rows } = await run({
+    params: [syncSequenceName(table), count],
+    text: `SELECT nextval(format('%I.%I', current_schema(), $1::text)::regclass)::text AS n FROM generate_series(1, $2::int)`,
+  });
+  return rows.map((row) => String(row.n)).sort((a, b) => (BigInt(a) < BigInt(b) ? -1 : 1));
+}
+
+/** The next change numbers of a table on MySQL / MariaDB, as the store takes them (the counter row, last) */
+async function mysqlNumbers(run: SqlMigrationRun, table: string, count: number): Promise<string[]> {
+  await run({
+    params: [count, table],
+    text: `UPDATE ${quoteMysqlIdentifier(MYSQL_SYNC_COUNTERS)} SET \`seq\` = \`seq\` + $1 WHERE \`model\` = $2`,
+  });
+  const { rows } = await run({
+    params: [table],
+    text: `SELECT \`seq\` FROM ${quoteMysqlIdentifier(MYSQL_SYNC_COUNTERS)} WHERE \`model\` = $1`,
+  });
+  if (!rows.length) {
+    throw new Error(`runSqlMigration(): ${table} is not the table of a synchronized model (no change counter)`);
+  }
+  const last = BigInt(rows[0].seq);
+  return Array.from({ length: count }, (_, index) => (last - BigInt(count - 1 - index)).toString());
+}

package/src/core/modules/sync/INTEGRATION-CHECKLIST.md

@@ -0,0 +1,95 @@
+# Sync Integration Checklist
+
+Offer a model to offline clients (`docs/offline-sync-protocol.md`). Background: [`README.md`](./README.md).
+
+## Reference Implementation
+
+- Local: `node_modules/@lenne.tech/nest-server/src/server/modules/sync-note/`
+- GitHub: https://github.com/lenneTech/nest-server/tree/develop/src/server/modules/sync-note
+
+The reference is not part of the reference server (`ServerModule` does not import it); the sync contract suite runs on
+exactly these files.
+
+## Required Files (Create in Order)
+
+### 1. Enable the module
+
+**Edit:** `src/config.env.ts`
+
+```typescript
+sync: { cursorSecret: process.env.SYNC_CURSOR_SECRET },
+```
+
+WHY: the cursors are signed with it. Without `sync.cursorSecret` (or `SECRETS_ENCRYPTION_KEY`) the boot fails in
+`production` / `staging`.
+
+### 2. The model
+
+**Create:** `src/server/modules/<module>/<module>.model.ts`
+**Copy from:** `sync-note.model.ts`
+
+- `@PersistedModel({ sync: { roles: { pull, create, update, delete }, strategy } })` — declare all four roles.
+  WHY: the roles on your controllers do not reach `/sync`; an operation without roles here is open to admins only.
+- Do **not** declare `version`, `deletedAt`, `syncAt`, `syncSeq` — the store adds them (a declared one is refused).
+- Declare `createdBy` when an operation uses `S_CREATOR` or `securityCheck()` decides by the creator.
+- `securityCheck()` decides who sees a record — a pull and every push lookup run through it.
+- **MySQL / MariaDB:** the owner account creates the change-order triggers at boot. WHY: with binary logging on (the
+  MySQL 8.4 default) that needs `SUPER` or `log_bin_trust_function_creators=1` on the server — without it the boot stops
+  with error 1419. The application account needs neither.
+
+### 3. The inputs
+
+**Create:** `inputs/<module>-create.input.ts`, `inputs/<module>.input.ts`
+**Copy from:** `inputs/sync-note-create.input.ts`, `inputs/sync-note.input.ts`
+
+WHY: a push's `data` is validated and whitelisted against them exactly like a request body — only what they declare
+can be set.
+
+### 4. The service
+
+**Create / edit:** `<module>.service.ts`
+**Copy from:** `sync-note.service.ts`
+
+```typescript
+@SyncService({ createInput: NoteCreateInput, model: Note, updateInput: NoteInput })
+```
+
+For `strategy: 'custom'` implement `resolveSyncConflict(context)` (`SyncConflictResolver`); the boot fails without it.
+
+### 5. The module
+
+**Edit:** `<module>.module.ts` — register the model with `CorePersistenceModule.forFeature([{ model, name, schema }])`
+**Copy from:** `sync-note.module.ts`
+
+WHY: only a model registered this way can be synchronized (its store maintains the system fields).
+
+### 6. An EXISTING model with data
+
+Making an existing model synchronized is a migration on every database: the boot refuses with the statements to apply
+(SQL: the `deleted_at` column, the live-only unique index, `DROP` of the full one; MongoDB:
+`SyncMigrationRequiredError`). See `.claude/rules/persistence.md` → "Synchronized models".
+
+## Verification Checklist
+
+- [ ] The boot logs `Offline sync for <Model>` and no "declares no sync roles" warning
+- [ ] `GET /sync/<Model>` answers `{ items, cursor, hasMore }` for a signed-in user with the pull roles, 403 without
+- [ ] A push of `{ mutationId, op: 'upsert', id, data }` answers `applied` with `version: 1`; the same push again too
+- [ ] A user of another tenant pulls none of the records and gets `not_found` / `ID_UNAVAILABLE` for their ids
+- [ ] `GET /sync/hints` (EventSource) sends `event: change` after a write in the user's scope, and nothing for another
+      tenant's; the client pulls on every hint and once after every reconnect
+- [ ] Writes past the CrudService (data store, native API, migration) call `CoreSyncService.notifyChange()`, and
+      multi-row data migrations on a synchronized SQL table use `runSqlMigration()` with `syncUpdate`
+- [ ] The client deletes every local record, cursor and unsent change on logout and on an account switch (the device
+      holds personal data — see [SECURITY.md](./SECURITY.md))
+
+## Common Mistakes
+
+| Mistake                                               | Symptom                                                                  | Fix                                                         |
+| ----------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------- |
+| No `sync.roles`                                       | Every push of a user is `rejected` / `FORBIDDEN`, pull 403; boot warning | Declare all four operations                                 |
+| `@SyncService()` missing                              | `404` for the model                                                      | Decorate the CrudService                                    |
+| Model registered with `MongooseModule.forFeature()`   | Boot error "not registered with CorePersistenceModule.forFeature()"      | Use `CorePersistenceModule.forFeature()`                    |
+| A system field declared on the model                  | Boot error "reserved on a synchronized model"                            | Remove it — the store maintains it                          |
+| Writes to a tenant-scoped model without `X-Tenant-Id` | Rejected by the tenant policy                                            | Send the header on writes; pulls may span all memberships   |
+| Records moved by a direct store / native write        | Previous owners keep their copies                                        | Call `CoreSyncService.bumpAccessEpoch()` after such a write |
+| A driver's default `new ObjectId()` on the client     | Ids predictable from one observed id                                     | Random tail per protocol §3, or uuidv7                      |

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

@@ -0,0 +1,188 @@
+# Sync (offline sync)
+
+Clients read and write while offline and reconcile with the server afterwards: they **pull** what changed since their
+cursor, **push** what they changed locally, and receive **tombstones** for deletions. The client contract is the
+protocol in [`docs/offline-sync-protocol.md`](../../../../docs/offline-sync-protocol.md) — a client needs `fetch` and
+nothing from this package. This module is the server side, on every database the framework supports (MongoDB
+standalone and replica set, PostgreSQL with TypeORM, Kysely or Drizzle, MySQL, MariaDB), with the same observable
+behaviour.
+
+Integration steps: [`INTEGRATION-CHECKLIST.md`](./INTEGRATION-CHECKLIST.md). Reference implementation:
+[`src/server/modules/sync-note/`](../../../server/modules/sync-note/).
+
+## What it adds
+
+| Route                                | Protocol |                                                            |
+| ------------------------------------ | -------- | ---------------------------------------------------------- |
+| `GET /sync/{model}?cursor=…&limit=…` | §5       | One page of changes after the cursor, tombstones included  |
+| `POST /sync/{model}`                 | §6       | Apply `{ items: [...] }` item by item, one result per item |
+| `GET /sync/hints?models=…`           | §9       | SSE: `event: change` with `{ model, at }` — pull now       |
+| `subscription { syncHint(models) }`  | §9       | The same hints over GraphQL (where GraphQL is enabled)     |
+
+Nothing without the `sync` configuration: no route, no infrastructure model, no listener on the write paths.
+
+## Configuration (`sync`, presence implies enabled)
+
+```typescript
+sync: {
+  cursorSecret: process.env.SYNC_CURSOR_SECRET,  // else SECRETS_ENCRYPTION_KEY; REQUIRED in production / staging
+  path: 'sync',
+  pull: { defaultLimit: 200, maxLimit: 1000, maxBytes: 1_048_576, windowSeconds: undefined /* MongoDB, derived */ },
+  push: { maxItems: 100 },
+  hints: { debounceMs: 250, sse: true, graphql: true },  // false: both channels off
+  retention: { mutationsDays: 30, tombstonesDays: 90 },  // tombstonesDays: false keeps them for ever
+  rateLimit: { pull: { max: 120, windowSeconds: 60 }, push: { max: 60, windowSeconds: 60 } },  // false: off
+}
+```
+
+`true` or `{}` enables it with these defaults. The full reference: `ISync` in
+`common/interfaces/server-options.interface.ts`.
+
+## Offering a model
+
+Two declarations, both explicit — a model is never offered by accident:
+
+1. **The model** — `@PersistedModel({ sync: { roles, strategy, scope, idFormat } })`. This makes it a synchronized
+   model in the data store (version, tombstones, live-only unique indexes, change order — see
+   `.claude/rules/persistence.md` → "Synchronized models") and carries what the sync routes need:
+   - `roles` per operation (`pull`, `create`, `update`, `delete`). The roles a project puts on its own routes do **not**
+     reach `/sync`; an operation without roles is open to `ADMIN` only, and the boot warns until they are declared. They
+     are passed as `serviceOptions.roles`, so `S_CREATOR` / `S_SELF` are decided against the stored record.
+   - `strategy`: `reject` (default), `lww`, `merge` (field by field; `@SyncField('reject')` marks a field that still
+     conflicts), `custom` (the service's `resolveSyncConflict()`).
+   - `scope`: the user-id fields a tombstone keeps (e.g. `['ownerId']`), so a deletion reaches exactly its users.
+2. **The service** — `@SyncService({ model, createInput, updateInput })` on the model's `CrudService`. Every pull and
+   push runs through that service; `data` is validated and whitelisted against the inputs like a request body.
+
+The model must be registered with `CorePersistenceModule.forFeature()`.
+
+## Security model
+
+| Rule                            | How                                                                                                                                                                                                                                                                                                                        |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The full pipeline, no lean path | Pull reads through the service's `find()` (`process()`, output `@Restricted`, tenant policy, RLS) and runs every record through `securityCheck()`; push writes through `create()` / `update()` / `delete()`                                                                                                                |
+| Operation rights                | The model's `sync.roles`, deny by default (ADMIN only)                                                                                                                                                                                                                                                                     |
+| Hidden fields                   | No answer depends on a value the caller may not read: a repeated create is always `conflict` with the record as the caller sees it, never compared with `data`                                                                                                                                                             |
+| Foreign ids                     | Change / delete: `not_found`, exactly like a missing id. Create: `ID_UNAVAILABLE` — the same answer for every reason an id cannot be used                                                                                                                                                                                  |
+| No hard delete                  | Push `delete` goes through `CrudService.delete()`, which tombstones a synchronized model on every path                                                                                                                                                                                                                     |
+| Tombstones                      | Carry id, version, `deletedAt`, `updatedAt`, `tenantId` and the scope fields the caller may see — no content                                                                                                                                                                                                               |
+| Cursor                          | Opaque, HMAC-signed, bound to model and user; another user's, another model's or a tampered cursor is `410 invalid`                                                                                                                                                                                                        |
+| Access loss                     | A fingerprint of the caller's access (user, tenant scope, roles, membership role, verification) and access epochs travel in the cursor; a change answers `410 access`, the client resyncs in full; a caller who may not pull at all, or names a left tenant in `X-Tenant-Id`, gets `403` and drops its copies the same way |
+| Cookie push                     | `Content-Type: application/json`; while the server uses cookies, `Sec-Fetch-Site: cross-site` and an untrusted `Origin` answer 403                                                                                                                                                                                         |
+| API tokens                      | Refused like on every route without `@ApiTokenScopes()` (see "Extending")                                                                                                                                                                                                                                                  |
+| Session expired                 | 401 for the whole request before any item; the client resends the same items, mutation ids recognise them                                                                                                                                                                                                                  |
+
+A pull or push without `X-Tenant-Id` spans every tenant the caller belongs to (the tenant guard's membership logic);
+writes to a tenant-scoped model need the header, as everywhere — a create without it is `rejected` / `FORBIDDEN` on
+every database, because nothing could tell which of the caller's tenants the record belongs to. A pull without it reads
+each of the caller's tenants on its own and merges them in change order, so the tenant-led change index serves every
+page.
+
+What a client must do on its side — delete its local data on logout and on an account switch, keep credentials out of
+reach of injected scripts, cache no API responses — is in [SECURITY.md](./SECURITY.md).
+
+## Clients
+
+The protocol needs `fetch` and nothing from the server's code (`docs/offline-sync-protocol.md`). Two test clients in
+the framework repository prove it end to end against the reference server, with one shared protocol implementation
+(`tests/clients/sync-client.mjs`, not part of the package):
+
+| Client                                                                                       | Storage                | Suite                                |
+| -------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------ |
+| PWA in Chrome, served by the test server, service worker for offline loading, session cookie | IndexedDB              | `tests/sync-pwa-client.e2e-spec.ts`  |
+| Node, as a desktop or React Native app would be, bearer session token                        | SQLite (`node:sqlite`) | `tests/sync-node-client.e2e-spec.ts` |
+
+Both pass the same scenarios (`tests/helpers/sync-client-scenarios.ts`): create, change and delete offline, then online;
+a conflict; two tabs pushing at once; a session that expired while offline; cleared storage. Two server processes with
+clocks 10 s apart lose no change under parallel writers (`tests/sync-clock-skew.e2e-spec.ts`). A Nuxt composable for
+projects follows in `@lenne.tech/nuxt-extensions`.
+
+## Idempotency and repeats
+
+Every item carries a `mutationId`. The module **claims** it before the write (model, user, record, mutation id —
+hashed, unique), records the outcome afterwards and answers a repeat with that outcome for `retention.mutationsDays`.
+A repeat that finds a claim still being written answers `retry` — that is how two tabs sending the same push end in one
+write and no false conflict. A claim older than 30 s belongs to a request that died and is taken over.
+
+## Change order and windows
+
+The store decides how changes are ordered (`capabilities.changeOrder`): on SQL a commit-ordered sequence (`syncSeq`) —
+no repeats; on MongoDB the server clock (`syncAt`) with a window W below each run's start — records changed within W
+are delivered again, clients keep the higher `version`. W is derived: replica set or sharded cluster — the server's
+`transactionLifetimeLimitSeconds` (60 when unreadable) + 30 s; standalone — 30 s. `sync.pull.windowSeconds` overrides
+it; it must cover the longest time a write can take from its stamp until it is visible.
+
+On MySQL / MariaDB the change numbers come from triggers the owner account (`database.ownerUrl`) creates at boot. With
+binary logging on — the MySQL 8.4 default — that needs `SUPER` or `log_bin_trust_function_creators=1` on the server
+(the parameter group on managed MySQL), otherwise the boot stops with error 1419. The application account needs
+neither.
+
+## Hints
+
+A hint tells a connected client that pulling is worthwhile; sync works without them (protocol §9).
+
+- **Source:** every successful `create()` / `update()` / `delete()` of the model's `CrudService` — on every database,
+  no change feed. A write past it (the data store, the native API, a migration) calls
+  `CoreSyncService.notifyChange(model, tenantIds)`, or clients learn of it at their next pull.
+- **Content:** `{ model, at }` only. **Recipients:** callers with the model's pull roles and, on a tenant-scoped model,
+  only for changes in their own tenants (the validated `X-Tenant-Id`, without it every membership). `models` narrows a
+  channel; a name that is not offered never matches and reveals nothing.
+- **Bursts:** one hint per model and tenant per `hints.debounceMs`, already at the sender. **Replicas:** with `redis`
+  every replica receives every hint through one channel and delivers it to its own subscribers; without Redis a hint
+  stays on its replica.
+- **Long-lived channels are re-checked:** the GraphQL subscription runs on the WebSocket `CoreModule` re-checks; an SSE
+  stream is registered in the same registry and ends at once on an invalidation naming the caller or their tenant, and
+  otherwise before the first hint after `graphQl.subscriptionRevalidationMs` — the EventSource reconnects (`retry`) and
+  the new request passes the guards. A client pulls once after every (re)connect.
+
+## Tombstone purge
+
+Every hour, on one replica (a lease: Redis, else the SQL lease table, else `cron-locks` in MongoDB), each model's
+horizon moves to `retention.tombstonesDays` ago **first**, then the older tombstones are deleted for good. A client
+whose cursor is older than the horizon answers its next pull with `410 horizon` and resyncs; nothing is skipped.
+The tombstones go in batches of 1000, read by id and deleted by id: one statement over the whole table would lock
+every row it scans on MySQL / MariaDB and hold up every write of the model.
+`CoreSyncService.purgeTombstones({ before?, model? })` runs it on demand.
+
+## Data migrations on a synchronized SQL table
+
+A multi-row write in a migration goes through `runSqlMigration()` as a `syncUpdate`, never as a plain `UPDATE`:
+
+```typescript
+await runSqlMigration(ownerUrl, [
+  { syncUpdate: { table: 'sync_notes', set: "status = 'archived'", where: "created_at < '2026-01-01'" } },
+]);
+```
+
+It locks the rows first, then takes the change numbers like the store, then writes them with `version + 1` — the order
+that cannot deadlock with a running application on MySQL / MariaDB, and the version a client's stale edit then
+conflicts with. On MySQL / MariaDB each `syncUpdate` runs in a transaction of its own, because a DDL statement before
+it has already committed the migration's. `set` and `where` are reviewed SQL, like every statement of a migration.
+
+## Infrastructure models
+
+| Model          | Collection / table                 | Holds                                                                                                                    |
+| -------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `SyncMutation` | `syncMutations` / `sync_mutations` | Claims and outcomes of pushed mutations, `expiresAt` (TTL on MongoDB, expiry sweep on SQL; every reader checks it)       |
+| `SyncState`    | `syncStates` / `sync_states`       | Access epochs (`epoch:t:<model>:<tenant>`, `epoch:u:<model>:<tenant>:<user>`) and tombstone horizons (`horizon:<model>`) |
+
+Both follow `database` like every other model.
+
+## Extending
+
+Override through `CoreModule.forRoot(env, { sync: { controller, hintsController, resolver, service } })`:
+
+- **`CoreSyncService`** — every step is `protected`: `readChanges()`, `toSyncRecord()`, `accessState()`,
+  `resolveUpdateConflict()`, `writeFailure()`, …
+- **`CoreSyncController`** — e.g. to release a scope to API tokens: extend it, re-declare `pull()` / `push()` with their
+  route decorators plus `@ApiTokenScopes('sync')`, and call `super`.
+- **`CoreSyncHintsController`** — `GET /sync/hints`, a controller of its own that the module registers before
+  `CoreSyncController`: Nest registers a class's own routes before the inherited ones, so a re-declared `pull()`
+  (`@Get(':model')`) would otherwise read `hints` as a model name. Extend it the same way to release hints to API
+  tokens. `CoreSyncBaseController` holds what both share (`scopeTenants()`, `limit()`).
+- **`CoreSyncResolver`** — the `syncHint` subscription.
+- **`CoreSyncService` is global** while `sync` is configured: inject it in any project service (with `@Optional()` where
+  the project also runs without `sync`) to call `notifyChange()` / `bumpAccessEpoch()`.
+- **Access that moves past `CrudService.update()`** (a direct store write, a migration, the native API) bumps no epoch:
+  call `CoreSyncService.bumpAccessEpoch(model, tenantId, userId?)` after such a write, or the clients concerned keep
+  their copies until their next full resync.