Skip to content

Latest commit

 

History

History
419 lines (354 loc) · 33.3 KB

offline-sync-protocol.md

File metadata and controls

419 lines (354 loc) · 33.3 KB

Offline sync protocol

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 epic's design plan, which the team keeps outside this public repository; references to §15 below point into its list of decisions.

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 JSON; a client needs fetch and nothing from the server's code. It serves mobile apps (React Native, Capacitor) with SQLite, web apps and PWAs with IndexedDB or SQLite-WASM, and desktop or Node clients — on every database the server supports (MongoDB, PostgreSQL with any engine, MySQL / MariaDB) with the same observable behaviour.

1. Principles

  1. Stateless server. The server keeps nothing per device. The cursor is opaque, owned by the client, and every device and every browser tab may hold its own.
  2. The same security pipeline as every other request. A pull reads through CrudService (rights, @Restricted, securityCheck, tenant policy before every store call, tenant row check after every read, row-level security on PostgreSQL, interceptors); a push writes through it. There is no lean path around it.
  3. Operation rights are declared for sync. The roles a project puts on its own routes (@Roles on a controller, roles passed to update() in a controller) do not reach /sync. Each sync model declares who may pull, create, update and delete; an operation without a declaration is open to administrators only.
  4. Every pushed change stands alone. Each item is applied atomically and independently; one failing item never rolls back another.
  5. No silent loss. When the server cannot deliver a consistent delta — a cursor behind the retention horizon, a changed access scope — it says so (§8) instead of returning partial data.
  6. Opt-in per model. A project without a sync configuration gets no new field, index, route or code path.

2. Concepts

Term Meaning
Sync model A model the project declared syncable. Only those are reachable under /sync.
Record One row/document of a sync model as the client sees it, read through the normal output pipeline.
id The record's id, chosen by the client for records it creates (§3).
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). 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, in the one format the model declares:

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.
  • 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 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 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 — 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 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; 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).
  • Size limits: push accepts at most maxPushItems items (default 100) and the server's JSON body limit; pull pages are bounded by count and by size (§5.2).
  • Rate limits: pull and push have their own per-user limits; a refused request answers 429 with Retry-After.

5. Pull

5.1 Request

GET /sync/{model}?cursor={cursor}&limit={n}
Parameter Meaning
cursor Absent: start from nothing (a full state, in pages). Present: continue after this cursor.
limit Records per page, 1..maxPullLimit (default 200, maximum 1000).

5.2 Response

{
  "items": [
    { "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…",
  "hasMore": true
}
  • items holds live records (with data, the record as the normal output pipeline returns it, minus id, version, updatedAt and deletedAt) and tombstones (no data).
  • A page ends at limit records or when its serialized size reaches maxPullBytes (default 1 MiB), whichever comes first — a page always holds at least one item when one is pending. hasMore says whether to ask again immediately.
  • cursor is returned on every page and is a valid resume point: a client that crashes after storing page n and its 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. 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.

5.3 What a pull guarantees

  • 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. 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

6.1 Request

POST /sync/{model}
Content-Type: application/json

{ "items": [ … ] }

6.2 Item

{ "mutationId": "0190f8b3-…", "op": "upsert", "id": "6720c0…", "baseVersion": 2, "data": { "title": "…" } }
{ "mutationId": "0190f8b4-…", "op": "delete", "id": "6720c1…", "baseVersion": 5 }
Field Meaning
mutationId Unique per change, generated by the client (uuidv7). The same change sent again carries the same mutationId.
op upsert (create or update) or delete (creates a tombstone; a hard delete is not reachable through sync).
id The record's id (§3).
baseVersion The version the client's change is based on. Absent only on the item that creates the record. Every later item carries the version the item before it produces — a create gives 1, each applied change adds 1 (§6.3) — so a record created and changed twice offline is pushed as the create, then baseVersion: 1, then baseVersion: 2. Such a chain may travel in one request: when an item of it is not stored, the server holds the rest back (§6.3). A client may instead fold all unsent changes of one record into a single item.
data The fields to set, validated against the model's input type like any create/update. Absent for delete.
fields Optional, for merge: the field names the client changed. Without it, every key in data counts as changed.

6.3 Processing

  • Items are processed in the order sent, each in its own atomic step. A batch is not a transaction: on a database without transactions (MongoDB standalone) it could not be one, so it is not one anywhere.
  • An item referencing a record created earlier in the same batch sees that record.
  • Once an item of a record is not stored (conflict, rejected, not_found, retry), the later items of that record in the same batch are held back: never applied, answered retry behind a retry (send them again together), otherwise conflict with the server's record (not_found when the caller may not see one). Each of them builds on the version the item before it produces (§6.2); applied on its own, its baseVersion could match another writer's version and the change would land on data the client never saw. Items of other records are unaffected. The server holds back within one request only; across requests the client keeps the order (§11).
  • upsert without baseVersion on an id that does not exist creates the record with version: 1.
  • 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 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

A conflict is a baseVersion that no longer matches. What happens is the model's (or field's) strategy:

Strategy Result
reject (default) Nothing changes; status conflict with the server's record. The client decides.
lww The change is applied on top of the current state. "Last" means last to arrive at the server, never the device's clock. Status applied.
merge Field by field: fields the client changed overwrite, fields only the server changed stay. Fields declared reject still conflict. Status merged with the resulting record.
custom A project hook receives the server record, the client change and the base version and returns the result or a refusal; it runs inside the same pipeline.

6.5 Repeats and parallel tabs

  • A repeated create is recognised by its id; a repeated change by its mutationId. The server records the outcome of every mutation id for mutationRetention (default 30 days) and answers a repeat with the recorded status and the current record — whether the first attempt's response was lost or the client retried after a login. When two tabs send the same change at once, one is applied and the other is answered retry while the first is still in progress; sent again, it receives the recorded outcome. Neither a duplicate nor a false conflict results.
  • After mutationRetention the server no longer recognises the mutation id. A repeated create meets its own record and is answered conflict with it (§3); the client compares it with its local copy and resolves it like any conflict. A repeated change meets its own effect as a version mismatch, and the strategy decides: reject answers conflict with the server's record, which already contains the change; lww writes the same values again; merge answers merged. Never a duplicate record.
  • Tabs sharing one IndexedDB should still coordinate (Web Locks API or a BroadcastChannel leader) to avoid needless traffic; correctness does not depend on it.

6.6 Response

200 with one result per item, in the order sent:

{
  "results": [
    { "mutationId": "0190f8b3-…", "id": "6720c0…", "status": "applied", "version": 3 },
    { "mutationId": "0190f8b4-…", "id": "6720c1…", "status": "conflict", "version": 7, "record": { … } },
    { "mutationId": "0190f8b5-…", "id": "6720c9…", "status": "rejected", "code": "VALIDATION_FAILED", "details": [ … ] }
  ]
}

7. Item statuses and codes

Status Meaning Client action
applied The change is stored (also for a recognised repeat). version is the new version. Store version; mark the change sent.
merged Stored after a field merge; record is the result. Replace the local record.
conflict Not stored; record is the server's current record (a tombstone when it was deleted). Resolve, then push again with baseVersion = record.version, or drop the change.
rejected Not stored, for the reason in code. Retrying the same change will not help. Show or log; drop or correct the change — and the record's later changes, which built on it.
not_found An update or delete for a record that does not exist or that the caller may not see — the same answer for both. Drop the local record and its queued changes.
retry Not stored for a transient reason (a lock timeout, a store outage, the same mutationId still in progress). Send the same item again later, the record's later changes with it — never before it.
code (with rejected) Meaning
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 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.

8. Resync

When the server cannot continue a cursor consistently, pull answers:

410 Gone
{ "code": "SYNC_RESYNC_REQUIRED", "reason": "horizon" }
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 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 until hasMore is false, then push the kept changes (they meet the new state through the normal conflict rules). After an access resync records the client may no longer see are gone, which is the point. The server forces this resync rather than sending a removal per record; a per-record signal may follow later.

9. Hints

Hints tell a connected client that pulling is worthwhile. They are optional: sync works with pull alone, triggered at start, on the online event and on focus. The server never assumes a client syncs in the background (the Background 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 (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. 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

Status When
400 Malformed body or query, unknown op, more than maxPushItems items.
401 Not authenticated or session expired. Nothing was applied.
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, 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 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. Send a later change only in the same request as the change before it, or after that one came back applied or merged: the server holds a chain back within one request only (§6.3), and a later change sent on its own could match another writer's version.
  • Store each pulled page and its cursor atomically; compare version before overwriting a local record.
  • 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. 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 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

Without a sync configuration nothing changes: no field, index, route or code path is added, and the test suite of a project stays as it is.

14. Requirement trace

Every requirement of DEV-3819 and where this document meets it (P = the offline-sync design plan).

Requirement (DEV-3819) Where
HTTP with JSON, fully documented, client needs only fetch §1, §4–§10
No per-device server state; opaque client-owned cursor, one per device/tab §1, §5.2
Clients create ids in the server format, repeated create idempotent after days, format checked §3, §6.5
Id collision with a foreign record does not reveal it §3, §7 (ID_UNAVAILABLE), decided O2 (§15)
Pull pages bounded by count and size; full state without cursor; resume after abort §5.1, §5.2
Cursor behind the tombstone horizon → clear "resync" (410) §8
Optional, exchangeable hint channel: GraphQL subscription and SSE; pull-only works §9
Conflict strategies reject / lww / merge / custom; LWW by server arrival order §6.4
Cookie and bearer auth; cookie push under the CSRF/origin rules of all writes §4
Expired session while offline → 401, nothing discarded, resend without duplicates §4, §6.5
Parallel pushes from several tabs: no duplicates, no false conflicts §6.5
Cleared browser storage starts cleanly §5.2, §11
No background push assumed; sync on start, online, focus §9, §11
Only the DataStore port and the neutral query language; differences via store.capabilities P §3.1, P §3.3
version, deletedAt, cursor field and index from model metadata; SQL schema evolution adds them P §3.2, P §3.6
Optimistic lock as an atomic conditional change, port operation with contract test §6.3, P §3.3 (E1)
Tombstones filtered from all normal reads incl. count, distinct, populate P §3.3 (E2)
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 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); 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 (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

15. Open questions

# Question Decided by Notes
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