Crate baukit_sync 

Revision allocation and hybrid logical clocks for incremental sync.

A syncable row carries a revision drawn from a counter that is private to its owner. A client pulls by asking for everything above the revision it last saw, so the counter must be monotonic per owner and must move in the same transaction as the row write it stamps. next_revision does exactly that. The hlc module supplies a cross-runtime logical clock for ordering writes when physical clocks stall or move backward.

What this crate is not

Baukit does not standardize a sync protocol. Wire payloads, conflict resolution, batching, and the pull endpoint stay product-owned, as docs/platform/offline-readiness-contract.md says. This crate owns two mechanisms: revision allocation and timestamp generation. Merge rules stay product-owned.

Schema

Products copy POSTGRES_MIGRATION_SQL into their own ordered migrations; the crate never runs migrations at process startup. Products whose existing counter uses user_id can instead copy POSTGRES_RENAME_USER_ID_TO_OWNER_ID_SQL. The reference migration also documents the column convention every syncable table follows: id, owner_id, updated_at, deleted_at, revision, plus an (owner_id, revision) index.

Usage

Call next_revision inside the transaction that writes the row, and stamp the returned value onto that row. If the transaction rolls back, the allocation rolls back with it and the revision is never handed out.

let mut transaction = pool.begin().await?;
let revision = baukit_sync::next_revision(&mut transaction, owner_id).await?;
sqlx::query("UPDATE product_records SET revision = $1 WHERE owner_id = $2")
    .bind(revision)
    .bind(owner_id)
    .execute(&mut *transaction)
    .await?;
transaction.commit().await?;

Modules

hlc

Hybrid logical timestamps compatible with JavaScript safe integers.

Constants

POSTGRES_MIGRATION_SQL

Reference PostgreSQL schema and column convention for product migrations.

POSTGRES_RENAME_USER_ID_TO_OWNER_ID_SQL

One-shot PostgreSQL migration from sync_revisions.user_id to owner_id.

Functions

current_revision

Reads the owner’s current revision without allocating a new one.

current_revision_for_update

Reads and locks the owner’s current revision without allocating a new one.

ensure_owner

Creates the owner’s revision counter if it does not exist yet.

next_revision

Allocates the owner’s next revision inside the caller’s transaction.