---
fragment_id: oscar.map.cloud-sync-stub.002
domain: MAP
rule: Forward-compat cloud-sync fields (stub — fields only, no behaviour)
source: app/src/data/models/MapLayer.ts, app/src/data/models/Document.ts
bound_to_modules:
  - oscar.map
status: SHIPPED
version: .002
---

# Cloud sync stub (per Item 9 of operator design + rules.md §13)

v0.2.0 adds forward-compat sync fields to `MapLayer` and `Document` records so a future cloud-sync doctrine pass can populate them without a schema migration. v0.2.0 has no behaviour that reads or writes these fields.

## Fields on MapLayer

```
MapLayer.syncState: 'local' | 'syncing' | 'synced' | 'conflict'   // default 'local'
MapLayer.syncedAt: ISO8601 | null                                   // default null
MapLayer.serverVersion: number | null                               // default null
```

## Fields on Document

```
Document.syncState: 'local' | 'syncing' | 'synced' | 'conflict'   // default 'local'
Document.syncedAt: ISO8601 | null                                   // default null
Document.serverVersion: number | null                               // default null
```

## v0.2.0 constraints (per rules.md §13)

v0.2.0 MUST NOT:

- Read any `syncState` field for behaviour
- Write any `syncState` field from anywhere (writes are reserved for the future cloud-sync pass)
- Make sync state visible in any UI surface (no "synced" badges, no "syncing..." spinners related to cloud)
- Block any operation based on `syncState !== 'synced'`

The fields exist purely for forward compatibility. Their presence in v0.2.0 is a no-op. They MUST be defaulted correctly on record creation and on record read (legacy v0.1.0 records read with `syncState: 'local'`, `syncedAt: null`, `serverVersion: null`).

## Why this exists

The cloud-sync feature is out of scope for v0.2.0. Adding the fields now means:

- The schema is already shaped for sync when the feature lands
- A future cloud-sync doctrine pass can write a fragment that simply defines the sync behaviour, without touching the data model
- No migration is required when sync lands — records already have the right shape

## Future doctrine pass (not in v0.2.0)

A future `oscar.map.cloud-sync.003` doctrine pass (version .003 fragments) will define:

- The sync queue data structure
- The conflict resolution policy
- The auth flow
- The operator profile shape (currently hard-coded to 'operator' in version ledger per oscar.map.versioning.002)
- The cloud backend contract

Until that doctrine pass lands, the sync fields are dormant.