Clears a persisted keyset resume position after a CLEAN scan (plan.md §8a), so the next run
starts a fresh seek from the beginning. Keeps the record (still WatermarkType='Cursor') for
bookkeeping but nulls the value — a null value is what the restore logic reads as "no scan in
progress". No-op when no watermark record exists yet.
Loads the current watermark for a specific entity map direction.
The CompanyIntegrationEntityMap ID to load the watermark for
User context for data access
The watermark entity if found, or null if no watermark exists yet
Loads the previously-stored partition→rollup map (empty map when none / first sync / wrong type), so the next reconcile can diff against it and deep-sync only the partitions whose rollup moved.
Persists a keyset/seek resume position for an INTERRUPTED scan (plan.md §8a).
Stored on the Pull watermark record as WatermarkType='Cursor' so Load surfaces it and
ProcessPullSync can resume the seek (key > AfterKey) on the next run instead of re-scanning
from the start. Only meaningful for connectors that declare a StableOrderingKey; the engine
gates the call on that, so a timestamp connector's record is never written here. Idempotent —
safe to call repeatedly at the checkpoint cadence and once more on graceful early-exit.
Persists the partition→rollup map for a partition hash-diff (Merkle) reconcile of a watermark-less
source (plan.md §7). Stored on the Pull watermark record as WatermarkType='ChangeToken' (the
map IS an opaque change-detection token), JSON-encoded. The object is no-watermark, so this field
is free; a partition-reconcile object never also carries a timestamp/cursor. Idempotent upsert.
Updates or creates the watermark for a specific entity map. If a watermark record already exists, it is updated in place. If none exists, a new record is created.
The CompanyIntegrationEntityMap ID to update the watermark for
The new watermark value to store
User context for data access
Updates the progress fields on an existing watermark mid-sync without changing the WatermarkValue. Updates RecordsSynced to the cumulative total written so far and refreshes LastSyncAt so the DB reflects live progress between batches. Silently skips if no watermark record exists yet.
The entity map being synced
Cumulative number of records written to DB so far
User context for data access
Validates a watermark value against its expected type.
The watermark value to validate
The expected type of watermark
true if the watermark is valid for its type, false otherwise
Service for loading and updating sync watermarks used for incremental data fetching. Watermarks track the "last known position" so each sync only fetches changes since the last run.