@lenne.tech/nest-server 12.1.1 → 12.3.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "12.1.1",
+  "version": "12.3.0",
   "type": "module",
-  "description": "Server framework in TypeScript on top of NestJS: GraphQL and REST APIs on MongoDB, PostgreSQL, MySQL or MariaDB, with authentication, field-level permissions, multi-tenancy and an AI assistant.",
+  "description": "Server framework in TypeScript on top of NestJS: GraphQL and REST APIs on MongoDB, PostgreSQL, MySQL or MariaDB, with authentication, field-level permissions, multi-tenancy, offline sync and an AI assistant.",
   "keywords": [
     "node",
     "nest",
@@ -15,6 +15,7 @@
     "graphql",
     "rest",
     "multi-tenancy",
+    "offline-sync",
     "typescript"
   ],
   "author": "lenne.Tech <info@lenne.tech> (https://lenne.tech)",
@@ -103,18 +104,18 @@
     "@as-integrations/express5": "1.1.2",
     "@getbrevo/brevo": "6.2.0",
     "@modelcontextprotocol/sdk": "1.32.2",
-    "@nestjs/apollo": "14.1.1",
+    "@nestjs/apollo": "14.1.2",
     "@nestjs/common": "12.3.2",
     "@nestjs/core": "12.3.2",
-    "@nestjs/graphql": "14.1.0",
+    "@nestjs/graphql": "14.1.2",
     "@nestjs/jwt": "12.0.3",
     "@nestjs/passport": "12.0.0",
     "@nestjs/platform-express": "12.3.2",
     "@nestjs/schedule": "12.0.2",
-    "@nestjs/swagger": "12.0.5",
+    "@nestjs/swagger": "12.1.0",
     "@nestjs/terminus": "12.1.0",
-    "@tus/file-store": "2.1.1",
-    "@tus/server": "2.4.6",
+    "@tus/file-store": "2.1.2",
+    "@tus/server": "2.4.7",
     "@types/supertest": "7.2.1",
     "bcrypt": "6.0.0",
     "class-transformer": "0.5.1",
@@ -130,13 +131,13 @@
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "17.1.0",
     "graphql-ws": "6.3.0",
-    "jose": "6.2.13",
+    "jose": "6.2.15",
     "js-sha256": "1.0.0",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
     "multer": "2.5.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "10.3.0",
+    "nodemailer": "10.3.1",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -225,9 +226,9 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1159.0",
-    "@aws-sdk/lib-storage": "3.1159.0",
-    "@aws-sdk/s3-request-presigner": "3.1159.0",
+    "@aws-sdk/client-s3": "3.1161.0",
+    "@aws-sdk/lib-storage": "3.1161.0",
+    "@aws-sdk/s3-request-presigner": "3.1161.0",
     "@better-auth/core": "1.7.14",
     "@better-auth/passkey": "1.7.14",
     "@compodoc/compodoc": "2.0.0",
@@ -236,8 +237,8 @@
     "@nestjs/schematics": "12.0.12",
     "@nestjs/testing": "12.3.2",
     "@swc/cli": "0.8.2",
-    "@swc/core": "1.16.20",
-    "@tus/s3-store": "2.0.9",
+    "@swc/core": "1.16.21",
+    "@tus/s3-store": "2.1.0",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
@@ -247,31 +248,32 @@
     "@types/node": "26.6.6",
     "@types/passport": "1.0.17",
     "@types/pg": "8.23.1",
-    "@vitest/coverage-v8": "5.0.5",
+    "@vitest/coverage-v8": "5.1.0",
     "better-auth": "1.7.14",
-    "bullmq": "6.5.1",
+    "bullmq": "6.5.4",
     "cross-env": "10.1.0",
     "drizzle-orm": "1.0.0-rc.5",
     "ioredis": "6.0.0",
-    "kysely": "0.29.7",
+    "kysely": "0.29.8",
     "mongodb": "7.7.0",
     "mongoose": "9.11.4",
     "mysql2": "3.24.6",
     "nodemon": "3.1.14",
-    "otpauth": "9.5.2",
+    "otpauth": "9.6.0",
     "oxfmt": "0.75.0",
     "oxlint": "1.90.0",
     "oxlint-tsgolint": "7.0.2005",
     "pg": "8.23.1",
+    "playwright-core": "1.64.1",
     "rimraf": "6.1.3",
-    "smtp-server": "3.21.1",
+    "smtp-server": "3.21.3",
     "tsx": "4.23.15",
     "tus-js-client": "4.3.1",
     "typeorm": "1.1.2",
     "typescript": "6.0.3",
     "unplugin-swc": "2.0.0",
-    "vite": "8.3.4",
-    "vitest": "5.0.5"
+    "vite": "8.3.5",
+    "vitest": "5.1.0"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/config.env.ts

@@ -59,7 +59,9 @@ const config: { [env: string]: IServerOptions } = {
         rpId: 'localhost',
         rpName: 'Nest Server Local',
       },
-      rateLimit: { enabled: true, max: 100, windowSeconds: 60 },
+      // 200: sign-in and sign-up get the strict half (100), the headroom the suites had while the limiter
+      // counted every IAM request of a client on one shared counter of 100
+      rateLimit: { enabled: true, max: 200, windowSeconds: 60 },
       secret: process.env.BETTER_AUTH_SECRET || 'BETTER_AUTH_SECRET_LOCAL_32_CHARS_M',
       // Social providers disabled in local environment (no credentials)
       socialProviders: {
@@ -367,7 +369,9 @@ const config: { [env: string]: IServerOptions } = {
         rpId: 'localhost',
         rpName: 'Nest Server Local',
       },
-      rateLimit: { enabled: true, max: 100, windowSeconds: 60 },
+      // 200: sign-in and sign-up get the strict half (100), the headroom the suites had while the limiter
+      // counted every IAM request of a client on one shared counter of 100
+      rateLimit: { enabled: true, max: 200, windowSeconds: 60 },
       secret: process.env.BETTER_AUTH_SECRET || 'BETTER_AUTH_SECRET_LOCAL_32_CHARS_M',
       // Social providers disabled in local environment (no credentials)
       socialProviders: {

package/src/core/common/helpers/graphql-ws-connection.helper.ts

@@ -82,6 +82,17 @@ export interface IWsConnectionRegistration {
    */
   carrier: object;
 
+  /** How the log names the connection when it is closed. Default `GraphQL WebSocket`. */
+  channel?: string;
+
+  /**
+   * The connection cannot be re-checked in place — an HTTP stream has no handshake to repeat — so every re-check ends
+   * it, and the client's reconnect passes the guards again. The end the re-check interval brings is planned and logged
+   * at debug; one an invalidation brings (sign-out, role or tenant change) is logged like every withdrawn
+   * authorization. `reauthenticate` is not called.
+   */
+  endsOnRecheck?: boolean;
+
   /**
    * Re-run the handshake's authentication. Resolves to the user the credential authenticates as NOW,
    * or to a falsy value when it no longer does. A rejection counts as falsy. Without it only the
@@ -105,7 +116,9 @@ export interface IWsConnectionIdentity {
 
 /** @internal The registered state of one connection. */
 export interface WsConnection {
+  readonly channel: string;
   readonly email?: string;
+  readonly endsOnRecheck: boolean;
   readonly iamId?: string;
   readonly reauthenticate?: () => any;
   readonly socket?: IWsConnectionSocket;
@@ -206,13 +219,15 @@ export function readWsTenantHeader(contextValue: any): string | undefined {
  * the handshake recorded on the carrier.
  */
 export function registerWsConnection(registration: IWsConnectionRegistration): void {
-  const { carrier, reauthenticate, socket, user } = registration;
+  const { carrier, channel, endsOnRecheck, reauthenticate, socket, user } = registration;
   if (!carrier || typeof carrier !== 'object') {
     return;
   }
   const userId = user?.id ?? user?._id;
   const connection: WsConnection = {
+    channel: channel || 'GraphQL WebSocket',
     email: typeof user?.email === 'string' ? user.email.toLowerCase() : undefined,
+    endsOnRecheck: endsOnRecheck === true,
     iamId: typeof user?.iamId === 'string' ? user.iamId : undefined,
     reauthenticate,
     socket,
@@ -246,15 +261,20 @@ export function getWsConnection(contextValue: any): undefined | WsConnection {
 
 /**
  * Close a connection whose authorization no longer holds. Idempotent; always answers `false` so a
- * caller can `return terminate(...)`.
+ * caller can `return terminate(...)`. `debug` is for a planned end, which says nothing about the user.
  */
-function terminate(connection: WsConnection, reason: string): false {
+function terminate(connection: WsConnection, reason: string, level: 'debug' | 'log' = 'log'): false {
   if (connection.terminated) {
     return false;
   }
   connection.terminated = true;
   liveConnections.delete(connection);
-  logger.log(`Closing GraphQL WebSocket of user ${connection.userId ?? '(unknown)'}: ${reason}`);
+  const message = `Closing ${connection.channel} of user ${connection.userId ?? '(unknown)'}: ${reason}`;
+  if (level === 'debug') {
+    logger.debug(message);
+  } else {
+    logger.log(message);
+  }
   try {
     // A close reason is limited to 123 bytes on the wire; these are short and ASCII.
     connection.socket?.close(WS_AUTHORIZATION_CHANGED_CLOSE_CODE, reason);
@@ -265,7 +285,15 @@ function terminate(connection: WsConnection, reason: string): false {
 }
 
 async function revalidate(connection: WsConnection): Promise<boolean> {
+  const invalidated = connection.stale;
   connection.stale = false;
+  if (connection.endsOnRecheck) {
+    // Nothing to check in place: the end IS the re-check, and the reconnect is authorized afresh. Only an invalidation
+    // says that the rights may have changed; the interval is the planned beat and must not read like a lost session.
+    return invalidated
+      ? terminate(connection, 'authorization invalidated, client reconnects')
+      : terminate(connection, 're-check interval reached, client reconnects', 'debug');
+  }
   try {
     let user = connection.user;
     if (connection.reauthenticate) {

package/src/core/common/interfaces/server-options.interface.ts

@@ -510,8 +510,14 @@ export type IBetterAuth = IBetterAuthWithoutPasskey | IBetterAuthWithPasskey;
  */
 export interface IBetterAuthEmailVerificationConfig {
   /**
-   * Whether to automatically sign in the user after email verification.
-   * @default true
+   * Whether `GET /iam/verify-email` signs in the browser that opens the verification link.
+   *
+   * Off by default, as in Better-Auth (12.3.0+; before, the framework defaulted to `true`). Switching it on signs in
+   * WHOEVER opens the link, to the account the link belongs to: someone who signs up with their own address and
+   * forwards the unopened link has the recipient's browser signed in to their account, and what the recipient then
+   * enters lands there (login CSRF). Only switch it on where verification links reach nobody but their owner.
+   *
+   * @default false
    */
   autoSignInAfterVerification?: boolean;
 
@@ -975,6 +981,17 @@ export interface IBetterAuthSocialProvider {
    */
   clientSecret: string;
 
+  /**
+   * Whether a first sign-in through this provider may create an account.
+   *
+   * Unset, the provider follows `betterAuth.emailAndPassword.disableSignUp`: with that set to `true` (since 12.3.0)
+   * nobody gets a new account through any provider, while existing users keep signing in. `false` opens sign-up
+   * through this provider although `disableSignUp` closes it otherwise; `true` closes it for this provider alone.
+   * Only a boolean counts: any other value follows `emailAndPassword.disableSignUp`.
+   * @default emailAndPassword.disableSignUp
+   */
+  disableSignUp?: boolean;
+
   /**
    * Whether this provider is enabled.
    * Defaults to true when clientId and clientSecret are provided.
@@ -2004,7 +2021,13 @@ export interface IAi {
    * Fallback total context window (input + output tokens) used to budget the
    * assembled session messages when a connection has no `contextWindow` set. When the
    * conversation (per user/session) would overflow, the oldest history turns are
-   * dropped and oversized payloads truncated before the LLM call.
+   * dropped and oversized payloads truncated before the LLM call. Native tool
+   * definitions count against that budget too (12.3.0+), and when the system prompt and
+   * tools take more than half of it, a warning names the connection once per process.
+   *
+   * A test that guards the prompt size against this value guards the connections WITHOUT
+   * a window of their own — the worst case — not the window a pinned or detected
+   * connection actually has. Name it that way; raising its limit removes that guard.
    * @default 8192
    */
   contextWindow?: number;
@@ -2061,14 +2084,14 @@ export interface IAi {
    * a caller sees and may run is decided server-side by the registry's role filter
    * (`AiToolRegistry.forUser()`), re-checked at execution time, and the
    * confirmation gate reads the `mutating`/`destructive` FLAGS, never the
-   * description text. (`AiTool.authorize()` runs in plan mode only — in auto mode
-   * and over MCP, data-level checks belong inside `execute()`.)
+   * description text. (`AiTool.authorize()` runs before every execution — auto
+   * mode, plan mode and MCP — on the call's arguments, never its description.)
    *
    * Applies to the EMULATED tool protocol, not to a provider as such. In auto mode
    * a connection with native tool calling receives every full description and schema
-   * through `buildToolSchemas()` regardless, so no truncation is applied there and no
-   * `search_tools` banner is emitted — capping would otherwise assert a truncation
-   * that the tool payload right next to it contradicts.
+   * through `buildToolSchemas()` regardless, and its catalog lists names only since
+   * 12.3.0 (`nativeToolCatalog`), so this cap has no effect there and no `search_tools`
+   * banner is emitted.
    *
    * **Plan mode always uses the emulated protocol** (it sends no native schemas), so a
    * native connection IS truncated there. Because plan mode returns a complete plan in
@@ -2091,6 +2114,17 @@ export interface IAi {
    */
   deferToolSummaryChars?: number;
 
+  /**
+   * What the system prompt's tool catalog holds for a connection with NATIVE tool calling in auto mode (12.3.0+).
+   * Such a connection receives every description and parameter schema in the tool payload, so by default the catalog
+   * lists names only — repeating the descriptions (and, without `deferToolSchemas`, the schemas) paid for every tool
+   * twice. `'full'` restores the full catalog, for a model that picks tools better with the descriptions in the prompt.
+   *
+   * Emulated connections and plan mode always get the full catalog: there it is the model's only source.
+   * @default 'names'
+   */
+  nativeToolCatalog?: 'full' | 'names';
+
   /** Maximum number of agent-loop iterations (tool round-trips). @default 5 */
   maxIterations?: number;
 
@@ -2142,11 +2176,32 @@ export interface IAi {
    * answers with a built-in consent page: sign-in through Better-Auth (password + 2FA),
    * then Allow / Deny. Replace it via `CoreModule.forRoot(env, { ai: { mcpOAuthService } })`.
    * Without `oauth`, MCP authenticates via the existing Bearer/session token.
+   *
+   * `tools/call` applies the admin's tool policies and a tool's `authorize()`, and asks the user before a
+   * tool that needs confirmation (`destructive`, or `mutating` under `ai.confirmation.mutating`) — see
+   * `confirmation`.
    * @default false
    */
   mcp?:
     | boolean
     | {
+        /**
+         * Whether MCP asks the user — through MCP elicitation, a yes/no form the client shows — before a
+         * `destructive` tool, or a `mutating` one under `ai.confirmation.mutating` (12.3.0+). The tool runs only
+         * on an explicit yes; a client without the `elicitation` capability gets a refusal. `authorize()` runs
+         * either way, and an admin's `ask` tool policy always asks.
+         *
+         * - `true` / `{}` / unset: MCP asks, unless a user switched it off for themselves
+         *   (`PUT /ai/settings`, `updateAiSettings` — like a "bypass permissions" mode).
+         * - `false`: MCP asks nobody, unless a user switched it on for themselves.
+         * - `{ default, enforced }`: `default` as above; `enforced: true` ignores every user's choice and
+         *   refuses a change with 403.
+         *
+         * Only `false` / `default: false` switch the default off and only `enforced: true` enforces, so a
+         * misspelt value never relaxes the gate.
+         * @default { default: true, enforced: false }
+         */
+        confirmation?: boolean | { default?: boolean; enforced?: boolean };
         enabled?: boolean;
         oauth?: boolean;
         /**
@@ -2164,6 +2219,17 @@ export interface IAi {
          */
         oauthLoginUrl?: string;
         oauthSecret?: string;
+        /**
+         * Serve `/ai/mcp` without sessions: every POST builds its own server and transport for the
+         * authenticated user and ends with the response, no `mcp-session-id` is issued, and GET /
+         * DELETE answer 405. Any replica can answer any request, so no sticky sessions are needed
+         * behind a load balancer. The price is what a session carries: server-initiated messages
+         * (notifications, SSE streams) and server-initiated requests — MCP elicitation among them, so a
+         * tool that needs confirmation (`confirmation`) is refused unless the user or `confirmation`
+         * switched the question off. A server that only offers read tools uses none of it (12.3.0+).
+         * @default false
+         */
+        stateless?: boolean;
       };
 
   /** Rate limiting for prompts. */
@@ -3509,6 +3575,16 @@ export interface IServerOptions {
     path?: string;
   };
 
+  /**
+   * Offline sync (`docs/offline-sync-protocol.md`): `GET/POST /sync/{model}` for the models whose service carries
+   * `@SyncService()` and whose model is declared with `@PersistedModel({ sync })`. Presence implies enabled — `true`
+   * or `{}` enables it with the defaults, `{ enabled: false }` pre-configures without enabling. Absent: no route, no
+   * store, no code path.
+   *
+   * @since 12.2.0
+   */
+  sync?: boolean | ISync;
+
   /**
    * System setup configuration for initial admin creation.
    *
@@ -3831,6 +3907,125 @@ export interface IS3Config {
   stagingBucket?: string;
 }
 
+/**
+ * Offline sync (`sync`, presence implies enabled). See `src/core/modules/sync/README.md`.
+ *
+ * @since 12.2.0
+ */
+export interface ISync {
+  /**
+   * Secret the pull cursors are signed with (HMAC; the key is derived from it). Falls back to the
+   * `SECRETS_ENCRYPTION_KEY` environment variable. REQUIRED in `production` / `staging` — the boot fails without it;
+   * elsewhere an insecure development default is used with a warning. Changing it answers every client's next pull
+   * with a full resync (`410 invalid`).
+   */
+  cursorSecret?: string;
+
+  /**
+   * Pre-configure without enabling.
+   * @default true (when the object is present)
+   */
+  enabled?: boolean;
+
+  /**
+   * Hints that a synchronized model changed (protocol §9): SSE `GET /sync/hints` and the GraphQL subscription
+   * `syncHint`, carrying `{ model, at }` only, to callers with the model's pull roles and — on a tenant-scoped model —
+   * for changes in their own tenants. A hint only means "pull now": a client works without them. `false` switches both
+   * channels off; with `redis` a hint reaches the subscribers of every replica.
+   * @default on (both channels)
+   */
+  hints?:
+    | boolean
+    | {
+        /**
+         * At most one hint per model and tenant within this many milliseconds — a burst of writes is one hint.
+         * @default 250
+         */
+        debounceMs?: number;
+        /** @default true (when the object is present) */
+        enabled?: boolean;
+        /**
+         * The GraphQL subscription `syncHint` (only where GraphQL is enabled).
+         * @default true
+         */
+        graphql?: boolean;
+        /**
+         * The SSE stream `GET /sync/hints`.
+         * @default true
+         */
+        sse?: boolean;
+      };
+
+  /**
+   * Route prefix of the sync endpoints.
+   * @default 'sync'
+   */
+  path?: string;
+
+  pull?: {
+    /**
+     * Records per page when the client sends no `limit`.
+     * @default 200
+     */
+    defaultLimit?: number;
+    /**
+     * Upper bound of the serialized size of one page; a page ends before it would exceed it (it always holds at least
+     * one item when one is pending).
+     * @default 1048576 (1 MiB)
+     */
+    maxBytes?: number;
+    /**
+     * Highest `limit` a client may ask for (at most 1000).
+     * @default 1000
+     */
+    maxLimit?: number;
+    /**
+     * MongoDB only: the window W a pull run re-reads below its previous start (plan §3.4). Changes stamped within W
+     * before a run started may be repeated; a write that takes longer than W from its stamp until it is visible would
+     * be missed, so W must cover the longest such write.
+     * @default replica set / sharded: the server's `transactionLifetimeLimitSeconds` (60 when unreadable) + 30;
+     *   standalone: 30
+     */
+    windowSeconds?: number;
+  };
+
+  push?: {
+    /**
+     * Items per push request; more answer 400.
+     * @default 100
+     */
+    maxItems?: number;
+  };
+
+  /**
+   * Per-user rate limits of pull and push (fixed window; exact across replicas when `redis` is configured). `false`
+   * switches both off, `{ pull: false }` one of them.
+   * @default pull 120 / 60 s, push 60 / 60 s
+   */
+  rateLimit?:
+    | false
+    | {
+        pull?: false | { max?: number; windowSeconds?: number };
+        push?: false | { max?: number; windowSeconds?: number };
+      };
+
+  retention?: {
+    /**
+     * How long the outcome of a pushed mutation is kept, so a repeat is answered with it (protocol §6.5).
+     * @default 30
+     */
+    mutationsDays?: number;
+    /**
+     * How long a tombstone is kept. Every hour (on one replica, under a lease) the purge first moves the model's
+     * horizon to this age, then deletes the older tombstones for good; a client whose cursor is older than the horizon
+     * answers its next pull with a full resync (`410 horizon`). `false` keeps tombstones for ever; an invalid value
+     * (zero, negative, not a number) falls back to the default — never to "purge everything".
+     * @default 90
+     */
+    tombstonesDays?: false | number;
+  };
+}
+
 export interface ISystemSetup {
   /**
    * Whether system setup is enabled.
@@ -4258,6 +4453,10 @@ interface IBetterAuthBase {
      * Disable user registration (sign-up) via BetterAuth.
      * Passed through to better-auth's native emailAndPassword.disableSignUp.
      * Custom endpoints (GraphQL + REST) also check this flag early.
+     * Since 12.3.0 it closes social sign-up too: every configured social provider receives it as its own
+     * `disableSignUp`, so a first sign-in through Google, GitHub etc. creates no account, while existing users keep
+     * signing in. `socialProviders.<name>.disableSignUp: false` opens one provider deliberately. Plugins a project
+     * registers itself through `options.plugins` are not covered.
      * The Swagger document built by `setupSwagger()` then leaves out `POST /iam/sign-up/email`,
      * which would answer `SIGNUP_DISABLED` to every caller.
      * @default false
@@ -4831,6 +5030,26 @@ export interface ICoreModuleOverrides {
     service?: Type<any>;
   };
 
+  /**
+   * Override the offline sync endpoints, the hint subscription and their service (`sync` config).
+   *
+   * - `controller` must extend `CoreSyncController` (e.g. to release a sync scope to API tokens)
+   * - `hintsController` must extend `CoreSyncHintsController` (`GET /sync/hints`, e.g. for API tokens there too)
+   * - `resolver` must extend `CoreSyncResolver` (the `syncHint` subscription)
+   * - `service` must extend `CoreSyncService`
+   *
+   * @example
+   * ```typescript
+   * { sync: { controller: SyncController } }
+   * ```
+   */
+  sync?: {
+    controller?: Type<any>;
+    hintsController?: Type<any>;
+    resolver?: Type<any>;
+    service?: Type<any>;
+  };
+
   /**
    * Override AI module collaborators with project-specific subclasses.
    *
@@ -4853,6 +5072,7 @@ export interface ICoreModuleOverrides {
    * - `slotService` must extend `CoreAiSlotService`
    * - `toolGrantService` must extend `CoreAiToolGrantService`
    * - `toolPolicyService` must extend `CoreAiToolPolicyService`
+   * - `userSettingService` must extend `CoreAiUserSettingService`
    *
    * @example
    * ```typescript
@@ -4886,6 +5106,7 @@ export interface ICoreModuleOverrides {
     slotService?: Type<any>;
     toolGrantService?: Type<any>;
     toolPolicyService?: Type<any>;
+    userSettingService?: Type<any>;
   };
 
   /**

package/src/core/common/interfaces/service-options.interface.ts

@@ -32,6 +32,11 @@ export interface ServiceOptions {
   // If truly: create mode is activated
   create?: boolean;
 
+  // The id `create()` gives the new record: on a synchronized model the id a client chose offline, in the model's
+  // format (refused otherwise), on any other model a 24-character hex id. Passed beside the input because an input
+  // class keeps only the fields it declares: an `id` inside the input is lost the moment `inputType` maps it
+  createId?: string;
+
   // Current user to set ownership, check rights and other things
   currentUser?: {
     [key: string]: any;
@@ -42,9 +47,19 @@ export interface ServiceOptions {
   // Field selection for results (will be overwritten by populate if populate was set)
   fieldSelection?: FieldSelection;
 
+  // Conditional change of a synchronized model (`@PersistedModel({ sync })`): `update()` and `delete()` apply only
+  // when the stored record still has this version, in one atomic statement, and throw a 409 (`VersionConflictError`)
+  // otherwise. Refused on a model that is not synchronized
+  expectedVersion?: number;
+
   // Determines whether all restrictions are ignored
   force?: boolean;
 
+  // Read a synchronized model's tombstones too — its deleted records, which every other read leaves out (get, find,
+  // findOne, findAndCount, distinct). Reads only: update() and delete() never touch a tombstone and answer 404 for one.
+  // Applies to the main model only: a populated reference to a tombstone stays empty
+  includeTombstones?: boolean;
+
   // Overwrites type of input (array items)
   inputType?: new (...params: any[]) => any;
 

package/src/core/common/persistence/core-persistence.module.ts

@@ -4,8 +4,15 @@ import { getConnectionToken, getModelToken } from './mongo/mongoose-compat.js';
 import type { Model } from 'mongoose';
 
 import { registerModelSchema } from './model-metadata.registry.js';
+import { isDeclaredSchema } from './mongo/model-declarations.js';
+import { applySyncSchema, assertSyncCollectionReady } from './mongo/sync-schema.plugin.js';
 import { MongooseDataStore } from './mongoose-data-store.js';
-import { getPersistedModelOptions, getPersistedModelOptionsByName } from './persisted-model.decorator.js';
+import {
+  getPersistedModelOptions,
+  getPersistedModelOptionsByName,
+  getPersistedSyncByName,
+} from './persisted-model.decorator.js';
+import { resolveSyncOptions } from './sync-model.js';
 import {
   bindStoreToModel,
   getPersistenceRuntime,
@@ -46,7 +53,15 @@ export interface PersistenceModelDefinition extends ModelDefinition {
 export class CorePersistenceModule {
   static forFeature(models: PersistenceModelDefinition[]): DynamicModule {
     for (const model of models) {
-      registerModelSchema(model.name, model.schema);
+      const sync = resolveSyncOptions(
+        model.model ? getPersistedModelOptions(model.model)?.sync : getPersistedSyncByName(model.name),
+        model.name,
+      );
+      // Described as declared first, then prepared: the descriptor must not see the Mongoose sync paths
+      registerModelSchema(model.name, model.schema, sync);
+      if (sync && !isDeclaredSchema(model.schema)) {
+        applySyncSchema(model.schema, sync);
+      }
       registerPersistedModel({
         declaredSource:
           model.dataSource ??
@@ -88,6 +103,10 @@ export class CorePersistenceModule {
             ? // No SQL source and no MongoDB connection: the project runs without a database (`database: false`)
               unavailableStore(model.name, 'the project runs without a database (`database: false`)')
             : new MongooseDataStore(mongooseModel);
+        // A synchronized model on MongoDB: the collection must hold nothing from before it was synchronized
+        if (store.capabilities.mongoosePopulate && store.capabilities.changeOrder) {
+          await assertSyncCollectionReady(mongooseModel);
+        }
         registerDataStore(model.name, store);
         bindStoreToModel(mongooseModel, store);
         // A stand-in already refuses, naming the cause; a real Mongoose model of a model routed elsewhere is made to

package/src/core/common/persistence/data-source.runtime.ts

@@ -13,6 +13,7 @@ import {
 } from './data-source.config.js';
 import type { ModelDescriptor } from './model-descriptor.interface.js';
 import { getModelDescriptor } from './model-metadata.registry.js';
+import { withSequenceField } from './sync-model.js';
 import { MongooseDataStore } from './mongoose-data-store.js';
 import {
   getPersistedModels,
@@ -190,10 +191,12 @@ export class DataSourceRuntime implements PersistenceRuntime {
   }
 
   private async openStore(source: ResolvedDataSource, name: string): Promise<DataStore<any>> {
-    const model = getModelDescriptor(name);
-    if (!model) {
+    const declared = getModelDescriptor(name);
+    if (!declared) {
       throw new Error(`No descriptor for model "${name}" — register it with CorePersistenceModule.forFeature()`);
     }
+    // A synchronized model's table also carries its commit-ordered change position (offline-sync plan §3.4)
+    const model = withSequenceField(declared);
     const app = await this.executor(source);
     const dialect = this.dialect(source);
     let changes: SchemaChange[];