Client

oversqlite is the SQLite client SDK for the current bundle-based contract.

NewClient(...) installs the runtime and metadata tables, but it does not attach a user. The startup flow is:

1. Open(ctx)
2. Attach(ctx, userID) after sign-in
3. normal sync operations

oversqlite manages source identity internally. Host application code does not provide source ids to Open(), does not rotate them manually, and does not provide replacement source ids to Rebuild().

Authenticated sync requests still carry the runtime’s current source through Oversync-Source-ID. Auth remains separately host-owned.

SQLite State

• _sync_dirty_rows: one coalesced local dirty row per structured key
• _sync_snapshot_stage: rows staged during rebuild
• _sync_outbox_bundle: singleton frozen push snapshot state
• _sync_outbox_rows: rows belonging to that frozen snapshot
• _sync_push_stage: authoritative committed rows staged before final replay
• _sync_row_state: authoritative replicated row state for managed tables
• _sync_managed_tables: registry of managed tables whose triggers were installed by oversqlite
• _sync_source_state: per-source sequencing state and replacement lineage
• _sync_attachment_state: current source, binding state, bundle checkpoint, and rebuild gate
• _sync_operation_state: lifecycle and source-recovery state
• _sync_apply_state: trigger suppression state during authoritative local apply

Public Operations

• Open(ctx) error
• Attach(ctx, userID) (AttachResult, error)
• Detach(ctx) (DetachResult, error)
• PendingSyncStatus(ctx) (PendingSyncStatus, error)
• SyncStatus(ctx) (SyncStatus, error)
• SyncThenDetach(ctx) (SyncThenDetachResult, error)
• UninstallSync(ctx) error
• PushPending(ctx) (PushReport, error)
• PullToStable(ctx) (RemoteSyncReport, error)
• Sync(ctx) (SyncReport, error)
• Rebuild(ctx) (RemoteSyncReport, error)
• LastBundleSeqSeen(ctx) (int64, error)
• SourceInfo(ctx) (SourceInfo, error)

Optional Watch Wakeups

Config.BundleChangeWatchMode defaults to BundleChangeWatchOff. Set it to BundleChangeWatchAuto to let Start(ctx) use GET /sync/watch only when the server advertises bundle_change_watch=true.

Watch mode is a latency optimization. Events never mutate SQLite directly; the client wakes its existing pull/sync behavior, so dirty-row checks, outbox replay, source recovery, snapshot recovery, and download pause rules still apply. WatchFallbackInterval controls low-frequency fallback polling while a watch stream is active; 0 means BackoffMax, or 60s when BackoffMax is unset.

Preconditions

Require no prior lifecycle step:

• Open(ctx)

Require successful Open(ctx):

• Attach(ctx, userID)
• PendingSyncStatus(ctx)
• SourceInfo(ctx)
• UninstallSync(ctx)

Require successful Open(ctx) plus durable attached local state:

• Detach(ctx)

Require successful Open(ctx) plus successful Attach(ctx, userID):

• PushPending(ctx)
• PullToStable(ctx)
• Sync(ctx)
• Rebuild(ctx)
• SyncStatus(ctx)
• LastBundleSeqSeen(ctx)
• SyncThenDetach(ctx)

Recovery

• PullToStable() may rebuild from snapshots while keeping the current source when incremental history is below the retained floor
• committed-remote replay pruned below the retained floor uses keep-source rebuild behavior, advances local source sequencing past the already committed tuple, and clears committed-remote outbox state only after recovery succeeds
• stale/pruned, out-of-order, changed, or retired source upload cases enter durable source-recovery-required mode
• PushPending(), PullToStable(), and Sync() fail closed while source recovery is active
• Rebuild(ctx) is the explicit recovery entry point
• when source recovery is active, Rebuild(ctx) internally chooses rebuild-plus-rotate and preserves frozen outbox intent across that recovery

Source recovery can be entered for:

• history_pruned
• source_sequence_out_of_order
• source_sequence_changed
• source_retired

Host code should treat SourceRecoveryRequiredError as a durable recovery gate: surface that sync requires rebuild, call Rebuild(ctx) while authenticated, and let oversqlite manage the replacement source identity internally.

Diagnostic Surface

SourceInfo(ctx) is debug-only. It exposes:

• CurrentSourceID
• RebuildRequired
• SourceRecoveryRequired
• SourceRecoveryReason

CurrentSourceID is opaque. Callers must not persist it externally or treat its format as part of the host API contract.

Typed Preconditions And Results

• OpenRequiredError
• AttachRequiredError
• DestructiveTransitionInProgressError

Normal lifecycle and sync branches such as retry-later attach, blocked detach, paused push/pull, and already-at-target pull are reported as structured result values with error == nil.