Change feeds and checkpoints
sync_changes reports authorized local change identities after a caller-owned
checkpoint. It is a delta feed, not a full snapshot, baseline export or provider
change stream. Call the normal resource reader to obtain current detail and bytes;
a change identity does not preserve permission to read that resource later.
Checkpoint protocol
Section titled “Checkpoint protocol”The MCP path validates a UUID cursor and a page size from 1 to 50, defaulting to 50. The underlying database RPC accepts up to 100; that larger bound is not the public tool’s accepted limit. The database binds each cursor to Auth user, selected company, permitted source types, visibility epoch and page size. It serializes the checkpoint/page decision under the feed’s transaction/locks and preserves a returned page/replacement for replay.
| Result | Meaning | Next action |
|---|---|---|
snapshot_required |
New checkpoint at the current feed position, with no baseline data | Save data.cursor; read subsequent changes with the same limit. The name does not imply an available snapshot endpoint. |
ok |
One authorized delta page; an empty final page is valid | Save the returned cursor/data.next, including limit, for the next check. |
resync_required |
Visibility/source set changed or retained history is insufficient | Follow its reason, clear data whose authority may have changed and use the replacement checkpoint. |
invalid_cursor or expired_cursor |
That cursor cannot continue this caller’s feed | Open a new checkpoint rather than rewriting the old cursor. |
| Limit mismatch or malformed cursor | Arguments violate the continuation contract | Preserve the original page size; correct the supplied arguments. |
Replaying a cursor is not a new authorization grant. Company/user binding remains required. The MCP service calls the database RPC with the incoming caller bearer and then rechecks message events against current inbox visibility. Selected downstream bearer reuse remains an explicit MCP boundary.
Source coverage
Section titled “Source coverage”The response includes source coverage for the caller. Complete/partial/forbidden classifications describe each registered source contract, not a universal guarantee that every relevant aggregate or provider event appears. Projects, work orders, customers, invoices/payments, conversations, document metadata, purchase invoices, articles, deliveries, accounts, vouchers and payroll receipts have different coverage statements in the implementation.
For example, message events identify conversations/messages; attachment bytes require a separate authorized document read. Document changes cover selected project/work-order file metadata, not every archived candidate or original byte. Payment events cover Toolora’s connector projection; current register/deletion parity remains a separate reconciliation fact. A payroll receipt event is not proof of a payroll run.
Visibility and retained history
Section titled “Visibility and retained history”Changes in capability/source availability or resource visibility can require a replacement checkpoint. The current RPC reports reasons such as visibility change, source-type change, both, or expired retained change history. Previously cached records may need to be discarded or revalidated. A cursor is not a frozen company snapshot; ordinary source reads can see a later current state.
The API’s returned counts reflect the filtered result. Do not infer that a batch of zero retained message events means no company activity occurred: permission filtering can remove events from the visible page. Likewise, a new checkpoint starts future tracking; it cannot establish complete historical synchronization.
Synthetic example and recovery
Section titled “Synthetic example and recovery”Synthetic User A opens a checkpoint with limit 17, then reuses exactly that limit on every continuation. If another company’s user supplies the cursor, company/user binding refuses that continuation. If A loses a visible resource, honor the resynchronization instruction and recheck cached detail rather than retaining old authority through a saved reference.
Use a new checkpoint after invalid/expired history and preserve the explicit coverage gap. Do not advance an invented sequence, clear history tables or turn a partial source into a complete export. Deterministic wrapper tests and actual SQL-role/continuation tests prove different parts of this contract; the delivery PR states executed and reused evidence. No shared-company export is performed.