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.
- 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.
- 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. - Operation rights are declared for sync. The roles a project puts on its own routes (
@Roleson a controller,rolespassed toupdate()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. - Every pushed change stands alone. Each item is applied atomically and independently; one failing item never rolls back another.
- 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.
- Opt-in per model. A project without a sync configuration gets no new field, index, route or code path.
| 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). |
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 answersID_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.
- Base path
/sync(configurable). Model names in paths are the names the project registered for sync. - Tenant: with
X-Tenant-Ida 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 undercors.allowAll, a development setting) — and push additionally requiresContent-Type: application/json(which forces a CORS preflight; required of every push,400otherwise) and, while the server uses cookies, refuses a request whoseOriginis not a trusted origin or whoseSec-Fetch-Siteiscross-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
401for 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
maxPushItemsitems (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
429withRetry-After.
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). |
{
"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
}itemsholds live records (withdata, the record as the normal output pipeline returns it, minusid,version,updatedAtanddeletedAt) and tombstones (nodata).- A page ends at
limitrecords or when its serialized size reachesmaxPullBytes(default 1 MiB), whichever comes first — a page always holds at least one item when one is pending.hasMoresays whether to ask again immediately. cursoris 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 higherversion. 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 compareversionand 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.
- 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
securityCheckhide.
POST /sync/{model}
Content-Type: application/json
{ "items": [ … ] }
{ "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. |
- 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, answeredretrybehind aretry(send them again together), otherwiseconflictwith the server's record (not_foundwhen the caller may not see one). Each of them builds on the version the item before it produces (§6.2); applied on its own, itsbaseVersioncould 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). upsertwithoutbaseVersionon an id that does not exist creates the record withversion: 1.upsertwithbaseVersionis an atomic conditional change: it applies only when the stored version still equalsbaseVersion(WHERE id = … AND version = …or the MongoDB equivalent; never read-then-write), and it incrementsversion.deletewith a matchingbaseVersionturns the record into a tombstone through the normal delete pipeline (the model's delete rights,securityCheck, audit apply). Deleting a tombstone again is answeredapplied. A delete through any other route of the server leaves a tombstone too, so clients learn of it the same way.- An
upserton a tombstone is a conflict, never a silent resurrection.
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. |
- A repeated create is recognised by its id; a repeated change by its
mutationId. The server records the outcome of every mutation id formutationRetention(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 answeredretrywhile the first is still in progress; sent again, it receives the recorded outcome. Neither a duplicate nor a false conflict results. - After
mutationRetentionthe server no longer recognises the mutation id. A repeated create meets its own record and is answeredconflictwith 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:rejectanswersconflictwith the server's record, which already contains the change;lwwwrites the same values again;mergeanswersmerged. Never a duplicate record. - Tabs sharing one IndexedDB should still coordinate (Web Locks API or a
BroadcastChannelleader) to avoid needless traffic; correctness does not depend on it.
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": [ … ] }
]
}| 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. |
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.
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,taskwithAccept: text/event-stream, authenticated like any request (modelsoptional: all models without it; a name that is not offered never matches). Events:event: changewithdata: {"model":"note","at":"2026-11-02T09:15:44.002Z"}; a comment line every 25 seconds keeps proxies from closing the stream, andretry: 3000tells 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.404when 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.
| 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.
- Sync at start, on
online, on focus, and after a hint; back off exponentially on429,503and 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
baseVersionthe 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 backappliedormerged: 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
versionbefore 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.mdlists what to delete and how to keep the credential out of reach. - On
410 accessand on403to 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'sSECURITY.md). - Treat a cleared storage as a fresh start (no cursor).
- 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_foundlike an unused id, a create on its idID_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.
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.
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 |
| # | 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 |