@lenne.tech/nest-server 12.1.1 → 12.2.0

package/docs/offline-sync-protocol.md

@@ -1,9 +1,11 @@
 # Offline sync protocol
 
-> **Status: specification, not implemented yet.** Phase 1 of the offline-sync epic (DEV-3819, this phase DEV-3898).
-> Nothing described here exists in the package before the sync module ships (phase 4). The implementation plan, the
-> port extensions and the reasoning live in the framework repository under `.claude/plans/offline-sync/PLAN.md`.
-> Points the cursor prototype (phase 2) still decides are marked **OPEN** and listed in §15, next to the owner's decisions.
+> **Status: implemented** by the sync module (`src/core/modules/sync/`, 12.2.0): pull, push, conflicts, client ids and
+> resync (DEV-3901), hints (§9) and the tombstone purge (DEV-3902), proven end to end by a PWA and a Node test client
+> and by two server instances with skewed clocks (DEV-3903). Specified in
+> phase 1 of the offline-sync epic (DEV-3819, DEV-3898), the open points decided by the cursor prototype of phase 2
+> (DEV-3899). The implementation plan, the port extensions, the reasoning and the measurements live in the framework
+> repository under `.claude/plans/offline-sync/PLAN.md`; §15 lists every decision.
 
 Clients read and write while disconnected and reconcile with the server when they are back: they pull what changed
 since their cursor, push what they changed locally, and receive tombstones for deletions. The protocol is HTTP with
@@ -37,58 +39,69 @@ supports (MongoDB, PostgreSQL with any engine, MySQL / MariaDB) with the same ob
 | `version` | An integer the server increments on every change of the record, starting at 1. Never set by a client. |
 | `updatedAt` | The server's time of the last change. Informational; ordering never relies on it. |
 | `deletedAt` | `null` for a live record, the deletion time for a tombstone. |
-| Tombstone | What remains of a deleted record: `id`, `version`, `deletedAt`, `updatedAt`, on a tenant-scoped model `tenantId`, and the user-id fields the model declares as its scope (e.g. `ownerId`). No content field. |
+| Tombstone | What remains of a deleted record: `id`, `version`, `deletedAt`, `updatedAt`, on a tenant-scoped model `tenantId`, and the user-id fields the model declares as its scope (e.g. `ownerId`). The server also keeps its audit fields (`createdAt`, `createdBy`, `updatedBy` — who deleted it); a pull sends none of them. No content field. |
 | Cursor | Opaque string the server returns with every pull page; the client sends it back to continue. |
 | Retention horizon | How long tombstones are kept. A cursor older than the horizon cannot be continued (§8). |
 | Mutation id | A unique id the client gives every pushed change, so a repeated push is recognised (§6.5). |
 
 ## 3. Identifiers
 
-**Clients create the ids of records they create offline.** Two formats are accepted for sync models:
+**Clients create the ids of records they create offline**, in the one format the model declares:
 
-| Format | Shape | Generated by |
-|---|---|---|
-| ObjectId-hex | 24 lowercase hex characters (`^[0-9a-f]{24}$`) | the server's own format; any ObjectId generator |
-| uuidv7 | 36 characters, `xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx`, lowercase | `crypto.randomUUID()` is v4 — use a uuidv7 generator |
-
-* The server validates the format of every id it receives and refuses anything else (`INVALID_ID`, §7). It never
-  rewrites a client id.
-* Records the server creates itself (a create through the normal API) keep the server's format, ObjectId-hex. Server
-  ids are predictable from an observed one, so a client could occupy the next ones; on a sync model the server
+| Format | Shape | Used by | Generated by |
+|---|---|---|---|
+| ObjectId-hex | 24 lowercase hex characters (`^[0-9a-f]{24}$`) | every model unless declared otherwise — existing models and projects change nothing | the client, as in MongoDB's own model where the driver creates the id — but with a random tail: 4 timestamp bytes plus 8 bytes from a secure random source, fresh for every id (see below); not a driver's default `new ObjectId()` |
+| uuidv7 | 36 characters, `xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx`, lowercase | a model declared with it — a choice for **new** models only | a uuidv7 generator (`crypto.randomUUID()` is v4) |
+
+* **One format per model, never mixed** in a collection or table (decided 2026-10-29). An existing model does not
+  switch: that would mix both formats in its data.
+* The server validates every id it receives against the model's format and refuses anything else (`INVALID_ID`, §7).
+  It never rewrites a client id.
+* Records the server creates itself (a create through the normal API) get the model's format. Server-generated
+  ObjectIds are predictable from an observed one, so a client could occupy the next ones; on a sync model the server
   therefore generates a fresh id and retries when its own id is taken, and a normal create never fails on that.
-* Ids of models that are not syncable keep today's rule: ObjectId-hex only. Declaring a model syncable widens the
-  accepted formats for that model alone.
-* **Prefer uuidv7.** It carries 74 random bits, so ids of other clients cannot be guessed. An ObjectId carries a
-  timestamp, a per-process value and a counter; ids generated close to a known one are predictable.
+* Ids of models that are not syncable keep today's rule: ObjectId-hex only.
+* **A client's next ids must not be predictable.** A uuidv7 carries 74 random bits by construction. A driver's default
+  ObjectId does not: its per-process value and counter make every next id of a client predictable from one it has
+  created, so a member of the same tenant who sees one could create those ids first, and the client's own create
+  would then meet a record that is not its own. That is why a client fills the 8 bytes after an ObjectId's timestamp
+  from a secure random source (`crypto.getRandomValues`) for every id — still a valid ObjectId, as unguessable as a
+  uuidv7. The server cannot tell how an id was generated, so this rule is the client's. Beyond it, every access is
+  checked against the caller's rights, an id taken by a record the caller may not see answers `ID_UNAVAILABLE`, and
+  the push rate limit bounds probing. ObjectId stays the default; uuidv7 is a model's choice for new models.
 * Records created offline may reference each other by these ids before any of them reached the server. Push them in
   dependency order (§6.3) or accept that a reference may point to a record the server has not received yet — the server
   checks a reference against the caller's rights only where the model declares that check.
 
-How each database stores both formats: the id column is already a string column wide enough for both on PostgreSQL
+How each database stores the formats: the id column is already a string column wide enough for both on PostgreSQL
 (`text`) and MySQL / MariaDB (`varchar(255)`). On MongoDB an ObjectId-hex id is stored as an ObjectId and a uuidv7 id
-as a string `_id`; the format alone decides the representation, so every lookup by id is deterministic. References to
-a sync model use the same mapping. **OPEN (phase 2):** Mongoose casting, populate and sort on a collection holding both
-representations are verified by the prototype before phase 3 builds on them.
+as a BSON UUID (binary subtype 4, MongoDB's recommended UUID representation); the core keeps ids as strings, the store
+converts at its boundary. References to a model use that model's representation. Because a collection holds one
+format, casting, populate and sort never meet two representations side by side.
 
-**A create whose id is already taken** by a record or tombstone the caller may see is answered `conflict` with that record as the
-caller may see it (§6.5) — without comparing the stored values with `data`: an answer that depended on the comparison
+**A create whose id is already taken** by a record or tombstone the caller may see — inside their tenant scope, with the
+model's pull roles, not hidden by `securityCheck` — is answered `conflict` with that record as the caller may see it (§6.5) — without comparing the stored values with `data`: an answer that depended on the comparison
 would let the caller test guesses for fields hidden from them. Taken by a record or tombstone the caller may **not**
 see, the item is refused with `ID_UNAVAILABLE` — the same answer,
 same timing, for every reason an id cannot be used; it carries no tenant, owner, content or deletion state. That an id
 is occupied stays observable — decided (O2, §15): ids stay unique across tenants, the push rate limit bounds probing,
-and a uuidv7 id of someone else cannot be guessed in the first place.
+and an id generated as above (uuidv7, or ObjectId-hex with its random tail) cannot be guessed in the first place.
 
 ## 4. Requests and authentication
 
 * **Base path** `/sync` (configurable). Model names in paths are the names the project registered for sync.
+* **Tenant:** with `X-Tenant-Id` a request covers that one tenant (and requires an active membership in it); without the
+  header it spans every tenant the caller is an active member of.
 * **Authentication:** a Better-Auth session cookie or a bearer token (JWT or session token), exactly as for every other
   route. API tokens are refused on sync routes unless the project releases a sync scope for them.
 * **Writes with cookie authentication** follow the rules of every writing endpoint — the session cookie is
   `SameSite=lax`, credentialed CORS is answered for the trusted origins (for any origin under `cors.allowAll`, a
   development setting) — and push additionally requires
-  `Content-Type: application/json` (which forces a CORS preflight) and refuses a request whose `Origin` is not a
-  trusted origin or whose `Sec-Fetch-Site` is `cross-site`. A bearer-authenticated request carries no ambient
-  credential and is not subject to these checks.
+  `Content-Type: application/json` (which forces a CORS preflight; required of every push, `400` otherwise) and,
+  while the server uses cookies, refuses a request whose `Origin` is not a trusted origin or whose `Sec-Fetch-Site` is
+  `cross-site` (`403`). The trusted origins are those credentialed CORS answers plus the app's and the API's own. A
+  client without fetch metadata (a native app, a server) sends neither header and is not affected; a browser app
+  using a bearer token runs on a trusted origin anyway, or CORS would refuse it first.
 * **Session expired while offline:** push answers `401` for the whole request before it looks at any item. Nothing is
   applied and nothing is discarded; after signing in again the client sends the same items with the same mutation ids
   and gets no duplicates (§6.5).
@@ -114,7 +127,7 @@ GET /sync/{model}?cursor={cursor}&limit={n}
 ```json
 {
   "items": [
-    { "id": "0190f8a2-…", "version": 3, "updatedAt": "2026-11-02T09:14:03.120Z", "deletedAt": null, "data": { "title": "…" } },
+    { "id": "6720c0…", "version": 3, "updatedAt": "2026-11-02T09:14:03.120Z", "deletedAt": null, "data": { "title": "…" } },
     { "id": "6720c1…", "version": 5, "updatedAt": "2026-11-02T09:15:44.002Z", "deletedAt": "2026-11-02T09:15:44.002Z" }
   ],
   "cursor": "c3luYzpub3RlOjE…",
@@ -131,8 +144,10 @@ GET /sync/{model}?cursor={cursor}&limit={n}
   cursor continues with page n+1. Apply a page's items and store its cursor in one local transaction.
 * **Ordering and duplicates.** Pages are ordered by the server's change order, not by `updatedAt`. A record may appear
   more than once across pages (it changed again while the client was paging) — keep the item with the higher
-  `version`. **OPEN (phase 2):** whether the chosen cursor also delivers an unchanged record twice (an overlap window
-  does, a change sequence does not); clients must tolerate it either way by comparing `version`.
+  `version`. Depending on the database the server runs on, a pull also repeats **unchanged** records (decided in
+  phase 2, P2-2): on MongoDB a run re-reads what changed within a window W before its cursor (on a replica set the
+  server's transaction lifetime — 60 s by default — plus 30 s, on a standalone 30 s; decided in DEV-3901), on SQL
+  databases it never does. Clients compare `version` and need not know which.
 * Without a cursor the client receives every record and every unexpired tombstone it may see, then continues with the
   last cursor like any delta. A client whose local storage was cleared (Safari removes the storage of a site not
   installed after seven days without interaction) simply starts without a cursor.
@@ -142,8 +157,9 @@ GET /sync/{model}?cursor={cursor}&limit={n}
 * Every change committed before the pull started and visible to the caller is delivered in some page of the run that
   starts at the given cursor — regardless of how many server instances wrote it, whether their clocks differ, whether
   two changes carry the same timestamp, or whether a transaction committed after a younger one was already pulled.
-  **OPEN (phase 2):** the mechanism (P §3.4: a server-assigned change sequence with a commit horizon, or an
-  overlap window with `version` comparison) is chosen by the prototype on every target database.
+  The mechanism (decided in phase 2, P §3.4, measured on every target database): on SQL databases a change sequence
+  the server assigns in commit order, on MongoDB the server's clock with a window that a commit cannot outlast. The
+  cursor is opaque either way; a client never reads or compares it.
 * No record and no tombstone of another tenant, and no record the caller's rights or `securityCheck` hide.
 
 ## 6. Push
@@ -160,7 +176,7 @@ Content-Type: application/json
 ### 6.2 Item
 
 ```json
-{ "mutationId": "0190f8b3-…", "op": "upsert", "id": "0190f8a2-…", "baseVersion": 2, "data": { "title": "…" } }
+{ "mutationId": "0190f8b3-…", "op": "upsert", "id": "6720c0…", "baseVersion": 2, "data": { "title": "…" } }
 { "mutationId": "0190f8b4-…", "op": "delete", "id": "6720c1…", "baseVersion": 5 }
 ```
 
@@ -182,8 +198,9 @@ Content-Type: application/json
 * `upsert` with `baseVersion` is an **atomic conditional change**: it applies only when the stored version still equals
   `baseVersion` (`WHERE id = … AND version = …` or the MongoDB equivalent; never read-then-write), and it increments
   `version`.
-* `delete` with a matching `baseVersion` turns the record into a tombstone through the normal update pipeline (rights,
-  `securityCheck`, audit apply). Deleting a tombstone again is answered `applied`.
+* `delete` with a matching `baseVersion` turns the record into a tombstone through the normal delete pipeline (the
+  model's delete rights, `securityCheck`, audit apply). Deleting a tombstone again is answered `applied`. A delete through
+  any other route of the server leaves a tombstone too, so clients learn of it the same way.
 * An `upsert` on a tombstone is a conflict, never a silent resurrection.
 
 ### 6.4 Conflicts
@@ -219,9 +236,9 @@ A conflict is a `baseVersion` that no longer matches. What happens is the model'
 ```json
 {
   "results": [
-    { "mutationId": "0190f8b3-…", "id": "0190f8a2-…", "status": "applied", "version": 3 },
+    { "mutationId": "0190f8b3-…", "id": "6720c0…", "status": "applied", "version": 3 },
     { "mutationId": "0190f8b4-…", "id": "6720c1…", "status": "conflict", "version": 7, "record": { … } },
-    { "mutationId": "0190f8b5-…", "id": "0190f8a9-…", "status": "rejected", "code": "VALIDATION_FAILED", "details": [ … ] }
+    { "mutationId": "0190f8b5-…", "id": "6720c9…", "status": "rejected", "code": "VALIDATION_FAILED", "details": [ … ] }
   ]
 }
 ```
@@ -241,7 +258,7 @@ A conflict is a `baseVersion` that no longer matches. What happens is the model'
 |---|---|
 | `VALIDATION_FAILED` | `data` failed input validation; `details` lists the fields. |
 | `FORBIDDEN` | The caller may not change this record or these fields. |
-| `INVALID_ID` | The id has neither accepted format. |
+| `INVALID_ID` | The id does not match the model's id format (§3). |
 | `ID_UNAVAILABLE` | The id cannot be used (§3); no further detail by design. |
 | `CUSTOM_REFUSED` | The `custom` conflict hook refused the change. |
 
@@ -257,7 +274,7 @@ When the server cannot continue a cursor consistently, pull answers:
 | `reason` | Cause |
 |---|---|
 | `horizon` | The cursor is older than the tombstone retention horizon; deletions in between may be gone. |
-| `access` | The caller's access changed since the cursor was issued: a tenant membership removed, a role changed, a record moved to another tenant or visibility scope. |
+| `access` | The caller's access changed since the cursor was issued while the caller may still pull the model: a tenant membership removed (on a pull without `X-Tenant-Id`), a role changed, a record moved to another tenant or visibility scope. Once the caller may not pull the model at all, the pull answers `403` instead (§10). |
 | `invalid` | The cursor is malformed, was issued for another model or user, or for an incompatible sync configuration. |
 
 **Client procedure:** keep the unsent local changes, delete every local record of that model, pull without a cursor
@@ -272,13 +289,18 @@ start, on the `online` event and on focus. The server never assumes a client syn
 Sync API exists only in Chromium).
 
 * **SSE** for every web client: `GET /sync/hints?models=note,task` with `Accept: text/event-stream`, authenticated like
-  any request. Events: `event: change` with `data: {"model":"note","at":"2026-11-02T09:15:44.002Z"}`; a comment line
-  every 25 seconds keeps proxies from closing the stream.
+  any request (`models` optional: all models without it; a name that is not offered never matches). Events:
+  `event: change` with `data: {"model":"note","at":"2026-11-02T09:15:44.002Z"}`; a comment line every 25 seconds keeps
+  proxies from closing the stream, and `retry: 3000` tells the EventSource how soon to reconnect. A signed-in caller
+  always gets the stream (`200`); models the caller may not pull simply never send a hint, so the stream reveals
+  nothing about which models exist. `404` when the server switched the SSE channel off.
 * **GraphQL subscription** for clients that use GraphQL: `subscription { syncHint(models: ["note"]) { model at } }`.
 * A hint carries the model name and a time — no record, no id, no tenant. It is sent only to subscribers who hold the
   model's pull roles and may read the changed tenant's records of that model; bursts are collapsed (default 250 ms).
 * Both channels are long-lived, so the server checks them again during their lifetime like its GraphQL WebSockets: a
-  channel whose user lost access, signed out or changed roles is closed; the client reconnects and is checked anew.
+  channel whose user lost access, signed out or changed roles is closed; the client reconnects and is checked anew. An
+  SSE stream also ends before its first hint after the re-check interval (30 s by default) and is reconnected — a hint
+  is never delivered on rights older than that.
 * On reconnect a client pulls once, because hints sent while it was disconnected are not replayed.
 
 ## 10. HTTP errors
@@ -287,40 +309,49 @@ Sync API exists only in Chromium).
 |---|---|
 | `400` | Malformed body or query, unknown `op`, more than `maxPushItems` items. |
 | `401` | Not authenticated or session expired. Nothing was applied. |
-| `403` | Authenticated, but without the model's pull roles (pull, hints); a cookie-authenticated push failing the origin rules. A push item lacking the operation's roles is `rejected` / `FORBIDDEN` (§7). |
+| `403` | On a pull: the caller may not pull the model (pull roles withdrawn), or `X-Tenant-Id` names a tenant they left or that was deactivated — access loss like `410 access`: delete that model's (and tenant's) local records and cursor; the unsent changes cannot be pushed under this account (§11). On a push: a cookie-authenticated push failing the origin rules. A push item lacking the operation's roles is `rejected` / `FORBIDDEN` (§7). |
 | `404` | The model is not registered for sync. |
 | `410` | Resync required (§8). |
 | `413` | The body exceeds the server's limit. |
 | `429` | Rate limit; `Retry-After` says when to try again. |
 | `503` | A store needed for the request is unavailable; retry later. |
 
-Error bodies use the framework's error-code format (`#LTNS_…` codes, registered when the module ships).
+Error bodies use the framework's error-code format, sync codes in `#LTNS_0700`–`#LTNS_0799` (`SYNC_RESYNC_REQUIRED`,
+`SYNC_MODEL_NOT_FOUND`, `SYNC_INVALID_REQUEST`, `SYNC_ORIGIN_REFUSED`, `SYNC_STORE_UNAVAILABLE`; 429 is
+`RATE_LIMIT_EXCEEDED`). The `410` body is always the one §8 shows, whatever exception filter the project registered.
 
 ## 11. Client duties
 
 * Sync at start, on `online`, on focus, and after a hint; back off exponentially on `429`, `503` and network errors.
-* Generate ids (uuidv7 recommended) and mutation ids locally; persist unsent changes with their mutation ids until a
+* Generate ids in the model's format with the random part §3 requires, and mutation ids, locally; persist unsent changes with their mutation ids until a
   terminal status (`applied`, `merged`, `conflict`, `rejected`, `not_found`) arrives.
 * Give every queued change of one record the `baseVersion` the change before it produces (§6.2), or fold them into one
   item; push them in that order.
 * Store each pulled page and its cursor atomically; compare `version` before overwriting a local record.
-* **On logout delete every local record and the cursors.** The device holds personal data outside the server; the
-  integration guide of the sync module lists what to delete.
+* **On logout delete every local record, the cursors and the unsent changes**, and do the same before another user's
+  first pull. The device holds personal data outside the server; the sync module's `SECURITY.md` lists what to delete
+  and how to keep the credential out of reach.
+* **On `410 access` and on `403` to a pull, delete the local records of that model** (and tenant) and the cursor — the
+  caller lost access, and the device must not keep what the server would no longer send (§8, §10, the module's
+  `SECURITY.md`).
 * Treat a cleared storage as a fresh start (no cursor).
 
 ## 12. What the server guarantees
 
 * Pull and push run through the same `@Restricted`, `securityCheck`, tenant and output pipeline as every other
   request, with the operation roles the model declares for sync (§1); hints reach only callers with the pull roles.
-* A pull never delivers a record or tombstone of another tenant; a push never changes one and never reveals that one
-  exists (`not_found` / `ID_UNAVAILABLE`, §3, §7).
+* A pull never delivers a record or tombstone of another tenant; a push never changes one. An update or delete of it
+  answers `not_found` like an unused id, a create on its id `ID_UNAVAILABLE` — the same answer for every reason, with
+  nothing about the record; that an id is taken stays observable by design (§3, decided O2, §15).
 * Tombstones carry no content field. On a model whose records only certain users may see, the tombstone keeps the
   user-id fields the model declares as its scope (e.g. `ownerId`, decided O1, §15), so it reaches exactly the users who
   could see the record — never the rest of the tenant.
 * Hard deletes are not reachable through sync.
 * Changes are never lost by the cursor (§5.3) and never duplicated by retries (§6.5).
-* Idempotency records, rate-limit counters and the retention horizon live in infrastructure stores with an explicit
-  expiry condition, never in a TTL index; expired tombstones are removed by a cron job under the `LockStore` lease.
+* Idempotency records and rate-limit counters live in infrastructure stores with an explicit expiry condition that
+  every reader checks itself — a TTL index (MongoDB) or the expiry sweep (SQL) only removes what has expired. The
+  retention horizon never expires. Tombstones older than `sync.retention.tombstonesDays` (90 days) are removed every
+  hour under a lease, after the horizon moved past them.
 
 ## 13. Compatibility
 
@@ -353,13 +384,16 @@ Every requirement of DEV-3819 and where this document meets it (P = `.claude/pla
 | Unique indexes do not fail on tombstones (partial; MySQL via generated column) | P §3.3 (E3), P §3.6 |
 | Cursor without loss across instances, clocks, equal timestamps, late commits; prototype decides | §5.3, P §3.4, P phase 2 |
 | Push item-atomic; batch transaction only with `capabilities.transactions`, not the default | §6.3 |
-| Hints via `capabilities.changeFeed` where present, else emitted by the CrudService via in-process / Redis pub/sub | §9, P §3.9 |
+| Hints emitted by the store after every successful write, via in-process / Redis pub/sub; no change feed (P2-5, §15) | §9, P §3.9 |
 | Idempotency keys, rate-limit counters, retention horizon in infrastructure stores with explicit expiry; cron sweep under `LockStore` | §12, P §3.7 |
 | Every pull/push through the full pipeline; no `pullLean` | §1, §12 |
-| Tombstones carry `tenantId` and only `id`, `version`, `deletedAt`, `updatedAt` | §2, §12; plus declared user-id scope fields, decided O1 (§15) |
+| Tombstones carry `tenantId` and only `id`, `version`, `deletedAt`, `updatedAt` | §2, §12; plus declared user-id scope fields, decided O1 (§15); the server keeps the audit fields too (DEV-3900), a pull sends none |
 | Hard delete not reachable through sync | §6.2, §12 |
-| Access loss → client deletes local copies; at least a forced full resync | §8 |
-| Integration doc says what a client deletes on logout | §11 (detailed in the module's checklist, phase 6) |
+| Access loss → client deletes local copies; at least a forced full resync | §8 (`410 access`), §10 / §11 (`403` on a pull) |
+| Integration doc says what a client deletes on logout | §11, the module's `SECURITY.md` and its checklist |
+| Acceptance: the same contract suite green on MongoDB standalone and replica set, PostgreSQL × three engines (and MySQL, MariaDB) | `tests/sync-contract.e2e-spec.ts` (framework repository) |
+| Acceptance: no lost change with parallel writers on two instances with skewed clocks | `tests/sync-clock-skew.e2e-spec.ts` |
+| Acceptance: PWA test client in a browser, and a client without one, pass the same scenarios | `tests/sync-pwa-client.e2e-spec.ts`, `tests/sync-node-client.e2e-spec.ts` |
 | Without sync configuration nothing changes | §1, §13 |
 | Decisions 2026-10-29: both id formats, full resync on access loss, SSE + GraphQL, test clients, prototype decides the cursor | §3, §8, §9, P §11 |
 
@@ -367,10 +401,10 @@ Every requirement of DEV-3819 and where this document meets it (P = `.claude/pla
 
 | # | Question | Decided by | Notes |
 |---|---|---|---|
-| P2-1 | Cursor mechanism: change sequence with a commit horizon, or overlap window with `version` comparison | phase 2 prototype on MongoDB standalone and replica set, PostgreSQL × TypeORM / Kysely / Drizzle, MySQL, MariaDB | P §3.4 lists the candidates and what is measured |
-| P2-2 | Whether a page may repeat an unchanged record | phase 2, follows from P2-1 | Clients compare `version` either way (§5.2) |
-| P2-3 | MongoDB collections holding ObjectId and string `_id` side by side: casting, populate, sort, references | phase 2 | §3 |
-| P2-4 | Partial unique index on MongoDB with `{ deletedAt: { $type: 'null' } }`, on MySQL / MariaDB through virtual live-key columns (both refuse a plain partial unique index) | phase 2 contract case | P §3.6 |
-| P2-5 | Whether `capabilities.changeFeed` (change streams on a replica set, `LISTEN/NOTIFY` on PostgreSQL) is worth it for hints, measured against CrudService-emitted events | phase 2 | §9 |
+| P2-1 | Cursor mechanism: change sequence with a commit horizon, or overlap window with `version` comparison | **decided 2026-10-31 (DEV-3899, measured on all seven targets):** SQL — a commit-ordered sequence, the counter taken last (no horizon needed); MongoDB — the server clock with a window W derived from the transaction lifetime | P §3.4, P §5 |
+| P2-2 | Whether a page may repeat an unchanged record | **decided 2026-10-31 (DEV-3899):** on MongoDB yes, within W before the cursor; on SQL no | Clients compare `version` either way (§5.2) |
+| P2-3 | MongoDB collections holding ObjectId and string `_id` side by side: casting, populate, sort, references | **dropped 2026-10-29 (owner, DEV-3899):** one id format per model, never mixed — the question cannot arise | §3 |
+| P2-4 | Partial unique index on MongoDB with `{ deletedAt: { $type: 'null' } }`, on MySQL / MariaDB through virtual live-key columns (both refuse a plain partial unique index) | **decided 2026-10-31 (DEV-3899, measured):** MongoDB filters live records with `{ deletedAt: null }` (accepted on 5.0, 7.0, 8.2, covers a missing field, used by the matching query); PostgreSQL keeps `NULLS NOT DISTINCT` with `WHERE deleted_at IS NULL`; MySQL / MariaDB use the virtual live-key column. Every target refuses a second live value and a second live `NULL` and lets tombstones repeat a value | P §3.6, P §5 |
+| P2-5 | Whether `capabilities.changeFeed` (change streams on a replica set, `LISTEN/NOTIFY` on PostgreSQL) is worth it for hints, measured against CrudService-emitted events | **decided 2026-10-31 (DEV-3899):** no. A feed would add hints only for writes that bypass the store. Those reach a client with its next pull at the earliest (on SQL the sequence trigger numbers them too, on MongoDB they carry no cursor field and are not pulled at all — sync models are written through the store), and hints are optional by design. The store path is needed on MySQL, MariaDB and standalone MongoDB regardless. One source, the store's write events | §9, P §3.9 |
 | O1 | Tombstones on per-user-visibility models | **decided 2026-10-29 (owner):** a tombstone keeps the user-id fields the model declares as its scope (`syncScope`, e.g. `ownerId`) — only user ids, never content | §2, §12; otherwise a tombstone either reaches the whole tenant (ids and deletion times of other users' records) or nobody (a deletion never reaches the owner's other devices) |
 | O2 | Id collision with a record the caller may not see | **decided 2026-10-29 (owner):** the uniform `ID_UNAVAILABLE` stays, ids stay unique across tenants | §3; ids unique per tenant would change every lookup, reference and route by id in the framework |

package/docs/security-overrides.md

@@ -89,6 +89,20 @@ overrides:
   '@graphql-tools/utils@>=12.0.0 <12.1.0': '12.1.0'
 ```
 
+### Advisories no override can fix yet: `minimatch` and `glob` (2026-10-31)
+
+[GHSA-g3hv-75wg-m249](https://github.com/advisories/GHSA-g3hv-75wg-m249) (minimatch `< 11.0.1`, moderate, DoS
+through globparts amplification) and [GHSA-3g3m-2fjr-6pw4](https://github.com/advisories/GHSA-3g3m-2fjr-6pw4)
+(glob `<= 14.0.1`, moderate) are fixed only in new majors that no consumer can take yet: `@nestjs/cli` 12.0.11
+pins minimatch 10.2.6 exactly, ts-morph 28 (`@ts-morph/common` 0.29), nodemon, `@swc/cli` and glob 13 need the 9.x /
+10.x lines, rimraf 6.1.3 needs glob 13 — all on their newest release. An override across the major is no way out
+(minimatch 11 removed `makeRe()` and `Minimatch#regexp`). nest-server suppresses both in its own repository with
+`auditConfig.unusableFixConsumers`, which `check:overrides` re-tests on every run. What it found for its own tree:
+the only production path is `@lenne.tech/nest-server > ts-morph > @ts-morph/common > minimatch`, used by the
+Permissions module's scanner with globs the developer writes; every other path is dev tooling. Your project's tree
+may have other paths, so check `pnpm why minimatch --prod` and `pnpm why glob --prod` before you suppress the same
+way, and remove the entries once your consumers move to minimatch 11 / glob 14.
+
 ### Only on nest-server 11.x: `ws` and `js-yaml`
 
 `@nestjs/graphql` 13 and `@nestjs/swagger` 11 exact-pin vulnerable versions of these two; their 12.x

package/migration-guides/12.1.x-to-12.2.x.md

@@ -0,0 +1,154 @@
+# Migration Guide: 12.1.x → 12.2.x
+
+## No breaking change
+
+12.2.0 adds **offline sync**: mobile apps (React Native, Capacitor) with SQLite, web apps and PWAs with IndexedDB, and
+desktop or Node clients read and write while disconnected and reconcile with the server afterwards. It is opt-in in
+two places — the `sync` configuration and a declaration per model — and **without both nothing changes**: no field,
+index, route or code path is added, and a project's test suite stays as it is (protocol §13). It is a MINOR because of
+its size, not because anything existing moves.
+
+## Overview
+
+| Category | Details |
+|---|---|
+| **Breaking Changes** | None |
+| **New Features** | Synchronized models: `version`, tombstones, live-only unique indexes, a change order on every database (§2). The sync module: `GET/POST /sync/{model}` with cursor pull, idempotent push, conflict strategies, client ids, resync (§3). Change hints over SSE and GraphQL, tombstone purge, the `syncUpdate` migration helper (§4). `ServiceOptions.expectedVersion` for conditional changes of a synchronized model (§2) |
+| **Bugfixes** | None that change existing behaviour |
+| **Migration Effort** | None for an update. Offering a model to offline clients: about an hour per model, plus the client (§5) |
+
+## Quick Migration
+
+```bash
+pnpm add @lenne.tech/nest-server@12.2.0
+pnpm run build
+pnpm test
+```
+
+No dependency of a project changes. **Vendor mode**: run `/lt-dev:backend:update-nest-server-core` as usual; the new
+module is `src/core/modules/sync/`.
+
+## 1. What changes for an existing project
+
+Nothing, unless it switches offline sync on. The framework's own models are not synchronized, the `CrudService` keeps
+its behaviour for every model that does not declare `sync`, and no route is registered without the `sync`
+configuration.
+
+## 2. Synchronized models
+
+A model takes part in offline sync when it is declared with `sync` and registered with
+`CorePersistenceModule.forFeature()`:
+
+```typescript
+@PersistedModel({
+  sync: {
+    roles: { create: [RoleEnum.S_USER], delete: [RoleEnum.S_CREATOR], pull: [RoleEnum.S_USER], update: [RoleEnum.S_CREATOR] },
+    strategy: 'merge',
+  },
+})
+@Schema({ timestamps: true })
+@ObjectType()
+export class Note extends CorePersistenceModel { … }
+```
+
+The store then keeps three system fields on every write path — `version`, `deletedAt` and the change position
+(`syncSeq` on SQL, `syncAt` on MongoDB) — never settable through an input:
+
+- **Deletes leave tombstones**: `CrudService.delete()` and every port delete keep the record as a tombstone without
+  content, so clients learn of the deletion. Reads leave tombstones out.
+- **Unique indexes apply to live records only**, so delete-then-recreate with the same value works.
+- **Conditional changes**: `ServiceOptions.expectedVersion` on `update()` / `delete()` is one statement with the
+  version as its condition; another version answers `409` (`VersionConflictError`). Only a synchronized model has a
+  `version`: on any other model `expectedVersion` throws `UnsupportedCapabilityError`.
+
+**Making an EXISTING model synchronized is a migration** on every database — the boot refuses with the statements to
+run (SQL: the new column and live-only indexes; MongoDB: `SyncMigrationRequiredError`, dropping the old unique indexes
+and stamping every document). Details: `.claude/rules/persistence.md` → "Synchronized models".
+
+## 3. The sync module
+
+```typescript
+// config.env.ts
+sync: {
+  cursorSecret: process.env.SYNC_CURSOR_SECRET, // else SECRETS_ENCRYPTION_KEY; required in production/staging
+},
+```
+
+```typescript
+@SyncService({ createInput: NoteCreateInput, model: Note, updateInput: NoteInput })
+@Injectable()
+export class NoteService extends CrudService<Note, NoteCreateInput, NoteInput> { … }
+```
+
+- `GET /sync/{model}`: one page of changes after an opaque, signed cursor; `410` with a reason when the client must
+  resync (`invalid`, `horizon`, `access`).
+- `POST /sync/{model}`: items processed in order, each atomic; idempotent through mutation ids; client-generated ids
+  (ObjectId-hex with a random tail, or uuidv7 for new models); strategies `reject`, `lww`, `merge` (`@SyncField()` for
+  fields), `custom` (`resolveSyncConflict()` on the service).
+- Every pull and push runs through the model's `CrudService` with the roles from `sync.roles` — the roles of the
+  project's own routes do not apply here, and an operation without roles is ADMIN only.
+- Without `X-Tenant-Id` a request spans every tenant the caller belongs to.
+
+The protocol for client authors: `docs/offline-sync-protocol.md`. The module: `src/core/modules/sync/README.md`.
+
+## 4. Hints, purge, data migrations
+
+- **Hints**: `GET /sync/hints` (Server-Sent Events, event `change`) and the GraphQL subscription `syncHint(models)` tell
+  a client "pull now" — `{ model, at }` only, to callers with the pull roles and access to the tenant. With `redis`
+  every replica's subscribers receive them. `sync.hints: false` switches them off.
+- **Purge**: tombstones older than `sync.retention.tombstonesDays` (90) are deleted every hour on one replica, after
+  the retention horizon moved past them; a client behind it resyncs.
+- **Data migrations** of a synchronized SQL table: `runSqlMigration(ownerUrl, [{ syncUpdate: { table, set, where } }])`
+  raises `version` and numbers the rows like a store write. A bare `UPDATE` would let a stale client overwrite the
+  migrated value without a conflict.
+- **Writes past the CrudService** (data store, native API) call `CoreSyncService.notifyChange()` for hints and
+  `bumpAccessEpoch()` when a record changes tenant or owner.
+
+## 5. Offering a model to offline clients — checklist
+
+Follow `src/core/modules/sync/INTEGRATION-CHECKLIST.md`. In short:
+
+1. Declare `@PersistedModel({ sync: { roles, strategy } })` and register the model with `CorePersistenceModule.forFeature()`.
+2. Put `@SyncService({ model, createInput, updateInput })` on its `CrudService`.
+3. Add `sync: {}` (with a `cursorSecret` for deployed stages) to the configuration.
+4. Give the client its duties: delete every local record, cursor and unsent change on logout and on an account switch
+   (`src/core/modules/sync/SECURITY.md`).
+
+The reference model is `src/server/modules/sync-note/`; the framework's own test clients (a PWA on IndexedDB and a Node
+client on SQLite, `tests/clients/` in the framework repository) show a complete client in a few hundred lines.
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---|---|
+| Project without `sync` configuration | Unchanged |
+| Model without `sync` in a project with `sync` | Unchanged; not reachable under `/sync` |
+| `CrudService.delete()` on a synchronized model | Leaves a tombstone; a hard delete is the purge's alone |
+| Project controller extending `CoreSyncController` | Fine — the hint route is `CoreSyncHintsController`'s, registered first, so re-declaring `pull()` cannot shadow it |
+| TTL index on a synchronized model | Refused at registration — an expired record would vanish without a tombstone |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Boot fails: `cursorSecret` missing | Production / staging without `sync.cursorSecret` or `SECRETS_ENCRYPTION_KEY` | Set one of them |
+| Boot fails with SQL statements or `SyncMigrationRequiredError` | An existing model was declared `sync` | Run the printed migration (§2) |
+| Warning "declares no sync roles" | `sync.roles` missing an operation | Declare roles per operation; otherwise ADMIN only |
+| `400` on a push | `Content-Type` is not `application/json` | Send JSON |
+| `403` on a cookie push | `Sec-Fetch-Site: cross-site` or an untrusted `Origin` | Push from a trusted origin (`appUrl`, `baseUrl`, `cors.allowedOrigins`) |
+| Every cursor answers `410 invalid` | `cursorSecret` changed | Expected: clients resync once |
+| Boot fails on MySQL / MariaDB with error 1419 (`You do not have the SUPER privilege and binary logging is enabled`) once a model is declared `sync` | The change-order triggers are created by the owner account (`database.ownerUrl`); with binary logging on (the MySQL 8.4 default) that needs `SUPER` or `log_bin_trust_function_creators=1` | Set `log_bin_trust_function_creators=1` on the server (the parameter group on managed MySQL), or grant the owner `SUPER`. The application account needs neither |
+| A client keeps records after its user left a tenant | The client treats only `410 access` as access loss | A pull answering `403` (pull roles withdrawn, or `X-Tenant-Id` naming a left tenant) is access loss too: drop that model's local records and cursor (`SECURITY.md`) |
+| Hints only on one replica | No `redis` configured | Configure `redis`; hints are never a correctness signal |
+
+## Module Documentation
+
+- `src/core/modules/sync/README.md` — module overview, configuration, security model, hints, purge
+- `src/core/modules/sync/INTEGRATION-CHECKLIST.md` — integration steps
+- `src/core/modules/sync/SECURITY.md` — what the server enforces, what a client must do
+- `docs/offline-sync-protocol.md` — the client contract
+- `src/server/modules/sync-note/` — reference model
+
+## References
+
+- nest-server-starter: unaffected (it declares no synchronized model)

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "12.1.1",
+  "version": "12.2.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)",
@@ -263,6 +264,7 @@
     "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",
     "tsx": "4.23.15",