@lenne.tech/nest-server 12.1.1 → 12.2.0

package/.claude/rules/architecture.md

@@ -70,6 +70,7 @@ proves the build loads and runs with them unresolvable. Rules: `.claude/rules/pe
 | **Hub** | Build-free ADMIN-gated operator cockpit at `/hub` (config-gated per environment; 17 panels, runtime collectors, mailbox, admin actions) |
 | **Migrate** | Database migration utilities |
 | **Permissions** | ADMIN-gated security-map report (routes + roles + `@Restricted` fields); also surfaced in the Hub's "Routes / Permissions" panel |
+| **Sync** | Opt-in (`sync`) offline sync for models declared `@PersistedModel({ sync })`: pull by cursor, push with idempotency and conflict strategies, resync on access loss — through the model's CrudService; change hints over SSE and GraphQL, filtered per subscriber; hourly tombstone purge under a lease |
 | **SystemSetup** | Initial admin creation for fresh deployments |
 | **Tus** | Resumable file uploads via tus.io protocol |
 | **User** | Core user management functionality |

package/.claude/rules/configurable-features.md

@@ -325,6 +325,7 @@ This pattern is currently applied to:
 | Multi-Tenancy | `multiTenancy` | Presence Implies Enabled | **`excludeSchemas` is an OFF SWITCH for isolation, per model** — a listed schema gets no tenant filter at all; since 11.35.0 the plugin WARNS once per model when the excluded schema declares `tenantId` (i.e. was built for isolation). The framework's own docs recommended `['User', 'Session']` until then; that is withdrawn — it is only right for the global-user model. Since 11.35.0 GraphQL operations over the WEBSOCKET also run inside a `RequestContext` (`CoreModule` installs a context-aware `execute`/`subscribe` pair inside `subscriptions`, where `ApolloDriver` forwards it): the tenant comes from the handshake header validated against an active membership, else from the subscriber's memberships, and an unresolvable tenant leaves the safety net to refuse the read rather than returning everything. `headerName: 'x-tenant-id'`, `membershipModel: 'TenantMember'`, `adminBypass: true`, `excludeSchemas: []`, `roleHierarchy: { member: 1, manager: 2, owner: 3 }`, `cacheTtlMs: 30000` (0 disables, process-local). System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives before real roles; method-level system roles take precedence; membership validated for context when system role grants access + header present. Hierarchy roles use level comparison, normal roles use exact match. Use `DefaultHR` or `createHierarchyRoles()` for type-safe role constants. Bypass: `RequestContext.runWithBypassTenantGuard()`. Cache invalidation: `invalidateUser(userId)` / `invalidateAll()` are **instance** methods on the singleton `CoreTenantGuard` — inject it and call `this.tenantGuard?.invalidateUser(userId)`, never `CoreTenantGuard.invalidateUser(...)` (there is no static). With `redis` configured, both additionally BROADCAST the invalidation to every replica (`<keyPrefix>:tenant-cache:invalidate` pub/sub); without Redis they clear the local process only, so other replicas stay stale until `cacheTtlMs`. A received broadcast clears locally without re-publishing. **`isTenantActive` (11.42.0)**: optional hook `(tenantId, { connection, store }) => boolean \| Promise<boolean>`, absent = every tenant active (no change). `store(modelName)` (12.x, db-agnostic) is the data store of a model registered with `CorePersistenceModule.forFeature()`, wherever `database` routes it, and THROWS for any other model — an `undefined` would read as "active" in a hook written with `?.` and open every deactivated tenant. Asked AFTER the membership check on every path that establishes a tenant: 403 on header paths and for tenant API tokens, no enrichment on `S_EVERYONE`, dropped from the header-less tenant list, no tenant for a NEW WebSocket subscription, and since 11.42.3 an OPEN one is closed with 4403 on `invalidateTenant()` (or at its next event once `graphQl.subscriptionRevalidationMs` has passed — see the GraphQL Subscription Re-check row); an admin under `adminBypass` is exempt (someone must be able to switch it back on). Only `false` deactivates. Cached for `cacheTtlMs`; `invalidateTenant(tenantId)` clears and broadcasts (`{ scope: 'tenant' }`). A function, so `config.env.ts` only — not reachable through `NSC__*`. **`adminBypass: false` (11.42.0)** additionally withholds two things that went around it: `CoreUserService.update()` refuses changing another account's e-mail or password (`assertCredentialChangeAllowed()`, administrator targets included — promote-then-change — system work without a current user exempt), and the AI tool registry grants no ADMIN bypass |
 | GraphQL Subscription Re-check | `graphQl.subscriptionRevalidationMs` | Numeric — `0` = STRICTEST, `false` = off, invalid → default (a fifth shape: Family C's "invalid never means unbounded", but `0` asks for MORE checking, not less) | **30000 since 11.42.3.** Before, a WebSocket was authorized once, at the handshake, and every event and operation on it ran on that snapshot until the client reconnected. Every connection a `CoreModule` `onConnect` accepts is now registered (`registerWsConnection()`) and re-checked — at once when an invalidation names it (`CoreTenantGuard.invalidateUser()` / `invalidateTenant()` / `invalidateAll()`, `CoreUserService.setRoles()` and role/verification `update()`s, the legacy password reset, and Better-Auth deleting a session through `wsSessionRevocationPlugin()`), and otherwise before the next event or operation once the last check is older than this value. The check re-runs the handshake's own authentication (session store, Better-Auth JWT signature/expiry, or for legacy tokens `CoreAuthService.verifyJwt()` — signature/expiry, verified on the WebSocket since 11.42.3 — plus the device binding) and the tenant resolution; any difference in user id, roles, verification state or tenant scope closes the socket with **4403**, which the graphql-ws client retries — the user continues with current rights or is refused at the handshake. `0` re-checks on every event and operation (one session lookup each); `false` switches only the TIME-based check off, invalidations still apply. Process-local registry: an invalidation reaches other replicas only where a Redis broadcast carries it — the tenant guard's (memberships, tenants) and, since 12.1.1, the Better-Auth user mapper's (`invalidateUserCache()`: roles and verification of IAM users); everything else is bounded by the interval. A project that replaces `onConnect` through `graphQl.driver.subscriptions` must call `registerWsConnection()` itself to keep this. Implementation: `common/helpers/graphql-ws-connection.helper.ts` |
 | API Tokens | `apiTokens` | Boolean Shorthand + Presence Implies Enabled — absent = off | `prefix: 'ltt'`, `scopes: []` (vocabulary; empty = no token creatable, boot warning), `manageRole`: highest hierarchy role, `maxAssertionLifetimeSeconds: 900` (invalid → default, never unbounded — Family C), `rateLimit: { max: 600, windowSeconds: 60 }` per token (**on by default**, `false` disables; Redis-shared when configured), `userTokens: true`, `tenantTokens: true` (effective only with `multiTenancy`), `encryptionKey` → `SECRETS_ENCRYPTION_KEY` → dev default (boot FAILS in production/staging). Top-level, NOT under `multiTenancy`: user tokens must work without it. **Deny by default**: every guard refuses a token on a route without `@ApiTokenScopes()`, public routes included, via ONE shared function (`enforceApiTokenRoute`) called BEFORE each guard's public-route shortcut. USER tokens act as their user with global roles REMOVED (no admin bypass); TENANT tokens act with the lowest hierarchy role in their own tenant, and a route guarded ONLY by `S_SELF` / `S_CREATOR` refuses them (a tenant token is nobody's self — skipping those roles would grant for any target). A tenant token depends on no member, so it outlives an off-boarded or deleted tenant until the project calls `deleteAllForTenant()`. The boot refuses a hierarchy in which that lowest role reaches `manageRole`. A prefixed credential that fails answers 401 on every route (not anonymous); `CoreBetterAuthMiddleware` skips prefixed credentials entirely, cookie fallback included. A password reset that ends the user's sessions ends their USER tokens too (legacy reset always; IAM reset while `betterAuth.emailAndPassword.revokeSessionsOnPasswordReset` is on), wired through `core-api-token.registry.ts` so neither reset path imports the optional module. Implementation: `src/core/modules/api-token/` |
+| Offline Sync | `sync` | Boolean Shorthand + Presence Implies Enabled — absent = off | **Absent → nothing registered**: no route, no infrastructure model, no listener on the write paths. `true` / `{}` enables `GET /sync/{model}` (pull) and `POST /sync/{model}` (push) for every model whose CrudService carries `@SyncService({ model, createInput, updateInput })` and whose model is declared with `@PersistedModel({ sync: { roles, strategy } })`. Defaults: `path: 'sync'`, `pull: { defaultLimit: 200, maxLimit: 1000 (ceiling 1000), maxBytes: 1048576 }`, `push: { maxItems: 100 }`, `retention: { mutationsDays: 30, tombstonesDays: 90 }`, `hints: { debounceMs: 250 }`, `rateLimit: { pull: { max: 120, windowSeconds: 60 }, push: { max: 60, windowSeconds: 60 } }` per user (`false` switches both or one off; Redis-shared when configured). `cursorSecret` → `SECRETS_ENCRYPTION_KEY` → development default (boot FAILS in production/staging); changing it answers every cursor `410 invalid`. `pull.windowSeconds` (MongoDB only) overrides the derived window W: replica set or sharded — the server's `transactionLifetimeLimitSeconds` (60 when unreadable) + 30, standalone — 30; it must cover the longest time a write takes from its stamp until it is visible, a smaller one loses changes for good. **Operation roles are the model's** (`sync.roles.pull/create/update/delete`): the roles a project puts on its own routes never reach `/sync`, and an operation without roles is ADMIN only (boot warning). Every pull and push runs through the model's CrudService (`process()`, `securityCheck()`, tenant policy, RLS). Without `X-Tenant-Id` a request spans the caller's memberships. Cookie pushes need `Content-Type: application/json`; while cookies are in use `Sec-Fetch-Site: cross-site` and an untrusted `Origin` answer 403. API tokens are refused unless a project controller releases a scope. Error codes `LTNS_0700`–`LTNS_0799`. **Hints (12.x, DEV-3902)**: `GET /sync/hints` (Server-Sent Events, event `change`, `?models=` narrows) and the GraphQL subscription `syncHint(models)` tell a client "pull now" — payload `{ model, at }` only, never content or ids. Sent from `CrudService.create()` / `update()` / `delete()` of a synchronized model (`CoreSyncService.notifyChange()` for a write past the CrudService), at most one per model and tenant per `hints.debounceMs`; received only by a subscriber with the model's pull roles and access to the tenant. With `redis` every replica's subscribers receive them (`<keyPrefix>:sync:hints`), without it only this replica's. A stream is registered like a WebSocket (`registerWsConnection()`) and ENDS on every invalidation or re-check, the client reconnects with its current rights. `hints: false` switches both channels off, `hints.sse` / `hints.graphql: false` one; no hint is a correctness signal — a missed one is caught by the next pull. **Tombstone purge**: tombstones older than `retention.tombstonesDays` (90; `false` keeps them for good, an invalid value → 90) are hard-deleted every hour on one replica (lease: Redis → the default SQL source's `lt_locks` → `cron-locks`), after the retention horizon moved past them — a client whose cursor predates the horizon answers `410 horizon`. `purgeTombstones()` runs it by hand. **Data migrations** of a synchronized table go through `runSqlMigration()` with `{ syncUpdate: { table, set, where } }`, which raises `version` and numbers the rows like a store write. **Client duties** (delete local data on logout and account switch, no token in `localStorage`, no cached API responses): `src/core/modules/sync/SECURITY.md`; reference test clients (PWA on IndexedDB, Node on SQLite) in `tests/clients/`. Overrides: `CoreModule.forRoot(env, { sync: { controller, hintsController, resolver, service } })` — the hints route is a controller of its own, registered before the pull route, because a project controller re-declaring `pull()` (`@Get(':model')`) would otherwise read `hints` as a model name. The purge deletes in batches of 1000 by id (one `DELETE … WHERE deleted_at < ?` locks every row it scans on MySQL / MariaDB). Implementation: `src/core/modules/sync/` (README, INTEGRATION-CHECKLIST), protocol `docs/offline-sync-protocol.md` |
 | BetterAuth Tenant Skip | `betterAuth.skipTenantCheck` | Explicit Boolean | `true` (default). When `true` and no `X-Tenant-Id` header is sent, IAM endpoints (controller + resolver) skip `CoreTenantGuard` tenant validation. When header IS present, normal membership validation runs regardless. Set `false` for tenant-aware auth scenarios (subdomain-based, invite links, SSO per tenant) |
 | Debug Process Input | `debugProcessInput` | Explicit Boolean | `false` (default). When `true`, logs a debug message when `prepareInput()` changes the input type during `process()`. Has performance cost due to `JSON.stringify` on every `process()` call — enable only for debugging |
 | JSONTransport Production Guard | `email.smtp` with `jsonTransport` | Runtime Guard | Throws `Error` when `email.smtp` has a truthy `jsonTransport` property in `production` or `staging` environments (read from config `env` field). JSONTransport silently discards all outgoing mail — the guard prevents accidental misconfiguration that causes password-reset, 2FA, and verification emails to vanish. Use `{ jsonTransport: true }` only in CI/e2e/local environments |

package/.claude/rules/package-management.md

@@ -401,6 +401,13 @@ any has moved:
    second version of the same consumer is a path nobody assessed, and comparing by name alone let
    one ride along on the other's declaration, with the winner decided by lockfile order.
 
+**Several consumers (12.1.1+)** are joined with ` + `, each at its assessed version —
+`'@nestjs/cli@12.0.11 + nodemon@3.1.14 cannot use 11.0.1'`. One vulnerable package often sits under
+several dev tools at once, and before this a declaration could name only one, so such a finding had no
+honest way in. Every listed consumer gets checks 1 and 3, and one more: a listed consumer that no
+longer pulls an affected package fails too (mutation `unusable-fix-accepts-idle-consumer`), because a
+list is where a path that is gone would otherwise keep covering.
+
 The third check reads **both halves** of the lockfile. `importers:` holds what the repository itself
 declares (`.`, `projects/api`, `projects/app`), `snapshots:` the edges between third-party packages
 — and the first is the likelier production path, because a direct dependency can simply be raised.
@@ -430,7 +437,15 @@ plus one for the opposite failure, a guard that rejects a declaration which is s
 matters just as much: a check that cries wolf on correct entries is a check that gets switched off,
 which is how the hole this feature closes came about in the first place.
 
-**No current entry (since 2026-10-24).** `GHSA-vfj7-8cjw-p6xm` (braces, via nodemon / npm-watch) was
+**Current entries (since 2026-10-31, owner decision, DEV-3899).** `GHSA-g3hv-75wg-m249` (minimatch
+`< 11.0.1`) and `GHSA-3g3m-2fjr-6pw4` (glob `<= 14.0.1`), both moderate, both fixed only in a new major
+released 2026-10-27 that none of their consumers can take yet — five for minimatch (`@nestjs/cli` pins
+10.2.6 exactly), rimraf for glob. The justification is in the comment above `ignoreGhsas`, the
+declarations in `unusableFixConsumers`. `tests/unit/audit-suppression-scope.spec.ts` keeps glob out of
+the production tree and allows minimatch there only under `@ts-morph/common` (ts-morph, the Permissions
+module's scanner, matching globs the developer writes) — its `prodVia` form.
+
+**Before that, no entry from 2026-10-24.** `GHSA-vfj7-8cjw-p6xm` (braces, via nodemon / npm-watch) was
 listed from 2026-10-11 to 2026-10-24: a dev-tooling-only path of an advisory with no patched release
 at all. GitHub withdrew the advisory on 2026-10-23, and `check:overrides` reported the entry as
 obsolete on the next run — the guard doing exactly its job, since a withdrawal changes nothing in

package/.claude/rules/persistence.md

@@ -91,6 +91,32 @@ On every SQL database a path segment `__proto__`, `constructor` or `prototype` i
 object from path segments would otherwise reach `Object.prototype` — on MySQL that switched tenant isolation off for the
 whole process. Never build an update path from request data without validating it against the model.
 
+## Synchronized models (offline sync, 12.x)
+
+`@PersistedModel({ sync: true | { idFormat, scope } })` makes a model synchronizable (`common/persistence/sync-model.ts`,
+plan `.claude/plans/offline-sync/PLAN.md` §3.3). Only a model registered with `CorePersistenceModule.forFeature()`; a
+model without `sync` keeps every behaviour bit for bit.
+
+| Rule | Why |
+|---|---|
+| `version`, `deletedAt` and the change position (`syncSeq` on SQL, `syncAt` on MongoDB) are written by the store only — never put them in an input or update | they are stripped anyway; a version the caller could set would defeat the conditional change, a `deletedAt` would delete with update rights |
+| Every framework delete of such a model leaves a tombstone (`CrudService.delete()`, `deleteById/One/Many`); `hardDelete` with `includeTombstones` is the purge's | a hard delete through a normal route reaches no client — the record stays on every device |
+| Reads leave tombstones out; only the sync module passes `includeTombstones` (`ServiceOptions` or the port's options) | counts, distinct values and populated references must not show deleted records |
+| A conditional change is `ServiceOptions.expectedVersion` on `CrudService.update()` / `delete()` — one statement with the version as its condition, `VersionConflictError` (409) on another version | read-then-write lets two clients both apply their change |
+| A unique index applies to live records only, also for a missing value (MongoDB partial index, PostgreSQL `NULLS NOT DISTINCT … WHERE deleted_at IS NULL`, MySQL / MariaDB virtual `lt_lk_*` columns); a unique index inside an embedded object is refused | delete-then-recreate with the same value must work; tombstones keep no content, so their missing values must not collide |
+| Making an EXISTING model synchronized is a migration on every database. SQL: the boot refuses with the statements (the `deleted_at` column, the live-only index, `DROP` of the full index it replaces); the other columns, the trigger and the numbering of existing rows follow automatically. MongoDB: the boot refuses with `SyncMigrationRequiredError` — drop the old unique indexes and give every document `version`, `deletedAt` and `syncAt` (the error prints both statements); Mongoose then builds the live-only indexes | a full unique index left in place refuses the second tombstone; a document without `syncAt` never reaches a client |
+| No TTL on a synchronized model (refused at registration); no `replaceOne` / pipeline update on MongoDB (refused) | an expired record vanishes without a tombstone; a replacement carries no version increment |
+| On SQL the database numbers changes: a trigger per table (PostgreSQL: advisory lock + sequence; MySQL / MariaDB: the counter row `lt_sync_counters`); a write that sets `sync_seq` itself is not renumbered. On MySQL / MariaDB every store write takes its number LAST instead (marks the row `-1`, then numbers it before COMMIT) | tier-2/3 writes are numbered too; on MySQL / MariaDB `FOR UPDATE` locks index gaps, and a write that held the counter while it waited for one deadlocked with a multi-row write (measured) — a multi-row write outside the store must lock its rows first and set the numbers last, as `updateRows()` does |
+| On MySQL with binary logging, creating the triggers needs `SUPER` or `log_bin_trust_function_creators=1` for the owner account | MySQL refuses `CREATE TRIGGER` otherwise (error 1419); the application account never needs it |
+| MongoDB stamps updates with `$currentDate` and inserts with the server clock read through `hello.localTime` — never `Date.now()` | application clocks differ between replicas; the pull's window relies on one clock |
+| A model reaches `/sync` only with `@SyncService({ model, createInput, updateInput })` on its CrudService AND `sync.roles` for every operation (`pull`, `create`, `update`, `delete`); without roles an operation is ADMIN only | the roles of a project's own routes never reach the sync routes — a push without its own roles lets any reader overwrite |
+| The sync module reads and writes through the model's CrudService only (`find`, `get`, `create`, `update`, `delete` with `expectedVersion`), never `native()` / `raw()` or the driver name; what differs it asks `store.capabilities` and `store.changeClock()` | the security pipeline (`process()`, `securityCheck()`, tenant policy, RLS) is the point; DEV-3819 forbids a lean path |
+| A write that moves a synchronized record to another tenant or away from a scope user OUTSIDE `CrudService.update()` (store, native API, migration) calls `CoreSyncService.bumpAccessEpoch()` | only `CrudService.update()` reports such a move; otherwise the clients that lost the record keep their copy until a full resync |
+| A write of a synchronized model OUTSIDE the CrudService (store, native API, migration) calls `CoreSyncService.notifyChange(model, tenantIds)` | only `CrudService.create()` / `update()` / `delete()` send a hint; without it online clients learn of the change at their next scheduled pull instead of at once — nothing is lost, it is only later |
+| A data migration that changes rows of a synchronized table uses `runSqlMigration()` with `{ syncUpdate: { table, set, where } }`, never a bare `UPDATE` | the helper raises `version` and numbers the rows like a store write; a bare `UPDATE` keeps the old version, so a client's conditional push overwrites the migrated value without a conflict |
+| Tombstones are removed only by the purge (`retention.tombstonesDays`), which moves the retention horizon first | a tombstone removed before the horizon passes it is never seen by a client whose cursor is older — the record stays on that device |
+| A client id on create goes through `ServiceOptions.createId`, never inside the input | an input class keeps only the fields it declares — mapping it drops an `id` |
+
 ## Tests
 
 A suite proves a behaviour on both databases: the `e2e` vitest project runs it on MongoDB, the `postgres` project on

package/.claude/rules/testing.md

@@ -32,10 +32,10 @@ that every `*.spec.ts` / `*.test.ts` in the repo is claimed by **exactly one** r
 mis-named suite fails the build instead of silently passing. Type-only tests
 (`tests/types/*.type-test.ts`) are compiled by `pnpm run test:types`, never executed.
 
-## Infrastructure containers (Redis + S3 + PostgreSQL + MySQL + MariaDB)
+## Infrastructure containers (Redis + S3 + PostgreSQL + MySQL + MariaDB + MongoDB replica set)
 
-**Twenty** e2e suites talk to a **real** Redis, a **real** S3-compatible store and/or a **real**
-PostgreSQL, MySQL or MariaDB rather than a mock, and they **fail loudly** when it is missing — a silently skipped
+**Twenty-two** e2e suites talk to a **real** Redis, a **real** S3-compatible store and/or a **real**
+PostgreSQL, MySQL, MariaDB or MongoDB replica set rather than a mock, and they **fail loudly** when it is missing — a silently skipped
 infrastructure test is how an untested driver ships:
 
 | Suite | Needs |
@@ -60,13 +60,15 @@ infrastructure test is how an untested driver ships:
 | `tests/persistence-mysql-executor.e2e-spec.ts` | MySQL + MariaDB |
 | `tests/persistence-mysql-schema.e2e-spec.ts` | MySQL + MariaDB |
 | `tests/persistence-mysql-wiring.e2e-spec.ts` | MySQL + MariaDB |
+| `tests/sync-contract.e2e-spec.ts` | PostgreSQL + MySQL + MariaDB + MongoDB replica set (and MongoDB) |
+| `tests/sync-clock-skew.e2e-spec.ts` | PostgreSQL + MySQL + MongoDB replica set (and MongoDB) |
 
-Beyond these twenty, the `postgres` vitest project runs the whole e2e suite once more on PostgreSQL (see "Behaviour
+Beyond these twenty-two, the `postgres` vitest project runs the whole e2e suite once more on PostgreSQL (see "Behaviour
 matrices" below), so without the PostgreSQL container that project fails as a whole while `e2e` runs.
 
-`tests/global-setup.ts` starts all five containers automatically, so `pnpm test` works from a clean
+`tests/global-setup.ts` starts all six containers automatically, so `pnpm test` works from a clean
 machine with no manual docker command. It is idempotent (a running container is reused) and never
-fatal: without Docker every other suite still runs, and the twenty above report their own actionable
+fatal: without Docker every other suite still runs, and the twenty-two above report their own actionable
 error.
 
 ```bash
@@ -75,10 +77,10 @@ pnpm run test:infra:status   # what is running
 pnpm run test:infra:down     # stop and remove
 ```
 
-| | Redis | S3 (RustFS) | PostgreSQL | MySQL 8.4 | MariaDB 11.8 |
-|---|---|---|---|---|---|
-| Port | 6380 (6379 is an auth-protected TurboOps Redis on lt dev machines) | 9102 | 5440 | 3316 | 3317 |
-| Container | `nest-server-2985-redis` | `nest-server-2985-rustfs` | `nest-server-2985-postgres` | `nest-server-2985-mysql` | `nest-server-2985-mariadb` |
+| | Redis | S3 (RustFS) | PostgreSQL | MySQL 8.4 | MariaDB 11.8 | MongoDB 8.0 replica set |
+|---|---|---|---|---|---|---|
+| Port | 6380 (6379 is an auth-protected TurboOps Redis on lt dev machines) | 9102 | 5440 | 3316 | 3317 | 27019 |
+| Container | `nest-server-2985-redis` | `nest-server-2985-rustfs` | `nest-server-2985-postgres` | `nest-server-2985-mysql` | `nest-server-2985-mariadb` | `nest-server-2985-mongo-rs` |
 
 **PostgreSQL runs with two roles, as every environment does** (`.claude/plans/db-agnostic/PLAN.md`
 §3.9): `nest_owner` owns the databases and their schema, `nest_app` owns nothing and has neither
@@ -98,6 +100,12 @@ Overridable via `MYSQL_HOST`, `MYSQL_PORT`, `MARIADB_HOST`, `MARIADB_PORT`, `MYS
 whole e2e suite: the matrices carry their columns (persistence: one per engine; core modules and where
 parity: one per server).
 
+**The MongoDB replica set** (one node, `rs0`) exists for the sync contract matrix (DEV-3901): on a replica set a
+project's transaction can commit a synchronized write long after its stamp — what the pull window must cover — and the
+standalone MongoDB every other suite uses shows nothing of that. The readiness step initiates the set idempotently;
+the suite connects with `directConnection=true` and drops its database itself in `afterAll` (the database lifecycle
+collects only the standalone). Overridable via `MONGO_RS_HOST`, `MONGO_RS_PORT`.
+
 **CI provisions its own** containers in `.github/workflows/*.yml` and sets `LT_TEST_INFRA=0` so the
 automatic start stays out of the way. Same images, same ports — only who starts them differs. Set
 `LT_TEST_INFRA=0` locally too if you want to manage them yourself.
@@ -311,6 +319,36 @@ reason, never fall back to MongoDB, while the `e2e` project runs. `--project e2e
 
 The **data store** contract follows the same discipline: `tests/helpers/persistence-matrix.ts` declares the cases (CRUD contract plus the security policies), `tests/persistence-parity.e2e-spec.ts` executes them against a store obtained via `CorePersistenceModule.forFeature()` + `@InjectStore()` with every security plugin registered, and `tests/unit/persistence-parity-matrix.spec.ts` guards that every (case, database) cell is declared. It has ten columns: `mongodb`, PostgreSQL once per engine (`postgres-typeorm`, `postgres-kysely`, `postgres-drizzle`) — a `SqlDataStore` over the schema the migrator created, connected as the application role, so row-level security binds every case — and MySQL and MariaDB once per engine (`mysql-*`, `mariadb-*`, phase 6), a `MysqlDataStore` connected as the DML-only application account. Without row-level security there, `native-api-tenant-refused` is DIFFERENT-BY-DESIGN for those six columns and its complement asserts that a native query reaches every tenant while the store still isolates. Each tenant layer of the SQL store is additionally proven ALONE in `tests/persistence-sql-store.e2e-spec.ts` — the matrix runs them together, where one layer hides the loss of another.
 
+The **offline-sync protocol** follows it one level above the store: `tests/helpers/sync-contract-matrix.ts` declares
+what `GET/POST /sync/{model}` promise — pull, resume, resync, push with every strategy, idempotency, two tabs, tenant
+isolation, the infrastructure stores, the change hints over SSE and GraphQL (tenant and role filter, the stream ending
+on a re-check), the tombstone purge behind the horizon and the `syncUpdate` migration helper — and
+`tests/sync-contract.e2e-spec.ts` runs it through HTTP on seven columns: MongoDB standalone and replica set, PostgreSQL
+× three engines, MySQL, MariaDB. The window repeats of MongoDB are DIFFERENT-BY-DESIGN against SQL's "never repeated",
+each side with its own case; the migration helper is IMPOSSIBLE on the two MongoDB columns (it is a SQL statement). Its
+structural guard is `tests/unit/sync-contract-matrix.spec.ts`; the reference model it runs on is
+`src/server/modules/sync-note/`. Hints across replicas need a second application on one Redis and live in
+`tests/multi-replica.e2e-spec.ts`.
+
+**Offline sync end to end (DEV-3903).** Three suites prove the protocol from the client's side, all on the reference
+server (`tests/helpers/sync-test-app.ts`, which the contract matrix boots too):
+
+| Suite | What | Needs |
+|-------|------|-------|
+| `tests/sync-pwa-client.e2e-spec.ts` | The PWA test client (`tests/clients/pwa/`, IndexedDB, service worker) in Chrome, served by the test server, offline via Playwright | an installed Chrome (`playwright-core` downloads none; GitHub's Ubuntu runners ship one; `SYNC_PWA_CHROME` names another executable) |
+| `tests/sync-node-client.e2e-spec.ts` | The same client on SQLite (`node:sqlite`), bearer session token | nothing extra |
+| `tests/sync-clock-skew.e2e-spec.ts` | Two server PROCESSES with clocks 5 s ahead and behind, parallel writers on both, readers on either instance and one switching instances per page: no change lost. MongoDB runs with `pull.windowSeconds: 2` — the derived window (30 s / 90 s) would cover any skew — and needs the reader that STAYS with the fast clock: a switching reader soon starts a run on the slow one and picks a misstamped change up again, so with it alone the suite stayed green against mutation `sync-mongo-stamp-app-clock` | the containers above |
+
+The two client suites share one protocol implementation (`tests/clients/sync-client.mjs`) and one scenario list
+(`tests/helpers/sync-client-scenarios.ts`); `tests/unit/sync-client-scenarios.spec.ts` fails when a suite misses a
+scenario, and `tests/unit/sync-client.spec.ts` checks the client against an in-memory server, so a client bug does not
+cost an e2e run. Both run on MongoDB (`e2e`) and PostgreSQL (`postgres`) like every suite. The clock-skew suite starts
+its servers through the framework's SWC loader (`tests/helpers/sync-server.process.ts`, relative imports with `.js`)
+with `tests/helpers/skewed-clock.mjs` preloaded, because two Nest applications in one process share the persistence
+registry; it brings its own databases and is excluded from the `postgres` project. The skewed `Date` keeps the name
+`Date` and `prototype.constructor`: Mongoose resolves a schema type by the constructor's name, and `@UnifiedField`
+tells a class from a type factory by `prototype.constructor` — without both the server does not boot.
+
 ### A cell is EXECUTED, IMPOSSIBLE, or DIFFERENT-BY-DESIGN — never merely absent
 
 Omitting a case for one implementation and declaring it impossible there produce the same artefact
@@ -372,8 +410,9 @@ pnpm run check:mutations -- --id=<id>       # one mutation
 pnpm run check:mutations -- --list          # the registry, without running anything
 pnpm run check:mutations -- --allow-dirty   # when the fix and its evidence share a working tree
 pnpm run check:mutations -- --jobs=4        # N mutations at a time (default: 2, or 4 on >=12 cores)
-pnpm run check:mutations -- --no-infra      # only the 248 that need no MongoDB
+pnpm run check:mutations -- --no-infra      # only the 260 that need no MongoDB
 pnpm run check:mutations -- --since=<ref>   # only mutations touching files changed since <ref>
+pnpm run check:mutations -- --shard=2/4     # this job's quarter of the selection (CI splits the full run)
 ```
 
 `--no-infra` and `--since` narrow the run for LOCAL work and are deliberately not wired into the
@@ -391,7 +430,7 @@ when the registry, a vitest config or a setup file changed, since those can move
 commit, and in CI alongside the publish without blocking it. The price of caching is a cache that
 has to model each spec's full dependency closure correctly, and getting that wrong produces a stale
 PASS for a test that has since gone vacuous — exactly what the gate is there to prevent. Bad trade
-at 442 mutations.
+at 476 mutations.
 
 **Decided 2026-10-03 (repo owner): keep the full run.** Measured at 128 mutations, the CI job for
 11.41.6 took **14 minutes**. The trigger to revisit is that wall time, not the mutation count —
@@ -399,6 +438,32 @@ the count was never the cost: re-evaluate once the "Regression evidence" job in
 exceeds **30 minutes** (`gh run view <id> --json jobs` shows start and end). Below that line,
 adding a mutation needs no decision.
 
+**Re-evaluated 2026-10-30 (DEV-3910): the run stays full, it is SPLIT.** The line was crossed by far —
+58.5 min for 407 mutations at the 12.1.0 publish, 53 min for 442 at 12.1.1, almost all of it the cold
+start below. Both workflows now run the gate as a matrix of four jobs, each `--shard=i/4` of the same
+selection: every mutation in exactly one shard, unit and e2e mutations dealt out separately so no shard
+collects the slow ones, nothing cached or skipped. The new trigger: **the slowest shard exceeds 30
+minutes → raise the shard count** (matrix and `--shard` together, one line per workflow). What the split
+must keep is pinned by `tests/unit/mutation-sharding.spec.ts`:
+
+| Property | Why it is load-bearing |
+|----------|------------------------|
+| Every mutation in exactly one shard (mutation `mutation-shard-drops-residue`) | a lost mutation is invisible — every shard is green, each honestly reporting what it ran |
+| The matrix lists 1..N for the N `--shard` names (mutations `evidence-matrix-misses-a-shard`, and `evidence-plan-lists-fewer-shards` for the on-demand plan job) | a shorter matrix never starts the missing shards |
+| `fail-fast: false` in both workflows | GitHub cancels the rest of a matrix on the first failure, and with it their verdicts |
+| One issue per red run, from the `regression-evidence-report` job after the matrix | two red shards each looking for an open issue at once both create one |
+
+A shard that holds none of a non-empty selection (`--id=<x>` with four shards) ends 0 and says so; an
+empty SELECTION still fails before sharding (2 for `--since` / `--no-infra`, 1 for an unmatched
+`--id`). `regression-evidence.yml` takes a `shards` input (default 4) so a single `--id` run can use
+one job. `/lt-dev:publish` reads the workflow run's conclusion, which any red shard turns red.
+
+**More shards stop helping at the slowest single mutation.** A mutation that makes tests HANG costs
+retries × timeout per red test — 3 attempts × 60 s in low-resource mode. At 12.1.1 four such mutations
+took 44 % of all lane time, the largest (`gridfs-upload-source-error-unhandled`) ~18 minutes on its
+own, so no shard count brings a shard below that. When the slowest shard is one such mutation, shorten
+the spec's failure path (a tighter per-test timeout, a fail-fast assertion), not the split.
+
 Not part of `pnpm run check` — it edits source and re-runs whole e2e suites. It belongs in review
 and on the publish path. It is also reachable on demand, without cutting a release:
 
@@ -436,9 +501,9 @@ exactly the environment where the answer matters.
 
 ### The cost is vitest's cold start, not the tests
 
-Worth knowing before optimising the wrong thing: the specs behind all 194 e2e mutations add up to
+Worth knowing before optimising the wrong thing: the specs behind all 216 e2e mutations add up to
 **~40 seconds**. The step takes ~740s. The remaining ~700s is paying vitest's startup — process
-spawn, transform, module graph, mongod connect, DB create and drop — once per mutation, 442 times.
+spawn, transform, module graph, mongod connect, DB create and drop — once per mutation, 476 times.
 That work is largely single-threaded I/O and barely scales with cores: the full registry measures
 **744s on a 12-core laptop and 777s on a 4-vCPU CI runner**.
 

package/CLAUDE.md

@@ -200,10 +200,11 @@ pnpm run reinit         # Clean reinstall + tests + build
 **Key Components:**
 - `CoreModule` - Dynamic module with GraphQL (optional, disable via `graphQl: false`), MongoDB, security
 - `src/core/common/` - Decorators, helpers, interceptors, services
-- `src/core/modules/` - ApiToken, Auth, BetterAuth, ErrorCode, File, HealthCheck, Hub, Migrate, Permissions, SystemSetup, Tus, User
+- `src/core/modules/` - ApiToken, Auth, BetterAuth, ErrorCode, File, HealthCheck, Hub, Migrate, Permissions, Sync, SystemSetup, Tus, User
   - **ApiToken** - Opt-in (`apiTokens`) USER and TENANT tokens + signed assertions. Denied on every route without `@ApiTokenScopes()`; all three guards share `enforceApiTokenRoute()`. See `src/core/modules/api-token/README.md`.
   - **Hub** - Build-free ADMIN-gated operator cockpit at `/hub` (config-gated per environment; 17 panels, runtime collectors, mailbox, admin actions). See `src/core/modules/hub/README.md`.
   - **Permissions** - ADMIN-gated security-map report (routes + roles + `@Restricted` fields); also surfaced in the Hub's "Routes / Permissions" panel.
+  - **Sync** - Opt-in (`sync`) offline sync: `GET/POST /sync/{model}` for models declared `@PersistedModel({ sync })` whose CrudService carries `@SyncService()`, change hints over SSE (`GET /sync/hints`) and GraphQL (`syncHint`), hourly tombstone purge; protocol in `docs/offline-sync-protocol.md`, client duties in the module's `SECURITY.md`, reference test clients in `tests/clients/`. See `src/core/modules/sync/README.md`.
 - **Optional central infrastructure** (11.33.0+) - `CoreRedisService` (`redis` config) and `CoreS3Service` (`s3` config) turn process-local state into shared state for multi-replica deployments: rate-limit counters, cron deduplication, GraphQL subscriptions, tenant-cache and IAM role-cache invalidation, Hub collectors, file storage (`file.storage: 's3'`; the driver is otherwise derived — S3 → GridFS → filesystem — and an unavailable one fails the boot rather than falling back) and TUS staging. Both are inert without their config, and their client libraries are **optional peer dependencies** (`ioredis`, `bullmq`, `@aws-sdk/client-s3`, `@aws-sdk/lib-storage`, `@aws-sdk/s3-request-presigner`, `@tus/s3-store`) — a project that uses neither installs nothing extra. When adding a distributed feature, always keep the non-configured fallback path.
 
 See `.claude/rules/architecture.md` for detailed documentation.

package/FRAMEWORK-API.md

@@ -1,6 +1,6 @@
 # @lenne.tech/nest-server — Framework API Reference
 
-> Auto-generated from source code as of 2026-10-29 (v12.1.1)
+> Auto-generated from source code as of 2026-11-01 (v12.2.0)
 > File: `FRAMEWORK-API.md` — compact, machine-readable API surface for Claude Code
 
 ## CoreModule.forRoot()
@@ -52,6 +52,7 @@
   - `sha256?`: `boolean` — Whether to enable verification and automatic encryption for received passwords that are not in sha256 format
   - `shutdownDelayMs?`: `number` (default: `0 (no delay)`) — Delay in milliseconds between receiving a shutdown signal and starting the
   - `staticAssets?`: `{ options?: ServeStaticOptions; path?: string; }` — Configuration for useStaticAssets
+  - `sync?`: `boolean | ISync` — Offline sync (`docs/offline-sync-protocol.md`): `GET/POST /sync/{model}` for the models whose service carries
   - `systemSetup?`: `ISystemSetup` — System setup configuration for initial admin creation.
   - `templates?`: `{ engine?: string; path?: string; }` — Templates
   - `trustProxy?`: `string | number | boolean | string[]` (default: `false (Express default — the forwarded chain is not trusted)`) — Express `trust proxy` setting — how far up the `X-Forwarded-For` chain this app believes.
@@ -215,6 +216,7 @@ When `passkey` is enabled, `trustedOrigins` is required (compile-time enforcemen
 ### ICoreModuleOverrides
 
   - `apiToken?`: `{ model?: Type<any>; service?: Type<any>; }` — Override API token collaborators with project-specific subclasses (`apiTokens` config).
+  - `sync?`: `{ controller?: Type<any>; hintsController?: Type<any>; resolver?: Type<any>; ...` — Override the offline sync endpoints, the hint subscription and their service (`sync` config).
   - `ai?`: `{ budgetService?: Type<any>; connectionResolver?: Type<any>; connectionServic...` — Override AI module collaborators with project-specific subclasses.
   - `betterAuth?`: `{ controller?: Type<any>; resolver?: Type<any>; }` — Override BetterAuth controller and/or resolver.
   - `errorCode?`: `{ controller?: Type<any>; service?: Type<any>; }` — Override ErrorCode controller and/or service.
@@ -284,9 +286,12 @@ When `passkey` is enabled, `trustedOrigins` is required (compile-time enforcemen
   - `checkRights?`: `boolean`
   - `collation?`: `CollationOptions`
   - `create?`: `boolean`
+  - `createId?`: `string`
   - `currentUser?`: `{ [key: string]: any; id: string; roles?: string[]; }`
   - `fieldSelection?`: `FieldSelection`
+  - `expectedVersion?`: `number`
   - `force?`: `boolean`
+  - `includeTombstones?`: `boolean`
   - `inputType?`: `new (...params: any[]) => any`
   - `outputType?`: `new (...params: any[]) => any`
   - `populate?`: `string | PopulateOptions | (string | PopulateOptions)[]`
@@ -311,7 +316,7 @@ Generic: `CrudService<Model, CreateInput, UpdateInput>`
 - `async create(input: PlainObject<CreateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Create item
 - `async createForce(input: PlainObject<CreateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Create item without checks or restrictions
 - `async createRaw(input: PlainObject<CreateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Create item without checks, restrictions or preparations
-- `distinct(property: string)`: `Promise<string[]>` — Get distinct values of a property
+- `distinct(property: string, serviceOptions?: ServiceOptions)`: `Promise<string[]>` — Get distinct values of a property
 - `async get(id: string, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Get item by ID
 - `async getForce(id: string, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Get item by ID without checks or restrictions
 - `async getRaw(id: string, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Get item by ID without checks, restrictions or preparations
@@ -338,6 +343,15 @@ Generic: `CrudService<Model, CreateInput, UpdateInput>`
 - `async updateForce(id: string, input: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Update item via ID without checks or restrictions
 - `async updateRaw(id: string, input: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Update item via ID without checks, restrictions or preparations
 - `async delete(id: string, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Delete item via ID
+- `withTombstones(query: Q, serviceOptions?: ServiceOptions)`: `Q` — A Mongoose query or aggregation that also sees tombstones when the caller asked (`includeTombstones`)
+- `expectedVersionOf(serviceOptions?: ServiceOptions)`: `number` — `serviceOptions.expectedVersion`, checked; only a synchronized model has a version
+- `assertVersion(id: string, stored: any, expectedVersion: number)`: `void` — The early answer to a conditional change on a record that already has another version
+- `versionConflict(id: string)`: `never`
+- `syncAccessSnapshot(stored: Record<string, any>)`: `Record<string, any>` — The tenant and scope fields of a stored record as they are BEFORE a write — taken before `mergePlain()`, which
+- `async reportSyncAccessMove(stored: Record<string, any>, written: Record<string, any>)`: `Promise<void>` — Tell the sync module that this write took a synchronized record away from users who could see it: moved to
+- `reportSyncChange(records: Record<string, any>[])`: `void` — Tell the sync module that a write of a synchronized record succeeded, so the subscribers of its hints learn of it
+- `syncChanged(created: R)`: `R` — `reportSyncChange()` for a created record, which it answers
+- `async removeOrTombstone(id: string, expectedVersion: number)`: `Promise<void>` — Delete through the store: a synchronized model's record becomes a tombstone (conditional on `expectedVersion`),
 - `async deleteForce(id: string, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Delete item via ID without checks or restrictions
 - `async deleteRaw(id: string, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Delete item via ID without checks, restrictions or preparations
 - `async pushToArray(id: string | Types.ObjectId | { id?: any; _id?: any; }, field: string, items: any, options?: { $slice?: number; $position?: number; $sort?: Record<string, 1 | -1>; })`: `Promise<void>` — Append items to an array field without loading the full array.
@@ -364,6 +378,7 @@ Generic: `CrudService<Model, CreateInput, UpdateInput>`
 | `hub` | README, CHECKLIST | `src/core/modules/hub/` |
 | `migrate` | README | `src/core/modules/migrate/` |
 | `permissions` | README, CHECKLIST | `src/core/modules/permissions/` |
+| `sync` | README, CHECKLIST | `src/core/modules/sync/` |
 | `system-setup` | README, CHECKLIST | `src/core/modules/system-setup/` |
 | `tenant` | README, CHECKLIST | `src/core/modules/tenant/` |
 | `tus` | README, CHECKLIST | `src/core/modules/tus/` |

package/README.md

@@ -17,6 +17,7 @@ An enterprise-grade extension layer on top of [NestJS](https://nestjs.com/) for
 - [Multi-Tenancy](#multi-tenancy)
 - [Databases](#databases)
 - [API Tokens](#api-tokens)
+- [Offline Sync](#offline-sync)
 - [AI Assistant & MCP](#ai-assistant--mcp)
 - [Operator Hub](#operator-hub)
 - [Scalability](#scalability)
@@ -63,6 +64,7 @@ This generates a complete module with model, inputs, resolver, controller, and s
 | **Authorization** | Extensible role-based access control, field-level restrictions (also on nested types), system roles, hierarchy roles; every entry point checked, not just the route |
 | **Database** | MongoDB (Mongoose), PostgreSQL, MySQL or MariaDB (TypeORM, Kysely or Drizzle) — per project or per model — behind one CrudService and security pipeline; tenant isolation enforced by row-level security on PostgreSQL; schema evolution and SQL migrations by the framework; advanced filtering & pagination |
 | **Multi-Tenancy** | Header-based tenant isolation, membership management, hierarchy roles, auto-filtering, a tenant row check after every read, deactivatable tenants |
+| **Offline Sync** | Mobile, web and desktop clients read and write offline and reconcile later: delta pull by cursor, push with conflict strategies, tombstones, client-generated ids, change hints over SSE and GraphQL — on every supported database, through the same security pipeline |
 | **File Handling** | GridFS, S3 or filesystem storage, presigned downloads, resumable uploads via TUS protocol (up to 50 GB, S3 staging) |
 | **AI** | AI assistant with tool registry, plan mode, confirmation policy, token budgets, conversations and SSE streaming; MCP server (`/ai/mcp`) with OAuth 2.1 |
 | **Security** | Defense-in-depth: input validation, password hashing, role guard, audit fields, response filtering, security headers, SSRF guard for user-entered URLs, re-checked WebSocket subscriptions |
@@ -361,6 +363,21 @@ Opt-in bearer tokens for integrations and scripts (`apiTokens` configuration):
 
 Details: [src/core/modules/api-token/README.md](src/core/modules/api-token/README.md).
 
+## Offline Sync
+
+Opt-in (`sync` configuration) for apps that must work without a connection — React Native or Capacitor with SQLite,
+PWAs with IndexedDB, desktop and Node clients:
+
+- **Protocol** — HTTP with JSON, fully documented in [docs/offline-sync-protocol.md](docs/offline-sync-protocol.md); a client needs `fetch` and nothing else
+- **Pull** by an opaque cursor that loses no change across instances, clocks and late commits; pages bounded by count and size; `410` with a clear reason when a resync is needed
+- **Push** item by item with idempotent mutation ids, client-generated ids, conditional writes on `version`, and the strategies `reject`, `lww`, `merge` and `custom`
+- **Tombstones** for deletions, hourly purge behind a retention horizon; hints over SSE (`GET /sync/hints`) and the GraphQL subscription `syncHint`
+- **Security** — every pull and push runs through the model's `CrudService` (`@Restricted`, `securityCheck()`, tenant policy, row-level security); lost access forces a resync
+
+A model takes part with `@PersistedModel({ sync: { roles, strategy } })` and `@SyncService()` on its service.
+Details: [src/core/modules/sync/README.md](src/core/modules/sync/README.md), client duties in
+[src/core/modules/sync/SECURITY.md](src/core/modules/sync/SECURITY.md).
+
 ## AI Assistant & MCP
 
 An optional AI module (`ai` configuration) for any OpenAI-compatible model endpoint:
@@ -440,6 +457,7 @@ The Module Inheritance Pattern ensures any core module can be extended to integr
 | **Hub** | ADMIN-only operator cockpit at `/hub` |
 | **Migrate** | Migrations for MongoDB and SQL with distributed locking for cluster deployments |
 | **Permissions** | Security map report: routes, roles and `@Restricted` fields (HTML, JSON, Markdown) |
+| **Sync** | Offline sync for mobile, web and desktop clients: pull, push, conflicts, tombstones, hints |
 | **SystemSetup** | Initial admin creation for fresh deployments |
 
 ### CrudService

package/dist/core/common/interfaces/server-options.interface.d.ts

@@ -424,6 +424,7 @@ export interface IServerOptions {
         options?: ServeStaticOptions;
         path?: string;
     };
+    sync?: boolean | ISync;
     systemSetup?: ISystemSetup;
     templates?: {
         engine?: string;
@@ -458,6 +459,40 @@ export interface IS3Config {
     secretAccessKey?: string;
     stagingBucket?: string;
 }
+export interface ISync {
+    cursorSecret?: string;
+    enabled?: boolean;
+    hints?: boolean | {
+        debounceMs?: number;
+        enabled?: boolean;
+        graphql?: boolean;
+        sse?: boolean;
+    };
+    path?: string;
+    pull?: {
+        defaultLimit?: number;
+        maxBytes?: number;
+        maxLimit?: number;
+        windowSeconds?: number;
+    };
+    push?: {
+        maxItems?: number;
+    };
+    rateLimit?: false | {
+        pull?: false | {
+            max?: number;
+            windowSeconds?: number;
+        };
+        push?: false | {
+            max?: number;
+            windowSeconds?: number;
+        };
+    };
+    retention?: {
+        mutationsDays?: number;
+        tombstonesDays?: false | number;
+    };
+}
 export interface ISystemSetup {
     enabled?: boolean;
     initialAdmin?: ISystemSetupInitialAdmin;
@@ -541,6 +576,12 @@ export interface ICoreModuleOverrides {
         model?: Type<any>;
         service?: Type<any>;
     };
+    sync?: {
+        controller?: Type<any>;
+        hintsController?: Type<any>;
+        resolver?: Type<any>;
+        service?: Type<any>;
+    };
     ai?: {
         budgetService?: Type<any>;
         connectionResolver?: Type<any>;

package/dist/core/common/interfaces/service-options.interface.d.ts

@@ -8,13 +8,16 @@ export interface ServiceOptions {
     checkRights?: boolean;
     collation?: CollationOptions;
     create?: boolean;
+    createId?: string;
     currentUser?: {
         [key: string]: any;
         id: string;
         roles?: string[];
     };
     fieldSelection?: FieldSelection;
+    expectedVersion?: number;
     force?: boolean;
+    includeTombstones?: boolean;
     inputType?: new (...params: any[]) => any;
     outputType?: new (...params: any[]) => any;
     populate?: (PopulateOptions | string)[] | PopulateOptions | string;

package/dist/core/common/persistence/core-persistence.module.js

@@ -8,8 +8,11 @@ var CorePersistenceModule_1;
 import { Module } from '@nestjs/common';
 import { getConnectionToken, getModelToken } from './mongo/mongoose-compat.js';
 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, registerDataStore, registerPersistedModel, } from './persistence-runtime.registry.js';
 import { getStoreToken } from './persistence.tokens.js';
 import { guardRoutedModel, isStandInModel, standInModel } from './routed-model.guard.js';
@@ -17,7 +20,11 @@ import { unavailableStore } from './unavailable-store.js';
 let CorePersistenceModule = CorePersistenceModule_1 = class CorePersistenceModule {
     static forFeature(models) {
         for (const model of models) {
-            registerModelSchema(model.name, model.schema);
+            const sync = resolveSyncOptions(model.model ? getPersistedModelOptions(model.model)?.sync : getPersistedSyncByName(model.name), model.name);
+            registerModelSchema(model.name, model.schema, sync);
+            if (sync && !isDeclaredSchema(model.schema)) {
+                applySyncSchema(model.schema, sync);
+            }
             registerPersistedModel({
                 declaredSource: model.dataSource ??
                     (model.model ? getPersistedModelOptions(model.model) : getPersistedModelOptionsByName(model.name))
@@ -51,6 +58,9 @@ let CorePersistenceModule = CorePersistenceModule_1 = class CorePersistenceModul
                         ?
                             unavailableStore(model.name, 'the project runs without a database (`database: false`)')
                         : new MongooseDataStore(mongooseModel);
+                if (store.capabilities.mongoosePopulate && store.capabilities.changeOrder) {
+                    await assertSyncCollectionReady(mongooseModel);
+                }
                 registerDataStore(model.name, store);
                 bindStoreToModel(mongooseModel, store);
                 if (!store.capabilities.mongoosePopulate && !isStandInModel(mongooseModel)) {

package/dist/core/common/persistence/core-persistence.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"core-persistence.module.js","sourceRoot":"","sources":["../../../../src/core/common/persistence/core-persistence.module.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EAAiB,MAAM,EAAY,MAAM,gBAAgB,CAAC;AAEjE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAG/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,wBAAwB,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AAC1G,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AA6BnD,IAAM,qBAAqB,6BAA3B,MAAM,qBAAqB;IAChC,MAAM,CAAC,UAAU,CAAC,MAAoC;QACpD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,mBAAmB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;YAC9C,sBAAsB,CAAC;gBACrB,cAAc,EACZ,KAAK,CAAC,UAAU;oBAChB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,wBAAwB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,8BAA8B,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;wBAChG,EAAE,UAAU;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,MAAM,EAAE,KAAK,CAAC,MAAM;aACrB,CAAC,CAAC;QACL,CAAC;QAID,MAAM,cAAc,GAAe,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;YAC3D;gBACE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,CAAC;gBACzD,OAAO,EAAE,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC;gBAClC,UAAU,EAAE,CAAC,UAAwE,EAAE,EAAE,CACvF,UAAU;oBACR,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;oBACjG,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC;aAC7C;YACD,GAAG,CAAC,KAAK,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;gBACtD,MAAM,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACnC,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,IAAI,CAAC;gBAC1C,UAAU,EAAE,CAAC,MAAmC,EAAE,EAAE,CAClD,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC;aACtF,CAAC,CAAC;SACJ,CAAC,CAAC;QACH,MAAM,MAAM,GAAe,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAChD,MAAM,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACnC,OAAO,EAAE,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC;YAGlC,UAAU,EAAE,KAAK,EAAE,aAAyB,EAAE,EAAE;gBAC9C,MAAM,OAAO,GAAG,qBAAqB,EAAE,CAAC;gBACxC,MAAM,KAAK,GAAG,OAAO;oBACnB,CAAC,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC;oBACvD,CAAC,CAAC,cAAc,CAAC,aAAa,CAAC;wBAC7B,CAAC;4BACC,gBAAgB,CAAC,KAAK,CAAC,IAAI,EAAE,yDAAyD,CAAC;wBACzF,CAAC,CAAC,IAAI,iBAAiB,CAAC,aAAa,CAAC,CAAC;gBAC3C,iBAAiB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBACrC,gBAAgB,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;gBAEvC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,gBAAgB,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,EAAE,CAAC;oBAC3E,gBAAgB,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;gBACzC,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;SACF,CAAC,CAAC,CAAC;QACJ,OAAO;YACL,OAAO,EAAE;gBACP,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAE,QAAgC,CAAC,OAAO,CAAC;gBAC9E,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAE,KAA6B,CAAC,OAAO,CAAC;aACjE;YACD,MAAM,EAAE,uBAAqB;YAC7B,SAAS,EAAE,CAAC,GAAG,cAAc,EAAE,GAAG,MAAM,CAAC;SAC1C,CAAC;IACJ,CAAC;CACF,CAAA;AA/DY,qBAAqB;IADjC,MAAM,CAAC,EAAE,CAAC;GACE,qBAAqB,CA+DjC"}
+{"version":3,"file":"core-persistence.module.js","sourceRoot":"","sources":["../../../../src/core/common/persistence/core-persistence.module.ts"],"names":[],"mappings":"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"}

package/dist/core/common/persistence/data-source.runtime.js

@@ -4,6 +4,7 @@ import { RequestContext } from '../services/request-context.service.js';
 import { expiredRecordsFilter } from './expiry-sweep.js';
 import { redactUrl, resolveModelSource, } from './data-source.config.js';
 import { getModelDescriptor } from './model-metadata.registry.js';
+import { withSequenceField } from './sync-model.js';
 import { MongooseDataStore } from './mongoose-data-store.js';
 import { getPersistedModels, } from './persistence-runtime.registry.js';
 import { sqlDialect } from './sql/sql-dialect.js';
@@ -140,10 +141,11 @@ export class DataSourceRuntime {
         return source ? this.resolved.sources[source] : undefined;
     }
     async openStore(source, name) {
-        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()`);
         }
+        const model = withSequenceField(declared);
         const app = await this.executor(source);
         const dialect = this.dialect(source);
         let changes;