@lenne.tech/nest-server 12.1.1 → 12.3.0

package/src/core/common/persistence/sync-model.ts

@@ -0,0 +1,270 @@
+import type {
+  FieldDescriptor,
+  IndexDescriptor,
+  ModelDescriptor,
+  SyncDescriptor,
+  SyncIdFormat,
+} from './model-descriptor.interface.js';
+
+export type { SyncDescriptor, SyncIdFormat } from './model-descriptor.interface.js';
+
+/**
+ * Synchronized models (offline sync, `docs/offline-sync-protocol.md`, offline-sync plan §3.2).
+ *
+ * A model declared with `@PersistedModel({ sync })` carries three system fields every store maintains and no caller
+ * writes — `version`, `deletedAt` and its position in the change order — and its delete leaves a tombstone instead of
+ * removing the record. This leaf holds the declaration, the descriptor it produces and the field names, so the stores,
+ * the schema compilers and the Mongoose plugin read one definition. Types and plain functions only: every persistence
+ * file may import it without an import cycle.
+ */
+
+/**
+ * How a push meets a record that changed since the client's base version (protocol §6.4): `reject` answers `conflict`,
+ * `lww` applies the change on top (last to ARRIVE at the server wins), `merge` applies the fields the client changed
+ * unless one of them is declared `@SyncField('reject')`, `custom` asks the model service's `resolveSyncConflict()`.
+ */
+export type SyncConflictStrategy = 'custom' | 'lww' | 'merge' | 'reject';
+
+/**
+ * Who may do what through the sync routes (protocol §1.3), passed as `serviceOptions.roles` to every `CrudService`
+ * call of the module — so `S_CREATOR` and `S_SELF` are decided against the stored record, as everywhere. The roles
+ * a project puts on its own routes do not reach `/sync`; an operation without roles here is open to `ADMIN` only.
+ */
+export interface SyncOperationRoles {
+  create?: string[];
+  delete?: string[];
+  /** Also who may receive hints for the model; `S_CREATOR` / `S_SELF` decide nothing here (a pull has no record) */
+  pull?: string[];
+  update?: string[];
+}
+
+const SYNC_STRATEGIES: readonly SyncConflictStrategy[] = ['custom', 'lww', 'merge', 'reject'];
+const SYNC_OPERATIONS: readonly (keyof SyncOperationRoles)[] = ['create', 'delete', 'pull', 'update'];
+
+export interface SyncModelOptions {
+  /**
+   * Format of the model's ids. `uuidv7` is meant for NEW models: ids are stored as text on SQL and as a BSON UUID
+   * (binary subtype 4) on MongoDB, and every reference to the model must hold that format too.
+   * @default 'objectId'
+   */
+  idFormat?: SyncIdFormat;
+  /**
+   * Operation roles of the sync routes (`SyncOperationRoles`). Read by the sync module only.
+   * @default every operation open to ADMIN only (the boot warns until roles are declared)
+   */
+  roles?: SyncOperationRoles;
+  /**
+   * The user-id fields a tombstone keeps besides `tenantId` (e.g. `['ownerId']`), so a deletion reaches exactly the
+   * users who could see the record. Every other content field is cleared when the record is deleted.
+   * @default []
+   */
+  scope?: string[];
+  /**
+   * What a push does when the record changed since the client's base version. Read by the sync module only.
+   * @default 'reject'
+   */
+  strategy?: SyncConflictStrategy;
+}
+
+/** Incremented by every write; `1` after the insert */
+export const SYNC_VERSION_FIELD = 'version';
+/** `null` for a live record, the deletion time for a tombstone */
+export const SYNC_DELETED_FIELD = 'deletedAt';
+/** MongoDB's change position: the server clock of the last write (plan §3.4, C2) */
+export const SYNC_CLOCK_FIELD = 'syncAt';
+/** The SQL change position: a commit-ordered sequence number (plan §3.4, C1d) */
+export const SYNC_SEQUENCE_FIELD = 'syncSeq';
+/** The value a multi-row statement writes before its final statement numbers the rows (plan §3.4) */
+export const SYNC_SEQUENCE_PENDING = -1;
+
+/** Fields only the store writes on a synchronized model */
+export const SYNC_SYSTEM_FIELDS: readonly string[] = Object.freeze([
+  SYNC_VERSION_FIELD,
+  SYNC_DELETED_FIELD,
+  SYNC_CLOCK_FIELD,
+  SYNC_SEQUENCE_FIELD,
+]);
+
+/**
+ * The live-record condition: the same form in every read filter and in every partial unique index, because MongoDB
+ * uses a partial index only for a query that implies its filter, and the equality also covers a document without the
+ * field (P2-4, measured in phase 2). SQL compiles it to `deleted_at IS NULL`.
+ */
+export function liveFilter(): { deletedAt: null } {
+  return { [SYNC_DELETED_FIELD]: null } as { deletedAt: null };
+}
+
+/** The declaration of `@PersistedModel({ sync })`, resolved; `undefined` for a model that is not synchronized */
+export function resolveSyncOptions(
+  value: boolean | SyncModelOptions | undefined,
+  model: string,
+): SyncDescriptor | undefined {
+  if (value === undefined || value === false) {
+    return undefined;
+  }
+  const options: SyncModelOptions = value === true ? {} : value;
+  if (!options || typeof options !== 'object') {
+    throw new Error(`@PersistedModel(${model}): sync must be true or an options object`);
+  }
+  const idFormat = options.idFormat ?? 'objectId';
+  if (idFormat !== 'objectId' && idFormat !== 'uuidv7') {
+    throw new Error(
+      `@PersistedModel(${model}): sync.idFormat must be 'objectId' or 'uuidv7', got ${JSON.stringify(idFormat)}`,
+    );
+  }
+  const scope = options.scope ?? [];
+  if (!Array.isArray(scope) || scope.some((field) => typeof field !== 'string' || !field)) {
+    throw new Error(`@PersistedModel(${model}): sync.scope must be a list of field names`);
+  }
+  if (options.strategy !== undefined && !SYNC_STRATEGIES.includes(options.strategy)) {
+    throw new Error(
+      `@PersistedModel(${model}): sync.strategy must be one of ${SYNC_STRATEGIES.join(', ')}, got ${JSON.stringify(options.strategy)}`,
+    );
+  }
+  if (options.roles !== undefined) {
+    const roles = options.roles;
+    const invalid =
+      !roles ||
+      typeof roles !== 'object' ||
+      Object.entries(roles).some(
+        ([operation, list]) =>
+          !SYNC_OPERATIONS.includes(operation as keyof SyncOperationRoles) ||
+          !Array.isArray(list) ||
+          list.some((role) => typeof role !== 'string' || !role),
+      );
+    if (invalid) {
+      throw new Error(
+        `@PersistedModel(${model}): sync.roles maps ${SYNC_OPERATIONS.join(', ')} to lists of role names`,
+      );
+    }
+  }
+  return { idFormat, scope: Object.freeze([...scope]) };
+}
+
+/**
+ * The descriptor of a synchronized model: the system fields added, the id typed by the declared format, and every
+ * unique index restricted to live records — so deleting a record and creating one with the same unique value works,
+ * on every database (plan §3.6). Database-neutral: the change position (`syncSeq` / `syncAt`) is the store's own
+ * column, added by the dialect that keeps it.
+ *
+ * Refuses what would make the model lose deletions or system fields: a TTL index (records would vanish without a
+ * tombstone), a declared field of a system name, a scope field the model does not have.
+ */
+export function withSyncDescriptor(descriptor: ModelDescriptor, sync: SyncDescriptor): ModelDescriptor {
+  const name = descriptor.name;
+  for (const field of SYNC_SYSTEM_FIELDS) {
+    if (descriptor.fields[field]) {
+      throw new Error(`${name}: "${field}" is reserved on a synchronized model — rename the field`);
+    }
+  }
+  for (const field of sync.scope) {
+    if (!descriptor.fields[field]) {
+      throw new Error(`${name}: sync.scope names "${field}", which the model does not declare`);
+    }
+  }
+  const nestedUnique = descriptor.indexes.find(
+    (index) => index.options.unique === true && Object.keys(index.fields).some((path) => path.includes('.')),
+  );
+  if (nestedUnique) {
+    // MongoDB keeps such an index on the embedded schema, out of reach of the live-only rewrite: a tombstone (which
+    // keeps no values) would collide on it with the next deletion
+    throw new Error(
+      `${name}: a unique index inside an embedded object (${JSON.stringify(nestedUnique.fields)}) is not supported on a ` +
+        'synchronized model — declare the unique field on the model itself',
+    );
+  }
+  if (
+    descriptor.indexes.some((index) => 'expireAfterSeconds' in index.options) ||
+    Object.values(descriptor.fields).some((field) => field.expiresAfterSeconds !== undefined)
+  ) {
+    throw new Error(
+      `${name}: a synchronized model cannot expire records (TTL) — an expired record disappears without a tombstone, ` +
+        'and every client keeps it',
+    );
+  }
+
+  const fields: Record<string, FieldDescriptor> = { ...descriptor.fields };
+  if (sync.idFormat === 'uuidv7' && fields._id) {
+    fields._id = { ...fields._id, kind: 'uuid' };
+  }
+  fields[SYNC_VERSION_FIELD] = systemField(SYNC_VERSION_FIELD, 'number', 1);
+  fields[SYNC_DELETED_FIELD] = systemField(SYNC_DELETED_FIELD, 'date', null);
+
+  return {
+    ...descriptor,
+    fields,
+    indexes: descriptor.indexes.map((index) => liveUniqueIndex(index)),
+    sync,
+  };
+}
+
+/**
+ * A unique index restricted to live records. A sparse one keeps its meaning through `$exists` — MongoDB refuses
+ * `sparse` together with a `partialFilterExpression`. Every other index is returned unchanged.
+ */
+export function liveUniqueIndex(index: IndexDescriptor): IndexDescriptor {
+  if (index.options.unique !== true) {
+    return index;
+  }
+  const { sparse, ...options } = index.options;
+  const existing = (options.partialFilterExpression as Record<string, unknown> | undefined) ?? {};
+  const exists =
+    sparse === true ? Object.fromEntries(Object.keys(index.fields).map((path) => [path, { $exists: true }])) : {};
+  return {
+    fields: { ...index.fields },
+    options: { ...options, partialFilterExpression: { ...existing, ...exists, ...liveFilter() } },
+  };
+}
+
+/**
+ * The descriptor a SQL store works with: a synchronized model's descriptor plus its commit-ordered change position
+ * `syncSeq` (a `bigint` column the database's trigger numbers, plan §3.4) and the pull's index over it, led by the
+ * tenant every pull on a tenant-scoped model is filtered by. Any other descriptor is returned as it is.
+ */
+export function withSequenceField(descriptor: ModelDescriptor): ModelDescriptor {
+  if (!descriptor.sync || descriptor.fields[SYNC_SEQUENCE_FIELD]) {
+    return descriptor;
+  }
+  const field = systemField(SYNC_SEQUENCE_FIELD, 'bigint', undefined);
+  return {
+    ...descriptor,
+    fields: { ...descriptor.fields, [SYNC_SEQUENCE_FIELD]: field },
+    indexes: [
+      ...descriptor.indexes,
+      {
+        fields: descriptor.tenantScoped ? { tenantId: 1, [SYNC_SEQUENCE_FIELD]: 1 } : { [SYNC_SEQUENCE_FIELD]: 1 },
+        options: {},
+      },
+    ],
+  };
+}
+
+/** Whether a partial filter is exactly the live-record condition (PostgreSQL then keeps `NULLS NOT DISTINCT`) */
+export function isLiveFilter(filter: unknown): boolean {
+  if (!filter || typeof filter !== 'object') {
+    return false;
+  }
+  const keys = Object.keys(filter);
+  return (
+    keys.length === 1 &&
+    keys[0] === SYNC_DELETED_FIELD &&
+    (filter as Record<string, unknown>)[SYNC_DELETED_FIELD] === null
+  );
+}
+
+function systemField(name: string, kind: FieldDescriptor['kind'], value: unknown): FieldDescriptor {
+  return {
+    ...(value === undefined ? {} : { default: value }),
+    hasDefault: value !== undefined,
+    index: false,
+    isArray: false,
+    kind,
+    lowercase: false,
+    name,
+    required: false,
+    select: true,
+    sparse: false,
+    trim: false,
+    unique: false,
+  };
+}

package/src/core/common/services/crud.service.ts

@@ -9,7 +9,19 @@ import { convertFilterArgsToQuery } from '../helpers/filter.helper.js';
 import { mergePlain, prepareServiceOptionsForCreate } from '../helpers/input.helper.js';
 import { ServiceOptions } from '../interfaces/service-options.interface.js';
 import type { FindOptions, Where } from '../persistence/data-store.interface.js';
+import { getModelDescriptor } from '../persistence/model-metadata.registry.js';
+import { getSyncAccessListener } from '../persistence/sync-access.registry.js';
 import { UnsupportedCapabilityError } from '../persistence/unsupported-capability.error.js';
+import { isDuplicateIdError } from '../persistence/mongoose-data-store.js';
+import { includeTombstones, syncOfSchema } from '../persistence/mongo/sync-schema.plugin.js';
+import type { SyncDescriptor } from '../persistence/model-descriptor.interface.js';
+import {
+  assertClientId,
+  assertExpectedVersion,
+  insertWithServerId,
+  suppliedId,
+  VersionConflictError,
+} from '../persistence/policies/sync.policy.js';
 import { CoreModel } from '../models/core-model.model.js';
 import { PaginationInfo } from '../models/pagination-info.model.js';
 import { PlainObject } from '../types/plain-object.type.js';
@@ -74,14 +86,36 @@ export abstract class CrudService<
     return this.process(
       async (data) => {
         const currentUserId = serviceOptions?.currentUser?.id;
+        const createId = serviceOptions?.createId;
         if (this.usesNeutralStore) {
-          return this.dataStore.insert({ ...data.input, createdBy: currentUserId, updatedBy: currentUserId } as any);
+          return this.syncChanged(
+            await this.dataStore.insert({
+              ...data.input,
+              ...(createId === undefined || createId === null ? {} : { id: createId }),
+              createdBy: currentUserId,
+              updatedBy: currentUserId,
+            } as any),
+          );
         }
-        return new (this.mainDbModel as MongooseModel<Document & Model>)({
-          ...data.input,
-          createdBy: currentUserId,
-          updatedBy: currentUserId,
-        }).save();
+        const build = (id?: string) =>
+          new (this.mainDbModel as MongooseModel<Document & Model>)({
+            ...data.input,
+            ...(id === undefined ? {} : { _id: id }),
+            createdBy: currentUserId,
+            updatedBy: currentUserId,
+          });
+        const sync = this.mongoSync;
+        if (!sync) {
+          return build(createId ?? undefined).save();
+        }
+        // A synchronized model keeps a client's id in its format and replaces a taken server id (plan §3.3, E6)
+        const supplied = createId ?? suppliedId(data.input ?? {});
+        if (supplied !== undefined && supplied !== null) {
+          return this.syncChanged(
+            await build(assertClientId(supplied, sync.idFormat, this.mainDbModel.modelName)).save(),
+          );
+        }
+        return this.syncChanged(await insertWithServerId(sync.idFormat, (id) => build(id).save(), isDuplicateIdError));
       },
       { input, serviceOptions },
     );
@@ -110,8 +144,8 @@ export abstract class CrudService<
   /**
    * Get distinct values of a property
    */
-  distinct(property: string): Promise<string[]> {
-    return this.dataStore.distinct(property) as Promise<string[]>;
+  distinct(property: string, serviceOptions?: ServiceOptions): Promise<string[]> {
+    return this.dataStore.distinct(property, undefined, tombstoneOption(serviceOptions)) as Promise<string[]>;
   }
 
   /**
@@ -119,13 +153,16 @@ export abstract class CrudService<
    */
   async get(id: string, serviceOptions?: ServiceOptions): Promise<Model> {
     if (this.usesNeutralStore) {
-      const record = await this.dataStore.findById(id, neutralSelect(serviceOptions?.select));
+      const record = await this.dataStore.findById(id, {
+        ...neutralSelect(serviceOptions?.select),
+        ...tombstoneOption(serviceOptions),
+      });
       if (!record) {
         throw new NotFoundException(`No ${this.mainModelConstructor.name} found with ID: ${id}`);
       }
       return this.process(async () => record, { dbObject: record, serviceOptions });
     }
-    const query = this.mainDbModel.findById(id);
+    const query = this.withTombstones(this.mainDbModel.findById(id), serviceOptions);
     if (serviceOptions?.select) {
       query.select(serviceOptions.select);
     }
@@ -190,7 +227,10 @@ export abstract class CrudService<
         }
 
         // Find in DB
-        let find = this.mainDbModel.find(filterQuery.filterQuery, null, filterQuery.queryOptions);
+        let find = this.withTombstones(
+          this.mainDbModel.find(filterQuery.filterQuery, null, filterQuery.queryOptions),
+          serviceOptions,
+        );
         const collation = serviceOptions?.collation || ConfigService.get('mongoose.collation');
         if (collation) {
           find = find.collation(collation);
@@ -261,7 +301,7 @@ export abstract class CrudService<
           const { options, where } = neutralQuery(filterQuery, serviceOptions);
           const [items, totalCount] = await Promise.all([
             this.dataStore.find(where, filter?.samples ? { ...options, sample: filter.samples } : options),
-            this.dataStore.count(where),
+            this.dataStore.count(where, tombstoneOption(serviceOptions)),
           ]);
           const queryOptions = filterQuery.queryOptions || {};
           return {
@@ -323,7 +363,12 @@ export abstract class CrudService<
         // Find and process db items
         const collation = serviceOptions?.collation || ConfigService.get('mongoose.collation');
         const dbResult =
-          (await this.mainDbModel.aggregate(aggregation, collation ? { collation } : {}).exec())[0] || {};
+          (
+            await this.withTombstones(
+              this.mainDbModel.aggregate(aggregation, collation ? { collation } : {}),
+              serviceOptions,
+            ).exec()
+          )[0] || {};
         dbResult.totalCount = dbResult.totalCount?.[0]?.total || 0;
         dbResult.items = dbResult.items?.map((item) => this.mainDbModel.hydrate(item)) || [];
 
@@ -443,13 +488,17 @@ export abstract class CrudService<
           return this.dataStore.findOne(where, {
             collation: options.collation,
             exclude: options.exclude,
+            includeTombstones: options.includeTombstones,
             select: options.select,
             sort: options.sort,
           });
         }
 
         // Find in DB
-        let find = this.mainDbModel.findOne(filterQuery.filterQuery, null, filterQuery.queryOptions);
+        let find = this.withTombstones(
+          this.mainDbModel.findOne(filterQuery.filterQuery, null, filterQuery.queryOptions),
+          serviceOptions,
+        );
         const collation = serviceOptions?.collation || ConfigService.get('mongoose.collation');
         if (collation) {
           find = find.collation(collation);
@@ -657,18 +706,31 @@ export abstract class CrudService<
    * Update item via ID
    */
   async update(id: string, input: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions): Promise<Model> {
+    const expectedVersion = this.expectedVersionOf(serviceOptions);
     if (this.usesNeutralStore) {
       const stored = await this.dataStore.findById(id);
       if (!stored) {
         throw new NotFoundException(`No ${this.mainModelConstructor.name} found with ID: ${id}`);
       }
+      this.assertVersion(id, stored, expectedVersion);
       return this.process(
         async (data) => {
           // The same write as on MongoDB: the stored record merged with the input, written back whole — minus
           // the id, which never changes, and the update time, which the store stamps
+          const before = this.syncAccessSnapshot(stored);
           const merged = mergePlain(stored, data.input, { updatedBy: serviceOptions?.currentUser?.id });
           const { _id: _mongoId, id: _id, updatedAt: _updatedAt, ...patch } = merged as Record<string, any>;
-          return this.dataStore.updateById(id, patch as any);
+          const updated =
+            expectedVersion === undefined
+              ? await this.dataStore.updateById(id, patch as any)
+              : // One statement with the version as its condition: of two changes made on the same version, one applies
+                ((await this.dataStore.updateOne({ id, version: expectedVersion } as Where, patch as any)) ??
+                this.versionConflict(id));
+          if (updated) {
+            await this.reportSyncAccessMove(before, merged);
+            this.reportSyncChange(before, merged);
+          }
+          return updated;
         },
         { dbObject: stored, input, serviceOptions },
       );
@@ -677,15 +739,28 @@ export abstract class CrudService<
     if (!dbObject) {
       throw new NotFoundException(`No ${this.mainModelConstructor.name} found with ID: ${id}`);
     }
+    this.assertVersion(id, dbObject, expectedVersion);
     return this.process(
       async (data) => {
         const currentUserId = serviceOptions?.currentUser?.id;
+        const before = this.syncAccessSnapshot(dbObject);
         const merged = mergePlain(dbObject, data.input, { updatedBy: currentUserId });
-        const query = this.mainDbModel.findByIdAndUpdate(id, merged, { returnDocument: 'after' });
+        const query =
+          expectedVersion === undefined
+            ? this.mainDbModel.findByIdAndUpdate(id, merged, { returnDocument: 'after' })
+            : this.mainDbModel.findOneAndUpdate({ _id: id, version: expectedVersion } as any, merged, {
+                returnDocument: 'after',
+              });
         if (serviceOptions?.select) {
           query.select(serviceOptions.select);
         }
-        return await query.exec();
+        const updated = await query.exec();
+        if (!updated) {
+          return expectedVersion === undefined ? updated : this.versionConflict(id);
+        }
+        await this.reportSyncAccessMove(before, merged);
+        this.reportSyncChange(before, merged);
+        return updated;
       },
       { dbObject, input, serviceOptions },
     );
@@ -715,14 +790,17 @@ export abstract class CrudService<
    * Delete item via ID
    */
   async delete(id: string, serviceOptions?: ServiceOptions): Promise<Model> {
+    const expectedVersion = this.expectedVersionOf(serviceOptions);
     if (this.usesNeutralStore) {
       const stored = await this.dataStore.findById(id, neutralSelect(serviceOptions?.select));
       if (!stored) {
         throw new NotFoundException(`No ${this.mainModelConstructor.name} found with ID: ${id}`);
       }
+      this.assertVersion(id, stored, expectedVersion);
       return this.process(
         async () => {
-          await this.dataStore.deleteById(id);
+          await this.removeOrTombstone(id, expectedVersion);
+          this.reportSyncChange(stored);
           return stored;
         },
         { dbObject: stored, serviceOptions },
@@ -736,15 +814,169 @@ export abstract class CrudService<
     if (!dbObject) {
       throw new NotFoundException(`No ${this.mainModelConstructor.name} found with ID: ${id}`);
     }
+    this.assertVersion(id, dbObject, expectedVersion);
     return this.process(
       async () => {
-        await this.mainDbModel.findByIdAndDelete(id).exec();
+        if (this.mongoSync) {
+          // A synchronized model's delete leaves a tombstone, which is how clients learn of it
+          await this.removeOrTombstone(id, expectedVersion);
+          this.reportSyncChange(dbObject);
+        } else {
+          await this.mainDbModel.findByIdAndDelete(id).exec();
+        }
         return dbObject;
       },
       { dbObject, serviceOptions },
     );
   }
 
+  // -- synchronized models (`@PersistedModel({ sync })`) ------------------------------------------------------
+
+  /** The sync declaration of the main model on its MongoDB path, read from the Mongoose schema */
+  protected get mongoSync(): SyncDescriptor | undefined {
+    return this.usesNeutralStore ? undefined : syncOfSchema(this.mainDbModel?.schema);
+  }
+
+  /** Whether the main model is synchronized, on whichever database it lives */
+  protected get isSynchronized(): boolean {
+    return !!this.dataStore?.capabilities.changeOrder;
+  }
+
+  /** A Mongoose query or aggregation that also sees tombstones when the caller asked (`includeTombstones`) */
+  protected withTombstones<Q extends object>(query: Q, serviceOptions?: ServiceOptions): Q {
+    return serviceOptions?.includeTombstones && this.mongoSync ? includeTombstones(query) : query;
+  }
+
+  /** `serviceOptions.expectedVersion`, checked; only a synchronized model has a version */
+  protected expectedVersionOf(serviceOptions?: ServiceOptions): number | undefined {
+    if (serviceOptions?.expectedVersion === undefined || serviceOptions.expectedVersion === null) {
+      return undefined;
+    }
+    if (!this.isSynchronized) {
+      throw new UnsupportedCapabilityError(
+        `expectedVersion: ${this.mainModelConstructor?.name ?? this.dataStore?.modelName} is not a synchronized model ` +
+          '(@PersistedModel({ sync }))',
+      );
+    }
+    return assertExpectedVersion(serviceOptions.expectedVersion);
+  }
+
+  /** The early answer to a conditional change on a record that already has another version */
+  protected assertVersion(id: string, stored: any, expectedVersion: number | undefined): void {
+    if (expectedVersion !== undefined && stored?.version !== expectedVersion) {
+      this.versionConflict(id);
+    }
+  }
+
+  protected versionConflict(id: string): never {
+    throw new VersionConflictError(this.mainModelConstructor?.name ?? this.dataStore.modelName, id);
+  }
+
+  /**
+   * The tenant and scope fields of a stored record as they are BEFORE a write — taken before `mergePlain()`, which
+   * merges the input INTO the stored object. `undefined` when nobody listens or the model is not synchronized.
+   */
+  protected syncAccessSnapshot(stored: Record<string, any> | undefined): Record<string, any> | undefined {
+    if (!stored || !getSyncAccessListener() || !this.isSynchronized) {
+      return undefined;
+    }
+    const scope = getModelDescriptor(this.dataStore.modelName)?.sync?.scope ?? [];
+    return Object.fromEntries(
+      ['tenantId', ...scope].map((field) => [field, Array.isArray(stored[field]) ? [...stored[field]] : stored[field]]),
+    );
+  }
+
+  /**
+   * Tell the sync module that this write took a synchronized record away from users who could see it: moved to
+   * another tenant, or a scope field (`sync.scope`, e.g. `ownerId`) changed away from a user (offline-sync plan §3.8).
+   * Their clients then answer the next pull with a full resync and lose the local copy. A no-op without the module.
+   * A failure is logged, never thrown: the write it follows has happened.
+   */
+  protected async reportSyncAccessMove(
+    stored: Record<string, any> | undefined,
+    written: Record<string, any>,
+  ): Promise<void> {
+    const listener = getSyncAccessListener();
+    if (!listener || !stored) {
+      return;
+    }
+    const model = this.dataStore.modelName;
+    const ids = (value: unknown): string[] =>
+      value === undefined || value === null
+        ? []
+        : (Array.isArray(value) ? value : [value]).flatMap((item) =>
+            item === undefined || item === null ? [] : [String(getStringIds(item))],
+          );
+    const after = (field: string) => (field in written ? written[field] : stored[field]);
+    const [tenantBefore] = ids(stored.tenantId);
+    const tenantChanged = !!tenantBefore && ids(after('tenantId'))[0] !== tenantBefore;
+    const usersLost = (getModelDescriptor(model)?.sync?.scope ?? []).flatMap((field) => {
+      const now = new Set(ids(after(field)));
+      return ids(stored[field]).filter((user) => !now.has(user));
+    });
+    if (!tenantChanged && !usersLost.length) {
+      return;
+    }
+    try {
+      await listener.recordMoved({ model, tenantChanged, tenantId: tenantBefore, usersLost: [...new Set(usersLost)] });
+    } catch (error) {
+      Logger.error(
+        `Sync access epoch for a moved ${model} record not bumped — affected clients keep their copy until their next ` +
+          `full resync: ${(error as Error)?.message ?? error}`,
+        this.constructor.name,
+      );
+    }
+  }
+
+  /**
+   * Tell the sync module that a write of a synchronized record succeeded, so the subscribers of its hints learn of it
+   * (offline-sync plan §3.9) — with the tenants the record was in before and after the write. A no-op without the
+   * module and on any other model; a failure is logged, never thrown: the write has happened.
+   */
+  protected reportSyncChange(...records: (Record<string, any> | null | undefined)[]): void {
+    const listener = getSyncAccessListener();
+    if (!listener?.recordChanged || !this.isSynchronized) {
+      return;
+    }
+    const tenantIds = new Set<string>();
+    for (const record of records) {
+      const tenantId = record?.tenantId;
+      if (tenantId !== undefined && tenantId !== null && tenantId !== '') {
+        tenantIds.add(String(getStringIds(tenantId)));
+      }
+    }
+    try {
+      listener.recordChanged({ model: this.dataStore.modelName, tenantIds: [...tenantIds] });
+    } catch (error) {
+      Logger.warn(
+        `Sync hint for a ${this.dataStore.modelName} write not sent — clients learn of it at their next pull: ` +
+          `${(error as Error)?.message ?? error}`,
+        this.constructor.name,
+      );
+    }
+  }
+
+  /** `reportSyncChange()` for a created record, which it answers */
+  protected syncChanged<R>(created: R): R {
+    this.reportSyncChange(created as any);
+    return created;
+  }
+
+  /**
+   * Delete through the store: a synchronized model's record becomes a tombstone (conditional on `expectedVersion`),
+   * any other model's is removed
+   */
+  protected async removeOrTombstone(id: string, expectedVersion: number | undefined): Promise<void> {
+    if (expectedVersion === undefined) {
+      await this.dataStore.deleteById(id);
+      return;
+    }
+    const removed = await this.dataStore.deleteOne({ id, version: expectedVersion } as Where);
+    if (!removed) {
+      this.versionConflict(id);
+    }
+  }
+
   /**
    * Delete item via ID without checks or restrictions
    * Warning: Disables the handling of rights and restrictions!
@@ -897,6 +1129,11 @@ function neutralSelect(select: unknown): Pick<FindOptions, 'exclude' | 'select'>
   };
 }
 
+/** `includeTombstones` of the service options as a store option */
+function tombstoneOption(serviceOptions?: ServiceOptions): { includeTombstones?: boolean } {
+  return serviceOptions?.includeTombstones ? { includeTombstones: true } : {};
+}
+
 /** The filter and query options of a CrudService call as the neutral filter and find options */
 function neutralQuery(
   query: { filterQuery?: unknown; queryOptions?: QueryOptions },
@@ -906,6 +1143,7 @@ function neutralQuery(
   const options: FindOptions = {
     collation: (serviceOptions?.collation || ConfigService.get('mongoose.collation')) as Record<string, unknown>,
     ...neutralSelect(serviceOptions?.select),
+    ...tombstoneOption(serviceOptions),
   };
   const skip = queryOptions.skip ?? queryOptions.offset;
   const limit = queryOptions.limit ?? queryOptions.take;