Skip to content
pgxsinkit

buildSyncStateView

buildSyncStateView<TTable>(entry, projection): string

Defined in: packages/contracts/src/convergence-model.ts:88

Generate the per-writable-table <table>_sync_state view (ADR-0011 decision 2): a derived projection — never a stored copy — over synced + overlay + journal that answers “what is this entity’s convergence state?” with one authoritative, queryable row per entity that has local activity (an overlay or journal row). Keyed on the real PK columns, never a generic entity_key_json (decision 2).

Columns:

  • observed_server_version — the synced row’s Server version (NULL when no echo has landed).
  • acked_server_version — the highest Server version the server assigned to our acked writes.
  • pending_count — journal rows still owed to the server (pending/sending/failed).
  • has_acked_unobserved_write — an acked create/update whose echo has not yet caught up. Derived from the same buildOverlayResolutionBarrier predicate the resolver uses (decision 4), so what the UI shows can never drift from what the resolver does.
  • local_delete_pending — an optimistic delete is staged in the overlay.
  • conflict_state — the reason a conflicted (stale, reject-if-stale) write was declined, or NULL when the entity has no conflicted mutation (ADR-0015). Surfaced from the journal’s conflict_reason, scoped to status = 'conflicted' so a stale failure reason never leaks in.
  • quarantined_count — terminal local writes the server permanently rejected (ADR-0006): a poison mutation named in a batch rejection, or one that exhausted the attempt cap. Quarantine blocks sync and keeps the optimistic overlay, so without this the view would show an entity with pending_count = 0 and conflict_state = NULL yet still carrying un-converged local intent.
  • quarantine_state — the last_error of a quarantined write (the rejection reason), or NULL when the entity has none. The reason counterpart to quarantined_count, mirroring conflict_state.

Note pending_count is the retryable owed set (pending/sending/failed); a quarantined write is terminal, counted separately so a blocked write is never mistaken for one still in flight.

The Read model stays lean (it already carries overlay_kind); an app that wants per-row convergence status joins this view on the PK.

Type Parameters

Section titled “Type Parameters”

TTable

Section titled “TTable”

TTable extends AnyPgTable

Parameters

Section titled “Parameters”

entry

Section titled “entry”

SyncTableEntry<TTable>

projection

Section titled “projection”

SyncStateViewProjection

Returns

Section titled “Returns”

string