Snapshot and incremental sync

Initial snapshot

1. Call health and record its public generation before reading any records.
2. Page /demand/gaps until next_cursor is null, checking meta.public_generation as each response arrives.
3. Reject the read if any page identifies a different generation.
4. Once the terminal page reports a complete snapshot, persist its returned records and meta.sync.checkpoint together.

Do not expose the partially paged dataset as a new local version. Build it separately, validate the terminal checkpoint, then replace the prior local snapshot atomically.

Incremental reads

Pass that terminal checkpoint to /demand/changes. Apply changes in response order and store each continuation with the page it accompanies.

A 409 means the checkpoint, filter window or public generation can no longer continue safely. Discard local incremental state and take a new full snapshot. Do not merge records from different generations.

Customer changes contain only scheduled cohort releases. A cohort release may supply a safe detail URL. If that URL returns 404, continue draining changes because a later tombstone or archive may already have won.

Partner snapshot and incremental syncSequence

Coherence checks

A client should verify:

1. every snapshot page has the same public generation;
2. the terminal page reports a complete full snapshot and an opaque checkpoint;
3. summary and taxonomy use that generation before presenting a combined dashboard; and
4. a probe from the terminal checkpoint contains no unseen change before the bundle is accepted.

Date-window snapshots use a repeated full read for the final consistency check because the changes resource rejects date filters.

Crash-safe local application

Store records, active filters, public generation and checkpoint as one local transaction. During incremental sync, apply each page and its continuation together. If the process stops before commit, repeat the page. If a detail lookup returns unavailable, continue the ordered feed.

Retain the last coherent local snapshot during 429 and 503 responses. Clear it only when your own retention policy requires it or authorization is no longer valid.