Skip to main content

syncular_client/
client.rs

1//! The Syncular v2 Rust client core (SPEC.md client-behavior contract):
2//! rusqlite local storage, §3.2/§3.3 effective-scope persistence + purge,
3//! §4 pull/cursor/bootstrap (§4.7 resume, §5.6 segment application), §6
4//! push with outbox order, §7 optimistic apply / rollback / replay-on-top,
5//! §2.3 clientCommitId idempotency, §8 realtime client rules, §10 errors.
6//!
7//! Built from `SPEC.md` and the committed `ssp2` codec alone — no
8//! reference to the v1 Rust tree or the v2 TypeScript client.
9
10use crate::{ProgressObserver, ProgressPhase, ProgressState};
11use ssp2::encode_message;
12use std::borrow::Cow;
13#[cfg(test)]
14use std::cell::Cell;
15use std::cell::RefCell;
16use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet, VecDeque};
17use std::sync::Arc;
18
19use rusqlite::types::{ToSqlOutput, Value as SqlValue, ValueRef};
20use rusqlite::{Connection, OpenFlags, OptionalExtension};
21use serde::{Deserialize, Serialize};
22use serde_json::{json, Map, Value};
23use sha2::{Digest, Sha256};
24use ssp2::decode::WIRE_VERSION;
25use ssp2::model::{
26    FencedRecord, Frame, LiveStatus, MediaType, Message, MsgKind, Op, OpResult, PushStatus,
27    SubStatus,
28};
29use ssp2::primitives::RawJson;
30use ssp2::registration::canonical_scope_json;
31use ssp2::segment::{decode_rows_segment, Column, ColumnType, ColumnValue, Row, RowsSegment};
32use ssp2::{decode_message, encode_presence_publish, parse_control, ControlMessage, PresenceKind};
33
34use crate::api::{
35    AppliedServerCommit, AppliedServerCommitSource, ClientChangeBatch, ClientDiagnosticsHost,
36    ClientDiagnosticsLease, ClientDiagnosticsReplica, ClientDiagnosticsSchema,
37    ClientDiagnosticsSnapshot, ClientDiagnosticsStorage, ClientError, ClientLimits, CommandEffects,
38    CommitDelivery, CommitOperation, CommitOperationOutcome, CommitOutcome, CommitOutcomeQuery,
39    CommitOutcomeResolution, CommitOutcomeStatus, ConflictRecord, CoverageSnapshot,
40    CurrentBaseProof, CurrentBaseProofReason, DiagnosticLastChange, DiagnosticLastRound,
41    DiagnosticQueryFailure, DiagnosticRoundCounters, DiagnosticUnits, EchoRecord, FetchedBlob,
42    LeaseState, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataPurgeTarget,
43    LocalDataRebootstrapInput, LocalDataRebootstrapResult, Mutation, PresencePeer,
44    PreviousVersionStatus, QueryOwner, QueryReadFailure, QueryRow, QuerySnapshot, QueryValue,
45    RejectionDetails, RejectionRecord, ResolveCommitOutcomeInput, RetainedCommitRow,
46    RetainedUniqueConflict, RowState, SchemaFloor, SnapshotRead, SyncIntent, SyncOutcome,
47    SyncReport, SyncStatusSnapshot, TableChange, UnitCatchup, UnitRecord, UnitScopes, UnitStatus,
48    WindowBase, WindowChange, WindowCoverage, WindowState, WindowUnitRef,
49    CLIENT_DIAGNOSTICS_VERSION, MAX_DIAGNOSTIC_QUERY_FAILURES,
50};
51use crate::api::{RealtimePolicy, RealtimeState, REALTIME_UNAVAILABLE_CODE};
52#[cfg(feature = "bench-internals")]
53use crate::bench::{Phase, Recorder};
54use crate::previous_version::{
55    capture_previous_version_from_replica, first_incompatibility,
56    reconcile_previous_version_at_boot, set_local_schema_descriptor,
57    sweep_previous_version_container, PendingCommitAudit, PreviousVersionContextConfig,
58    PreviousVersionLifecycle, PreviousVersionReadSpec, PreviousVersionSnapshot,
59};
60use crate::schema::{parse_schema_json, ClientSchema, FtsIndexSchema, TableSchema};
61use crate::transport::{BlobDownload, SegmentRequest, Transport, TransportError};
62use crate::values::{
63    bytes_to_hex, column_value_to_json, decode_row_bytes, encode_sparse_row_json, full_row_values,
64    is_canonical_bytes_envelope, json_to_column_value, json_to_scope_map, normalize_values_casing,
65    render_row_id_json, scope_map_to_json,
66};
67
68/// §4.2 default: rows and SQLite images, both applied in committed chunks.
69/// Bit 3 (signed URLs, §5.4) is
70/// added per transport capability at request-build time.
71const DEFAULT_ACCEPT: u8 = 0b0111;
72const ACCEPT_INLINE_ROWS: u8 = 1 << 0;
73const ACCEPT_EXTERNAL_ROWS: u8 = 1 << 1;
74const ACCEPT_SQLITE: u8 = 1 << 2;
75const ACCEPT_SIGNED_URLS: u8 = 1 << 3;
76const MAX_DIAGNOSTIC_DOMAINS: usize = 256;
77
78/// §10.1 `recommendedAction` carried by a server HTTP error body.
79fn recommended_action_of(details: &Option<Value>) -> Option<String> {
80    details
81        .as_ref()?
82        .get("recommendedAction")?
83        .as_str()
84        .map(str::to_owned)
85}
86
87/// §7.4.1 persisted local schema-version marker (`_syncular_meta` key).
88pub(crate) const LOCAL_SCHEMA_VERSION_KEY: &str = "localSchemaVersion";
89const LOCAL_REVISION_KEY: &str = "localRevision";
90/// §4.5 replica cursor; absent means `-1`.
91const REPLICA_CURSOR_KEY: &str = "replicaCursor";
92/// Hex of the last pull `LIVE_END.echoDigest` (§4.2); absent means empty.
93const ECHO_DIGEST_KEY: &str = "echoDigest";
94/// Hex of the registration digest of the list the server stores (§4.1).
95const REGISTERED_DIGEST_KEY: &str = "registrationDigest";
96/// §7.1: the identity of the outbox sequence.
97const OUTBOX_ID_KEY: &str = "outboxId";
98const CLIENT_ID_KEY: &str = "clientId";
99const LEASE_STATE_KEY: &str = "leaseState";
100const SCHEMA_FLOOR_KEY: &str = "schemaFloor";
101pub(crate) const LOG_EPOCH_KEY: &str = "logEpoch";
102/// Persisted fail-closed quarantine marker: present while a security preflight
103/// is pending and `activateSecurity` has yet to run. Storing it in the replica
104/// keeps the gate with the data it protects, so a rebuilt host handle reopening
105/// the same file returns in preflight even though its in-memory state is fresh.
106const SECURITY_PREFLIGHT_PENDING_KEY: &str = "securityPreflightPending";
107const LOCAL_REBOOTSTRAP_RECEIPT_VERSION: u8 = 2;
108const MAX_JS_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
109/// §7.4.4 client-local code: a pending outbox commit cannot re-encode under
110/// the new schema after a bump. Never a wire code (§10.3).
111const OUTBOX_INCOMPATIBLE_CODE: &str = "sync.outbox_incompatible";
112/// §5.11 client-local code: an encode at the push seam resolved no usable key
113/// id or named an unknown key. Never a wire code (§10.3).
114const ENCRYPT_FAILED_CODE: &str = "client.encrypt_failed";
115const INVALID_REQUEST_CODE: &str = "sync.invalid_request:";
116/// §7.4.4: static text for a persisted commit the current codec refuses.
117const LEGACY_VALUE_REFUSAL_MESSAGE: &str =
118    "the persisted commit carries values the current codec refuses";
119/// §7.4.4: bounded reason on every intrinsic value drop.
120const INVALID_STORED_VALUES_REASON: &str = "invalid_stored_values";
121
122#[derive(Debug, Serialize, Deserialize)]
123#[serde(rename_all = "camelCase", deny_unknown_fields)]
124struct PersistedLocalDataRebootstrapReceipt {
125    version: u8,
126    retained_commits: u64,
127    reset_subscriptions: u64,
128}
129
130fn invalid_local_rebootstrap_receipt() -> String {
131    "sync.local_corrupt: persisted local rebootstrap receipt is invalid".to_owned()
132}
133
134fn encode_local_rebootstrap_receipt(
135    retained_commits: usize,
136    reset_subscriptions: usize,
137) -> Result<String, String> {
138    let retained_commits =
139        u64::try_from(retained_commits).map_err(|_| invalid_local_rebootstrap_receipt())?;
140    let reset_subscriptions =
141        u64::try_from(reset_subscriptions).map_err(|_| invalid_local_rebootstrap_receipt())?;
142    if retained_commits > MAX_JS_SAFE_INTEGER || reset_subscriptions > MAX_JS_SAFE_INTEGER {
143        return Err(invalid_local_rebootstrap_receipt());
144    }
145    serde_json::to_string(&PersistedLocalDataRebootstrapReceipt {
146        version: LOCAL_REBOOTSTRAP_RECEIPT_VERSION,
147        retained_commits,
148        reset_subscriptions,
149    })
150    .map_err(|_| invalid_local_rebootstrap_receipt())
151}
152
153fn decode_local_rebootstrap_receipt(value: &str) -> Result<(usize, usize), String> {
154    // Pre-0.15.36 markers proved application but did not retain the receipt.
155    if value == "v1" {
156        return Ok((0, 0));
157    }
158    let receipt: PersistedLocalDataRebootstrapReceipt =
159        serde_json::from_str(value).map_err(|_| invalid_local_rebootstrap_receipt())?;
160    if receipt.version != LOCAL_REBOOTSTRAP_RECEIPT_VERSION
161        || receipt.retained_commits > MAX_JS_SAFE_INTEGER
162        || receipt.reset_subscriptions > MAX_JS_SAFE_INTEGER
163    {
164        return Err(invalid_local_rebootstrap_receipt());
165    }
166    Ok((
167        usize::try_from(receipt.retained_commits)
168            .map_err(|_| invalid_local_rebootstrap_receipt())?,
169        usize::try_from(receipt.reset_subscriptions)
170            .map_err(|_| invalid_local_rebootstrap_receipt())?,
171    ))
172}
173
174#[cfg(test)]
175mod observation_tests;
176
177/// Internal state for hosts that perform network I/O outside the client owner.
178#[doc(hidden)]
179pub struct CurrentBasePreparation {
180    client_commit_id: String,
181    sequence: i64,
182    units: Vec<UnitRecord>,
183    transport_epoch: u64,
184    registration_epoch: u64,
185    security_epoch: u64,
186}
187
188#[cfg(test)]
189mod units_tests;
190
191#[derive(Debug, Clone)]
192struct OutboxOp {
193    upsert: bool,
194    table: String,
195    row_id: String,
196    base_version: Option<i64>,
197    /// Schema-agnostic local form (§0): driver JSON values, encoded with
198    /// the current codec at send time. A key's presence IS the §6.1 sparse
199    /// presence set — both the overlay and the wire payload derive from it.
200    values: Option<Map<String, Value>>,
201    /// §7.1 insert intent: `mutate` recorded this upsert while the row was
202    /// absent from the visible replica. Replay and send-time encoding present
203    /// every current-schema column; a column `values` lacks is NULL.
204    insert: bool,
205}
206
207impl OutboxOp {
208    /// The values this upsert presents under the current `table` (§7.1). An
209    /// insert-intent operation presents every column, a missing one as NULL;
210    /// `None` when a missing column is non-nullable, which leaves the commit
211    /// unencodable (§7.4.4), or when the operation carries no values.
212    fn presented_values(&self, table: &TableSchema) -> Option<Cow<'_, Map<String, Value>>> {
213        let values = self.values.as_ref()?;
214        if !self.insert || table.columns.iter().all(|c| values.contains_key(&c.name)) {
215            return Some(Cow::Borrowed(values));
216        }
217        full_row_values(table, values.clone()).ok().map(Cow::Owned)
218    }
219}
220
221impl From<&OutboxOp> for CommitOperation {
222    fn from(operation: &OutboxOp) -> Self {
223        Self {
224            table: operation.table.clone(),
225            row_id: operation.row_id.clone(),
226            op: if operation.upsert { "upsert" } else { "delete" }.to_owned(),
227            base_version: operation.base_version,
228            values: operation.values.clone(),
229            insert: operation.insert,
230        }
231    }
232}
233
234#[derive(Debug, Clone)]
235struct OutboxCommit {
236    client_commit_id: String,
237    ops: Vec<OutboxOp>,
238}
239
240/// One commit's `(table, value keys, insert intent)` per upsert operation — the classification
241/// shape the §7.4.4 send-time drop and the RFC 0005 D6 audit share, so the two
242/// can never disagree about which commits cannot re-encode.
243fn commit_audit_operations(commit: &OutboxCommit) -> Vec<(&str, Vec<&str>, bool)> {
244    commit
245        .ops
246        .iter()
247        .filter(|operation| operation.upsert)
248        .map(|operation| {
249            (
250                operation.table.as_str(),
251                operation
252                    .values
253                    .as_ref()
254                    .map(|values| values.keys().map(String::as_str).collect())
255                    .unwrap_or_default(),
256                operation.insert,
257            )
258        })
259        .collect()
260}
261
262type FailedCommit = (OutboxCommit, Map<String, Value>);
263
264#[derive(Debug, Clone)]
265struct CompiledLocalDataPurgeTarget {
266    table: String,
267    selectors: Vec<(String, Vec<String>)>,
268}
269
270struct StoredCommitOutcomeRow {
271    sequence: i64,
272    client_commit_id: String,
273    status: String,
274    recorded_at_ms: i64,
275    results_json: String,
276    operations_json: Option<String>,
277    resolution: String,
278    resolved_at_ms: Option<i64>,
279    replacement_client_commit_id: Option<String>,
280}
281
282impl StoredCommitOutcomeRow {
283    fn from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<Self> {
284        Ok(Self {
285            sequence: row.get(0)?,
286            client_commit_id: row.get(1)?,
287            status: row.get(2)?,
288            recorded_at_ms: row.get(3)?,
289            results_json: row.get(4)?,
290            operations_json: row.get(5)?,
291            resolution: row.get(6)?,
292            resolved_at_ms: row.get(7)?,
293            replacement_client_commit_id: row.get(8)?,
294        })
295    }
296}
297
298/// Section outcome distinguishing the §5.6 unit-local fail-closed
299/// path from a round-aborting failure (§1.4 rule 5).
300/// §4.4 a unit section's `SUB_START`.
301struct SectionStart {
302    id: String,
303    status: SubStatus,
304    reason_code: String,
305    bootstrap: bool,
306    fenced: Vec<FencedRecord>,
307}
308
309enum SectionError {
310    FailClosed,
311    Abort(String, String),
312    Transport(TransportError),
313}
314
315#[derive(Debug)]
316pub(crate) struct RequestMeta {
317    pushed_ids: Vec<String>,
318    /// Hex of the registration digest this pull carried; the server stores
319    /// that list once the round completes (§4.1).
320    registration_digest: String,
321    pub(crate) accept: u8,
322    /// §6.1 splitBatch: outbox commits held back from THIS request because
323    /// the running operation count reached the push cap — the next round
324    /// pushes them (`sync_needed` stays set while any remain).
325    deferred_commits: usize,
326}
327
328#[derive(Default)]
329struct ChangeAccumulator {
330    /// None means table-wide; Some is the exact scoped domain.
331    tables: BTreeMap<String, Option<BTreeSet<String>>>,
332    windows: BTreeMap<String, BTreeSet<String>>,
333    status: bool,
334    conflicts: bool,
335    rejections: bool,
336    outcomes: bool,
337}
338
339impl ChangeAccumulator {
340    fn table(&mut self, table: &str) {
341        self.tables.insert(table.to_owned(), None);
342    }
343
344    fn scope(&mut self, table: &str, key: String) {
345        match self.tables.get_mut(table) {
346            Some(None) => {}
347            Some(Some(keys)) => {
348                keys.insert(key);
349            }
350            None => {
351                self.tables
352                    .insert(table.to_owned(), Some(BTreeSet::from([key])));
353            }
354        }
355    }
356
357    fn window(&mut self, base_key: &str, value: &str) {
358        self.windows
359            .entry(base_key.to_owned())
360            .or_default()
361            .insert(value.to_owned());
362    }
363
364    fn touched(&self) -> bool {
365        !self.tables.is_empty()
366            || !self.windows.is_empty()
367            || self.status
368            || self.conflicts
369            || self.rejections
370            || self.outcomes
371    }
372}
373
374/// §6.1: the server caps total operations per request (reference default
375/// 500) and rejects the whole batch with `sync.too_many_operations`; the
376/// client "splits and retries". Splitting happens at build time: commits are
377/// included IN ORDER until the operation budget is spent, the rest wait for
378/// the next round.
379const PUSH_OPS_PER_REQUEST: usize = 500;
380const MAX_LOCAL_PURGE_TARGETS: usize = 64;
381const MAX_LOCAL_PURGE_SELECTORS: usize = 8;
382const MAX_LOCAL_PURGE_VALUES: usize = 128;
383const MAX_LOCAL_PURGE_VALUE_LENGTH: usize = 256;
384pub const SECURITY_PREFLIGHT_REQUIRED_CODE: &str = "client.security_preflight_required";
385
386/// Dirty visible tables; `None` means a whole-replica recovery/reset.
387struct OverlayDirty(RefCell<Option<BTreeSet<String>>>);
388
389impl OverlayDirty {
390    fn clean() -> Self {
391        Self(RefCell::new(Some(BTreeSet::new())))
392    }
393    fn get(&self) -> bool {
394        self.0
395            .borrow()
396            .as_ref()
397            .is_none_or(|tables| !tables.is_empty())
398    }
399    fn set(&self, dirty: bool) {
400        *self.0.borrow_mut() = if dirty { None } else { Some(BTreeSet::new()) };
401    }
402    fn table(&self, table: &str) {
403        if let Some(tables) = self.0.borrow_mut().as_mut() {
404            tables.insert(table.to_owned());
405        }
406    }
407    fn snapshot(&self) -> Option<BTreeSet<String>> {
408        self.0.borrow().clone()
409    }
410    fn restore(&self, tables: Option<BTreeSet<String>>) {
411        *self.0.borrow_mut() = tables;
412    }
413}
414
415/// A copy-on-write in-memory mirror: a [`Rollback`] shares it, and the first
416/// write after a capture copies it once.
417#[derive(Debug, Clone, Default)]
418struct Shared<T>(Arc<T>);
419
420impl<T> std::ops::Deref for Shared<T> {
421    type Target = T;
422    fn deref(&self) -> &T {
423        &self.0
424    }
425}
426
427impl<T: Clone> std::ops::DerefMut for Shared<T> {
428    fn deref_mut(&mut self) -> &mut T {
429        Arc::make_mut(&mut self.0)
430    }
431}
432
433impl<T> From<T> for Shared<T> {
434    fn from(value: T) -> Self {
435        Self(Arc::new(value))
436    }
437}
438
439/// The in-memory mirrors of durable state, captured before a local
440/// transaction and restored when it rolls back. Queues only grow inside a
441/// transaction, so their lengths suffice.
442#[derive(Debug, Clone)]
443struct Rollback {
444    outbox: Shared<Vec<Arc<OutboxCommit>>>,
445    failed_commits: Shared<Vec<FailedCommit>>,
446    conflicts: Shared<Vec<ConflictRecord>>,
447    rejections: Shared<Vec<RejectionRecord>>,
448    schema_floor: Option<SchemaFloor>,
449    lease_state: Option<LeaseState>,
450    stopped: bool,
451    upgrading: bool,
452    sync_needed: bool,
453    active_round: Option<uuid::Uuid>,
454    overlay_dirty: Option<BTreeSet<String>>,
455    change_queue: usize,
456    sync_intent_queue: usize,
457    last_change: Option<DiagnosticLastChange>,
458}
459
460pub struct SyncClient {
461    #[cfg(feature = "bench-internals")]
462    benchmark_phases: Recorder,
463    conn: Connection,
464    schema: ClientSchema,
465    client_id: String,
466    limits: ClientLimits,
467    outbox: Shared<Vec<Arc<OutboxCommit>>>,
468    failed_commits: Shared<Vec<FailedCommit>>,
469    retain_failed_commits: bool,
470    conflicts: Shared<Vec<ConflictRecord>>,
471    rejections: Shared<Vec<RejectionRecord>>,
472    schema_floor: Option<SchemaFloor>,
473    /// §7.3.5: the opaque auth-lease state (from LEASE frames + lease errors).
474    lease_state: Option<LeaseState>,
475    /// §1.6: the schema-floor response stops syncing until an upgrade.
476    stopped: bool,
477    /// §7.4.5: true while a schema-bump reset + first re-bootstrap is in flight.
478    upgrading: bool,
479    /// §8.4 coalesced sync-needed signal.
480    sync_needed: bool,
481    /// §8.8: how sync rounds treat the realtime binding, and its exact
482    /// availability state with the evidence behind a lost or refused one.
483    realtime_policy: RealtimePolicy,
484    realtime_state: RealtimeState,
485    realtime_reason_code: Option<String>,
486    realtime_retry_delay_ms: Option<u64>,
487    /// §8.6 presence: scopeKey → (`actorId clientId` peer key → peer).
488    presence: HashMap<String, HashMap<String, PresencePeer>>,
489    /// Client clock (epoch ms) for the §5.4 `urlExpiresAtMs` check; the
490    /// host may pin it (conformance runs on a virtual clock).
491    now_ms: Option<i64>,
492    /// §5.11 client-side encryption keys (`keyId → key bytes`). Empty ⇒ E2EE
493    /// off. The encrypt/decrypt seam (`values.rs`) is compiled only under the
494    /// `e2ee` feature; without it, a schema with encrypted columns fails loud.
495    encryption: crate::values::EncryptionConfig,
496    /// Fail-closed host bootstrap gate. While set, command hosts permit only
497    /// status/lifecycle inspection and an exact authorized local purge.
498    security_preflight: bool,
499    security_epoch: u64,
500    transport_enabled: bool,
501    transport_epoch: u64,
502    /// Raised by every registration change; a current-base proof spanning
503    /// one reports missing coverage.
504    registration_epoch: u64,
505    /// RFC 0005 D2/D8: the previous-version capture config. `None` (default)
506    /// means the feature is off; the descriptor write and the container orphan
507    /// sweep still happen.
508    previous_version: Option<PreviousVersionContextConfig>,
509    /// Per-table primary-key upsert SQL, built once per (full table name) —
510    /// the row write path runs per row during bootstrap (§5.6), so the SQL
511    /// string (and, via `prepare_cached`, its compiled statement) is reused
512    /// instead of being rebuilt and re-prepared per row. Cleared on a §7.4.3
513    /// schema reset (the column lists may have changed).
514    insert_sql: RefCell<HashMap<String, String>>,
515    /// §7.1: reconcile only tables whose base/outbox changed. Whole-replica
516    /// reset and restart explicitly invalidate every table.
517    overlay_dirty: OverlayDirty,
518    // First SQLite failure of the current operation, before savepoint cleanup.
519    storage_failure: RefCell<Option<QueryReadFailure>>,
520    /// Test-only structural performance signal: response processing must not
521    /// turn a batch of acknowledgements into one full overlay rebuild each.
522    #[cfg(test)]
523    overlay_rebuild_count: Cell<usize>,
524    #[cfg(test)]
525    acknowledged_replay_count: Cell<usize>,
526    /// Test-only structural performance signal: outcome retention is enforced
527    /// once per response rather than once per acknowledgement.
528    #[cfg(test)]
529    outcome_prune_count: Cell<usize>,
530    /// Exact observer-transaction output drained by command/FFI hosts.
531    progress: ProgressObserver,
532    change_queue: VecDeque<ClientChangeBatch>,
533    sync_intent_queue: VecDeque<SyncIntent>,
534    /// Explicit exponential retry policy for transient transport failures.
535    retry_delay_ms: u64,
536    /// §7.7: the background retry the current round scheduled, if any.
537    round_retry_delay_ms: Option<u64>,
538    /// A round whose response never completed (§1.5): the client keeps its
539    /// code and reports it on every following request until a round receives a
540    /// complete, decodable response. The server already recorded the round, so
541    /// nothing else can tell it the round failed on this side.
542    round_failure: Option<String>,
543    active_round: Option<uuid::Uuid>,
544    last_round: Option<DiagnosticLastRound>,
545    last_change: Option<DiagnosticLastChange>,
546    /// §7.6: latest failed owned snapshot read per owner id, oldest first.
547    query_failures: Vec<DiagnosticQueryFailure>,
548    /// SPEC §1.4 rule 4: the open coalesced apply transaction of a response.
549    coalesced: Option<CoalescedApply>,
550    /// A coalesced apply transaction of the current response failed; every
551    /// later observation of that response fails until it ends.
552    coalesced_failure: Option<String>,
553}
554
555/// SPEC §1.4 rule 4: the frames and blocks of one response share one local
556/// write transaction of at most `COALESCED_APPLY_ROWS` rows. The in-memory
557/// state captured at its `BEGIN` is restored when its `COMMIT` fails.
558struct CoalescedApply {
559    rows: usize,
560    rollback: Rollback,
561}
562
563const COALESCED_APPLY_ROWS: usize = 1024;
564
565pub(crate) fn quote_ident(name: &str) -> String {
566    format!("\"{}\"", name.replace('"', "\"\""))
567}
568/// §7.4.1 `_syncular_meta` helpers. Free functions so RFC 0005's
569/// previous-version module reads and writes the SAME records as the client
570/// instead of growing a parallel meta layer.
571pub(crate) fn meta_get(conn: &Connection, key: &str) -> rusqlite::Result<Option<String>> {
572    conn.query_row(
573        "SELECT value FROM _syncular_meta WHERE key = ?1",
574        rusqlite::params![key],
575        |row| row.get::<_, String>(0),
576    )
577    .optional()
578}
579
580pub(crate) fn meta_set(conn: &Connection, key: &str, value: &str) -> rusqlite::Result<()> {
581    conn.execute(
582        "INSERT OR REPLACE INTO _syncular_meta (key, value) VALUES (?1, ?2)",
583        rusqlite::params![key, value],
584    )
585    .map(|_| ())
586}
587
588pub(crate) fn meta_delete(conn: &Connection, key: &str) -> rusqlite::Result<()> {
589    conn.execute(
590        "DELETE FROM _syncular_meta WHERE key = ?1",
591        rusqlite::params![key],
592    )
593    .map(|_| ())
594}
595
596/// Seek by the existing key while retaining the exact legacy text match.
597fn row_id_predicate(table: &TableSchema) -> String {
598    let key = quote_ident(&table.primary_key);
599    let text_match = format!("CAST({key} AS TEXT) = ?1");
600    match table.columns[table.pk_index].ty {
601        ColumnType::String | ColumnType::Json => {
602            format!("{key} = ?1 AND {text_match}")
603        }
604        // Native columns have no declared SQLite affinity. Match the stored
605        // integer bind type explicitly. Unary + removes expression affinity so
606        // SQLite can seek the typeless key; the text check preserves exact IDs.
607        ColumnType::Integer | ColumnType::Boolean => {
608            format!("{key} = +CAST(?1 AS INTEGER) AND {text_match}")
609        }
610        // REAL-to-text conversion can round distinct values to the same text.
611        // Narrowing those matches by numeric equality would change behavior.
612        _ => text_match,
613    }
614}
615
616/// §3.3/§4.8/§5.6 row ownership: rows whose local scope columns match
617/// `effective` and that no entry of `owners` matches. `owners` holds the
618/// pair scopes of every owner of the table (§3.3 row ownership); a scoped delete never removes a row one of them still covers.
619/// Scope values bind by the column's declared type, as `row_id_predicate`
620/// does. `Ok(None)` matches nothing (an empty map or value list); `Err(())`
621/// is a missing local scope-column mapping (the fail-closed case).
622fn local_scope_predicate(
623    table: &TableSchema,
624    effective: &[(String, Vec<String>)],
625    owners: &[Vec<(String, Vec<String>)>],
626) -> Result<Option<(String, Vec<SqlValue>)>, ()> {
627    if effective.is_empty() || effective.iter().any(|(_, values)| values.is_empty()) {
628        return Ok(None);
629    }
630    let column = |variable: &str| {
631        let name = table.scope_column(variable).ok_or(())?;
632        let column = table
633            .columns
634            .iter()
635            .find(|column| column.name == name)
636            .ok_or(())?;
637        Ok((quote_ident(name), column.ty == ColumnType::Integer))
638    };
639    let mut clauses = Vec::new();
640    let mut params = Vec::new();
641    for (variable, values) in effective {
642        let (key, integer) = column(variable)?;
643        let holes = vec!["?"; values.len()].join(", ");
644        clauses.push(if integer {
645            params.extend(values.iter().cloned().map(SqlValue::Text));
646            let seek = vec!["+CAST(? AS INTEGER)"; values.len()].join(", ");
647            format!("{key} IN ({seek}) AND CAST({key} AS TEXT) IN ({holes})")
648        } else {
649            format!("{key} IN ({holes})")
650        });
651        params.extend(values.iter().cloned().map(SqlValue::Text));
652    }
653    // Owners bind as one JSON parameter per variable set, so the statement
654    // keeps its size at any owner count; owners of one variable bind the
655    // union of their values. An owner holding other values of a variable
656    // `effective` names owns none of its rows and drops out. Values compare
657    // as text, the exact semantics of the effective clauses.
658    let mut groups: BTreeMap<Vec<&str>, Vec<Vec<&[String]>>> = BTreeMap::new();
659    for owner in owners {
660        if owner.is_empty()
661            || owner.iter().any(|(variable, values)| {
662                values.is_empty()
663                    || effective.iter().any(|(name, wanted)| {
664                        name == variable && wanted.iter().all(|value| !values.contains(value))
665                    })
666            })
667        {
668            continue;
669        }
670        let mut owner: Vec<_> = owner.iter().collect();
671        owner.sort_by(|a, b| a.0.cmp(&b.0));
672        groups
673            .entry(
674                owner
675                    .iter()
676                    .map(|(variable, _)| variable.as_str())
677                    .collect(),
678            )
679            .or_default()
680            .push(owner.iter().map(|(_, values)| values.as_slice()).collect());
681    }
682    let within = |variable: &str, list: &str| {
683        let (key, integer) = column(variable)?;
684        let key = if integer {
685            format!("CAST({key} AS TEXT)")
686        } else {
687            key
688        };
689        Ok(format!("{key} IN (SELECT value FROM json_each({list}))"))
690    };
691    for (variables, tuples) in groups {
692        if let [variable] = variables[..] {
693            let values: BTreeSet<&String> = tuples.iter().flatten().copied().flatten().collect();
694            params.push(SqlValue::Text(
695                Value::from_iter(values.into_iter().cloned()).to_string(),
696            ));
697            clauses.push(format!("NOT {}", within(variable, "?")?));
698        } else {
699            params.push(SqlValue::Text(
700                serde_json::to_string(&tuples).expect("owner tuples serialize"),
701            ));
702            let matches = variables
703                .iter()
704                .enumerate()
705                .map(|(index, variable)| within(variable, &format!("o.value,'$[{index}]'")))
706                .collect::<Result<Vec<_>, ()>>()?;
707            clauses.push(format!(
708                "NOT EXISTS (SELECT 1 FROM json_each(?) o WHERE {})",
709                matches.join(" AND ")
710            ));
711        }
712    }
713    Ok(Some((clauses.join(" AND "), params)))
714}
715
716/// [`local_scope_predicate`] over decoded row values (retained rows).
717fn owns_local_row(
718    table: &TableSchema,
719    effective: &[(String, Vec<String>)],
720    owners: &[Vec<(String, Vec<String>)>],
721    values: &Map<String, Value>,
722) -> bool {
723    let matches = |scopes: &[(String, Vec<String>)]| {
724        !scopes.is_empty()
725            && scopes.iter().all(|(variable, allowed)| {
726                table
727                    .scope_column(variable)
728                    .and_then(|column| values.get(column))
729                    .filter(|value| !value.is_null())
730                    .is_some_and(|value| {
731                        allowed.contains(
732                            &value
733                                .as_str()
734                                .map_or_else(|| value.to_string(), str::to_owned),
735                        )
736                    })
737            })
738    };
739    matches(effective) && !owners.iter().any(|owner| matches(owner))
740}
741
742fn is_local_operation_code_like(value: &str) -> bool {
743    let bytes = value.as_bytes();
744    bytes.first().is_some_and(u8::is_ascii_alphanumeric)
745        && bytes
746            .iter()
747            .all(|byte| byte.is_ascii_alphanumeric() || matches!(*byte, b'.' | b'_' | b':' | b'-'))
748}
749
750fn base_table(name: &str) -> String {
751    quote_ident(&format!("_syncular_base_{name}"))
752}
753
754/// §4.8 deferred eviction record: (unit id, table, effective scope map).
755type PendingEvict = (String, String, Vec<(String, Vec<String>)>);
756
757/// §4.8: a stable key for a window base: variable + canonical fixed scopes.
758fn window_base_key(base: &WindowBase) -> String {
759    format!(
760        "{}\0{}",
761        base.variable,
762        ssp2::registration::canonical_unit_json(&scope_pairs(&base.fixed_scopes))
763    )
764}
765
766/// The unit of one window value: the fixed scopes plus the value.
767fn window_unit_scopes(base: &WindowBase, value: &str) -> UnitScopes {
768    let mut scopes = base.fixed_scopes.clone();
769    scopes.insert(base.variable.clone(), value.to_owned());
770    scopes
771}
772
773/// A unit's scope map as the codec and the digests take it.
774fn scope_pairs(scopes: &UnitScopes) -> Vec<(String, String)> {
775    let mut pairs: Vec<(String, String)> = scopes
776        .iter()
777        .map(|(variable, value)| (variable.clone(), value.clone()))
778        .collect();
779    pairs.sort_by(|a, b| a.0.encode_utf16().cmp(b.0.encode_utf16()));
780    pairs
781}
782
783/// §4.1: the unit covers every table declaring all of its variables.
784fn covers(table: &TableSchema, scopes: &UnitScopes) -> bool {
785    scopes
786        .keys()
787        .all(|variable| table.scope_column(variable).is_some())
788}
789
790/// §4.4: the effective scopes of the (unit, table) pair under `echo`: the
791/// scope map as one-element lists plus the fenced lists. `None` when the
792/// fence revoked the pair.
793fn pair_scopes(
794    scopes: &UnitScopes,
795    table: &str,
796    echo: Option<&[EchoRecord]>,
797) -> Option<Vec<(String, Vec<String>)>> {
798    let fenced = echo.and_then(|echo| echo.iter().find(|record| record.table == table));
799    if fenced.is_some_and(|record| record.status == "revoked") {
800        return None;
801    }
802    let mut effective: BTreeMap<String, Vec<String>> = fenced
803        .map(|record| record.scopes.clone())
804        .unwrap_or_default();
805    for (variable, value) in scopes {
806        effective.insert(variable.clone(), vec![value.clone()]);
807    }
808    Some(effective.into_iter().collect())
809}
810
811/// §3.3 row ownership: the pair scopes of every owner of `table` except
812/// `except_id`. An owner is active with a persisted echo and live or
813/// post-bootstrap, or bootstrapping with a segment of the table in its
814/// current bootstrap.
815fn unit_owners(
816    units: &[UnitRecord],
817    table: &TableSchema,
818    except_id: &str,
819) -> Vec<Vec<(String, Vec<String>)>> {
820    units
821        .iter()
822        .filter(|unit| {
823            unit.id != except_id
824                && unit.status == UnitStatus::Active
825                && unit.echo.is_some()
826                && (!unit.bootstrapping() || unit.seeded.contains(&table.name))
827                && covers(table, &unit.scopes)
828        })
829        .filter_map(|unit| pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()))
830        .collect()
831}
832
833/// §5.5 / §5.6: the unit's scope map, each value a one-element list.
834fn unit_scope_lists(scopes: &UnitScopes) -> Vec<(String, Vec<String>)> {
835    scopes
836        .iter()
837        .map(|(variable, value)| (variable.clone(), vec![value.clone()]))
838        .collect()
839}
840
841/// §7.1 acknowledged intent of the rows `?1` names (`[[table, id], ...]`).
842/// It joins through the (tbl, id) index: a scan per acknowledgement would
843/// make draining a batch quadratic.
844const ACKED_ROWS_BY_ROW: &str = "SELECT a.op_json,a.intent_json FROM json_each(?1) k JOIN _syncular_acked_rows a ON a.tbl=json_extract(k.value,'$[0]') AND a.id=json_extract(k.value,'$[1]') WHERE ?2 IS NULL OR a.tbl IN(SELECT value FROM json_each(?2)) ORDER BY a.commit_seq,a.idx";
845
846const UNIT_COLUMNS: &str =
847    "id, scopes, explicit, status, reason_code, cursor, bootstrap_state, seeded, echo";
848
849/// A unit row; a field that does not parse is a conversion failure, which
850/// both read paths classify as `sync.local_corrupt`.
851fn unit_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<UnitRecord> {
852    fn json<T: serde::de::DeserializeOwned>(index: usize, raw: &str) -> rusqlite::Result<T> {
853        serde_json::from_str(raw).map_err(|error| {
854            rusqlite::Error::FromSqlConversionFailure(
855                index,
856                rusqlite::types::Type::Text,
857                Box::new(error),
858            )
859        })
860    }
861    Ok(UnitRecord {
862        id: row.get(0)?,
863        scopes: json(1, &row.get::<_, String>(1)?)?,
864        explicit: row.get::<_, i64>(2)? == 1,
865        status: json(
866            3,
867            &serde_json::to_string(&row.get::<_, String>(3)?).expect("text"),
868        )?,
869        reason_code: row.get(4)?,
870        cursor: row.get(5)?,
871        bootstrap_state: row.get(6)?,
872        seeded: json(7, &row.get::<_, String>(7)?)?,
873        echo: row
874            .get::<_, Option<String>>(8)?
875            .map(|echo| json::<Vec<EchoRecord>>(8, &echo))
876            .transpose()?
877            .map(|echo| {
878                if echo
879                    .iter()
880                    .all(|record| record.status == "active" || record.status == "revoked")
881                {
882                    Ok(echo)
883                } else {
884                    Err(rusqlite::Error::FromSqlConversionFailure(
885                        8,
886                        rusqlite::types::Type::Text,
887                        "echo status is neither active nor revoked".into(),
888                    ))
889                }
890            })
891            .transpose()?,
892    })
893}
894
895/// Every unit in registration order (§4.1).
896fn load_units(conn: &Connection) -> rusqlite::Result<Vec<UnitRecord>> {
897    conn.prepare_cached(&format!(
898        "SELECT {UNIT_COLUMNS} FROM _syncular_units ORDER BY rowid"
899    ))?
900    .query_map([], unit_from_row)?
901    .collect()
902}
903
904fn get_unit(conn: &Connection, id: &str) -> rusqlite::Result<Option<UnitRecord>> {
905    conn.query_row(
906        &format!("SELECT {UNIT_COLUMNS} FROM _syncular_units WHERE id = ?1"),
907        [id],
908        unit_from_row,
909    )
910    .optional()
911}
912
913/// Insert or update in place: an update keeps the registration order.
914fn save_unit(conn: &Connection, unit: &UnitRecord) -> rusqlite::Result<()> {
915    conn.prepare_cached(&format!(
916        "INSERT INTO _syncular_units({UNIT_COLUMNS}) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9)
917         ON CONFLICT(id) DO UPDATE SET explicit=excluded.explicit, status=excluded.status,
918           reason_code=excluded.reason_code, cursor=excluded.cursor,
919           bootstrap_state=excluded.bootstrap_state, seeded=excluded.seeded, echo=excluded.echo"
920    ))?
921    .execute(rusqlite::params![
922        unit.id,
923        serde_json::to_string(&unit.scopes).expect("scope map serializes"),
924        i64::from(unit.explicit),
925        unit.status.name(),
926        unit.reason_code,
927        unit.cursor,
928        unit.bootstrap_state,
929        serde_json::to_string(&unit.seeded).expect("table list serializes"),
930        unit.echo
931            .as_ref()
932            .map(|echo| serde_json::to_string(echo).expect("echo serializes")),
933    ])
934    .map(|_| ())
935}
936
937/// §4.1 references: every window registry entry `(base, value)` holding a unit.
938fn window_refs(conn: &Connection, unit_id: &str) -> rusqlite::Result<Vec<(String, String)>> {
939    conn.prepare_cached("SELECT base, unit FROM _syncular_windows WHERE sub_id = ?1")?
940        .query_map([unit_id], |row| Ok((row.get(0)?, row.get(1)?)))?
941        .collect()
942}
943
944/// §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
945/// registrations and discard every synced state, so the next round sends the
946/// list and fresh-bootstraps every unit. The caller owns the transaction.
947fn reset_units(conn: &Connection) -> rusqlite::Result<()> {
948    conn.execute_batch(
949        "UPDATE _syncular_units SET status='active', reason_code=NULL, cursor=-1,
950           bootstrap_state=NULL, seeded='[]', echo=NULL;
951         DELETE FROM _syncular_meta WHERE key IN ('replicaCursor','echoDigest','registrationDigest');",
952    )
953}
954
955/// §4.5: the replica cursor, `-1` while no unit is live.
956fn replica_cursor(conn: &Connection) -> rusqlite::Result<i64> {
957    meta_get(conn, REPLICA_CURSOR_KEY)?.map_or(Ok(-1), |raw| {
958        raw.parse().map_err(|error| {
959            rusqlite::Error::FromSqlConversionFailure(
960                0,
961                rusqlite::types::Type::Text,
962                Box::new(error),
963            )
964        })
965    })
966}
967
968fn visible_table(name: &str) -> String {
969    quote_ident(name)
970}
971
972const FTS_SOURCE_ID_COLUMN: &str = "_syncular_source_id";
973
974/// §7.4.3: is a `sqlite_master` table name a synced table (visible or base),
975/// i.e. NOT one of the durable bookkeeping tables the reset preserves?
976fn is_synced_table_name(name: &str) -> bool {
977    if name.starts_with("sqlite_") {
978        return false;
979    }
980    if name.starts_with("_syncular_base_") {
981        return true; // the base half of a synced table pair
982    }
983    // Bookkeeping: outbox, units, meta, blob cache/uploads.
984    !name.starts_with("_syncular_")
985}
986
987/// `"sha256:" + hex` of the bytes — the content address (§5.9.1).
988fn blob_id_for(bytes: &[u8]) -> String {
989    let digest = Sha256::digest(bytes);
990    format!("sha256:{}", bytes_to_hex(&digest))
991}
992
993/// One [`SyncClient::write_row`] bind parameter, borrowing the row-codec
994/// value it wraps — strings/JSON/bytes bind as borrowed TEXT/BLOB (no copy
995/// per row on the §5.6 bootstrap path), scalars bind owned.
996enum RowParam<'a> {
997    Cell(&'a Option<ColumnValue>),
998    Version(i64),
999}
1000
1001impl rusqlite::ToSql for RowParam<'_> {
1002    fn to_sql(&self) -> rusqlite::Result<ToSqlOutput<'_>> {
1003        Ok(match self {
1004            RowParam::Version(v) => ToSqlOutput::Owned(SqlValue::Integer(*v)),
1005            RowParam::Cell(cell) => match cell {
1006                None => ToSqlOutput::Owned(SqlValue::Null),
1007                Some(ColumnValue::String(s)) => ToSqlOutput::Borrowed(ValueRef::Text(s.as_bytes())),
1008                Some(ColumnValue::Integer(i)) => ToSqlOutput::Owned(SqlValue::Integer(*i)),
1009                Some(ColumnValue::Float(f)) => ToSqlOutput::Owned(SqlValue::Real(*f)),
1010                Some(ColumnValue::Boolean(b)) => {
1011                    ToSqlOutput::Owned(SqlValue::Integer(i64::from(*b)))
1012                }
1013                Some(ColumnValue::Json(raw)) | Some(ColumnValue::BlobRef(raw)) => {
1014                    ToSqlOutput::Borrowed(ValueRef::Text(raw.0.as_bytes()))
1015                }
1016                // §5.10: crdt bytes store as BLOB, like bytes.
1017                Some(ColumnValue::Bytes(b)) | Some(ColumnValue::Crdt(b)) => {
1018                    ToSqlOutput::Borrowed(ValueRef::Blob(b))
1019                }
1020            },
1021        })
1022    }
1023}
1024
1025// Retain a typed primary key across the current import chunk without copying row payloads.
1026fn owned_sql_value(param: impl rusqlite::ToSql) -> Result<SqlValue, String> {
1027    match param.to_sql().map_err(|error| error.to_string())? {
1028        ToSqlOutput::Owned(value) => Ok(value),
1029        ToSqlOutput::Borrowed(value) => {
1030            SqlValue::try_from(value).map_err(|error| error.to_string())
1031        }
1032        _ => Err("sync.invalid_request: unsupported SQLite key parameter".into()),
1033    }
1034}
1035
1036/// §5.3 image cell → bind parameter, strict per the declared column type
1037/// (`boolean` from INTEGER 0/1, `json` from its raw TEXT, NULL only when
1038/// nullable). Mismatches are image-producer violations. Returns the cell
1039/// borrowed when the stored representation already matches what the row
1040/// codec would write, or the normalized scalar (boolean → 0/1, float from
1041/// INTEGER → REAL) otherwise — the local write is byte-identical to the
1042/// old convert-then-insert path without allocating per cell.
1043fn image_cell_param<'a>(column: &Column, value: ValueRef<'a>) -> Result<ToSqlOutput<'a>, String> {
1044    use ssp2::segment::ColumnType;
1045    let mismatch = || {
1046        Err(format!(
1047            "image column {:?} holds a value of the wrong type",
1048            column.name
1049        ))
1050    };
1051    match value {
1052        ValueRef::Null => {
1053            if !column.nullable {
1054                return Err(format!(
1055                    "image column {:?} is NULL but not nullable",
1056                    column.name
1057                ));
1058            }
1059            Ok(ToSqlOutput::Owned(SqlValue::Null))
1060        }
1061        ValueRef::Integer(i) => match column.ty {
1062            ColumnType::Integer => Ok(ToSqlOutput::Borrowed(value)),
1063            ColumnType::Boolean => Ok(ToSqlOutput::Owned(SqlValue::Integer(i64::from(i != 0)))),
1064            ColumnType::Float => Ok(ToSqlOutput::Owned(SqlValue::Real(i as f64))),
1065            _ => mismatch(),
1066        },
1067        ValueRef::Real(_) => match column.ty {
1068            ColumnType::Float => Ok(ToSqlOutput::Borrowed(value)),
1069            _ => mismatch(),
1070        },
1071        ValueRef::Text(t) => {
1072            std::str::from_utf8(t)
1073                .map_err(|_| format!("image column {:?} is not UTF-8", column.name))?;
1074            match column.ty {
1075                ColumnType::String | ColumnType::Json | ColumnType::BlobRef => {
1076                    Ok(ToSqlOutput::Borrowed(value))
1077                }
1078                _ => mismatch(),
1079            }
1080        }
1081        ValueRef::Blob(_) => match column.ty {
1082            // §5.10: a crdt column stores its opaque bytes as BLOB, like bytes.
1083            ColumnType::Bytes | ColumnType::Crdt => Ok(ToSqlOutput::Borrowed(value)),
1084            _ => mismatch(),
1085        },
1086    }
1087}
1088
1089pub(crate) fn sql_ref_to_json(column: &Column, value: rusqlite::types::ValueRef<'_>) -> Value {
1090    use rusqlite::types::ValueRef;
1091    match value {
1092        ValueRef::Null => Value::Null,
1093        ValueRef::Integer(i) => match column.ty {
1094            ssp2::segment::ColumnType::Boolean => Value::Bool(i != 0),
1095            ssp2::segment::ColumnType::Float => {
1096                serde_json::Number::from_f64(i as f64).map_or(Value::Null, Value::Number)
1097            }
1098            _ => Value::from(i),
1099        },
1100        ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1101        ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1102        ValueRef::Blob(b) => {
1103            let mut map = Map::new();
1104            map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1105            Value::Object(map)
1106        }
1107    }
1108}
1109
1110/// Bind a driver JSON value form as a rusqlite parameter for [`SyncClient::query`].
1111/// Objects are accepted in lossless `{"$bytes": hex}` and
1112/// `{"$bigint": decimal}` envelope forms.
1113fn json_param_to_sql(value: &Value) -> Result<SqlValue, String> {
1114    Ok(match value {
1115        Value::Null => SqlValue::Null,
1116        Value::Bool(b) => SqlValue::Integer(i64::from(*b)),
1117        Value::Number(n) => {
1118            if let Some(i) = n.as_i64() {
1119                SqlValue::Integer(i)
1120            } else if let Some(f) = n.as_f64() {
1121                SqlValue::Real(f)
1122            } else {
1123                return Err(format!("query param number {n} is out of range"));
1124            }
1125        }
1126        Value::String(s) => SqlValue::Text(s.clone()),
1127        Value::Object(_) => {
1128            if let Some(hex) = value.get("$bytes").and_then(Value::as_str) {
1129                SqlValue::Blob(crate::values::hex_to_bytes(hex)?)
1130            } else if let Some(decimal) = value.get("$bigint").and_then(Value::as_str) {
1131                SqlValue::Integer(decimal.parse::<i64>().map_err(|_| {
1132                    format!("query bigint param {decimal:?} is outside SQLite's i64 range")
1133                })?)
1134            } else {
1135                return Err(
1136                    "query object param must be a {$bytes: hex} or {$bigint: decimal} value"
1137                        .to_owned(),
1138                );
1139            }
1140        }
1141        Value::Array(_) => return Err("query array params are not supported".to_owned()),
1142    })
1143}
1144
1145/// Map a rusqlite value with no schema column to consult (arbitrary query
1146/// output): integers/reals/text pass through by stored affinity, blobs ride
1147/// as `{"$bytes": hex}`. Distinct from [`sql_ref_to_json`], which uses the
1148/// schema column type to recover booleans/floats/json.
1149fn sql_ref_to_json_dynamic(value: rusqlite::types::ValueRef<'_>) -> Value {
1150    use rusqlite::types::ValueRef;
1151    match value {
1152        ValueRef::Null => Value::Null,
1153        ValueRef::Integer(i) => {
1154            // JSON/Tauri IPC cannot represent every SQLite i64 exactly. Keep
1155            // ordinary UI-sized integers ergonomic and envelope only values
1156            // beyond JavaScript's safe range.
1157            const MAX_SAFE_INTEGER: i64 = 9_007_199_254_740_991;
1158            if (-MAX_SAFE_INTEGER..=MAX_SAFE_INTEGER).contains(&i) {
1159                Value::from(i)
1160            } else {
1161                let mut map = Map::new();
1162                map.insert("$bigint".to_owned(), Value::from(i.to_string()));
1163                Value::Object(map)
1164            }
1165        }
1166        ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1167        ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1168        ValueRef::Blob(b) => {
1169            let mut map = Map::new();
1170            map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1171            Value::Object(map)
1172        }
1173    }
1174}
1175
1176/// §7.5: SQLite failures classify by result code into [`QueryReadFailure`].
1177fn query_connection(
1178    conn: &Connection,
1179    sql: &str,
1180    params: &[QueryValue],
1181) -> Result<Vec<QueryRow>, QueryReadFailure> {
1182    let lowered_sql = crate::query_guard::lower_public_query_sql(sql);
1183    let mut stmt = crate::query_guard::prepare_read_only(conn, &lowered_sql)?;
1184    let bound: Vec<SqlValue> = params
1185        .iter()
1186        .map(json_param_to_sql)
1187        .collect::<Result<_, _>>()?;
1188    // §2.4: an unaliased physical version column stays engine-internal, so a
1189    // `SELECT *` row feeds straight back into mutation values. An explicit
1190    // alias (`_sync_version AS v`) returns it as ordinary query data.
1191    let columns: Vec<(usize, String)> = stmt
1192        .column_names()
1193        .enumerate()
1194        .filter(|(_, name)| *name != "_syncular_version")
1195        .map(|(i, name)| (i, name.to_owned()))
1196        .collect();
1197    let bound_refs: Vec<&dyn rusqlite::ToSql> =
1198        bound.iter().map(|v| v as &dyn rusqlite::ToSql).collect();
1199    let mut sql_rows = stmt.query(bound_refs.as_slice())?;
1200    let mut out = Vec::new();
1201    while let Some(row) = sql_rows.next()? {
1202        let mut record = Map::new();
1203        for (i, name) in &columns {
1204            let value = row.get_ref(*i)?;
1205            record.insert(name.clone(), sql_ref_to_json_dynamic(value));
1206        }
1207        out.push(record);
1208    }
1209    Ok(out)
1210}
1211
1212fn persisted_window_state(
1213    conn: &Connection,
1214    base: &WindowBase,
1215) -> Result<WindowState, QueryReadFailure> {
1216    let mut stmt = conn.prepare(
1217        "SELECT windows.unit, units.status, units.cursor, units.bootstrap_state
1218           FROM _syncular_windows AS windows
1219           LEFT JOIN _syncular_units AS units ON units.id = windows.sub_id
1220          WHERE windows.base = ?1
1221          ORDER BY windows.unit ASC",
1222    )?;
1223    let rows = stmt.query_map(rusqlite::params![window_base_key(base)], |row| {
1224        Ok((
1225            row.get::<_, String>(0)?,
1226            row.get::<_, Option<String>>(1)?,
1227            row.get::<_, Option<i64>>(2)?,
1228            row.get::<_, Option<String>>(3)?,
1229        ))
1230    })?;
1231    let mut units = Vec::new();
1232    let mut pending = Vec::new();
1233    for row in rows {
1234        let (unit, status, cursor, bootstrap_state) = row?;
1235        // §4.8: complete iff registered, active and not bootstrapping.
1236        if status.as_deref() != Some("active")
1237            || cursor.is_some_and(|cursor| cursor < 0 || bootstrap_state.is_some())
1238        {
1239            pending.push(unit.clone());
1240        }
1241        units.push(unit);
1242    }
1243    Ok(WindowState { units, pending })
1244}
1245
1246/// One read-only statement in a §7.5 snapshot read.
1247#[derive(Debug, Clone, Copy)]
1248pub struct SnapshotStatement<'a> {
1249    pub sql: &'a str,
1250    pub params: &'a [Value],
1251}
1252
1253/// A §7.5 atomic read request: read-only statements, window coverage, unit
1254/// catch-up states, and commit deliveries, all resolved from one SQLite read
1255/// transaction and one revision.
1256#[derive(Debug, Clone, Default)]
1257pub struct SnapshotReadRequest<'a> {
1258    pub statements: Vec<SnapshotStatement<'a>>,
1259    pub coverage: &'a [WindowCoverage],
1260    pub units: Vec<String>,
1261    pub commit_ids: Vec<String>,
1262}
1263
1264#[cfg(test)]
1265thread_local! {
1266    /// Test-only rendezvous that runs between the statements of one snapshot
1267    /// read. A test uses it to commit on another connection mid-read and prove
1268    /// the read transaction's snapshot and revision stay stable.
1269    static SNAPSHOT_READ_HOOK: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
1270        std::cell::RefCell::new(None);
1271}
1272
1273#[cfg(test)]
1274fn run_snapshot_read_hook() {
1275    SNAPSHOT_READ_HOOK.with(|slot| {
1276        if let Some(hook) = slot.borrow_mut().take() {
1277            hook();
1278        }
1279    });
1280}
1281
1282/// §7.5: resolve a request over one SQLite read transaction. The revision,
1283/// every statement's rows, coverage, catch-up states, and deliveries are
1284/// captured under one `SAVEPOINT`; any statement's failure rolls the whole
1285/// read back and releases the connection.
1286fn snapshot_read_connection(
1287    conn: &Connection,
1288    request: &SnapshotReadRequest<'_>,
1289) -> Result<SnapshotRead, QueryReadFailure> {
1290    conn.execute_batch("SAVEPOINT syncular_snapshot_read")?;
1291    let corrupt = |message: &str| QueryReadFailure {
1292        code: Some("sync.local_corrupt"),
1293        sqlite_code: None,
1294        sqlite_message: None,
1295        rollback_failure: None,
1296        message: message.to_owned(),
1297    };
1298    let stored_failure = |error: rusqlite::Error, message: &str| match error {
1299        rusqlite::Error::Utf8Error(..)
1300        | rusqlite::Error::InvalidColumnType(..)
1301        | rusqlite::Error::FromSqlConversionFailure(..)
1302        | rusqlite::Error::IntegralValueOutOfRange(..) => corrupt(message),
1303        _ => QueryReadFailure::from(error),
1304    };
1305    let result: Result<SnapshotRead, QueryReadFailure> = (|| {
1306        // The durable revision as a canonical decimal `u64`; a missing marker
1307        // is the legacy zero, and any other non-canonical value is corrupt.
1308        let revision: Option<String> = conn
1309            .query_row(
1310                "SELECT value FROM _syncular_meta WHERE key = ?1",
1311                rusqlite::params![LOCAL_REVISION_KEY],
1312                |row| row.get(0),
1313            )
1314            .optional()
1315            .map_err(|error| stored_failure(error, "persisted local revision is invalid"))?;
1316        let revision = match revision {
1317            None => "0".to_owned(),
1318            Some(value)
1319                if value == "0"
1320                    || (matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1321                        && value.bytes().all(|b| b.is_ascii_digit())
1322                        && value.parse::<u64>().is_ok()) =>
1323            {
1324                value
1325            }
1326            Some(_) => return Err(corrupt("persisted local revision is invalid")),
1327        };
1328        let mut queries = Vec::with_capacity(request.statements.len());
1329        for statement in &request.statements {
1330            queries.push(query_connection(conn, statement.sql, statement.params)?);
1331            #[cfg(test)]
1332            run_snapshot_read_hook();
1333        }
1334        let mut pending = Vec::new();
1335        let mut missing = Vec::new();
1336        for requested in request.coverage {
1337            let base_key = window_base_key(&requested.base);
1338            let state = persisted_window_state(conn, &requested.base)?;
1339            for unit in BTreeSet::from_iter(requested.units.iter().cloned()) {
1340                let reference = WindowUnitRef {
1341                    base_key: base_key.clone(),
1342                    unit: unit.clone(),
1343                };
1344                if !state.units.iter().any(|held| held == &unit) {
1345                    missing.push(reference);
1346                } else if state.pending.iter().any(|held| held == &unit) {
1347                    pending.push(reference);
1348                }
1349            }
1350        }
1351        let mut units = Vec::with_capacity(request.units.len());
1352        for id in &request.units {
1353            let exists: bool = conn.query_row(
1354                "SELECT EXISTS(SELECT 1 FROM _syncular_units WHERE id = ?1)",
1355                [id],
1356                |row| row.get(0),
1357            )?;
1358            if !exists {
1359                units.push(UnitCatchup::Unknown { id: id.clone() });
1360                continue;
1361            }
1362            // Every persisted field is required to be well typed; a corrupt
1363            // record fails typed instead of inventing a state.
1364            let unit = get_unit(conn, id)
1365                .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?
1366                .ok_or_else(|| corrupt("persisted unit state is invalid"))?;
1367            let cursor = match unit.cursor {
1368                Some(cursor) => cursor,
1369                None => replica_cursor(conn)
1370                    .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?,
1371            };
1372            if cursor.unsigned_abs() > MAX_JS_SAFE_INTEGER {
1373                return Err(corrupt("persisted unit state is invalid"));
1374            }
1375            let active = unit.status == UnitStatus::Active;
1376            let pending = unit.bootstrapping();
1377            units.push(UnitCatchup::Known {
1378                id: id.clone(),
1379                status: unit.status,
1380                live: unit.cursor.is_none(),
1381                cursor,
1382                has_resume_token: unit.bootstrap_state.is_some(),
1383                bootstrap_complete: active && !pending,
1384                known_pending_pages: active && pending,
1385                reason_code: unit.reason_code,
1386            });
1387        }
1388        let mut deliveries = Vec::with_capacity(request.commit_ids.len());
1389        for id in &request.commit_ids {
1390            let pending: bool = conn.query_row(
1391                "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id = ?1)",
1392                rusqlite::params![id],
1393                |row| row.get(0),
1394            )?;
1395            if pending {
1396                deliveries.push(CommitDelivery::Pending {
1397                    client_commit_id: id.clone(),
1398                });
1399                continue;
1400            }
1401            let row = conn
1402                .query_row(
1403                    "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
1404                            resolution, resolved_at_ms, replacement_client_commit_id
1405                       FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
1406                    rusqlite::params![id],
1407                    StoredCommitOutcomeRow::from_row,
1408                )
1409                .optional()
1410                .map_err(|error| stored_failure(error, "persisted commit outcome is invalid"))?;
1411            deliveries.push(match row {
1412                Some(row) => CommitDelivery::Known {
1413                    client_commit_id: id.clone(),
1414                    outcome: SyncClient::outcome_from_row(row)
1415                        .map_err(|_| corrupt("persisted commit outcome is invalid"))?,
1416                },
1417                None => CommitDelivery::Unknown {
1418                    client_commit_id: id.clone(),
1419                },
1420            });
1421        }
1422        Ok(SnapshotRead {
1423            revision,
1424            queries,
1425            coverage: CoverageSnapshot {
1426                complete: pending.is_empty() && missing.is_empty(),
1427                pending,
1428                missing,
1429            },
1430            units,
1431            deliveries,
1432        })
1433    })();
1434    match result {
1435        Ok(read) => {
1436            conn.execute_batch("RELEASE syncular_snapshot_read")?;
1437            Ok(read)
1438        }
1439        Err(mut error) => {
1440            if let Err(rollback) = conn
1441                .execute_batch("ROLLBACK TO syncular_snapshot_read; RELEASE syncular_snapshot_read")
1442            {
1443                error.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
1444            }
1445            Err(error)
1446        }
1447    }
1448}
1449
1450fn snapshot_connection(
1451    conn: &Connection,
1452    sql: &str,
1453    params: &[Value],
1454    coverage: &[WindowCoverage],
1455) -> Result<QuerySnapshot, QueryReadFailure> {
1456    let read = snapshot_read_connection(
1457        conn,
1458        &SnapshotReadRequest {
1459            statements: vec![SnapshotStatement { sql, params }],
1460            coverage,
1461            units: Vec::new(),
1462            commit_ids: Vec::new(),
1463        },
1464    )?;
1465    Ok(QuerySnapshot {
1466        revision: read.revision,
1467        rows: read
1468            .queries
1469            .into_iter()
1470            .next()
1471            .expect("single-query snapshot returns one result"),
1472        coverage: read.coverage,
1473    })
1474}
1475
1476/// A long-lived read-only SQLite sidecar for latency-critical native views.
1477/// Network rounds stay serialized on the mutable core owner, while atomic
1478/// query snapshots use this independent connection and therefore never queue
1479/// behind HTTP/WebSocket latency.
1480pub struct FileQuerySnapshotReader {
1481    path: String,
1482    conn: Option<Connection>,
1483}
1484
1485impl FileQuerySnapshotReader {
1486    #[must_use]
1487    pub fn new(path: impl Into<String>) -> Self {
1488        Self {
1489            path: path.into(),
1490            conn: None,
1491        }
1492    }
1493
1494    fn connection(&mut self) -> Result<&Connection, QueryReadFailure> {
1495        if self.conn.is_none() {
1496            let conn = Connection::open_with_flags(
1497                &self.path,
1498                OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
1499            )
1500            .map_err(QueryReadFailure::from)?;
1501            conn.busy_timeout(std::time::Duration::from_millis(250))
1502                .map_err(QueryReadFailure::from)?;
1503            self.conn = Some(conn);
1504        }
1505        self.conn
1506            .as_ref()
1507            .ok_or_else(|| QueryReadFailure::from("read sidecar connection missing".to_owned()))
1508    }
1509
1510    /// One atomic read over the shared primitive: every statement, coverage,
1511    /// catch-up, and delivery under one `SAVEPOINT` and one revision.
1512    pub fn snapshot_read(
1513        &mut self,
1514        request: &SnapshotReadRequest<'_>,
1515    ) -> Result<SnapshotRead, QueryReadFailure> {
1516        snapshot_read_connection(self.connection()?, request)
1517    }
1518
1519    /// The current durable local revision. A host can skip a read when it is
1520    /// unchanged; a corrupt or unreadable marker fails typed.
1521    pub fn local_revision(&mut self) -> Result<String, QueryReadFailure> {
1522        Ok(self
1523            .snapshot_read(&SnapshotReadRequest::default())?
1524            .revision)
1525    }
1526
1527    /// One unit's persisted catch-up state (see the §7.5 contract).
1528    pub fn unit_catchup(&mut self, id: &str) -> Result<UnitCatchup, QueryReadFailure> {
1529        let read = self.snapshot_read(&SnapshotReadRequest {
1530            units: vec![id.to_owned()],
1531            ..Default::default()
1532        })?;
1533        Ok(read
1534            .units
1535            .into_iter()
1536            .next()
1537            .expect("one requested catch-up"))
1538    }
1539
1540    /// One client commit's delivery status: pending, its retained outcome, or
1541    /// an explicit unknown (never held, or pruned by retention).
1542    pub fn commit_delivery(&mut self, id: &str) -> Result<CommitDelivery, QueryReadFailure> {
1543        let read = self.snapshot_read(&SnapshotReadRequest {
1544            commit_ids: vec![id.to_owned()],
1545            ..Default::default()
1546        })?;
1547        Ok(read
1548            .deliveries
1549            .into_iter()
1550            .next()
1551            .expect("one requested delivery"))
1552    }
1553
1554    /// Hosts report an owned failure, and the first success after it, to the
1555    /// owning core through [`SyncClient::record_query_read`] (§7.6).
1556    pub fn query_snapshot(
1557        &mut self,
1558        sql: &str,
1559        params: &[Value],
1560        coverage: &[WindowCoverage],
1561    ) -> Result<QuerySnapshot, QueryReadFailure> {
1562        snapshot_connection(self.connection()?, sql, params, coverage)
1563    }
1564}
1565
1566fn validate_authority_reads(
1567    schema: &ClientSchema,
1568    declarations: &[crate::api::AuthorityReadDeclaration],
1569) -> Result<(), String> {
1570    let mut seen = BTreeSet::new();
1571    for read in declarations {
1572        let table = schema
1573            .table(&read.table)
1574            .ok_or("client.authority_read_forbidden: authority table is not declared")?;
1575        let plain = |name: &str| {
1576            table.columns.iter().enumerate().any(|(i, c)| {
1577                c.name == name
1578                    && name != "authority_version"
1579                    && !name.starts_with("_sync")
1580                    && !table.encrypted_columns.iter().any(|e| e.index == i)
1581                    && matches!(
1582                        c.ty,
1583                        ssp2::segment::ColumnType::String
1584                            | ssp2::segment::ColumnType::Integer
1585                            | ssp2::segment::ColumnType::Float
1586                            | ssp2::segment::ColumnType::Boolean
1587                            | ssp2::segment::ColumnType::Json
1588                    )
1589            })
1590        };
1591        if !seen.insert(&read.table)
1592            || read.columns.is_empty()
1593            || read.columns.iter().collect::<BTreeSet<_>>().len() != read.columns.len()
1594            || !read.columns.contains(&table.primary_key)
1595            || !read.columns.iter().all(|c| plain(c))
1596            || read.scopes.is_empty()
1597            || !read.scopes.iter().all(|(v, values)| {
1598                table
1599                    .scope_column(v)
1600                    .is_some_and(|c| read.columns.iter().any(|column| column == c) && plain(c))
1601                    && !values.is_empty()
1602                    && values.iter().all(|v| !v.is_empty() && v != "*")
1603            })
1604        {
1605            return Err("client.authority_read_forbidden: authority reads require plain columns, a primary key and nonempty plain scope selectors".into());
1606        }
1607    }
1608    Ok(())
1609}
1610
1611// §7.4.2: every open and recreation checks before any persistent writes.
1612/// A marker read that hit a recognized SQLite storage failure keeps that
1613/// classification (BUSY/LOCKED stay retryable); only an unclassified read
1614/// failure is the invalid-marker `sync.local_corrupt`.
1615fn schema_marker_read_failure(error: rusqlite::Error) -> String {
1616    let failure = QueryReadFailure::from(error);
1617    if failure.code.is_some() {
1618        failure.to_string()
1619    } else {
1620        "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned()
1621    }
1622}
1623
1624/// §7.1: reject an invalid configured client limit before any storage is
1625/// opened or written. Zero would wedge the push queue and an out-of-range
1626/// value would differ per target; the TS core enforces the same bounds.
1627fn validate_client_limits(limits: &crate::api::ClientLimits) -> Result<(), String> {
1628    if limits.outcome_retention_max_entries == Some(0) {
1629        return Err("sync.invalid_request: outcomeRetentionMaxEntries must be positive".to_owned());
1630    }
1631    if [
1632        limits.max_push_commits_per_request,
1633        limits.max_push_operations_per_request,
1634        limits.max_push_request_bytes,
1635    ]
1636    .into_iter()
1637    .flatten()
1638    .any(|value| value == 0 || value > u32::MAX as usize)
1639    {
1640        return Err(
1641            "sync.invalid_request: push limit must be an integer in 1..=4294967295".to_owned(),
1642        );
1643    }
1644    Ok(())
1645}
1646
1647fn read_local_schema_version(conn: &Connection, requested: i32) -> Result<Option<i32>, String> {
1648    let corrupt =
1649        || "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned();
1650    let table_type: Option<String> = conn
1651        .query_row(
1652            "SELECT type FROM sqlite_master WHERE name = '_syncular_meta'",
1653            [],
1654            |row| row.get(0),
1655        )
1656        .optional()
1657        .map_err(schema_marker_read_failure)?;
1658    let Some(table_type) = table_type else {
1659        return Ok(None);
1660    };
1661    if table_type != "table" {
1662        return Err(corrupt());
1663    }
1664    // §7.4.2: a duplicated marker cannot be resolved. `query_row` would take
1665    // whichever row SQLite returns first, and an older one would drive a
1666    // destructive reset over a newer replica.
1667    let mut statement = conn
1668        .prepare("SELECT value FROM _syncular_meta WHERE key = ?1")
1669        .map_err(schema_marker_read_failure)?;
1670    let mut rows = statement
1671        .query([LOCAL_SCHEMA_VERSION_KEY])
1672        .map_err(schema_marker_read_failure)?;
1673    let value: Option<String> = rows
1674        .next()
1675        .map_err(schema_marker_read_failure)?
1676        .map(|row| row.get(0))
1677        .transpose()
1678        .map_err(schema_marker_read_failure)?;
1679    if rows.next().map_err(schema_marker_read_failure)?.is_some() {
1680        return Err(corrupt());
1681    }
1682    let Some(value) = value else {
1683        let has_descriptor = conn
1684            .query_row(
1685                "SELECT 1 FROM _syncular_meta WHERE key = ?1 LIMIT 1",
1686                [crate::previous_version::LOCAL_SCHEMA_DESCRIPTOR_KEY],
1687                |_| Ok(()),
1688            )
1689            .optional()
1690            .map_err(schema_marker_read_failure)?
1691            .is_some();
1692        if has_descriptor {
1693            return Err(corrupt());
1694        }
1695        return Ok(None);
1696    };
1697    if !matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1698        || !value.bytes().all(|b| b.is_ascii_digit())
1699    {
1700        return Err(corrupt());
1701    }
1702    let version = value.parse::<i32>().map_err(|_| corrupt())?;
1703    if version > requested {
1704        return Err(
1705            "client.schema_downgrade: persisted local schema is newer than the requested schema"
1706                .to_owned(),
1707        );
1708    }
1709    Ok(Some(version))
1710}
1711
1712/// A file replica on a browser worker must recover a hot journal before any
1713/// statement reads it. `wasm_vfs` replaces the installed OPFS VFS's reserved
1714/// lock callback, so install it before the connection opens its file.
1715#[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
1716fn prepare_wasm_replica(path: &str) -> Result<(), String> {
1717    if path.is_empty() || path == ":memory:" {
1718        return Ok(());
1719    }
1720    crate::wasm_vfs::disable_foreign_lock_check()
1721}
1722
1723#[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
1724fn prepare_wasm_replica(_path: &str) -> Result<(), String> {
1725    Ok(())
1726}
1727
1728impl SyncClient {
1729    pub fn new_with_identity(
1730        client_id: Option<String>,
1731        schema_json: &Value,
1732        limits: ClientLimits,
1733    ) -> Result<Self, String> {
1734        let resolved = client_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
1735        let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1736        Self::with_connection(resolved, schema_json, limits, conn)
1737    }
1738
1739    pub fn new(
1740        client_id: String,
1741        schema_json: &Value,
1742        limits: ClientLimits,
1743    ) -> Result<Self, String> {
1744        let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1745        Self::with_connection(client_id, schema_json, limits, conn)
1746    }
1747
1748    /// Build a client backed by an on-disk SQLite database at `path` — the
1749    /// seam a native host (Tauri plugin, FFI file-DB variant) uses to persist
1750    /// across process restarts. `create_tables` runs `IF NOT EXISTS`, so
1751    /// re-opening the same file reuses the persisted rows. Keeps rusqlite out
1752    /// of the command router's dependency set (the router only holds a path).
1753    pub fn open_path(
1754        client_id: String,
1755        schema_json: &Value,
1756        limits: ClientLimits,
1757        path: &str,
1758    ) -> Result<Self, String> {
1759        validate_client_limits(&limits)?;
1760        parse_schema_json(schema_json)?;
1761        prepare_wasm_replica(path)?;
1762        let conn = Connection::open(path).map_err(|e| format!("open db {path:?}: {e}"))?;
1763        Self::with_connection(client_id, schema_json, limits, conn)
1764    }
1765
1766    /// Open a file replica and resolve its client id. Native targets require
1767    /// WAL for the independent snapshot reader; `wasm32-unknown-unknown`
1768    /// accepts the sqlite-wasm worker journal instead.
1769    pub fn open_path_with_identity(
1770        client_id: Option<String>,
1771        schema_json: &Value,
1772        limits: ClientLimits,
1773        path: &str,
1774    ) -> Result<Self, String> {
1775        Self::open_path_with_identity_journal(
1776            client_id,
1777            schema_json,
1778            limits,
1779            path,
1780            !cfg!(all(target_arch = "wasm32", target_os = "unknown")),
1781        )
1782    }
1783
1784    fn open_path_with_identity_journal(
1785        client_id: Option<String>,
1786        schema_json: &Value,
1787        limits: ClientLimits,
1788        path: &str,
1789        require_wal: bool,
1790    ) -> Result<Self, String> {
1791        validate_client_limits(&limits)?;
1792        // §7.4.2: an invalid requested version is refused before the replica is
1793        // even created, so a rejected constructor leaves no file behind.
1794        parse_schema_json(schema_json)?;
1795        prepare_wasm_replica(path)?;
1796        let conn = Connection::open(path).map_err(|e| format!("open db {path:?}: {e}"))?;
1797        // A file-backed native client uses an independent read connection for
1798        // latency-critical snapshots. WAL is SQLite's intended reader/writer
1799        // concurrency mode: a view read never holds a rollback-journal lock
1800        // that delays the client's next commit. The busy timeout must precede
1801        // this replica's own startup transaction; WAL is applied only after
1802        // startup succeeded, because a refused open must leave the replica's
1803        // journal mode and contents untouched (§7.4.2).
1804        conn.busy_timeout(std::time::Duration::from_millis(250))
1805            .map_err(|error| format!("configure db {path:?} busy timeout: {error}"))?;
1806        // Durability is the caller's contract here, not the VFS default: a
1807        // rollback-journal commit needs FULL before it writes the database
1808        // pages, or a killed worker can leave a half-written image behind.
1809        // WAL below inherits the same setting.
1810        conn.pragma_update(None, "synchronous", "FULL")
1811            .map_err(|error| format!("configure db {path:?} synchronous: {error}"))?;
1812        let client = Self::with_connection_identity(client_id, schema_json, limits, conn)?;
1813        // A browser worker's sqlite-wasm VFS has no WAL mode, and the wasm
1814        // host has no independent snapshot reader. The WAL requirement exists
1815        // for native file replicas, where it is the reader/writer boundary.
1816        if require_wal {
1817            let journal_mode: String = client
1818                .conn
1819                .pragma_update_and_check(None, "journal_mode", "WAL", |row| row.get(0))
1820                .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
1821            if journal_mode != "wal" {
1822                return Err(
1823                    "sync.invalid_request: file-backed client requires WAL journal mode".to_owned(),
1824                );
1825            }
1826        }
1827        Ok(client)
1828    }
1829
1830    /// Delete a file replica at `path`, including its `-journal`, `-wal`, and
1831    /// `-shm` sidecars, through the VFS that owns it. Use this after
1832    /// `client.storage_corrupt`: an OPFS SAH pool stores those files under
1833    /// opaque names, so deleting the pool directory behind SQLite bypasses the
1834    /// pool's slot accounting.
1835    ///
1836    /// Close the client and every [`FileQuerySnapshotReader`] on `path` first;
1837    /// a VFS cannot delete a file another handle still owns. A file that does
1838    /// not exist counts as deleted, so a cleanly closed replica without
1839    /// sidecars resets. The next open
1840    /// creates a fresh replica (new client id) and re-bootstraps from the
1841    /// server. A memory replica has nothing to delete and fails with
1842    /// `sync.invalid_request`.
1843    pub fn reset_replica(path: &str) -> Result<(), String> {
1844        if path.is_empty() || path == ":memory:" {
1845            return Err("sync.invalid_request: a memory replica has nothing to reset".to_owned());
1846        }
1847        // SAFETY: a null VFS name asks SQLite for its process-wide default VFS,
1848        // the same one `Connection::open(path)` above selects. `xDelete` is
1849        // that VFS's own function pointer, and `c_name` outlives the call.
1850        let vfs = unsafe { rusqlite::ffi::sqlite3_vfs_find(std::ptr::null()) };
1851        if vfs.is_null() {
1852            return Err("client.storage_io: no SQLite VFS is registered".to_owned());
1853        }
1854        let delete = unsafe { (*vfs).xDelete }
1855            .ok_or_else(|| "client.storage_io: the SQLite VFS cannot delete files".to_owned())?;
1856        for suffix in ["-wal", "-shm", "-journal", ""] {
1857            let file_name = format!("{path}{suffix}");
1858            let c_name = std::ffi::CString::new(file_name.as_str()).map_err(|_| {
1859                format!("sync.invalid_request: replica path {file_name:?} contains a NUL byte")
1860            })?;
1861            // SAFETY: `vfs` and its `xDelete` pointer come from the live
1862            // SQLite library; `c_name` is a valid NUL-terminated path.
1863            let code = unsafe { delete(vfs, c_name.as_ptr(), 1) };
1864            // A cleanly closed WAL replica has no sidecars; a missing file is
1865            // already deleted.
1866            if code != rusqlite::ffi::SQLITE_OK && code != rusqlite::ffi::SQLITE_IOERR_DELETE_NOENT
1867            {
1868                return Err(format!(
1869                    "client.storage_io: deleting replica file {file_name:?} failed with SQLite code {code}"
1870                ));
1871            }
1872        }
1873        Ok(())
1874    }
1875
1876    #[must_use]
1877    pub fn client_id(&self) -> &str {
1878        &self.client_id
1879    }
1880
1881    /// Rotate the caller's client id (§1.5) and return the new one. Use it
1882    /// after a `sync.invalid_client_id` refusal (`recommendedAction:
1883    /// resetClientId`): the next round carries the new id. A live realtime
1884    /// socket is closed so the next connection registers with the new id.
1885    /// The replica and its outbox stay in place; wipe them yourself when the
1886    /// stored data belongs to the account that signed out.
1887    pub fn reset_client_id(&mut self, transport: &mut dyn Transport) -> Result<String, String> {
1888        self.disconnect_realtime(transport);
1889        let client_id = uuid::Uuid::new_v4().to_string();
1890        self.set_meta(CLIENT_ID_KEY, &client_id)?;
1891        self.client_id.clone_from(&client_id);
1892        self.round_failure = None;
1893        Ok(client_id)
1894    }
1895
1896    /// Build a client over a caller-supplied rusqlite connection — the seam a
1897    /// native host (Tauri plugin, FFI file-DB variant) uses to back the core
1898    /// with an on-disk database (`Connection::open(path)`) rather than the
1899    /// default `:memory:`. The connection MUST be fresh (no pre-existing
1900    /// syncular tables); `create_tables` runs `IF NOT EXISTS`, so re-opening
1901    /// the same file across process restarts reuses the persisted rows.
1902    pub fn with_connection(
1903        client_id: String,
1904        schema_json: &Value,
1905        limits: ClientLimits,
1906        conn: Connection,
1907    ) -> Result<Self, String> {
1908        Self::with_connection_identity(Some(client_id), schema_json, limits, conn)
1909    }
1910
1911    /// [`Self::with_connection`] for `open_path_with_identity`: no requested id
1912    /// means a durable replica's persisted `clientId` wins over a fresh one.
1913    fn with_connection_identity(
1914        client_id: Option<String>,
1915        schema_json: &Value,
1916        limits: ClientLimits,
1917        conn: Connection,
1918    ) -> Result<Self, String> {
1919        validate_client_limits(&limits)?;
1920        let schema = parse_schema_json(schema_json)?;
1921        validate_authority_reads(&schema, &limits.authority_reads)?;
1922        // RFC 0005 D8: resolve the previous-version config before the opening
1923        // reset runs — the capture happens inside it. Bad bounds fail loud.
1924        let previous_version = match limits.previous_version_context {
1925            Some(config) => {
1926                config.validate()?;
1927                Some(config)
1928            }
1929            None => None,
1930        };
1931        let mut client = SyncClient {
1932            #[cfg(feature = "bench-internals")]
1933            benchmark_phases: Recorder::default(),
1934            conn,
1935            schema,
1936            client_id: client_id
1937                .clone()
1938                .unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
1939            limits,
1940            outbox: Shared::default(),
1941            failed_commits: Shared::default(),
1942            retain_failed_commits: false,
1943            conflicts: Shared::default(),
1944            rejections: Shared::default(),
1945            schema_floor: None,
1946            lease_state: None,
1947            stopped: false,
1948            upgrading: false,
1949            sync_needed: false,
1950            realtime_policy: RealtimePolicy::Optional,
1951            realtime_state: RealtimeState::Disconnected,
1952            realtime_reason_code: None,
1953            realtime_retry_delay_ms: None,
1954            presence: HashMap::new(),
1955            now_ms: None,
1956            encryption: crate::values::EncryptionConfig::default(),
1957            security_preflight: false,
1958            security_epoch: 0,
1959            transport_enabled: true,
1960            transport_epoch: 0,
1961            registration_epoch: 0,
1962            previous_version,
1963            insert_sql: RefCell::new(HashMap::new()),
1964            overlay_dirty: OverlayDirty::clean(),
1965            storage_failure: RefCell::new(None),
1966            #[cfg(test)]
1967            overlay_rebuild_count: Cell::new(0),
1968            #[cfg(test)]
1969            acknowledged_replay_count: Cell::new(0),
1970            #[cfg(test)]
1971            outcome_prune_count: Cell::new(0),
1972            progress: ProgressObserver::default(),
1973            change_queue: VecDeque::new(),
1974            sync_intent_queue: VecDeque::new(),
1975            retry_delay_ms: 250,
1976            round_retry_delay_ms: None,
1977            round_failure: None,
1978            active_round: None,
1979            last_round: None,
1980            last_change: None,
1981            query_failures: Vec::new(),
1982            coalesced: None,
1983            coalesced_failure: None,
1984        };
1985        // The row write path leans on the prepared-statement cache (two
1986        // insert statements per synced table, plus the bookkeeping
1987        // statements); size it so a multi-table schema never thrashes.
1988        client
1989            .conn
1990            .set_prepared_statement_cache_capacity(64.max(client.schema.tables.len() * 4));
1991        // §7.4.2: one write transaction (SQLite `BEGIN IMMEDIATE`, a reserved
1992        // writer) covers the marker read, the identity check, and every
1993        // bookkeeping/schema write, so a concurrent open that upgraded the
1994        // replica cannot interleave between the guard and the writes, and a
1995        // refusal leaves the replica unchanged.
1996        client
1997            .conn
1998            .execute_batch("BEGIN IMMEDIATE")
1999            .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2000        let startup = (|| -> Result<(), String> {
2001            // The marker guard runs inside the write transaction, so the version
2002            // it validates is the version every write below commits under.
2003            let marker = read_local_schema_version(&client.conn, client.schema.version)?;
2004            // New app indexes may reference columns that only exist after a
2005            // version-bump reset.
2006            client.create_bookkeeping_tables()?;
2007            match client.get_meta(CLIENT_ID_KEY)? {
2008                Some(existing) => match client_id {
2009                    Some(requested) if existing != requested => {
2010                        return Err(format!(
2011                            "client.identity_mismatch: this database belongs to {existing:?}; refusing to rebind it to {requested:?}"
2012                        ))
2013                    }
2014                    _ => client.client_id = existing,
2015                },
2016                None => client.set_meta(CLIENT_ID_KEY, &client.client_id)?,
2017            }
2018            client.restore_persisted_state()?;
2019            client.failed_commits = client.load_failed_commits()?.into();
2020            match marker {
2021                None => {
2022                    client.create_synced_tables()?;
2023                    client.persist_schema_version()?;
2024                    client.save_unit_scope_schema()?;
2025                }
2026                Some(version) if version == client.schema.version => {
2027                    client.create_synced_tables()?;
2028                    // RFC 0005 D1: the same-version open backfills the descriptor
2029                    // for a database first opened by an unaware binary, so the
2030                    // NEXT bump can capture without needing a schema bump first.
2031                    set_local_schema_descriptor(&client.conn, &client.schema)
2032                        .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2033                    client.save_unit_scope_schema()?;
2034                }
2035                Some(_) => client.run_schema_reset()?,
2036            }
2037            // RFC 0005 D9: the reset sweep cannot see a container whose capture
2038            // committed in its OWN file while the replica's savepoint never
2039            // released — a crash at that seam leaves a container beside a matching
2040            // OLD marker, and the next open at that version runs no reset. Discard
2041            // it before anything can read it. No-op when no container exists.
2042            client.reconcile_previous_version_at_boot()?;
2043            client.clear_satisfied_persisted_schema_floor()?;
2044            client.prune_unknown_units(false)?;
2045            // §7.1/§7.4.4: recover intrinsically codec-invalid persisted values at
2046            // the full startup/reset reconciliation boundary, inside this open
2047            // transaction and after the schema and identity guards, so a commit
2048            // an earlier version accepted is dropped with durable rejection
2049            // evidence before any replay. A table the current schema removed
2050            // keeps the §7.4.4 send-time classification, and an unresolved
2051            // encryption key stays with the send seam because hosts configure
2052            // keys after open.
2053            client.drop_unencodable_outbox(false, None)?;
2054            if marker == Some(client.schema.version)
2055                && (!client.outbox.is_empty()
2056                    || !client.failed_commits.is_empty()
2057                    || client.has_acknowledged_rows()?)
2058            {
2059                // Reconstruct the visible optimistic overlay from the durable
2060                // base plus outbox instead of trusting a process-interrupted
2061                // mirror.
2062                client.overlay_dirty.set(true);
2063                client.rebuild_overlay()?;
2064            }
2065            // Every persisted active unit needs one catch-up pull on
2066            // open: realtime only covers changes after connection, while an
2067            // idempotent setWindow correctly creates no fresh command effect.
2068            // Pending outbox work has the same restart requirement. The core
2069            // owns this intent so native hosts never poll or require an
2070            // application-issued sync().
2071            client.enqueue_startup_sync_if_needed()?;
2072            Ok(())
2073        })();
2074        match startup {
2075            Ok(()) => match client.conn.execute_batch("COMMIT") {
2076                // §4.8: an eviction a crash interrupted finishes before any
2077                // read, with or without a transport; a replica reopened in
2078                // preflight finishes it at activation.
2079                Ok(()) => {
2080                    if !client.security_preflight {
2081                        client.drain_pending_evictions()?;
2082                    }
2083                    Ok(client)
2084                }
2085                Err(error) => {
2086                    let failure = Self::sqlite_failure(&client.storage_failure, error);
2087                    if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2088                        // Keep a failed rollback's typed storage classification.
2089                        let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2090                    }
2091                    Err(failure)
2092                }
2093            },
2094            Err(error) => {
2095                if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2096                    // Keep a failed rollback's typed storage classification.
2097                    let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2098                }
2099                Err(error)
2100            }
2101        }
2102    }
2103
2104    /// Pin the client clock (epoch ms) — the §5.4 expiry check runs
2105    /// against this instead of system time (conformance virtual clock).
2106    pub fn set_now_ms(&mut self, now_ms: i64) {
2107        self.now_ms = Some(now_ms);
2108    }
2109
2110    /// §5.11: install the client-side encryption keys (`keyId → key bytes`).
2111    /// The command router parses these from the `create` command's
2112    /// `encryption` config (keys as `{$bytes: hex}`).
2113    pub fn set_encryption(&mut self, encryption: crate::values::EncryptionConfig) {
2114        self.encryption = encryption;
2115    }
2116
2117    #[must_use]
2118    pub fn security_lifecycle(&self) -> &'static str {
2119        if self.security_preflight {
2120            "preflight"
2121        } else {
2122            "active"
2123        }
2124    }
2125
2126    #[must_use]
2127    pub fn security_preflight(&self) -> bool {
2128        self.security_preflight
2129    }
2130
2131    /// Host-owned, non-persisted network gate. Local operations remain available.
2132    pub fn set_transport_enabled(&mut self, transport: &mut dyn Transport, enabled: bool) {
2133        if self.transport_enabled != enabled {
2134            self.transport_enabled = enabled;
2135            self.transport_epoch = self.transport_epoch.wrapping_add(1);
2136            self.sync_intent_queue.clear();
2137            self.sync_intent_queue
2138                .push_back(if enabled && !self.security_preflight {
2139                    SyncIntent::Interactive
2140                } else {
2141                    SyncIntent::None
2142                });
2143        }
2144        // A captured reply keeps its normal apply/revocation semantics.
2145        if !enabled && self.active_round.is_none() {
2146            self.disconnect_realtime(transport);
2147        }
2148    }
2149
2150    pub fn transport_enabled(&self) -> bool {
2151        self.transport_enabled
2152    }
2153
2154    /// Quarantine this replica: enter the fail-closed gate, release all
2155    /// core-owned key material, and record the gate in the database so
2156    /// reopening re-enters preflight until `activate_security` clears it.
2157    ///
2158    /// Use [`SyncClient::seal_security_on_teardown`] for the shutdown barrier,
2159    /// which must NOT leave that durable mark.
2160    pub fn begin_security_preflight(&mut self) -> Result<(), String> {
2161        self.seal_security_on_teardown();
2162        // Persist the quarantine so it survives handle teardown and restart:
2163        // reopening this replica re-enters preflight until activation clears it.
2164        self.set_meta(SECURITY_PREFLIGHT_PENDING_KEY, "1")
2165    }
2166
2167    /// Release core-owned key material as a host tears the client down,
2168    /// WITHOUT recording a quarantine.
2169    ///
2170    /// Shutting an activated client down is not a quarantine event. Persisting
2171    /// the gate here marks every cleanly closed replica as pending, and the
2172    /// next plain `create` is then refused permanently: the reopen path
2173    /// restores the flag from the marker and the create guard rejects it. The
2174    /// in-memory flag still closes the gate for anything still holding this
2175    /// instance, which is all a teardown barrier needs.
2176    pub fn seal_security_on_teardown(&mut self) {
2177        self.cancel_sync_round();
2178        self.security_preflight = true;
2179        self.security_epoch = self.security_epoch.wrapping_add(1);
2180        self.encryption = crate::values::EncryptionConfig::default();
2181        self.sync_intent_queue.clear();
2182    }
2183
2184    /// Install the post-authentication keyring and release the host loop.
2185    pub fn activate_security(
2186        &mut self,
2187        encryption: crate::values::EncryptionConfig,
2188    ) -> Result<(), String> {
2189        if !self.security_preflight {
2190            return Err(
2191                "sync.invalid_request: activateSecurity requires security preflight".to_owned(),
2192            );
2193        }
2194        // §4.8: an interrupted eviction finishes before protected reads open.
2195        self.drain_pending_evictions()?;
2196        self.enqueue_startup_sync_if_needed()?;
2197        self.delete_meta(SECURITY_PREFLIGHT_PENDING_KEY)?;
2198        self.encryption = encryption;
2199        self.security_preflight = false;
2200        Ok(())
2201    }
2202
2203    fn clock_now_ms(&self) -> i64 {
2204        self.now_ms.unwrap_or_else(crate::wall_clock_ms)
2205    }
2206
2207    fn create_bookkeeping_tables(&self) -> Result<(), String> {
2208        let exists = |name: &str| {
2209            self.conn
2210                .query_row(
2211                    "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1)",
2212                    [name],
2213                    |row| row.get::<_, bool>(0),
2214                )
2215                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2216        };
2217        let outbox_existed = exists("_syncular_outbox")?;
2218        // Durable client bookkeeping (outbox + units + meta).
2219        self.conn
2220            .execute_batch(
2221                "CREATE TABLE IF NOT EXISTS _syncular_outbox (
2222                   seq INTEGER PRIMARY KEY AUTOINCREMENT,
2223                   commit_id TEXT NOT NULL UNIQUE, ops_json TEXT NOT NULL);
2224                 CREATE TABLE IF NOT EXISTS _syncular_row_deliveries (
2225                   tbl TEXT NOT NULL, id TEXT NOT NULL, commit_seq INTEGER NOT NULL, PRIMARY KEY(tbl,id));
2226                 CREATE TABLE IF NOT EXISTS _syncular_acked_rows (
2227                   commit_id TEXT NOT NULL, idx INTEGER NOT NULL, tbl TEXT NOT NULL, id TEXT NOT NULL,
2228                   commit_seq INTEGER NOT NULL, op_json TEXT NOT NULL, intent_json TEXT,
2229                   PRIMARY KEY(commit_id, idx));
2230                 CREATE INDEX IF NOT EXISTS _syncular_acked_rows_row
2231                   ON _syncular_acked_rows(tbl, id);
2232                 CREATE TABLE IF NOT EXISTS _syncular_failed_commits (
2233                   seq INTEGER PRIMARY KEY AUTOINCREMENT, client_commit_id TEXT NOT NULL UNIQUE,
2234                   operations_json TEXT NOT NULL, initial_json TEXT NOT NULL);
2235                 CREATE TABLE IF NOT EXISTS _syncular_commit_outcomes (
2236                   seq INTEGER PRIMARY KEY AUTOINCREMENT,
2237                   client_commit_id TEXT NOT NULL UNIQUE,
2238                   status TEXT NOT NULL CHECK(status IN ('applied', 'cached', 'conflict', 'rejected')),
2239                   recorded_at_ms INTEGER NOT NULL,
2240                   results_json TEXT NOT NULL,
2241                   operations_json TEXT,
2242                   resolution TEXT NOT NULL DEFAULT 'active'
2243                     CHECK(resolution IN ('active', 'resolved_keep_server', 'superseded', 'dismissed')),
2244                   resolved_at_ms INTEGER,
2245                   replacement_client_commit_id TEXT);
2246                 CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq
2247                   ON _syncular_commit_outcomes(resolution, seq);
2248                 CREATE TABLE IF NOT EXISTS _syncular_units (
2249                   id TEXT PRIMARY KEY, scopes TEXT NOT NULL,
2250                   explicit INTEGER NOT NULL DEFAULT 0,
2251                   status TEXT NOT NULL DEFAULT 'active', reason_code TEXT,
2252                   cursor INTEGER DEFAULT -1, bootstrap_state TEXT,
2253                   seeded TEXT NOT NULL DEFAULT '[]', echo TEXT);
2254                 CREATE TABLE IF NOT EXISTS _syncular_meta (
2255                   key TEXT PRIMARY KEY, value TEXT NOT NULL);
2256                 CREATE TABLE IF NOT EXISTS _syncular_windows (
2257                   base TEXT NOT NULL, unit TEXT NOT NULL, sub_id TEXT NOT NULL,
2258                   PRIMARY KEY (base, unit));
2259                 CREATE INDEX IF NOT EXISTS _syncular_windows_unit ON _syncular_windows(sub_id);
2260                 CREATE TABLE IF NOT EXISTS _syncular_pending_evictions (
2261                   unit_id TEXT NOT NULL, tbl TEXT NOT NULL,
2262                   effective_scopes TEXT NOT NULL, PRIMARY KEY (unit_id, tbl));
2263                 CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
2264                   commit_id TEXT NOT NULL, blob_id TEXT NOT NULL,
2265                   PRIMARY KEY(commit_id, blob_id));
2266                 CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body
2267                   ON _syncular_blob_commit_refs(blob_id);",
2268            )
2269            .map_err(|e| e.to_string())?;
2270        // Migrate an outcome journal created before failed aggregate
2271        // envelopes were retained. Historical rows intentionally stay NULL.
2272        let _ = self
2273            .conn
2274            .execute_batch("ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations_json TEXT");
2275        if self.get_meta(LOCAL_REVISION_KEY)?.is_none() {
2276            self.set_meta(LOCAL_REVISION_KEY, "0")?;
2277        }
2278        // §7.1: `outboxId` names the outbox sequence. A new outbox table starts
2279        // a new sequence, so it replaces the id in the same transaction.
2280        if !outbox_existed || self.get_meta(OUTBOX_ID_KEY)?.is_none() {
2281            self.set_meta(OUTBOX_ID_KEY, &uuid::Uuid::new_v4().to_string())?;
2282        }
2283        // §9: a replica written under wire version 3 keeps its outbox, journal,
2284        // rows and pending evictions and registers its units fresh. Its
2285        // subscriptions, cursors, echoes, resume tokens and window entries go;
2286        // units left from an earlier version 4 life restart.
2287        if exists("_syncular_window_pending_evict")? {
2288            let invalid: bool = self
2289                .conn
2290                .query_row(
2291                    "SELECT EXISTS(SELECT 1 FROM _syncular_window_pending_evict
2292                       WHERE NOT json_valid(effective_scopes)
2293                          OR json_type(effective_scopes) <> 'object'
2294                          OR EXISTS(SELECT 1 FROM json_each(effective_scopes)
2295                               WHERE type <> 'array'
2296                                  OR EXISTS(SELECT 1 FROM json_each(value) AS v
2297                                       WHERE v.type <> 'text')))",
2298                    [],
2299                    |row| row.get(0),
2300                )
2301                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2302            if invalid {
2303                return Err(
2304                    "sync.local_corrupt: a version 3 pending eviction cannot be upgraded"
2305                        .to_owned(),
2306                );
2307            }
2308            self.conn
2309                .execute_batch(
2310                    "INSERT OR REPLACE INTO _syncular_pending_evictions
2311                       SELECT sub_id, tbl, effective_scopes FROM _syncular_window_pending_evict;
2312                     DROP TABLE _syncular_window_pending_evict;
2313                     DROP TABLE IF EXISTS _syncular_subscriptions;
2314                     DELETE FROM _syncular_windows;",
2315                )
2316                .and_then(|()| reset_units(&self.conn))
2317                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2318        }
2319        // §5.9.7 blob cache. Mutable upload state stays off the body row so
2320        // completing a large upload does not rewrite its BLOB record.
2321        if self.schema_has_blobs() {
2322            if exists("_syncular_blobs")? {
2323                let mut statement = self
2324                    .conn
2325                    .prepare("PRAGMA table_info(_syncular_blobs)")
2326                    .map_err(|e| e.to_string())?;
2327                let mut columns = statement
2328                    .query_map([], |row| row.get::<_, String>(1))
2329                    .map_err(|e| e.to_string())?
2330                    .collect::<Result<Vec<_>, _>>()
2331                    .map_err(|e| e.to_string())?;
2332                columns.sort();
2333                let mut expected = vec![
2334                    "blob_id",
2335                    "byte_length",
2336                    "bytes",
2337                    "created_at_ms",
2338                    "media_type",
2339                ];
2340                expected.sort_unstable();
2341                if columns != expected {
2342                    return Err(
2343                        "sync.schema_mismatch: Local blob schema is incompatible".to_owned()
2344                    );
2345                }
2346            } else {
2347                self.conn
2348                    .execute_batch(
2349                        "CREATE TABLE _syncular_blobs(
2350                           blob_id TEXT PRIMARY KEY,
2351                           bytes BLOB NOT NULL,
2352                           byte_length INTEGER NOT NULL,
2353                           media_type TEXT,
2354                           created_at_ms INTEGER NOT NULL);",
2355                    )
2356                    .map_err(|e| e.to_string())?;
2357            }
2358            self.conn
2359                .execute_batch(
2360                    "CREATE TABLE IF NOT EXISTS _syncular_blob_uploads(
2361                       blob_id TEXT PRIMARY KEY,
2362                       media_type TEXT,
2363                       created_at_ms INTEGER NOT NULL);",
2364                )
2365                .map_err(|e| e.to_string())?;
2366        }
2367        Ok(())
2368    }
2369
2370    /// True iff any synced table declares a `blob_ref` column (§5.9).
2371    fn schema_has_blobs(&self) -> bool {
2372        self.schema
2373            .tables
2374            .iter()
2375            .any(|t| t.columns.iter().any(|c| c.ty == ColumnType::BlobRef))
2376    }
2377
2378    // -- meta (§7.4.1 marker, bookkeeping) ------------------------------------
2379
2380    fn get_meta(&self, key: &str) -> Result<Option<String>, String> {
2381        meta_get(&self.conn, key)
2382            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2383    }
2384
2385    // The caller holds the startup/reset transaction. Either both schema
2386    // records persist or the enclosing operation fails and rolls back.
2387    fn persist_schema_version(&self) -> Result<(), String> {
2388        self.conn
2389            .execute(
2390                "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
2391                rusqlite::params![LOCAL_SCHEMA_VERSION_KEY, self.schema.version.to_string()],
2392            )
2393            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2394        set_local_schema_descriptor(&self.conn, &self.schema)
2395            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2396    }
2397
2398    pub(crate) fn set_meta(&self, key: &str, value: &str) -> Result<(), String> {
2399        meta_set(&self.conn, key, value)
2400            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2401    }
2402
2403    fn delete_meta(&self, key: &str) -> Result<(), String> {
2404        meta_delete(&self.conn, key)
2405            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2406    }
2407
2408    /// §7.1: the durable outbox in FIFO order, in schema-agnostic local form.
2409    fn load_outbox(&self) -> Result<Vec<Arc<OutboxCommit>>, String> {
2410        let mut stmt = self
2411            .conn
2412            .prepare("SELECT commit_id, ops_json FROM _syncular_outbox ORDER BY seq ASC")
2413            .map_err(|error| error.to_string())?;
2414        let rows = stmt
2415            .query_map([], |row| {
2416                Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
2417            })
2418            .map_err(|error| error.to_string())?;
2419        let mut commits = Vec::new();
2420        for row in rows {
2421            let (client_commit_id, raw) = row.map_err(|error| error.to_string())?;
2422            let entries: Vec<Value> = serde_json::from_str(&raw).map_err(|error| {
2423                format!("invalid persisted outbox {client_commit_id:?}: {error}")
2424            })?;
2425            let mut ops = Vec::with_capacity(entries.len());
2426            for entry in entries {
2427                let op = entry.get("op").and_then(Value::as_str).unwrap_or("delete");
2428                ops.push(OutboxOp {
2429                    upsert: op == "upsert",
2430                    table: entry
2431                        .get("table")
2432                        .and_then(Value::as_str)
2433                        .ok_or_else(|| "persisted outbox operation missing table".to_owned())?
2434                        .to_owned(),
2435                    row_id: entry
2436                        .get("rowId")
2437                        .and_then(Value::as_str)
2438                        .ok_or_else(|| "persisted outbox operation missing rowId".to_owned())?
2439                        .to_owned(),
2440                    base_version: entry.get("baseVersion").and_then(Value::as_i64),
2441                    // A legacy entry's `changedFields` key is ignored:
2442                    // the values map is the presence set (§6.1).
2443                    values: entry.get("values").and_then(Value::as_object).cloned(),
2444                    insert: entry.get("insert") == Some(&Value::Bool(true)),
2445                });
2446            }
2447            commits.push(Arc::new(OutboxCommit {
2448                client_commit_id,
2449                ops,
2450            }));
2451        }
2452        Ok(commits)
2453    }
2454
2455    fn restore_persisted_state(&mut self) -> Result<(), String> {
2456        self.outbox = self.load_outbox()?.into();
2457
2458        self.prune_commit_outcomes()?;
2459        let active = self.commit_outcomes(CommitOutcomeQuery {
2460            active_only: true,
2461            ..CommitOutcomeQuery::default()
2462        })?;
2463        self.conflicts = active
2464            .iter()
2465            .flat_map(|outcome| outcome.results.iter())
2466            .filter_map(|result| match result {
2467                CommitOperationOutcome::Conflict { conflict } => Some(conflict.clone()),
2468                _ => None,
2469            })
2470            .collect::<Vec<_>>()
2471            .into();
2472        self.rejections = active
2473            .iter()
2474            .flat_map(|outcome| outcome.results.iter())
2475            .filter_map(|result| match result {
2476                CommitOperationOutcome::Error { rejection } => Some(rejection.clone()),
2477                _ => None,
2478            })
2479            .collect::<Vec<_>>()
2480            .into();
2481
2482        self.lease_state = self
2483            .get_meta(LEASE_STATE_KEY)?
2484            .map(|raw| serde_json::from_str(&raw))
2485            .transpose()
2486            .map_err(|error| format!("invalid persisted lease state: {error}"))?;
2487        self.schema_floor = self
2488            .get_meta(SCHEMA_FLOOR_KEY)?
2489            .map(|raw| serde_json::from_str(&raw))
2490            .transpose()
2491            .map_err(|error| format!("invalid persisted schema floor: {error}"))?;
2492        self.stopped = self.schema_floor.is_some();
2493        // A replica left in unactivated preflight reopens gated: the quarantine
2494        // decision persists with the data across handle teardown and restart.
2495        if self.get_meta(SECURITY_PREFLIGHT_PENDING_KEY)?.as_deref() == Some("1") {
2496            self.security_preflight = true;
2497        }
2498        Ok(())
2499    }
2500
2501    fn save_unit_scope_schema(&self) -> Result<(), String> {
2502        let declarations: BTreeMap<_, BTreeMap<_, _>> = self
2503            .schema
2504            .tables
2505            .iter()
2506            .map(|table| {
2507                (
2508                    table.name.clone(),
2509                    table
2510                        .scope_variables
2511                        .iter()
2512                        .map(|scope| {
2513                            (
2514                                scope.variable.clone(),
2515                                [scope.prefix.clone(), scope.column.clone()],
2516                            )
2517                        })
2518                        .collect(),
2519                )
2520            })
2521            .collect();
2522        self.set_meta(
2523            "subscriptionScopeSchema",
2524            &serde_json::to_string(&declarations).expect("scope schema serialization"),
2525        )
2526    }
2527
2528    /// Drop units that cover no table of the running schema, with their window
2529    /// registry rows and pending evictions; never translate scopes. At a bump
2530    /// (§7.4.3) a unit also needs every variable unchanged in prefix and column
2531    /// on every table it covered before.
2532    fn prune_unknown_units(&mut self, bump: bool) -> Result<(), String> {
2533        let previous: Option<BTreeMap<String, BTreeMap<String, [String; 2]>>> = if bump {
2534            self.get_meta("subscriptionScopeSchema")?
2535                .map(|raw| serde_json::from_str(&raw))
2536                .transpose()
2537                .map_err(|_| "sync.local_corrupt: invalid persisted scope schema".to_owned())?
2538        } else {
2539            None
2540        };
2541        // A table keeps the variables' meaning when each has the same prefix
2542        // and column as before. An old binary stored no declaration evidence;
2543        // matching names cannot prove unchanged meaning, so the app registers
2544        // again.
2545        let unchanged = |name: &str, variables: &[&String]| {
2546            let (Some(old), Some(table)) = (
2547                previous.as_ref().and_then(|previous| previous.get(name)),
2548                self.schema.table(name),
2549            ) else {
2550                return false;
2551            };
2552            variables.iter().all(|variable| {
2553                table
2554                    .scope_variables
2555                    .iter()
2556                    .find(|scope| &scope.variable == *variable)
2557                    .is_some_and(|scope| {
2558                        old.get(*variable) == Some(&[scope.prefix.clone(), scope.column.clone()])
2559                    })
2560            })
2561        };
2562        let compatible = |scopes: &UnitScopes| {
2563            if !self.schema.tables.iter().any(|table| covers(table, scopes)) {
2564                return false;
2565            }
2566            if !bump {
2567                return true;
2568            }
2569            let Some(previous) = &previous else {
2570                return false;
2571            };
2572            previous.iter().all(|(name, old)| {
2573                !scopes.keys().all(|variable| old.contains_key(variable))
2574                    || unchanged(name, &scopes.keys().collect::<Vec<_>>())
2575            })
2576        };
2577        let mut stale: BTreeSet<String> = self
2578            .stored(load_units(&self.conn))?
2579            .into_iter()
2580            .filter(|unit| !compatible(&unit.scopes))
2581            .map(|unit| unit.id)
2582            .collect();
2583        // A shrunk window's deferred eviction outlives its unit row and keeps
2584        // its per-table scopes. A table the schema no longer has cannot be
2585        // evicted, and at a bump a table whose scope declarations changed must
2586        // not be evicted by the outdated rule.
2587        for (id, table, effective) in self.load_pending_evictions()? {
2588            if self.schema.table(&table).is_none()
2589                || (bump
2590                    && !unchanged(
2591                        &table,
2592                        &effective
2593                            .iter()
2594                            .map(|(variable, _)| variable)
2595                            .collect::<Vec<_>>(),
2596                    ))
2597            {
2598                stale.insert(id);
2599            }
2600        }
2601        for id in &stale {
2602            for sql in [
2603                "DELETE FROM _syncular_windows WHERE sub_id = ?1",
2604                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
2605                "DELETE FROM _syncular_units WHERE id = ?1",
2606            ] {
2607                self.conn
2608                    .execute(sql, rusqlite::params![id])
2609                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2610            }
2611        }
2612        Ok(())
2613    }
2614
2615    pub fn local_revision(&self) -> Result<u64, String> {
2616        Ok(self
2617            .get_meta(LOCAL_REVISION_KEY)?
2618            .and_then(|value| value.parse().ok())
2619            .unwrap_or(0))
2620    }
2621
2622    /// §7.5: resolve a snapshot read on the mutable owner connection through
2623    /// the same primitive the read-only sidecar uses, so the command surface
2624    /// and the file sidecar return one revision, rows, coverage, catch-up, and
2625    /// delivery shape. The structured [`QueryReadFailure`] is preserved; an
2626    /// `owner` records its failure (and its next success) in diagnostics.
2627    pub fn snapshot_read(
2628        &mut self,
2629        request: &SnapshotReadRequest<'_>,
2630        owner: Option<QueryOwner<'_>>,
2631    ) -> Result<SnapshotRead, QueryReadFailure> {
2632        let result = snapshot_read_connection(&self.conn, request);
2633        if let Some(owner) = owner {
2634            self.record_query_read(owner, result.as_ref().err());
2635        }
2636        result
2637    }
2638
2639    #[must_use]
2640    pub fn status_snapshot(&self) -> SyncStatusSnapshot {
2641        SyncStatusSnapshot {
2642            current_schema_version: self.schema.version,
2643            outbox: self.outbox.len(),
2644            upgrading: self.upgrading,
2645            lease_state: self.lease_state.clone(),
2646            schema_floor: self.schema_floor.clone(),
2647            sync_needed: self.sync_needed,
2648            previous_version_context: self.previous_version_status(),
2649        }
2650    }
2651
2652    /// RFC 0005 A2: container presence for a host that must act on it (Diego's
2653    /// rollback precondition), read without creating the file.
2654    fn previous_version_status(&self) -> PreviousVersionStatus {
2655        let Some(replica_path) = self.previous_version_replica_path() else {
2656            return PreviousVersionStatus {
2657                present: false,
2658                created_at_ms: None,
2659            };
2660        };
2661        match crate::previous_version::read_previous_version_record(&replica_path) {
2662            Ok(Some(record)) => PreviousVersionStatus {
2663                present: true,
2664                created_at_ms: Some(record.created_at_ms),
2665            },
2666            _ => PreviousVersionStatus {
2667                present: std::path::Path::new(
2668                    &crate::previous_version::previous_version_container_path(&replica_path),
2669                )
2670                .exists(),
2671                created_at_ms: None,
2672            },
2673        }
2674    }
2675
2676    /// RFC 0005 D7: read captured rows from the previous local schema. `state`
2677    /// is always `previousVersion`; the container never makes
2678    /// `query_snapshot()` coverage complete. Lease stop/expiry, scope
2679    /// revocation, coverage completion and the TTL DISCARD the container and
2680    /// close the read with their own reason.
2681    pub fn previous_version_snapshot(
2682        &self,
2683        spec: &PreviousVersionReadSpec,
2684    ) -> Result<PreviousVersionSnapshot, String> {
2685        let now_ms = self.clock_now_ms();
2686        crate::previous_version::previous_version_snapshot(
2687            &self.conn,
2688            self.previous_version_replica_path().as_deref(),
2689            self.previous_version.as_ref(),
2690            PreviousVersionLifecycle {
2691                lease_inactive: self.previous_version_lease_inactive(now_ms),
2692                scope_revoked: self
2693                    .stored(load_units(&self.conn))?
2694                    .iter()
2695                    .any(|unit| unit.status == UnitStatus::Revoked),
2696                coverage_complete: self.previous_version_coverage_complete()?,
2697            },
2698            now_ms,
2699            self.schema.version,
2700            spec,
2701        )
2702    }
2703
2704    /// RFC 0005 D6: the advisory pre-reset compatibility audit.
2705    pub fn previous_version_audit(
2706        &self,
2707    ) -> Result<Option<crate::previous_version::PreviousVersionAudit>, String> {
2708        crate::previous_version::stored_previous_version_audit(&self.conn)
2709            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2710    }
2711
2712    /// RFC 0005 A2/D9: the executable downgrade step. Drop the container file
2713    /// and both metadata records, and report whether anything was present.
2714    /// Idempotent: absence is a successful no-op.
2715    pub fn previous_version_discard(
2716        &self,
2717    ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2718        self.drop_previous_version()
2719    }
2720
2721    fn drop_previous_version(
2722        &self,
2723    ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2724        let Some(replica_path) = self.previous_version_replica_path() else {
2725            return Ok(crate::previous_version::PreviousVersionDiscardOutcome {
2726                present: false,
2727                discarded: false,
2728            });
2729        };
2730        crate::previous_version::discard_previous_version(&self.conn, &replica_path)
2731    }
2732
2733    /// RFC 0005 D7: `leaseState.errorCode` or an expired lease.
2734    fn previous_version_lease_inactive(&self, now_ms: i64) -> bool {
2735        let Some(lease) = &self.lease_state else {
2736            return false;
2737        };
2738        if lease.error_code.is_some() {
2739            return true;
2740        }
2741        lease.expires_at_ms.is_some_and(|expires| expires <= now_ms)
2742    }
2743
2744    /// RFC 0005 D7: §7.4.5 replacement coverage — no active unit is
2745    /// bootstrapping. An empty active set is not completion (mirrors the TS
2746    /// predicate exactly).
2747    fn previous_version_coverage_complete(&self) -> Result<bool, String> {
2748        let units = self.stored(load_units(&self.conn))?;
2749        let mut active = units
2750            .iter()
2751            .filter(|unit| unit.status == UnitStatus::Active)
2752            .peekable();
2753        Ok(active.peek().is_some() && !active.any(UnitRecord::bootstrapping))
2754    }
2755
2756    /// RFC 0005 D7: lifetime triggers evaluated once per sync round, after the
2757    /// apply. A container that no longer has a reason to exist is discarded so
2758    /// the rows do not outlive the window they were kept for.
2759    fn previous_version_lifetime_check(&self) {
2760        let Some(config) = self.previous_version.filter(|config| config.enabled) else {
2761            return;
2762        };
2763        let now_ms = self.clock_now_ms();
2764        if self.previous_version_lease_inactive(now_ms) {
2765            let _ = self.drop_previous_version();
2766            return;
2767        }
2768        let Some(replica_path) = self.previous_version_replica_path() else {
2769            return;
2770        };
2771        let Ok(Some(record)) = crate::previous_version::read_previous_version_record(&replica_path)
2772        else {
2773            return;
2774        };
2775        let Ok(units) = load_units(&self.conn) else {
2776            return;
2777        };
2778        if units.iter().any(|unit| unit.status == UnitStatus::Revoked) {
2779            let _ = self.drop_previous_version();
2780            return;
2781        }
2782        if now_ms - record.created_at_ms > config.max_age_ms {
2783            let _ = self.drop_previous_version();
2784            return;
2785        }
2786        if self.previous_version_coverage_complete() == Ok(true) {
2787            let _ = self.drop_previous_version();
2788        }
2789    }
2790
2791    pub fn diagnostics_snapshot(&self) -> Result<ClientDiagnosticsSnapshot, String> {
2792        let registered = self.stored(load_units(&self.conn))?;
2793        // Both meta values in one statement: the FFI host recomputes
2794        // diagnostics after every command.
2795        let (local_revision, replica_cursor): (Option<String>, Option<String>) = self.stored(
2796            self.conn
2797                .prepare_cached(
2798                    "SELECT (SELECT value FROM _syncular_meta WHERE key = ?1),
2799                            (SELECT value FROM _syncular_meta WHERE key = ?2)",
2800                )
2801                .and_then(|mut statement| {
2802                    statement.query_row([LOCAL_REVISION_KEY, REPLICA_CURSOR_KEY], |row| {
2803                        Ok((row.get(0)?, row.get(1)?))
2804                    })
2805                }),
2806        )?;
2807        let mut units = DiagnosticUnits::default();
2808        for unit in &registered {
2809            *match unit.status {
2810                UnitStatus::Revoked => &mut units.revoked,
2811                UnitStatus::Failed => &mut units.failed,
2812                UnitStatus::Active if !unit.bootstrapping() => &mut units.complete,
2813                UnitStatus::Active
2814                    if unit.reason_code.as_deref() == Some("sync.cursor_expired") =>
2815                {
2816                    &mut units.reset
2817                }
2818                UnitStatus::Active => &mut units.bootstrapping,
2819            } += 1;
2820        }
2821        units.reason_codes = registered
2822            .iter()
2823            .filter_map(|unit| unit.reason_code.as_deref().map(Self::diagnostic_code))
2824            .collect::<BTreeSet<_>>()
2825            .into_iter()
2826            .collect();
2827        let captured_at_ms = self.clock_now_ms();
2828        let lease = if let Some(error_code) = self
2829            .lease_state
2830            .as_ref()
2831            .and_then(|state| state.error_code.clone())
2832        {
2833            ClientDiagnosticsLease {
2834                state: "stopped".to_owned(),
2835                expires_at_ms: self
2836                    .lease_state
2837                    .as_ref()
2838                    .and_then(|state| state.expires_at_ms),
2839                error_code: Some(Self::diagnostic_code(&error_code)),
2840            }
2841        } else if let Some(expires_at_ms) = self
2842            .lease_state
2843            .as_ref()
2844            .and_then(|state| state.expires_at_ms)
2845        {
2846            ClientDiagnosticsLease {
2847                state: if expires_at_ms <= captured_at_ms {
2848                    "expired".to_owned()
2849                } else {
2850                    "active".to_owned()
2851                },
2852                expires_at_ms: Some(expires_at_ms),
2853                error_code: None,
2854            }
2855        } else {
2856            ClientDiagnosticsLease {
2857                state: "none".to_owned(),
2858                expires_at_ms: None,
2859                error_code: None,
2860            }
2861        };
2862        let connectivity = match self.last_round.as_ref() {
2863            _ if !self.transport_enabled && self.active_round.is_none() => "offline",
2864            Some(round) if round.status == "succeeded" => "online",
2865            Some(round)
2866                if round.status == "failed"
2867                    && matches!(
2868                        round.cause_kind,
2869                        Some(
2870                            crate::TransportCauseKind::Network | crate::TransportCauseKind::Connect
2871                        )
2872                    ) =>
2873            {
2874                "offline"
2875            }
2876            Some(round) if round.status == "failed" && round.http_status.is_some() => "online",
2877            _ => "unknown",
2878        };
2879        Ok(ClientDiagnosticsSnapshot {
2880            version: CLIENT_DIAGNOSTICS_VERSION,
2881            captured_at_ms,
2882            host: ClientDiagnosticsHost {
2883                kind: "direct".to_owned(),
2884                role: "single".to_owned(),
2885                connectivity: connectivity.to_owned(),
2886                realtime: self.realtime_state,
2887                realtime_policy: self.realtime_policy,
2888                realtime_reason_code: self.realtime_reason_code.clone(),
2889                realtime_retry_delay_ms: self.realtime_retry_delay_ms,
2890            },
2891            security_lifecycle: self.security_lifecycle().to_owned(),
2892            schema: ClientDiagnosticsSchema {
2893                current_version: self.schema.version,
2894                upgrading: self.upgrading,
2895                required_version: self
2896                    .schema_floor
2897                    .as_ref()
2898                    .and_then(|floor| floor.required_schema_version),
2899                latest_version: self
2900                    .schema_floor
2901                    .as_ref()
2902                    .and_then(|floor| floor.latest_schema_version),
2903            },
2904            replica: ClientDiagnosticsReplica {
2905                local_revision: local_revision
2906                    .and_then(|value| value.parse::<u64>().ok())
2907                    .unwrap_or(0)
2908                    .to_string(),
2909                sync_needed: self.sync_needed,
2910                pending_outbox: self.outbox.len(),
2911            },
2912            lease,
2913            active_units: registered
2914                .iter()
2915                .filter(|unit| unit.status == UnitStatus::Active)
2916                .count(),
2917            units,
2918            replica_cursor: replica_cursor.map_or(Ok(-1), |raw| {
2919                raw.parse()
2920                    .map_err(|_| "sync.local_corrupt: persisted unit state is invalid".to_owned())
2921            })?,
2922            last_round: self.last_round.clone(),
2923            last_change: self.last_change.clone(),
2924            storage: self.diagnostics_storage(),
2925            query_failures: self.query_failures.clone(),
2926        })
2927    }
2928
2929    fn diagnostics_storage(&self) -> ClientDiagnosticsStorage {
2930        let read = || -> Result<ClientDiagnosticsStorage, rusqlite::Error> {
2931            let page_count: i64 = self
2932                .conn
2933                .query_row("PRAGMA page_count", [], |row| row.get(0))?;
2934            let page_size: i64 = self
2935                .conn
2936                .query_row("PRAGMA page_size", [], |row| row.get(0))?;
2937            // One cached aggregate, since the FFI host recomputes diagnostics
2938            // after every command; every invocation still reads current storage.
2939            let (outbox_bytes, outcome_entries, outcome_bytes): (i64, i64, i64) = self
2940                .conn
2941                .prepare_cached(
2942                    "SELECT (SELECT COALESCE(SUM(LENGTH(ops_json)), 0) FROM _syncular_outbox),
2943                            COUNT(*), COALESCE(SUM(LENGTH(results_json) + COALESCE(LENGTH(operations_json), 0)), 0)
2944                       FROM _syncular_commit_outcomes",
2945                )?
2946                .query_row([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?;
2947            let blob_bytes = if self.schema_has_blobs() {
2948                self.conn
2949                    .prepare_cached("SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs")?
2950                    .query_row([], |row| row.get(0))?
2951            } else {
2952                0
2953            };
2954            let pressure = self
2955                .limits
2956                .blob_cache_max_bytes
2957                .is_some_and(|limit| blob_bytes > limit);
2958            Ok(ClientDiagnosticsStorage {
2959                status: if pressure { "pressure" } else { "healthy" }.to_owned(),
2960                database_bytes_approx: Some(page_count.saturating_mul(page_size).max(0)),
2961                pending_outbox_bytes_approx: Some(outbox_bytes.max(0)),
2962                retained_outcome_bytes_approx: Some(outcome_bytes.max(0)),
2963                retained_outcome_entries: Some(outcome_entries.max(0)),
2964                blob_cache_bytes_approx: Some(blob_bytes.max(0)),
2965                pressure_reason_code: pressure.then(|| "client.blob_cache_over_limit".to_owned()),
2966            })
2967        };
2968        read().unwrap_or_else(|_| ClientDiagnosticsStorage {
2969            status: "unreadable".to_owned(),
2970            database_bytes_approx: None,
2971            pending_outbox_bytes_approx: None,
2972            retained_outcome_bytes_approx: None,
2973            retained_outcome_entries: None,
2974            blob_cache_bytes_approx: None,
2975            pressure_reason_code: None,
2976        })
2977    }
2978
2979    pub fn drain_change_batches(&mut self) -> Vec<ClientChangeBatch> {
2980        self.change_queue.drain(..).collect()
2981    }
2982
2983    pub fn drain_sync_intents(&mut self) -> Vec<SyncIntent> {
2984        let intents = self.sync_intent_queue.drain(..).collect();
2985        if self.transport_enabled {
2986            intents
2987        } else {
2988            vec![SyncIntent::None]
2989        }
2990    }
2991
2992    fn schedule_background_retry(&mut self) -> u64 {
2993        let delay_ms = self.retry_delay_ms;
2994        self.sync_intent_queue
2995            .push_back(SyncIntent::Background { delay_ms });
2996        self.retry_delay_ms = (self.retry_delay_ms * 2).min(30_000);
2997        self.round_retry_delay_ms = Some(delay_ms);
2998        delay_ms
2999    }
3000
3001    fn reset_background_retry(&mut self) {
3002        self.retry_delay_ms = 250;
3003    }
3004
3005    fn retryable_transport_code(code: &str) -> bool {
3006        code == "transport.failed"
3007            || code == "transport.timeout"
3008            || code == "transport.unavailable"
3009            || code == "sync.transport_failed"
3010    }
3011
3012    /// §1.8: the transport reported a refused or unreachable endpoint. The
3013    /// native transport says `connect` (DNS failure, connection refused,
3014    /// reset, or aborted); a browser fetch transport says `network`. Repeating
3015    /// the request on a backoff repairs neither, so no retry is scheduled.
3016    fn unreachable_transport(details: &Option<serde_json::Value>) -> bool {
3017        matches!(
3018            details
3019                .as_ref()
3020                .and_then(|details| details.get("causeKind"))
3021                .and_then(serde_json::Value::as_str),
3022            Some("connect" | "network")
3023        )
3024    }
3025
3026    /// §1.5: a segment fetch that fails inside an otherwise complete round is
3027    /// invisible to the server (the round response arrived whole), so its code
3028    /// rides the following requests like a socket-round failure. A code the
3029    /// frame grammar rejects is not reportable and the previous code stays.
3030    fn segment_fetch_failed(&mut self, error: TransportError) -> SectionError {
3031        if ssp2::model::valid_round_failure_code(&error.code) {
3032            self.round_failure = Some(error.code.clone());
3033        }
3034        SectionError::Transport(error)
3035    }
3036
3037    /// A failed round worth a background retry: a transport failure, or a
3038    /// §10.2 code the catalog marks retryable (clients may hardcode the
3039    /// catalog metadata, §10.1). Matches the TypeScript core, which retries
3040    /// on the server's `retryable` flag.
3041    fn retryable_failure_code(code: &str) -> bool {
3042        Self::retryable_transport_code(code)
3043            || matches!(
3044                code,
3045                "sync.auth_required"
3046                    | "sync.auth_lease_required"
3047                    | "sync.auth_lease_revoked"
3048                    | "sync.internal_error"
3049                    | "sync.idempotency_cache_miss"
3050                    | "sync.schema_not_ready"
3051                    | "sync.segment_expired"
3052                    | "sync.rate_limited"
3053                    | "sync.websocket_connection_limit"
3054            )
3055    }
3056
3057    fn diagnostic_code(code: &str) -> String {
3058        let valid = !code.is_empty()
3059            && code.len() <= 96
3060            && code.contains('.')
3061            && code
3062                .bytes()
3063                .next()
3064                .is_some_and(|byte| byte.is_ascii_lowercase())
3065            && code.bytes().all(|byte| {
3066                byte.is_ascii_lowercase()
3067                    || byte.is_ascii_digit()
3068                    || matches!(byte, b'.' | b'_' | b'-')
3069            });
3070        if valid {
3071            code.to_owned()
3072        } else {
3073            "client.unknown_failure".to_owned()
3074        }
3075    }
3076
3077    fn set_sync_needed(&mut self, value: bool, interactive: bool) {
3078        if self.sync_needed != value {
3079            if self.begin_observation("syncular_status").is_ok() {
3080                self.sync_needed = value;
3081                let batch = ChangeAccumulator {
3082                    status: true,
3083                    ..ChangeAccumulator::default()
3084                };
3085                if self.finish_observation("syncular_status", batch).is_err() {
3086                    self.rollback_observation("syncular_status");
3087                }
3088            } else {
3089                self.sync_needed = value;
3090            }
3091        }
3092        if value && interactive {
3093            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3094        }
3095    }
3096
3097    /// A unit-store result: a row that does not parse is `sync.local_corrupt`;
3098    /// every other SQLite error keeps its storage classification.
3099    fn stored<T>(&self, result: rusqlite::Result<T>) -> Result<T, String> {
3100        result.map_err(|error| match error {
3101            rusqlite::Error::FromSqlConversionFailure(..) => {
3102                "sync.local_corrupt: persisted unit state is invalid".to_owned()
3103            }
3104            error => Self::sqlite_failure(&self.storage_failure, error),
3105        })
3106    }
3107
3108    fn sqlite_failure(
3109        storage_failure: &RefCell<Option<QueryReadFailure>>,
3110        error: rusqlite::Error,
3111    ) -> String {
3112        let message = error.to_string();
3113        let failure = QueryReadFailure::from(error);
3114        let code = failure.code;
3115        if code.is_some() && storage_failure.borrow().is_none() {
3116            *storage_failure.borrow_mut() = Some(failure);
3117        }
3118        match code {
3119            Some(code) => format!("{code}: {message}"),
3120            None => message,
3121        }
3122    }
3123
3124    fn begin_observation(&self, name: &str) -> Result<(), String> {
3125        if let Some(failure) = &self.coalesced_failure {
3126            return Err(failure.clone());
3127        }
3128        // SQLite rolls a whole transaction back on some I/O and capacity
3129        // errors; later frames must not commit on their own after that.
3130        if self.coalesced.is_some() && self.conn.is_autocommit() {
3131            return Err("the coalesced apply transaction was rolled back".to_owned());
3132        }
3133        self.conn
3134            .execute_batch(&format!("SAVEPOINT {name}"))
3135            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3136    }
3137
3138    /// SPEC §1.4 rule 4: open a coalesced apply transaction unless a caller
3139    /// already owns one.
3140    fn begin_coalesced_apply(&mut self) -> Result<(), String> {
3141        if self.coalesced.is_some() || !self.conn.is_autocommit() {
3142            return Ok(());
3143        }
3144        self.conn
3145            .execute_batch("BEGIN")
3146            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3147        self.coalesced = Some(CoalescedApply {
3148            rows: 0,
3149            rollback: self.capture(),
3150        });
3151        Ok(())
3152    }
3153
3154    fn capture(&self) -> Rollback {
3155        Rollback {
3156            outbox: self.outbox.clone(),
3157            failed_commits: self.failed_commits.clone(),
3158            conflicts: self.conflicts.clone(),
3159            rejections: self.rejections.clone(),
3160            schema_floor: self.schema_floor.clone(),
3161            lease_state: self.lease_state.clone(),
3162            stopped: self.stopped,
3163            upgrading: self.upgrading,
3164            sync_needed: self.sync_needed,
3165            active_round: self.active_round,
3166            overlay_dirty: self.overlay_dirty.snapshot(),
3167            change_queue: self.change_queue.len(),
3168            sync_intent_queue: self.sync_intent_queue.len(),
3169            last_change: self.last_change.clone(),
3170        }
3171    }
3172
3173    fn restore(&mut self, rollback: Rollback) {
3174        self.outbox = rollback.outbox;
3175        self.failed_commits = rollback.failed_commits;
3176        self.conflicts = rollback.conflicts;
3177        self.rejections = rollback.rejections;
3178        self.schema_floor = rollback.schema_floor;
3179        self.lease_state = rollback.lease_state;
3180        self.stopped = rollback.stopped;
3181        self.upgrading = rollback.upgrading;
3182        self.sync_needed = rollback.sync_needed;
3183        self.active_round = rollback.active_round;
3184        self.overlay_dirty.restore(rollback.overlay_dirty);
3185        self.change_queue.truncate(rollback.change_queue);
3186        self.sync_intent_queue.truncate(rollback.sync_intent_queue);
3187        self.last_change = rollback.last_change;
3188    }
3189
3190    /// Account the rows of the next frame or block. A unit that would take the
3191    /// coalesced transaction past the bound commits the earlier units first.
3192    fn coalesce_unit(&mut self, rows: usize) -> Result<(), String> {
3193        let Some(open) = &self.coalesced else {
3194            return Ok(());
3195        };
3196        if open.rows > 0 && open.rows + rows > COALESCED_APPLY_ROWS {
3197            self.commit_coalesced_apply()?;
3198            self.begin_coalesced_apply()?;
3199        }
3200        if let Some(open) = &mut self.coalesced {
3201            open.rows += rows;
3202        }
3203        Ok(())
3204    }
3205
3206    /// COMMIT the coalesced transaction. A failed COMMIT rolls every coalesced
3207    /// frame back, restores the in-memory state of its `BEGIN`, drops the
3208    /// change batches and sync intents queued since, and fails the rest of the
3209    /// response.
3210    fn commit_coalesced_apply(&mut self) -> Result<(), String> {
3211        let Some(open) = self.coalesced.take() else {
3212            return Ok(());
3213        };
3214        let committed = if self.conn.is_autocommit() {
3215            Err("the coalesced apply transaction was rolled back".to_owned())
3216        } else {
3217            self.conn
3218                .execute_batch("COMMIT")
3219                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3220        };
3221        let Err(error) = committed else {
3222            return Ok(());
3223        };
3224        if !self.conn.is_autocommit() {
3225            if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3226                let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3227            }
3228        }
3229        self.restore(open.rollback);
3230        self.coalesced_failure = Some(error.clone());
3231        Err(error)
3232    }
3233
3234    /// End the response's coalescing: COMMIT what is open and clear a failure.
3235    fn finish_coalesced_apply(&mut self) -> Result<(), String> {
3236        let committed = self.commit_coalesced_apply();
3237        match self.coalesced_failure.take() {
3238            Some(failure) => Err(failure),
3239            None => committed,
3240        }
3241    }
3242
3243    fn rollback_observation(&self, name: &str) {
3244        if let Err(error) = self
3245            .conn
3246            .execute_batch(&format!("ROLLBACK TO {name}; RELEASE {name}"))
3247        {
3248            if let Some(failure) = self.storage_failure.borrow_mut().as_mut() {
3249                if failure.rollback_failure.is_none() {
3250                    failure.rollback_failure = Some(Box::new(QueryReadFailure::from(error)));
3251                }
3252            }
3253        }
3254    }
3255
3256    fn finish_observation(
3257        &mut self,
3258        name: &str,
3259        mut batch: ChangeAccumulator,
3260    ) -> Result<(), String> {
3261        #[cfg(feature = "bench-internals")]
3262        let _phase = self.benchmark_phases.start(Phase::ObservationCommit);
3263        if self.failed_commits.iter().any(|(commit, _)| {
3264            commit
3265                .ops
3266                .iter()
3267                .any(|operation| batch.tables.contains_key(&operation.table))
3268        }) {
3269            batch.outcomes = true;
3270        }
3271        if !batch.touched() {
3272            self.conn
3273                .execute_batch(&format!("RELEASE {name}"))
3274                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3275            return Ok(());
3276        }
3277        let revision = self
3278            .local_revision()?
3279            .checked_add(1)
3280            .ok_or_else(|| "local revision exhausted u64".to_owned())?;
3281        self.conn
3282            .execute(
3283                "INSERT OR REPLACE INTO _syncular_meta(key, value) VALUES (?1, ?2)",
3284                rusqlite::params![LOCAL_REVISION_KEY, revision.to_string()],
3285            )
3286            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3287        let status = batch.status.then(|| self.status_snapshot());
3288        let event = ClientChangeBatch {
3289            revision: revision.to_string(),
3290            tables: batch
3291                .tables
3292                .into_iter()
3293                .map(|(table, scope_keys)| TableChange {
3294                    table,
3295                    scope_keys: scope_keys.map(|keys| keys.into_iter().collect()),
3296                })
3297                .collect(),
3298            windows: batch
3299                .windows
3300                .into_iter()
3301                .map(|(base_key, units)| WindowChange {
3302                    base_key,
3303                    units: units.into_iter().collect(),
3304                })
3305                .collect(),
3306            status,
3307            conflicts_changed: batch.conflicts,
3308            rejections_changed: batch.rejections,
3309            outcomes_changed: batch.outcomes,
3310            applied_commits: Vec::new(),
3311        };
3312        self.conn
3313            .execute_batch(&format!("RELEASE {name}"))
3314            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3315        let mut diagnostic_tables = event
3316            .tables
3317            .iter()
3318            .map(|entry| entry.table.clone())
3319            .collect::<BTreeSet<_>>()
3320            .into_iter()
3321            .collect::<Vec<_>>();
3322        // §7.6: the selected variables of the changed window bases.
3323        let mut diagnostic_windows = event
3324            .windows
3325            .iter()
3326            .map(|entry| {
3327                entry
3328                    .base_key
3329                    .split('\0')
3330                    .next()
3331                    .unwrap_or_default()
3332                    .to_owned()
3333            })
3334            .collect::<BTreeSet<_>>()
3335            .into_iter()
3336            .collect::<Vec<_>>();
3337        let domains_truncated = diagnostic_tables.len() > MAX_DIAGNOSTIC_DOMAINS
3338            || diagnostic_windows.len() > MAX_DIAGNOSTIC_DOMAINS;
3339        diagnostic_tables.truncate(MAX_DIAGNOSTIC_DOMAINS);
3340        diagnostic_windows.truncate(MAX_DIAGNOSTIC_DOMAINS);
3341        self.last_change = Some(DiagnosticLastChange {
3342            revision: event.revision.clone(),
3343            recorded_at_ms: self.clock_now_ms(),
3344            tables: diagnostic_tables,
3345            windows: diagnostic_windows,
3346            domains_truncated,
3347            status_changed: event.status.is_some(),
3348            conflicts_changed: event.conflicts_changed,
3349            rejections_changed: event.rejections_changed,
3350            outcomes_changed: event.outcomes_changed,
3351        });
3352        self.change_queue.push_back(event);
3353        Ok(())
3354    }
3355
3356    fn record_scope_map(
3357        &self,
3358        batch: &mut ChangeAccumulator,
3359        table_name: &str,
3360        scopes: &[(String, Vec<String>)],
3361    ) {
3362        let Some(table) = self.schema.table(table_name) else {
3363            return;
3364        };
3365        // A bulk scoped delete whose map leaves a declared variable unnamed
3366        // cannot list the deleted rows' keys for it: the change is table-wide.
3367        if table.scope_variables.iter().any(|scope| {
3368            !scopes
3369                .iter()
3370                .any(|(variable, _)| *variable == scope.variable)
3371        }) {
3372            batch.table(table_name);
3373            return;
3374        }
3375        for (variable, values) in scopes {
3376            let Some(scope) = table
3377                .scope_variables
3378                .iter()
3379                .find(|scope| &scope.variable == variable)
3380            else {
3381                continue;
3382            };
3383            for value in values {
3384                batch.scope(table_name, format!("{}:{value}", scope.prefix));
3385            }
3386        }
3387    }
3388
3389    /// Record a row's current scope keys from the base or visible table.
3390    fn record_row_scopes(
3391        &self,
3392        batch: &mut ChangeAccumulator,
3393        table_name: &str,
3394        row_id: &str,
3395        base: bool,
3396    ) -> bool {
3397        let Some(table) = self.schema.table(table_name) else {
3398            return false;
3399        };
3400        if table.scope_variables.is_empty() {
3401            return false;
3402        }
3403        let columns = table
3404            .scope_variables
3405            .iter()
3406            .map(|scope| quote_ident(&scope.column))
3407            .collect::<Vec<_>>()
3408            .join(", ");
3409        let full_table = if base {
3410            base_table(table_name)
3411        } else {
3412            visible_table(table_name)
3413        };
3414        let sql = format!(
3415            "SELECT {columns} FROM {full_table} WHERE {} LIMIT 1",
3416            row_id_predicate(table)
3417        );
3418        let Ok(mut stmt) = self.conn.prepare_cached(&sql) else {
3419            return false;
3420        };
3421        let values = stmt.query_row(rusqlite::params![row_id], |row| {
3422            let mut values = Vec::with_capacity(table.scope_variables.len());
3423            for index in 0..table.scope_variables.len() {
3424                values.push(row.get::<_, Option<String>>(index)?);
3425            }
3426            Ok(values)
3427        });
3428        let Ok(values) = values else {
3429            return false;
3430        };
3431        let mut recorded = false;
3432        for (scope, value) in table.scope_variables.iter().zip(values) {
3433            if let Some(value) = value {
3434                batch.scope(table_name, format!("{}:{value}", scope.prefix));
3435                recorded = true;
3436            }
3437        }
3438        recorded
3439    }
3440
3441    fn record_commit_changes(
3442        &self,
3443        batch: &mut ChangeAccumulator,
3444        tables: &[String],
3445        changes: &[ssp2::model::Change],
3446    ) {
3447        #[cfg(feature = "bench-internals")]
3448        let _phase = self.benchmark_phases.start(Phase::ObservationPrepare);
3449        for change in changes {
3450            let Some(table_name) = tables.get(change.table_index as usize) else {
3451                continue;
3452            };
3453            let mut precise = self.record_row_scopes(batch, table_name, &change.row_id, true);
3454            if let Some(table) = self.schema.table(table_name) {
3455                for (variable, value) in &change.scopes {
3456                    if let Some(scope) = table
3457                        .scope_variables
3458                        .iter()
3459                        .find(|scope| &scope.variable == variable)
3460                    {
3461                        batch.scope(table_name, format!("{}:{value}", scope.prefix));
3462                        precise = true;
3463                    }
3464                }
3465            }
3466            if !precise {
3467                batch.table(table_name);
3468            }
3469        }
3470    }
3471
3472    /// Whether a base or visible row matches the scope predicate; `false`
3473    /// without a local scope-column mapping. A SQLite failure is an error.
3474    fn scoped_rows_exist(
3475        &self,
3476        table_name: &str,
3477        effective: &[(String, Vec<String>)],
3478        owners: &[Vec<(String, Vec<String>)>],
3479    ) -> Result<bool, String> {
3480        let Some(table) = self.schema.table(table_name) else {
3481            return Ok(false);
3482        };
3483        let Ok(Some((predicate, params))) = local_scope_predicate(table, effective, owners) else {
3484            return Ok(false);
3485        };
3486        for source in [base_table(table_name), visible_table(table_name)] {
3487            if self
3488                .conn
3489                .query_row(
3490                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
3491                    rusqlite::params_from_iter(&params),
3492                    |row| row.get::<_, bool>(0),
3493                )
3494                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
3495            {
3496                return Ok(true);
3497            }
3498        }
3499        Ok(false)
3500    }
3501
3502    /// §5.6 first-page clear of `unit_id`'s pair: delete its rows except
3503    /// those another owner covers (§3.3), failing closed without a local
3504    /// scope-column mapping. Owners are read only when a row matches, inside
3505    /// the caller's transaction. Returns whether rows matched.
3506    fn clear_scope(
3507        &mut self,
3508        table: &TableSchema,
3509        effective: &[(String, Vec<String>)],
3510        unit_id: &str,
3511    ) -> Result<bool, SectionError> {
3512        let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
3513        let matched = self
3514            .scoped_rows_exist(&table.name, effective, &[])
3515            .map_err(storage)?;
3516        let owners = if matched {
3517            unit_owners(
3518                &self.stored(load_units(&self.conn)).map_err(storage)?,
3519                table,
3520                unit_id,
3521            )
3522        } else {
3523            Vec::new()
3524        };
3525        let changed = matched
3526            && (owners.is_empty()
3527                || self
3528                    .scoped_rows_exist(&table.name, effective, &owners)
3529                    .map_err(storage)?);
3530        if !self
3531            .purge_scope_rows(&table.name, effective, &owners)
3532            .map_err(storage)?
3533        {
3534            return Err(SectionError::FailClosed);
3535        }
3536        Ok(changed)
3537    }
3538
3539    /// §7.4.5: true while a schema-bump reset + first re-bootstrap runs.
3540    pub fn upgrading(&self) -> bool {
3541        self.upgrading
3542    }
3543
3544    /// §7.4.2 "app ships new code": swap to a NEW generated schema while
3545    /// keeping this client's local database (identity, outbox, tables). The
3546    /// §7.4.1 marker check then fires the wipe/re-bootstrap flow when the
3547    /// version increases. Recreation runs the same marker guard as opening
3548    /// a durable replica, holds the guard and every write it authorizes under
3549    /// one write transaction, and preserves the current client (compiled
3550    /// schema, outbox, tables) on refusal.
3551    pub fn recreate_with_schema(&mut self, schema_json: &Value) -> Result<(), String> {
3552        let new_schema = parse_schema_json(schema_json)?;
3553        validate_authority_reads(&new_schema, &self.limits.authority_reads)?;
3554        self.conn
3555            .execute_batch("BEGIN IMMEDIATE")
3556            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3557        let prior_schema = std::mem::replace(&mut self.schema, new_schema);
3558        // §7.4.3/§7.4.4: a reset inside this transaction mutates in-memory
3559        // state (dropped outbox commits, rejections, upgrade and floor flags,
3560        // overlay dirtiness) and appends change/intent batches. A COMMIT that
3561        // fails after the reset succeeded rolls the database back, so every
3562        // one of those fields is captured here and restored with it.
3563        let rollback = self.capture();
3564        let guarded = (|| -> Result<(), String> {
3565            // §7.4.2: the marker is re-read under the write lock the caller
3566            // holds, so a replica another process upgraded meanwhile refuses
3567            // this recreation instead of having its marker and tables
3568            // downgraded.
3569            let marker = read_local_schema_version(&self.conn, self.schema.version)?;
3570            self.create_bookkeeping_tables()?;
3571            match marker {
3572                Some(version) if version < self.schema.version => self.run_schema_reset()?,
3573                None => {
3574                    self.create_synced_tables()?;
3575                    self.persist_schema_version()?;
3576                }
3577                _ => {}
3578            }
3579            // §7.4.2: recreation IS the boot for the in-memory core, so reload the
3580            // durable outbox the same-version path is about to replay. Only the
3581            // outbox is reloaded: the recovery below reads it, and the caller's
3582            // rollback snapshot already covers this field.
3583            self.outbox = self.load_outbox()?.into();
3584            // §7.1/§7.4.4: recover intrinsically codec-invalid persisted values at
3585            // this guarded boundary once the schema and marker agree. A bump went
3586            // through `run_schema_reset`, which performs the same recovery after
3587            // it creates the new physical tables and before its final replay.
3588            self.drop_unencodable_outbox(false, None)?;
3589            if marker == Some(self.schema.version)
3590                && (!self.outbox.is_empty()
3591                    || !self.failed_commits.is_empty()
3592                    || self.has_acknowledged_rows()?)
3593            {
3594                self.overlay_dirty.set(true);
3595                self.rebuild_overlay()?;
3596            }
3597            self.prune_unknown_units(false)?;
3598            self.save_unit_scope_schema()?;
3599            // The conformance recreate is the in-memory equivalent of reopening
3600            // a durable client. Apply the same startup catch-up contract even
3601            // when the schema itself did not change.
3602            self.enqueue_startup_sync_if_needed()?;
3603            Ok(())
3604        })();
3605        let outcome = match guarded {
3606            Ok(()) => self
3607                .conn
3608                .execute_batch("COMMIT")
3609                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error)),
3610            Err(error) => Err(error),
3611        };
3612        if let Err(error) = outcome {
3613            if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3614                // Keep a failed rollback's typed storage classification.
3615                let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3616            }
3617            self.schema = prior_schema;
3618            self.restore(rollback);
3619            // Prepared insert statements were derived from the reverted schema.
3620            self.insert_sql.borrow_mut().clear();
3621            return Err(error);
3622        }
3623        if !self.security_preflight {
3624            self.drain_pending_evictions()?;
3625        }
3626        Ok(())
3627    }
3628
3629    fn enqueue_startup_sync_if_needed(&mut self) -> Result<(), String> {
3630        let startup_work = !self.stopped
3631            && (!self.outbox.is_empty()
3632                || self.has_acknowledged_rows()?
3633                || !self.load_pending_evictions()?.is_empty()
3634                || self
3635                    .stored(load_units(&self.conn))?
3636                    .iter()
3637                    .any(|unit| unit.status == UnitStatus::Active));
3638        if startup_work {
3639            self.sync_needed = true;
3640            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3641        }
3642        Ok(())
3643    }
3644
3645    /// A native client persists schema-floor stops across process restarts.
3646    /// Once the running app already satisfies that floor, the persisted stop
3647    /// is only stale evidence from an older server round (for example, the
3648    /// server was restarted after catching up to an app that was ahead).
3649    /// Clear it and let the normal startup pull re-negotiate. If the server is
3650    /// still incompatible it will return the floor again in that first round.
3651    fn clear_satisfied_persisted_schema_floor(&mut self) -> Result<(), String> {
3652        let satisfied = self
3653            .schema_floor
3654            .as_ref()
3655            .and_then(|floor| floor.required_schema_version)
3656            .is_some_and(|required| self.schema.version >= required);
3657        if !satisfied {
3658            return Ok(());
3659        }
3660        self.delete_meta(SCHEMA_FLOOR_KEY)?;
3661        self.schema_floor = None;
3662        self.stopped = false;
3663        Ok(())
3664    }
3665
3666    /// RFC 0005 D1: discard an orphan or stale container at boot. The reset
3667    /// path already swept it; this covers a same-version or fresh-install open,
3668    /// which runs no reset and therefore no sweep — plus the D7 TTL, which only
3669    /// an aware binary can apply.
3670    fn reconcile_previous_version_at_boot(&self) -> Result<(), String> {
3671        let Some(replica_path) = self.previous_version_replica_path() else {
3672            return Ok(());
3673        };
3674        let max_age_ms = self
3675            .previous_version
3676            .filter(|config| config.enabled)
3677            .map(|config| config.max_age_ms);
3678        reconcile_previous_version_at_boot(
3679            &self.conn,
3680            &replica_path,
3681            self.schema.version,
3682            max_age_ms,
3683            self.clock_now_ms(),
3684        )
3685    }
3686
3687    /// RFC 0005 D3: the sibling container path, or `None` when the replica has
3688    /// no file — an in-memory replica returns an empty path, and a `file:` URI
3689    /// has no plain sibling path — so the feature resolves as off there.
3690    fn previous_version_replica_path(&self) -> Option<String> {
3691        let path = self.conn.path()?;
3692        if path.is_empty() || path.starts_with("file:") {
3693            return None;
3694        }
3695        Some(path.to_owned())
3696    }
3697
3698    /// §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
3699    /// and leaseState. Drops/recreates every synced table from the new
3700    /// schema, resets unit sync state (keeping registrations), clears
3701    /// the schema-floor stop state, rewrites the marker, drops outbox commits
3702    /// that cannot re-encode (§7.4.4), and replays the survivors on top.
3703    fn run_schema_reset(&mut self) -> Result<(), String> {
3704        self.begin_observation("syncular_schema_reset")?;
3705        let rollback = self.capture();
3706        let mut batch = ChangeAccumulator::default();
3707        let result = self
3708            .run_schema_reset_observed(&mut batch, true)
3709            .and_then(|()| self.finish_observation("syncular_schema_reset", batch));
3710        if let Err(error) = result {
3711            self.rollback_observation("syncular_schema_reset");
3712            self.restore(rollback);
3713            return Err(error);
3714        }
3715        Ok(())
3716    }
3717
3718    fn run_log_epoch_reset(&mut self, log_epoch: &str) -> Result<Vec<String>, String> {
3719        if self.get_meta(LOG_EPOCH_KEY)?.is_none() {
3720            self.begin_observation("syncular_epoch_acquisition")?;
3721            let rollback = self.capture();
3722            if let Err(error) = self.conn.execute(
3723                "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3724                rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3725            ) {
3726                self.rollback_observation("syncular_epoch_acquisition");
3727                return Err(Self::sqlite_failure(&self.storage_failure, error));
3728            }
3729            self.sync_needed = true;
3730            let batch = ChangeAccumulator {
3731                status: true,
3732                ..ChangeAccumulator::default()
3733            };
3734            if let Err(error) = self.finish_observation("syncular_epoch_acquisition", batch) {
3735                self.rollback_observation("syncular_epoch_acquisition");
3736                self.restore(rollback);
3737                return Err(error);
3738            }
3739            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3740            return Ok(Vec::new());
3741        }
3742        let resets = self
3743            .stored(load_units(&self.conn))?
3744            .into_iter()
3745            .map(|unit| unit.id)
3746            .collect();
3747        self.begin_observation("syncular_log_epoch_reset")?;
3748        let rollback = self.capture();
3749        let mut batch = ChangeAccumulator::default();
3750        let result = self
3751            .run_schema_reset_observed(&mut batch, false)
3752            .and_then(|()| {
3753                self.conn
3754                    .execute(
3755                        "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3756                        rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3757                    )
3758                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3759                self.sync_needed = true;
3760                batch.status = true;
3761                self.finish_observation("syncular_log_epoch_reset", batch)
3762            });
3763        if let Err(error) = result {
3764            self.rollback_observation("syncular_log_epoch_reset");
3765            self.restore(rollback);
3766            return Err(error);
3767        }
3768        self.sync_intent_queue.push_back(SyncIntent::Interactive);
3769        Ok(resets)
3770    }
3771
3772    fn run_schema_reset_observed(
3773        &mut self,
3774        batch: &mut ChangeAccumulator,
3775        capture: bool,
3776    ) -> Result<(), String> {
3777        // §7.4.2: the reset is the only path that wipes local tables for a
3778        // version bump, and it rewrites the marker last. Re-read the marker
3779        // under this reset's transaction: a replica another process upgraded
3780        // meanwhile refuses here instead of being reset to this client's
3781        // older schema.
3782        read_local_schema_version(&self.conn, self.schema.version)?;
3783        self.conn
3784            .execute_batch(
3785                "DELETE FROM _syncular_acked_rows; DELETE FROM _syncular_row_deliveries;",
3786            )
3787            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3788        self.cancel_sync_round();
3789        self.upgrading = true;
3790        batch.status = true;
3791        // RFC 0005 D6: classify the pending outbox against the NEW compiled
3792        // schema BEFORE the wipe, and record the advisory audit. This pass
3793        // drops nothing, so the audit sees the original pending intent; the
3794        // §7.4.4 send-time drop and the intrinsic value recovery later in this
3795        // reset are the paths that remove a commit. The classification is
3796        // shared with the send-time drop so the two cannot disagree about what
3797        // is incompatible.
3798        if self.previous_version.is_some_and(|config| config.enabled) {
3799            let previous_version = self
3800                .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
3801                .and_then(|value| value.parse::<i32>().ok())
3802                .unwrap_or(self.schema.version);
3803            let pending = self
3804                .outbox
3805                .iter()
3806                .map(|commit| PendingCommitAudit {
3807                    commit_id: &commit.client_commit_id,
3808                    operations: commit_audit_operations(commit),
3809                })
3810                .collect::<Vec<_>>();
3811            crate::previous_version::write_previous_version_audit(
3812                &self.conn,
3813                &crate::previous_version::build_previous_version_audit(
3814                    &self.schema,
3815                    &pending,
3816                    previous_version,
3817                    self.schema.version,
3818                    self.clock_now_ms(),
3819                ),
3820            )?;
3821        }
3822        // RFC 0005 D5: the container lives in its own FILE, so the reset can
3823        // never reach it. Sweep first (unconditional — also on the log-epoch
3824        // reset, which captures nothing), then capture BEFORE the wipe drops
3825        // any row. A refused capture records its reason and leaves no file.
3826        if let Some(replica_path) = self.previous_version_replica_path() {
3827            sweep_previous_version_container(&self.conn, &replica_path)?;
3828            if capture {
3829                if let Some(config) = self.previous_version.filter(|config| config.enabled) {
3830                    let previous_version = self
3831                        .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
3832                        .and_then(|value| value.parse::<i32>().ok())
3833                        .unwrap_or(self.schema.version);
3834                    capture_previous_version_from_replica(
3835                        &self.conn,
3836                        &replica_path,
3837                        previous_version,
3838                        self.schema.version,
3839                        &config,
3840                        self.clock_now_ms(),
3841                    )?;
3842                }
3843            }
3844        }
3845        for table in &self.schema.tables {
3846            batch.table(&table.name);
3847        }
3848        for (base_key, value) in self.load_window_registry()? {
3849            batch.window(&base_key, &value);
3850        }
3851        if capture {
3852            self.prune_unknown_units(true)?;
3853        }
3854        // The per-table insert SQL is derived from the OLD column lists.
3855        self.insert_sql.borrow_mut().clear();
3856        self.overlay_dirty.set(true);
3857        // Drop every synced table (base + visible) that currently exists —
3858        // discovered from sqlite_master so a bump that adds/removes tables is
3859        // handled. Bookkeeping tables (`_syncular_outbox/_units/_meta`
3860        // and the blob cache) are preserved; base tables are `_syncular_base_*`
3861        // so they are matched explicitly, not by the bookkeeping filter.
3862        // Drop virtual tables first so SQLite removes every FTS shadow table
3863        // atomically instead of the generic discovery tearing it apart.
3864        let virtual_tables: Vec<String> = {
3865            let mut stmt = self
3866                .conn
3867                .prepare(
3868                    "SELECT name FROM sqlite_master WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%'",
3869                )
3870                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3871            let rows = stmt
3872                .query_map([], |row| row.get::<_, String>(0))
3873                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3874            rows.filter_map(Result::ok)
3875                .filter(|name| is_synced_table_name(name))
3876                .collect()
3877        };
3878        for name in virtual_tables {
3879            self.conn
3880                .execute_batch(&format!(
3881                    "DROP TABLE IF EXISTS {}",
3882                    quote_ident(&format!("_syncular_fts_{name}"))
3883                ))
3884                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3885            self.conn
3886                .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
3887                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3888        }
3889        let existing: Vec<String> = {
3890            let mut stmt = self
3891                .conn
3892                .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
3893                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3894            let rows = stmt
3895                .query_map([], |row| row.get::<_, String>(0))
3896                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3897            rows.filter_map(Result::ok)
3898                .filter(|name| is_synced_table_name(name))
3899                .collect()
3900        };
3901        for name in &existing {
3902            if let Some(table) = name.strip_prefix("_syncular_base_") {
3903                batch.table(table);
3904            } else if !name.starts_with("_syncular_") {
3905                batch.table(name);
3906            }
3907        }
3908        for name in existing {
3909            self.conn
3910                .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
3911                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3912        }
3913        // Recreate the synced tables from the NEW schema.
3914        self.create_synced_tables()?;
3915        // Reset every unit's sync state, keeping the registration.
3916        reset_units(&self.conn)
3917            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3918        // The stop state is over: this client now ships a servable schema.
3919        self.stopped = false;
3920        self.schema_floor = None;
3921        self.delete_meta(SCHEMA_FLOOR_KEY)?;
3922        // Rewrite the marker LAST so a crash mid-reset re-runs the reset.
3923        self.persist_schema_version()?;
3924        self.save_unit_scope_schema()?;
3925        // §7.1/§7.4.4: the previous-version capture and audit above saw the
3926        // original pending intent; the synced tables now carry the new schema, so
3927        // recover intrinsically codec-invalid persisted values here, before the
3928        // final replay. A pending upsert that names a column the new schema
3929        // removed stays pending for the send-time `drop_incompatible_outbox`
3930        // prepass. The reset wrapper snapshots and restores the outbox,
3931        // rejections, and change queues, so a failed commit rolls this recovery
3932        // back with the rest of the reset.
3933        // §7.4.4: the enclosing reset observation owns the publication, so the
3934        // recovery contributes its rejection, outcome, and table domains to it.
3935        self.drop_unencodable_outbox(false, Some(batch))?;
3936        // Re-apply the surviving outbox optimistically over the empty tables.
3937        self.rebuild_overlay()?;
3938        Ok(())
3939    }
3940
3941    /// §7.4.4 send-time prepass: a persisted upsert whose values reference a
3942    /// column the current schema lacks (or a removed table) cannot be encoded
3943    /// (`commit_audit_operations` inspects upserts, so a value-free delete stays
3944    /// encodable and is validated by the server), nor can an insert-intent
3945    /// upsert that lacks a non-nullable column (§7.1, the audit's
3946    /// `missing-required-column`). Drop the commit, undo
3947    /// its optimistic projection, and raise a client-local
3948    /// `sync.outbox_incompatible` rejection.
3949    fn drop_incompatible_outbox(&mut self) -> Result<bool, String> {
3950        let incompatible = self
3951            .outbox
3952            .iter()
3953            .filter(|commit| {
3954                first_incompatibility(&self.schema, &commit_audit_operations(commit)).is_some()
3955            })
3956            .cloned()
3957            .collect::<Vec<_>>();
3958        if incompatible.is_empty() {
3959            return Ok(false);
3960        }
3961        self.drop_outbox_commits(
3962            &incompatible,
3963            OUTBOX_INCOMPATIBLE_CODE,
3964            "the persisted commit cannot encode under the current schema",
3965        )?;
3966        Ok(true)
3967    }
3968
3969    /// §7.4.4 incompatible-commit path, also taken by a refused blob upload
3970    /// (§5.9.7) with the server's code: reject every operation of `commits`,
3971    /// remove them from the outbox, and undo their optimistic rows.
3972    fn drop_outbox_commits(
3973        &mut self,
3974        incompatible: &[Arc<OutboxCommit>],
3975        code: &str,
3976        message: &str,
3977    ) -> Result<(), String> {
3978        // §7.4.4: one observation covers the durable outcome writes, the outbox
3979        // removal, the in-memory drop, and the overlay rebuild, so a storage
3980        // fault leaves the replica and the client unchanged and publishes no
3981        // change; a successful drop publishes exactly one batch carrying the
3982        // rejections, outcomes, status, and the tables whose projection changed.
3983        let rollback = self.capture();
3984        let owns_transaction = self.conn.is_autocommit();
3985        self.begin_observation("syncular_outbox_drop")?;
3986        let mut batch = ChangeAccumulator::default();
3987        let dropped = (|| -> Result<(), String> {
3988            let mut rejections = Vec::new();
3989            for commit in incompatible {
3990                let results = commit
3991                    .ops
3992                    .iter()
3993                    .enumerate()
3994                    .map(|(op_index, operation)| {
3995                        let rejection = RejectionRecord {
3996                            client_commit_id: commit.client_commit_id.clone(),
3997                            op_index: op_index as i32,
3998                            code: code.to_owned(),
3999                            message: message.to_owned(),
4000                            retryable: false,
4001                            details: None,
4002                            operation: Some(CommitOperation::from(operation)),
4003                        };
4004                        rejections.push(rejection.clone());
4005                        CommitOperationOutcome::Error { rejection }
4006                    })
4007                    .collect::<Vec<_>>();
4008                self.persist_commit_outcome(
4009                    &commit.client_commit_id,
4010                    CommitOutcomeStatus::Rejected,
4011                    &results,
4012                    Some(&commit.ops),
4013                )?;
4014                self.delete_outbox_persisted(&commit.client_commit_id)?;
4015                // A removed table has no local projection to invalidate; every
4016                // surviving table the dropped commit touched does.
4017                for operation in &commit.ops {
4018                    if self.schema.table(&operation.table).is_some() {
4019                        batch.table(&operation.table);
4020                    }
4021                }
4022            }
4023            self.prune_commit_outcomes()?;
4024            let incompatible_ids = incompatible
4025                .iter()
4026                .map(|commit| commit.client_commit_id.as_str())
4027                .collect::<BTreeSet<_>>();
4028            self.outbox
4029                .retain(|commit| !incompatible_ids.contains(commit.client_commit_id.as_str()));
4030            self.rejections.extend(rejections);
4031            // The dropped commits' purely-optimistic rows are undone: the
4032            // visible projection is re-derived from the surviving base + outbox.
4033            self.overlay_dirty.set(true);
4034            self.rebuild_overlay()?;
4035            batch.status = true;
4036            batch.rejections = true;
4037            batch.outcomes = true;
4038            Ok(())
4039        })();
4040        let result = dropped.and_then(|()| self.finish_observation("syncular_outbox_drop", batch));
4041        if let Err(error) = result {
4042            // An outer RELEASE is the COMMIT. Roll back that transaction
4043            // directly: retrying RELEASE after ROLLBACK TO still needs the
4044            // reader's lock. A nested observation only rolls back its savepoint.
4045            if owns_transaction {
4046                if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
4047                    let mut failure = self.storage_failure.borrow_mut();
4048                    let failure =
4049                        failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
4050                    failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
4051                }
4052            } else {
4053                self.rollback_observation("syncular_outbox_drop");
4054            }
4055            self.restore(rollback);
4056            return Err(error);
4057        }
4058        Ok(())
4059    }
4060
4061    /// §7.4.3: (re)create the base + visible table pair for every synced
4062    /// table in the CURRENT schema (idempotent — `IF NOT EXISTS`).
4063    fn create_synced_tables(&self) -> Result<(), String> {
4064        for table in &self.schema.tables {
4065            // The base half + the visible half form the synced-table pair. An
4066            // index name is global in SQLite, so the base half's indexes are
4067            // name-prefixed (`_syncular_base_<index>`) to stay distinct.
4068            for (full, index_prefix) in [
4069                (base_table(&table.name), "_syncular_base_"),
4070                (visible_table(&table.name), ""),
4071            ] {
4072                let mut cols: Vec<String> =
4073                    table.columns.iter().map(|c| quote_ident(&c.name)).collect();
4074                cols.push("\"_syncular_version\" INTEGER NOT NULL".to_owned());
4075                let sql = format!(
4076                    "CREATE TABLE IF NOT EXISTS {full} ({} , PRIMARY KEY ({}))",
4077                    cols.join(", "),
4078                    quote_ident(&table.primary_key)
4079                );
4080                self.conn
4081                    .execute(&sql, [])
4082                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4083                // Local secondary indexes (CREATE INDEX subset). Created on
4084                // both halves so mirror reads hit an index on either. Runs on
4085                // both the initial create and the §7.4.3 reset recreate path.
4086                for index in &table.indexes {
4087                    let unique = if index.unique { "UNIQUE " } else { "" };
4088                    let index_name = quote_ident(&format!("{index_prefix}{}", index.name));
4089                    let cols_sql = index
4090                        .columns
4091                        .iter()
4092                        .map(|c| quote_ident(c))
4093                        .collect::<Vec<_>>()
4094                        .join(", ");
4095                    let index_sql = format!(
4096                        "CREATE {unique}INDEX IF NOT EXISTS {index_name} ON {full} ({cols_sql})"
4097                    );
4098                    self.conn
4099                        .execute(&index_sql, [])
4100                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4101                }
4102            }
4103        }
4104        // FTS exists only on the visible half. It is a local search
4105        // projection, never a synced/base table or a wire-schema member.
4106        for table in &self.schema.tables {
4107            for index in &table.fts_indexes {
4108                self.create_fts_projection(table, index)?;
4109            }
4110        }
4111        Ok(())
4112    }
4113
4114    fn fts_projection_exists(&self, index: &FtsIndexSchema) -> Result<bool, String> {
4115        let count: i64 = self
4116            .conn
4117            .query_row(
4118                "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?1",
4119                rusqlite::params![index.name],
4120                |row| row.get(0),
4121            )
4122            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4123        Ok(count > 0)
4124    }
4125
4126    fn drop_fts_triggers(&self, index: &FtsIndexSchema) -> Result<(), String> {
4127        for suffix in ["ai", "ad", "au"] {
4128            self.conn
4129                .execute(
4130                    &format!(
4131                        "DROP TRIGGER IF EXISTS {}",
4132                        quote_ident(&format!("{}_{suffix}", index.name))
4133                    ),
4134                    [],
4135                )
4136                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4137        }
4138        Ok(())
4139    }
4140
4141    fn create_fts_triggers(
4142        &self,
4143        table: &TableSchema,
4144        index: &FtsIndexSchema,
4145    ) -> Result<(), String> {
4146        let fts = quote_ident(&index.name);
4147        let source = visible_table(&table.name);
4148        let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4149        let pk = quote_ident(&table.primary_key);
4150        let projection_columns = std::iter::once(source_id.clone())
4151            .chain(index.columns.iter().map(|column| quote_ident(column)))
4152            .collect::<Vec<_>>()
4153            .join(", ");
4154        let new_values = std::iter::once(format!("CAST(new.{pk} AS TEXT)"))
4155            .chain(
4156                index
4157                    .columns
4158                    .iter()
4159                    .map(|column| format!("new.{}", quote_ident(column))),
4160            )
4161            .collect::<Vec<_>>()
4162            .join(", ");
4163        let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4164        let delete_new = format!("DELETE FROM {fts} WHERE rowid = (SELECT id FROM {mapping} WHERE source_id = CAST(new.{pk} AS TEXT)); DELETE FROM {mapping} WHERE source_id = CAST(new.{pk} AS TEXT)");
4165        let delete_old = format!("DELETE FROM {fts} WHERE rowid = (SELECT id FROM {mapping} WHERE source_id = CAST(old.{pk} AS TEXT)); DELETE FROM {mapping} WHERE source_id = CAST(old.{pk} AS TEXT)");
4166        let insert_new = format!("INSERT INTO {mapping}(source_id) VALUES (CAST(new.{pk} AS TEXT)); INSERT INTO {fts} (rowid, {projection_columns}) VALUES ((SELECT id FROM {mapping} WHERE source_id = CAST(new.{pk} AS TEXT)), {new_values})");
4167        let bi = quote_ident(&format!("{}_bi", index.name));
4168        let ai = quote_ident(&format!("{}_ai", index.name));
4169        let ad = quote_ident(&format!("{}_ad", index.name));
4170        let au = quote_ident(&format!("{}_au", index.name));
4171        let replacement_exists = format!("EXISTS (SELECT 1 FROM {source} WHERE {pk} = new.{pk})");
4172        let sql = format!(
4173            "DROP TRIGGER IF EXISTS {bi};
4174             DROP TRIGGER IF EXISTS {ai};
4175             DROP TRIGGER IF EXISTS {ad};
4176             DROP TRIGGER IF EXISTS {au};
4177             CREATE TRIGGER {bi} BEFORE INSERT ON {source} WHEN {replacement_exists} BEGIN {delete_new}; END;
4178             CREATE TRIGGER {ai} AFTER INSERT ON {source} BEGIN {insert_new}; END;
4179             CREATE TRIGGER {ad} AFTER DELETE ON {source} BEGIN {delete_old}; END;
4180             CREATE TRIGGER {au} AFTER UPDATE ON {source} BEGIN {delete_old}; {delete_new}; {insert_new}; END;",
4181        );
4182        self.conn
4183            .execute_batch(&sql)
4184            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4185    }
4186
4187    fn rebuild_fts_projection(
4188        &self,
4189        table: &TableSchema,
4190        index: &FtsIndexSchema,
4191    ) -> Result<(), String> {
4192        let fts = quote_ident(&index.name);
4193        let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4194        let pk = quote_ident(&table.primary_key);
4195        let indexed_columns = index
4196            .columns
4197            .iter()
4198            .map(|column| quote_ident(column))
4199            .collect::<Vec<_>>();
4200        let projection_columns = std::iter::once(source_id.clone())
4201            .chain(indexed_columns.iter().cloned())
4202            .collect::<Vec<_>>()
4203            .join(", ");
4204        let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4205        let sql = format!(
4206            "DELETE FROM {fts}; DELETE FROM {mapping}; INSERT INTO {fts} ({projection_columns}) SELECT CAST({pk} AS TEXT), {columns} FROM {source}; INSERT INTO {mapping}(id, source_id) SELECT rowid, {source_id} FROM {fts};",
4207            columns = indexed_columns.join(", "),
4208            source = visible_table(&table.name),
4209        );
4210        self.conn
4211            .execute_batch(&sql)
4212            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4213    }
4214
4215    fn create_fts_projection(
4216        &self,
4217        table: &TableSchema,
4218        index: &FtsIndexSchema,
4219    ) -> Result<(), String> {
4220        self.begin_observation("syncular_fts_schema")?;
4221        let result = (|| {
4222            let existed = self.fts_projection_exists(index)?;
4223            let tokenizer = index.tokenize.replace('\'', "''");
4224            let columns = index
4225                .columns
4226                .iter()
4227                .map(|column| quote_ident(column))
4228                .collect::<Vec<_>>()
4229                .join(", ");
4230            let sql = format!(
4231            "CREATE VIRTUAL TABLE IF NOT EXISTS {fts} USING fts5({source_id} UNINDEXED, {columns}, tokenize='{tokenizer}')",
4232            fts = quote_ident(&index.name),
4233            source_id = quote_ident(FTS_SOURCE_ID_COLUMN),
4234        );
4235            self.conn.execute(&sql, []).map_err(|error| {
4236                format!(
4237                    "cannot create local FTS5 projection {:?}: {error}",
4238                    index.name
4239                )
4240            })?;
4241            let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4242            let mapped: bool = self
4243                .conn
4244                .query_row(
4245                    "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1)",
4246                    [format!("_syncular_fts_{}", index.name)],
4247                    |row| row.get(0),
4248                )
4249                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4250            self.conn.execute_batch(&format!("CREATE TABLE IF NOT EXISTS {mapping}(id INTEGER PRIMARY KEY, source_id TEXT NOT NULL UNIQUE)")).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4251            if !mapped && existed {
4252                self.conn
4253                    .execute_batch(&format!(
4254                        "INSERT INTO {mapping}(id, source_id) SELECT rowid, {} FROM {}",
4255                        quote_ident(FTS_SOURCE_ID_COLUMN),
4256                        quote_ident(&index.name)
4257                    ))
4258                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4259            }
4260            self.create_fts_triggers(table, index)?;
4261            if !existed {
4262                self.rebuild_fts_projection(table, index)?;
4263            }
4264            Ok(())
4265        })();
4266        if let Err(error) = result {
4267            self.rollback_observation("syncular_fts_schema");
4268            return Err(error);
4269        }
4270        if let Err(error) = self.conn.execute_batch("RELEASE syncular_fts_schema") {
4271            self.rollback_observation("syncular_fts_schema");
4272            return Err(error.to_string());
4273        }
4274        Ok(())
4275    }
4276
4277    // -- persistence write-through --------------------------------------------
4278
4279    fn persist_outbox_insert(&self, commit: &OutboxCommit) -> Result<(), String> {
4280        let ops: Vec<Value> = commit
4281            .ops
4282            .iter()
4283            .map(|op| {
4284                let mut entry = serde_json::json!({
4285                    "op": if op.upsert { "upsert" } else { "delete" },
4286                    "table": op.table,
4287                    "rowId": op.row_id,
4288                    "baseVersion": op.base_version,
4289                    "values": op.values.clone().map(Value::Object),
4290                });
4291                if op.insert {
4292                    entry["insert"] = Value::Bool(true);
4293                }
4294                entry
4295            })
4296            .collect();
4297        self.conn
4298            .execute(
4299                "INSERT OR REPLACE INTO _syncular_outbox (commit_id, ops_json) VALUES (?1, ?2)",
4300                rusqlite::params![commit.client_commit_id, Value::Array(ops).to_string()],
4301            )
4302            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4303        for operation in &commit.ops {
4304            let Some(values) = &operation.values else {
4305                continue;
4306            };
4307            let Some(table) = self.schema.table(&operation.table) else {
4308                continue;
4309            };
4310            for column in table
4311                .columns
4312                .iter()
4313                .filter(|column| column.ty == ColumnType::BlobRef)
4314            {
4315                let Some(Value::String(raw)) = values.get(&column.name) else {
4316                    continue;
4317                };
4318                let Ok(blob_ref) = serde_json::from_str::<Value>(raw) else {
4319                    continue;
4320                };
4321                let Some(blob_id) = blob_ref.get("blobId").and_then(Value::as_str) else {
4322                    continue;
4323                };
4324                self.conn
4325                    .execute(
4326                        "INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id, blob_id)
4327                         SELECT ?1, ?2 WHERE EXISTS (SELECT 1 FROM _syncular_blobs WHERE blob_id = ?2)",
4328                        rusqlite::params![commit.client_commit_id, blob_id],
4329                    )
4330                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4331            }
4332        }
4333        Ok(())
4334    }
4335
4336    fn delete_outbox_persisted(&self, client_commit_id: &str) -> Result<(), String> {
4337        self.conn
4338            .execute(
4339                "DELETE FROM _syncular_blob_commit_refs WHERE commit_id = ?1",
4340                rusqlite::params![client_commit_id],
4341            )
4342            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4343        self.conn
4344            .execute(
4345                "DELETE FROM _syncular_outbox WHERE commit_id = ?1",
4346                rusqlite::params![client_commit_id],
4347            )
4348            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4349        self.conn.execute("DELETE FROM _syncular_row_deliveries WHERE NOT EXISTS(SELECT 1 FROM _syncular_outbox,json_each(ops_json) WHERE json_extract(json_each.value,'$.table')=tbl AND json_extract(json_each.value,'$.rowId')=id)", [])
4350            .map(|_| ())
4351            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4352    }
4353
4354    fn outcome_status_name(status: CommitOutcomeStatus) -> &'static str {
4355        match status {
4356            CommitOutcomeStatus::Applied => "applied",
4357            CommitOutcomeStatus::Cached => "cached",
4358            CommitOutcomeStatus::Conflict => "conflict",
4359            CommitOutcomeStatus::Rejected => "rejected",
4360        }
4361    }
4362
4363    fn outcome_resolution_name(resolution: CommitOutcomeResolution) -> &'static str {
4364        match resolution {
4365            CommitOutcomeResolution::Active => "active",
4366            CommitOutcomeResolution::ResolvedKeepServer => "resolved_keep_server",
4367            CommitOutcomeResolution::Superseded => "superseded",
4368            CommitOutcomeResolution::Dismissed => "dismissed",
4369        }
4370    }
4371
4372    fn parse_outcome_status(value: &str) -> Result<CommitOutcomeStatus, String> {
4373        match value {
4374            "applied" => Ok(CommitOutcomeStatus::Applied),
4375            "cached" => Ok(CommitOutcomeStatus::Cached),
4376            "conflict" => Ok(CommitOutcomeStatus::Conflict),
4377            "rejected" => Ok(CommitOutcomeStatus::Rejected),
4378            _ => Err(format!("invalid persisted commit outcome status {value:?}")),
4379        }
4380    }
4381
4382    fn parse_outcome_resolution(value: &str) -> Result<CommitOutcomeResolution, String> {
4383        match value {
4384            "active" => Ok(CommitOutcomeResolution::Active),
4385            "resolved_keep_server" => Ok(CommitOutcomeResolution::ResolvedKeepServer),
4386            "superseded" => Ok(CommitOutcomeResolution::Superseded),
4387            "dismissed" => Ok(CommitOutcomeResolution::Dismissed),
4388            _ => Err(format!(
4389                "invalid persisted commit outcome resolution {value:?}"
4390            )),
4391        }
4392    }
4393
4394    fn persist_commit_outcome(
4395        &self,
4396        client_commit_id: &str,
4397        status: CommitOutcomeStatus,
4398        results: &[CommitOperationOutcome],
4399        operations: Option<&[OutboxOp]>,
4400    ) -> Result<(), String> {
4401        let results_json = serde_json::to_string(results).map_err(|error| error.to_string())?;
4402        let operations_json = operations
4403            .map(|items| {
4404                serde_json::to_string(&items.iter().map(CommitOperation::from).collect::<Vec<_>>())
4405            })
4406            .transpose()
4407            .map_err(|error| error.to_string())?;
4408        self.conn
4409            .execute(
4410                "INSERT INTO _syncular_commit_outcomes (
4411                   client_commit_id, status, recorded_at_ms, results_json,
4412                   operations_json, resolution
4413                 ) VALUES (?1, ?2, ?3, ?4, ?5, 'active')",
4414                rusqlite::params![
4415                    client_commit_id,
4416                    Self::outcome_status_name(status),
4417                    self.clock_now_ms(),
4418                    results_json,
4419                    operations_json
4420                ],
4421            )
4422            .map(|_| ())
4423            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4424    }
4425
4426    /// §7.2: the journal holds a stored cell only in its canonical shape. A cell
4427    /// the byte-envelope rule refuses cannot be journaled verbatim.
4428    fn stored_cell_is_representable(cell: &Value) -> bool {
4429        cell.is_null()
4430            || cell.is_string()
4431            || cell.is_boolean()
4432            || cell.is_number()
4433            || is_canonical_bytes_envelope(cell)
4434    }
4435
4436    fn stored_row_is_representable(value: &Value) -> bool {
4437        value
4438            .as_object()
4439            .is_some_and(|row| row.values().all(Self::stored_cell_is_representable))
4440    }
4441
4442    fn stored_operation_is_representable(value: &Value) -> bool {
4443        value.get("table").is_some_and(Value::is_string)
4444            && value.get("rowId").is_some_and(Value::is_string)
4445            && value.get("baseVersion").is_none_or(|v| {
4446                v.as_i64()
4447                    .is_some_and(|n| n.unsigned_abs() <= MAX_JS_SAFE_INTEGER)
4448            })
4449            && match value.get("op").and_then(Value::as_str) {
4450                Some("upsert") => {
4451                    value
4452                        .get("values")
4453                        .is_some_and(Self::stored_row_is_representable)
4454                        && value
4455                            .get("insert")
4456                            .is_none_or(|insert| *insert == Value::Bool(true))
4457                }
4458                Some("delete") => value.get("values").is_none() && value.get("insert").is_none(),
4459                _ => false,
4460            }
4461    }
4462
4463    /// §7.2/§7.4.4: a dropped commit keeps its operation envelope in the journal
4464    /// only when the journal reader accepts the serialized operation, which is the
4465    /// rule `outcome_from_row` applies to this same row later.
4466    fn outbox_op_is_journalable(operation: &OutboxOp) -> bool {
4467        serde_json::to_value(CommitOperation::from(operation))
4468            .is_ok_and(|value| Self::stored_operation_is_representable(&value))
4469    }
4470
4471    fn outcome_from_row(row: StoredCommitOutcomeRow) -> Result<CommitOutcome, String> {
4472        let StoredCommitOutcomeRow {
4473            sequence,
4474            client_commit_id,
4475            status,
4476            recorded_at_ms,
4477            results_json,
4478            operations_json,
4479            resolution,
4480            resolved_at_ms,
4481            replacement_client_commit_id,
4482        } = row;
4483        if sequence.unsigned_abs() > MAX_JS_SAFE_INTEGER
4484            || recorded_at_ms.unsigned_abs() > MAX_JS_SAFE_INTEGER
4485            || resolved_at_ms.is_some_and(|value| value.unsigned_abs() > MAX_JS_SAFE_INTEGER)
4486        {
4487            return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned());
4488        }
4489        let invalid = || "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
4490        let stored: Vec<Value> = serde_json::from_str(&results_json).map_err(|_| invalid())?;
4491        for result in &stored {
4492            let nested = match result.get("status").and_then(Value::as_str) {
4493                Some("conflict") => result.get("conflict"),
4494                Some("error") => result.get("rejection"),
4495                _ => None,
4496            };
4497            if nested
4498                .and_then(|record| record.get("operation"))
4499                .is_some_and(|op| !Self::stored_operation_is_representable(op))
4500                || (result.get("status").and_then(Value::as_str) == Some("conflict")
4501                    && nested
4502                        .and_then(|record| record.get("serverRow"))
4503                        .is_some_and(|row| !Self::stored_row_is_representable(row)))
4504            {
4505                return Err(invalid());
4506            }
4507        }
4508        let results: Vec<CommitOperationOutcome> =
4509            serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())?;
4510        let has_conflict = results
4511            .iter()
4512            .any(|result| matches!(result, CommitOperationOutcome::Conflict { .. }));
4513        let has_error = results
4514            .iter()
4515            .any(|result| matches!(result, CommitOperationOutcome::Error { .. }));
4516        let status = Self::parse_outcome_status(&status).map_err(|_| invalid())?;
4517        let redacted = results.is_empty() && operations_json.is_none();
4518        if match status {
4519            CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => has_conflict || has_error,
4520            CommitOutcomeStatus::Conflict => !(has_conflict || redacted),
4521            CommitOutcomeStatus::Rejected => has_conflict || !(has_error || redacted),
4522        } {
4523            return Err(invalid());
4524        }
4525        let operations: Option<Vec<CommitOperation>> = operations_json
4526            .map(|raw| {
4527                let stored: Vec<Value> = serde_json::from_str(&raw).map_err(|_| invalid())?;
4528                if !stored.iter().all(Self::stored_operation_is_representable) {
4529                    return Err(invalid());
4530                }
4531                serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())
4532            })
4533            .transpose()?;
4534        for result in &results {
4535            match result {
4536                CommitOperationOutcome::Conflict { conflict }
4537                    if conflict.server_version.unsigned_abs() > MAX_JS_SAFE_INTEGER =>
4538                {
4539                    return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned())
4540                }
4541                CommitOperationOutcome::Error { rejection } => {
4542                    if let Some(details) = &rejection.details {
4543                        let encoded = serde_json::to_string(details).map_err(|_| {
4544                            "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4545                        })?;
4546                        RejectionDetails::parse(&encoded).map_err(|_| {
4547                            "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4548                        })?;
4549                    }
4550                }
4551                _ => {}
4552            }
4553        }
4554        Ok(CommitOutcome {
4555            sequence,
4556            client_commit_id,
4557            status,
4558            recorded_at_ms,
4559            results,
4560            operations,
4561            retained_rows: None,
4562            resolution: Self::parse_outcome_resolution(&resolution)?,
4563            resolved_at_ms,
4564            replacement_client_commit_id,
4565        })
4566    }
4567
4568    /// Resolve declared unique keys through SQLite, including affinity and NULL semantics.
4569    fn unique_conflicts(
4570        &self,
4571        table: &TableSchema,
4572        values: &Map<String, Value>,
4573        base: bool,
4574    ) -> Result<Vec<RetainedUniqueConflict>, String> {
4575        let source = if base {
4576            base_table(&table.name)
4577        } else {
4578            visible_table(&table.name)
4579        };
4580        let mut conflicts = Vec::new();
4581        for index in table.indexes.iter().filter(|index| index.unique) {
4582            let mut params = vec![json_param_to_sql(
4583                values.get(&table.primary_key).ok_or("sync.local_corrupt")?,
4584            )?];
4585            for name in &index.columns {
4586                let column = table
4587                    .columns
4588                    .iter()
4589                    .find(|column| column.name == *name)
4590                    .ok_or("sync.local_corrupt")?;
4591                let cell = json_to_column_value(column, values.get(name))?;
4592                params.push(owned_sql_value(RowParam::Cell(&cell))?);
4593            }
4594            let sql = format!(
4595                "SELECT * FROM {source} WHERE {} != ? AND {}",
4596                quote_ident(&table.primary_key),
4597                index
4598                    .columns
4599                    .iter()
4600                    .map(|column| format!("{} = ?", quote_ident(column)))
4601                    .collect::<Vec<_>>()
4602                    .join(" AND ")
4603            );
4604            let mut statement = self
4605                .conn
4606                .prepare_cached(&sql)
4607                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4608            let records = statement
4609                .query_map(rusqlite::params_from_iter(params), |record| {
4610                    let values = table
4611                        .columns
4612                        .iter()
4613                        .enumerate()
4614                        .map(|(index, column)| {
4615                            let value = sql_ref_to_json(column, record.get_ref(index)?);
4616                            json_to_column_value(column, Some(&value)).map_err(|message| {
4617                                rusqlite::Error::ToSqlConversionFailure(message.into())
4618                            })
4619                        })
4620                        .collect::<Result<Row, _>>()?;
4621                    Ok((values, record.get::<_, i64>(table.columns.len())?))
4622                })
4623                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4624            for record in records {
4625                let (row, version) =
4626                    record.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4627                let row_id = render_row_id_json(Some(&column_value_to_json(&row[table.pk_index])))?;
4628                conflicts.push(RetainedUniqueConflict {
4629                    index: index.name.clone(),
4630                    columns: index.columns.clone(),
4631                    row_id,
4632                    server_row: table
4633                        .columns
4634                        .iter()
4635                        .zip(&row)
4636                        .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
4637                        .collect(),
4638                    server_version: version,
4639                });
4640            }
4641        }
4642        Ok(conflicts)
4643    }
4644
4645    fn attach_retained_rows(&self, mut outcome: CommitOutcome) -> Result<CommitOutcome, String> {
4646        if let Some((commit, initial)) = self
4647            .failed_commits
4648            .iter()
4649            .find(|(commit, _)| commit.client_commit_id == outcome.client_commit_id)
4650        {
4651            let mut rows = Vec::new();
4652            for operation in &commit.ops {
4653                // A table the current schema removed has no rows to retain.
4654                let Some(table) = self.schema.table(&operation.table) else {
4655                    continue;
4656                };
4657                let key =
4658                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
4659                        .map_err(|_| "sync.local_corrupt".to_owned())?;
4660                let base = self.stored_row(table, &operation.row_id, true)?;
4661                rows.push(RetainedCommitRow {
4662                    table: operation.table.clone(),
4663                    row_id: operation.row_id.clone(),
4664                    unique_conflicts: if operation.upsert {
4665                        self.unique_conflicts(
4666                            table,
4667                            initial
4668                                .get(&key)
4669                                .and_then(Value::as_object)
4670                                .or(operation.values.as_ref())
4671                                .ok_or("sync.local_corrupt")?,
4672                            true,
4673                        )?
4674                    } else {
4675                        Vec::new()
4676                    },
4677                    local_row: if operation.upsert {
4678                        initial
4679                            .get(&key)
4680                            .and_then(Value::as_object)
4681                            .cloned()
4682                            .or_else(|| operation.values.clone())
4683                    } else {
4684                        None
4685                    },
4686                    server_row: base.as_ref().map(|(values, _)| {
4687                        table
4688                            .columns
4689                            .iter()
4690                            .zip(values)
4691                            .map(|(column, value)| {
4692                                (column.name.clone(), column_value_to_json(value))
4693                            })
4694                            .collect()
4695                    }),
4696                    server_version: base.map(|(_, version)| version),
4697                });
4698            }
4699            outcome.retained_rows = Some(rows);
4700        }
4701        Ok(outcome)
4702    }
4703
4704    pub fn commit_outcome(&self, client_commit_id: &str) -> Result<Option<CommitOutcome>, String> {
4705        let row = self
4706            .conn
4707            .query_row(
4708                "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
4709                        resolution, resolved_at_ms, replacement_client_commit_id
4710                   FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
4711                rusqlite::params![client_commit_id],
4712                |row| {
4713                    Ok(StoredCommitOutcomeRow {
4714                        sequence: row.get(0)?,
4715                        client_commit_id: row.get(1)?,
4716                        status: row.get(2)?,
4717                        recorded_at_ms: row.get(3)?,
4718                        results_json: row.get(4)?,
4719                        operations_json: row.get(5)?,
4720                        resolution: row.get(6)?,
4721                        resolved_at_ms: row.get(7)?,
4722                        replacement_client_commit_id: row.get(8)?,
4723                    })
4724                },
4725            )
4726            .optional()
4727            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4728        row.map(|row| self.attach_retained_rows(Self::outcome_from_row(row)?))
4729            .transpose()
4730    }
4731
4732    /// Internal host step. The host must run its idle drive before finishing.
4733    #[doc(hidden)]
4734    pub fn prepare_current_base(
4735        &self,
4736        client_commit_id: &str,
4737        sequence: i64,
4738    ) -> Result<CurrentBasePreparation, CurrentBaseProof> {
4739        let outcome = self
4740            .commit_outcome(client_commit_id)
4741            .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?;
4742        let valid = outcome.as_ref().is_some_and(|outcome| {
4743            outcome.sequence == sequence
4744                && outcome.resolution == CommitOutcomeResolution::Active
4745                && matches!(
4746                    outcome.status,
4747                    CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
4748                )
4749                && outcome
4750                    .operations
4751                    .as_ref()
4752                    .zip(outcome.retained_rows.as_ref())
4753                    .is_some_and(|(operations, rows)| {
4754                        !rows.is_empty() && operations.len() == rows.len()
4755                    })
4756        });
4757        if !valid {
4758            return Err(CurrentBaseProof::failure(
4759                CurrentBaseProofReason::OutcomeUnavailable,
4760            ));
4761        }
4762        if !self.transport_enabled {
4763            return Err(CurrentBaseProof::failure(CurrentBaseProofReason::Offline));
4764        }
4765        Ok(CurrentBasePreparation {
4766            client_commit_id: client_commit_id.to_owned(),
4767            sequence,
4768            units: load_units(&self.conn)
4769                .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?,
4770            transport_epoch: self.transport_epoch,
4771            registration_epoch: self.registration_epoch,
4772            security_epoch: self.security_epoch,
4773        })
4774    }
4775
4776    /// Internal host step after the completed post-rejection idle drive.
4777    #[doc(hidden)]
4778    pub fn finish_current_base(
4779        &mut self,
4780        prepared: CurrentBasePreparation,
4781        drive: SyncOutcome,
4782    ) -> CurrentBaseProof {
4783        if !self.transport_enabled || self.transport_epoch != prepared.transport_epoch {
4784            return CurrentBaseProof::failure(CurrentBaseProofReason::Offline);
4785        }
4786        if self.registration_epoch != prepared.registration_epoch {
4787            return CurrentBaseProof::failure(CurrentBaseProofReason::MissingCoverage);
4788        }
4789        if self.security_preflight || self.security_epoch != prepared.security_epoch {
4790            return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed);
4791        }
4792        let report = match drive {
4793            SyncOutcome::Ok(report) => report,
4794            SyncOutcome::BudgetExhausted(_) => {
4795                return CurrentBaseProof::failure(CurrentBaseProofReason::BudgetExhausted)
4796            }
4797            _ => return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed),
4798        };
4799        if report.schema_floor.is_some() {
4800            return CurrentBaseProof::failure(CurrentBaseProofReason::SchemaFloor);
4801        }
4802        if self
4803            .conn
4804            .execute_batch("SAVEPOINT syncular_base_proof")
4805            .is_err()
4806        {
4807            return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
4808        }
4809        let proof = (|| {
4810            let snapshot = snapshot_read_connection(
4811                &self.conn,
4812                &SnapshotReadRequest {
4813                    units: prepared.units.iter().map(|unit| unit.id.clone()).collect(),
4814                    commit_ids: vec![prepared.client_commit_id.clone()],
4815                    ..Default::default()
4816                },
4817            )
4818            .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4819            let current = self
4820                .commit_outcome(&prepared.client_commit_id)
4821                .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4822            let unavailable = if report.revoked.is_empty() {
4823                CurrentBaseProofReason::OutcomeUnavailable
4824            } else {
4825                CurrentBaseProofReason::Revoked
4826            };
4827            let Some(outcome) = current else {
4828                return Err(unavailable);
4829            };
4830            if !matches!(
4831                snapshot.deliveries.first(),
4832                Some(CommitDelivery::Known { .. })
4833            ) || outcome.sequence != prepared.sequence
4834                || outcome.resolution != CommitOutcomeResolution::Active
4835                || !matches!(
4836                    outcome.status,
4837                    CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
4838                )
4839            {
4840                return Err(unavailable);
4841            }
4842            let (Some(operations), Some(rows)) = (outcome.operations, outcome.retained_rows) else {
4843                return Err(unavailable);
4844            };
4845            if rows.is_empty() || operations.len() != rows.len() {
4846                return Err(unavailable);
4847            }
4848            let after =
4849                load_units(&self.conn).map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4850            let complete: HashSet<&str> = snapshot
4851                .units
4852                .iter()
4853                .filter_map(|unit| match unit {
4854                    UnitCatchup::Known {
4855                        id,
4856                        bootstrap_complete: true,
4857                        ..
4858                    } => Some(id.as_str()),
4859                    _ => None,
4860                })
4861                .collect();
4862            // A unit id names one scope map (§4.1), so the same id before and
4863            // after the drive is the same registration.
4864            let candidates: Vec<&UnitRecord> = after
4865                .iter()
4866                .filter(|unit| {
4867                    complete.contains(unit.id.as_str())
4868                        && prepared.units.iter().any(|before| before.id == unit.id)
4869                })
4870                .collect();
4871            let covered = |table_name: &str, row: &Map<String, Value>| {
4872                let Some(table) = self.schema.table(table_name) else {
4873                    return false;
4874                };
4875                candidates.iter().any(|unit| {
4876                    covers(table, &unit.scopes)
4877                        && pair_scopes(&unit.scopes, table_name, unit.echo.as_deref()).is_some_and(
4878                            |scopes| {
4879                                scopes.iter().all(|(variable, allowed)| {
4880                                    table
4881                                        .scope_column(variable)
4882                                        .and_then(|column| match row.get(column) {
4883                                            Some(Value::String(value)) => Some(value.clone()),
4884                                            Some(Value::Bool(value)) => Some(value.to_string()),
4885                                            Some(Value::Number(value)) => {
4886                                                value.as_f64().map(|number| {
4887                                                    ryu_js::Buffer::new()
4888                                                        .format_finite(number)
4889                                                        .to_owned()
4890                                                })
4891                                            }
4892                                            _ => None,
4893                                        })
4894                                        .is_some_and(|value| {
4895                                            !value.is_empty() && allowed.contains(&value)
4896                                        })
4897                                })
4898                            },
4899                        )
4900                })
4901            };
4902            for row in &rows {
4903                let Some(base) = row.server_row.as_ref().or(row.local_row.as_ref()) else {
4904                    return Err(if report.revoked.is_empty() {
4905                        CurrentBaseProofReason::MissingCoverage
4906                    } else {
4907                        CurrentBaseProofReason::Revoked
4908                    });
4909                };
4910                if !covered(&row.table, base)
4911                    || row
4912                        .unique_conflicts
4913                        .iter()
4914                        .any(|conflict| !covered(&row.table, &conflict.server_row))
4915                {
4916                    return Err(if report.revoked.is_empty() {
4917                        CurrentBaseProofReason::MissingCoverage
4918                    } else {
4919                        CurrentBaseProofReason::Revoked
4920                    });
4921                }
4922            }
4923            Ok(rows)
4924        })();
4925        if self
4926            .conn
4927            .execute_batch("RELEASE syncular_base_proof")
4928            .is_err()
4929        {
4930            return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
4931        }
4932        match proof {
4933            Ok(rows) => CurrentBaseProof {
4934                proven: true,
4935                rows: Some(rows),
4936                reason: None,
4937            },
4938            Err(reason) => CurrentBaseProof::failure(reason),
4939        }
4940    }
4941
4942    pub fn prove_current_base(
4943        &mut self,
4944        transport: &mut dyn Transport,
4945        client_commit_id: &str,
4946        sequence: i64,
4947        max_rounds: Option<u32>,
4948    ) -> CurrentBaseProof {
4949        let prepared = match self.prepare_current_base(client_commit_id, sequence) {
4950            Ok(prepared) => prepared,
4951            Err(proof) => return proof,
4952        };
4953        let drive = self.sync_until_idle(transport, max_rounds);
4954        self.finish_current_base(prepared, drive)
4955    }
4956
4957    pub fn commit_outcomes(&self, query: CommitOutcomeQuery) -> Result<Vec<CommitOutcome>, String> {
4958        if query.limit == Some(0) {
4959            return Err("sync.invalid_request: commit outcome limit must be positive".to_owned());
4960        }
4961        let mut sql = String::from(
4962            "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
4963                    resolution, resolved_at_ms, replacement_client_commit_id
4964               FROM _syncular_commit_outcomes",
4965        );
4966        if query.active_only {
4967            sql.push_str(" WHERE resolution = 'active' AND status IN ('conflict', 'rejected')");
4968        }
4969        sql.push_str(" ORDER BY seq DESC");
4970        if let Some(limit) = query.limit {
4971            sql.push_str(&format!(" LIMIT {limit}"));
4972        }
4973        let mut stmt = self
4974            .conn
4975            .prepare(&sql)
4976            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4977        let rows = stmt
4978            .query_map([], |row| {
4979                Ok(StoredCommitOutcomeRow {
4980                    sequence: row.get(0)?,
4981                    client_commit_id: row.get(1)?,
4982                    status: row.get(2)?,
4983                    recorded_at_ms: row.get(3)?,
4984                    results_json: row.get(4)?,
4985                    operations_json: row.get(5)?,
4986                    resolution: row.get(6)?,
4987                    resolved_at_ms: row.get(7)?,
4988                    replacement_client_commit_id: row.get(8)?,
4989                })
4990            })
4991            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4992        let mut outcomes = Vec::new();
4993        for row in rows {
4994            outcomes.push(self.attach_retained_rows(Self::outcome_from_row(
4995                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
4996            )?)?);
4997        }
4998        Ok(outcomes)
4999    }
5000
5001    fn prune_commit_outcomes(&self) -> Result<(), String> {
5002        #[cfg(test)]
5003        self.outcome_prune_count
5004            .set(self.outcome_prune_count.get() + 1);
5005        let max_entries = self.limits.outcome_retention_max_entries.unwrap_or(1_000);
5006        let count = self
5007            .conn
5008            .query_row(
5009                "SELECT COUNT(*) FROM _syncular_commit_outcomes",
5010                [],
5011                |row| row.get::<_, i64>(0),
5012            )
5013            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5014            as usize;
5015        let excess = count.saturating_sub(max_entries);
5016        if excess == 0 {
5017            return Ok(());
5018        }
5019        let mut stmt = self
5020            .conn
5021            .prepare(
5022                "SELECT seq FROM _syncular_commit_outcomes
5023                  WHERE status IN ('applied', 'cached') OR resolution != 'active'
5024                  ORDER BY seq ASC LIMIT ?1",
5025            )
5026            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5027        let rows = stmt
5028            .query_map(rusqlite::params![excess as i64], |row| row.get::<_, i64>(0))
5029            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5030        let sequences = rows
5031            .collect::<Result<Vec<_>, _>>()
5032            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5033        drop(stmt);
5034        for sequence in sequences {
5035            self.conn
5036                .execute(
5037                    "DELETE FROM _syncular_commit_outcomes WHERE seq = ?1",
5038                    rusqlite::params![sequence],
5039                )
5040                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5041        }
5042        Ok(())
5043    }
5044
5045    // -- units (§4.1) ------------------------------------------------------------
5046
5047    /// Every registered unit in registration order (§4.1).
5048    pub fn units(&self) -> Result<Vec<UnitRecord>, String> {
5049        self.stored(load_units(&self.conn))
5050    }
5051
5052    pub fn unit(&self, id: &str) -> Result<Option<UnitRecord>, String> {
5053        self.stored(get_unit(&self.conn, id))
5054    }
5055
5056    /// Register one unit (§4.1) and return its id.
5057    pub fn subscribe(&mut self, scopes: UnitScopes) -> Result<String, String> {
5058        Ok(self.subscribe_many(vec![scopes])?.remove(0))
5059    }
5060
5061    /// Register several units in one local transaction and return their ids:
5062    /// one commit for all of them (on OPFS a commit costs milliseconds, so a
5063    /// cold start with hundreds of units pays it once). An error rolls back
5064    /// every registration of the call. Registering an active unit again
5065    /// changes nothing; a revoked unit re-arms (§3.3). A call that registers or
5066    /// re-arms a unit raises sync-needed with an interactive intent.
5067    pub fn subscribe_many(&mut self, units: Vec<UnitScopes>) -> Result<Vec<String>, String> {
5068        self.begin_observation("syncular_subscribe")?;
5069        let mut changed = false;
5070        let registered = (|| {
5071            let mut ids = Vec::with_capacity(units.len());
5072            for scopes in units {
5073                let (id, held) = self.hold_unit(scopes, true)?;
5074                changed |= held;
5075                ids.push(id);
5076            }
5077            self.conn
5078                .execute_batch("RELEASE syncular_subscribe")
5079                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5080            Ok(ids)
5081        })();
5082        let ids = match registered {
5083            Ok(ids) => ids,
5084            Err(error) => {
5085                self.rollback_observation("syncular_subscribe");
5086                return Err(error);
5087            }
5088        };
5089        if changed {
5090            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5091            self.set_sync_needed(true, true);
5092        }
5093        Ok(ids)
5094    }
5095
5096    /// Release the explicit reference to a unit. The unit leaves the
5097    /// registration list when no window base holds it (§4.1); its rows stay.
5098    pub fn unsubscribe(&mut self, id: &str) -> Result<(), String> {
5099        let Some(unit) = self.stored(get_unit(&self.conn, id))? else {
5100            return Ok(());
5101        };
5102        if !unit.explicit {
5103            return Ok(());
5104        }
5105        if !self.stored(window_refs(&self.conn, id))?.is_empty() {
5106            return self.stored(save_unit(
5107                &self.conn,
5108                &UnitRecord {
5109                    explicit: false,
5110                    ..unit
5111                },
5112            ));
5113        }
5114        self.conn
5115            .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5116            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5117        self.registration_epoch = self.registration_epoch.wrapping_add(1);
5118        if unit.status == UnitStatus::Active {
5119            self.set_sync_needed(true, true);
5120        }
5121        Ok(())
5122    }
5123
5124    /// Take one reference on a unit (§4.1): validate the scope map, register a
5125    /// new unit catching up with cursor `-1`, re-arm a revoked one (§3.3).
5126    /// Returns the id and whether the registration list changed.
5127    fn hold_unit(&mut self, scopes: UnitScopes, explicit: bool) -> Result<(String, bool), String> {
5128        if scopes.is_empty()
5129            || scopes.values().any(|value| value == "*")
5130            || !self
5131                .schema
5132                .tables
5133                .iter()
5134                .any(|table| covers(table, &scopes))
5135        {
5136            return Err("sync.invalid_subscription: a unit names one non-wildcard value per variable and covers a table".to_owned());
5137        }
5138        let id = ssp2::registration::unit_id(&scope_pairs(&scopes));
5139        let existing = self.stored(get_unit(&self.conn, &id))?;
5140        if let Some(existing) = existing
5141            .as_ref()
5142            .filter(|unit| unit.status != UnitStatus::Revoked)
5143        {
5144            if explicit && !existing.explicit {
5145                self.stored(save_unit(
5146                    &self.conn,
5147                    &UnitRecord {
5148                        explicit,
5149                        ..existing.clone()
5150                    },
5151                ))?;
5152            }
5153            return Ok((id, false));
5154        }
5155        self.delete_pending_evict(&id)?;
5156        self.stored(save_unit(
5157            &self.conn,
5158            &UnitRecord {
5159                id: id.clone(),
5160                scopes,
5161                explicit: explicit || existing.is_some_and(|unit| unit.explicit),
5162                status: UnitStatus::Active,
5163                reason_code: None,
5164                cursor: Some(-1),
5165                bootstrap_state: None,
5166                seeded: Vec::new(),
5167                echo: None,
5168            },
5169        ))?;
5170        Ok((id, true))
5171    }
5172
5173    // -- windows (§4.8) -----------------------------------------------------------
5174
5175    /// §4.8: set the windowed-in values of a base, one unit per value. Added
5176    /// values take a reference on their unit (a new unit bootstraps on the
5177    /// next sync); removed values release theirs, and a unit no reference
5178    /// holds leaves the registration list fused with its first eviction chunk
5179    /// (E1–E4). Idempotent; re-entry cancels a deferred eviction.
5180    pub fn set_window(
5181        &mut self,
5182        base: &WindowBase,
5183        units: &[String],
5184    ) -> Result<CommandEffects, String> {
5185        let base_key = window_base_key(base);
5186        let live = self.load_window_units(&base_key)?;
5187        let mut changed = false;
5188        for value in units {
5189            if live.iter().any(|(held, _)| held == value) {
5190                continue;
5191            }
5192            let rollback = self.capture();
5193            self.begin_observation("syncular_window")?;
5194            let widened = (|| {
5195                let (id, registered) = self.hold_unit(window_unit_scopes(base, value), false)?;
5196                self.sync_needed |= registered;
5197                self.conn
5198                    .execute(
5199                        "INSERT OR REPLACE INTO _syncular_windows(base, unit, sub_id) VALUES (?1, ?2, ?3)",
5200                        rusqlite::params![base_key, value, id],
5201                    )
5202                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5203                let mut batch = ChangeAccumulator::default();
5204                batch.window(&base_key, value);
5205                batch.status = true;
5206                self.finish_observation("syncular_window", batch)
5207            })();
5208            if let Err(error) = widened {
5209                self.rollback_observation("syncular_window");
5210                self.restore(rollback);
5211                return Err(error);
5212            }
5213            changed = true;
5214            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5215        }
5216        for (value, id) in live {
5217            if units.contains(&value) {
5218                continue;
5219            }
5220            self.rebuild_overlay_if_dirty()?;
5221            let rollback = self.capture();
5222            self.begin_observation("syncular_window")?;
5223            let remaining = self.release_window_unit(&base_key, &value, &id);
5224            let remaining = match remaining {
5225                Ok(remaining) => remaining,
5226                Err(error) => {
5227                    self.rollback_observation("syncular_window");
5228                    self.restore(rollback);
5229                    return Err(error);
5230                }
5231            };
5232            changed = true;
5233            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5234            if remaining {
5235                self.drain_pending_evictions()?;
5236            }
5237        }
5238        Ok(if changed && self.transport_enabled {
5239            CommandEffects::interactive()
5240        } else {
5241            CommandEffects::none()
5242        })
5243    }
5244
5245    /// §4.8 completeness oracle: the windowed-in values of a base and those
5246    /// whose unit is not complete. A value is complete once its unit is active
5247    /// and no longer bootstrapping; registration alone is not completeness.
5248    pub fn window_state(&self, base: &WindowBase) -> Result<WindowState, String> {
5249        persisted_window_state(&self.conn, base).map_err(|failure| failure.message)
5250    }
5251
5252    /// Registry rows for a base, ordered by value: (value, unit id).
5253    fn load_window_units(&self, base_key: &str) -> Result<Vec<(String, String)>, String> {
5254        let mut statement = self
5255            .conn
5256            .prepare_cached(
5257                "SELECT unit, sub_id FROM _syncular_windows WHERE base = ?1 ORDER BY unit ASC",
5258            )
5259            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5260        let rows = statement
5261            .query_map([base_key], |row| Ok((row.get(0)?, row.get(1)?)))
5262            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5263        rows.collect::<Result<_, _>>()
5264            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5265    }
5266
5267    /// Every window registry row: (base key, value).
5268    fn load_window_registry(&self) -> Result<Vec<(String, String)>, String> {
5269        let mut statement = self
5270            .conn
5271            .prepare_cached("SELECT base, unit FROM _syncular_windows ORDER BY base, unit")
5272            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5273        let rows = statement
5274            .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
5275            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5276        rows.collect::<Result<_, _>>()
5277            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5278    }
5279
5280    /// §4.8: release a window value's reference inside the caller's
5281    /// observation. When no reference holds the unit, unregister it fused with
5282    /// its first eviction chunk (E3): delete the rows of every covered table
5283    /// matching the persisted echo, except rows pinned by the outbox (E1) or
5284    /// owned by another unit (§3.3), and park the per-table scopes of what
5285    /// remains in the pending-eviction registry. Fails closed without a local
5286    /// scope-column mapping. Returns whether unpinned rows remain.
5287    fn release_window_unit(
5288        &mut self,
5289        base_key: &str,
5290        value: &str,
5291        id: &str,
5292    ) -> Result<bool, String> {
5293        self.conn
5294            .execute(
5295                "DELETE FROM _syncular_windows WHERE base = ?1 AND unit = ?2",
5296                rusqlite::params![base_key, value],
5297            )
5298            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5299        let mut batch = ChangeAccumulator::default();
5300        batch.window(base_key, value);
5301        batch.status = true;
5302        let unit = self.stored(get_unit(&self.conn, id))?;
5303        let mut remaining = false;
5304        if let Some(unit) = unit.filter(|unit| !unit.explicit) {
5305            if self.stored(window_refs(&self.conn, id))?.is_empty() {
5306                let units = self.stored(load_units(&self.conn))?;
5307                self.conn
5308                    .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5309                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5310                self.sync_needed = true;
5311                for table in self.schema.tables.clone() {
5312                    let Some(effective) = unit
5313                        .echo
5314                        .as_deref()
5315                        .filter(|_| covers(&table, &unit.scopes))
5316                        .and_then(|echo| pair_scopes(&unit.scopes, &table.name, Some(echo)))
5317                    else {
5318                        continue;
5319                    };
5320                    let pinned = self.pinned_row_ids(&table.name);
5321                    let owners = unit_owners(&units, &table, id);
5322                    let (more, deferred) =
5323                        self.evict_scope_rows(&table.name, &effective, &owners, &pinned)?;
5324                    remaining |= more;
5325                    if deferred {
5326                        self.save_pending_evict(id, &table.name, &effective)?;
5327                    }
5328                    self.record_scope_map(&mut batch, &table.name, &effective);
5329                }
5330            }
5331        }
5332        self.finish_observation("syncular_window", batch)?;
5333        Ok(remaining)
5334    }
5335
5336    /// §4.8 E1: delete base rows owned by the effective scopes
5337    /// ([`local_scope_predicate`]) EXCEPT pinned primary keys. Returns (more
5338    /// unpinned work, any scoped rows remain). A missing scope-column mapping
5339    /// fails without deleting rows.
5340    fn evict_scope_rows(
5341        &self,
5342        table_name: &str,
5343        effective: &[(String, Vec<String>)],
5344        owners: &[Vec<(String, Vec<String>)>],
5345        pinned: &std::collections::HashSet<String>,
5346    ) -> Result<(bool, bool), String> {
5347        let table = self.schema.table(table_name).ok_or("sync.unknown_table")?;
5348        let Some((scope, mut params)) = local_scope_predicate(table, effective, owners)
5349            .map_err(|()| "sync.scope_revoked".to_owned())?
5350        else {
5351            return Ok((false, false));
5352        };
5353        let scope_params = params.len();
5354        let pk = quote_ident(&table.primary_key);
5355        // Pinned ids are rowId text; the text form matches every key type.
5356        let predicate = if pinned.is_empty() {
5357            scope.clone()
5358        } else {
5359            params.extend(pinned.iter().cloned().map(SqlValue::Text));
5360            let holes = vec!["?"; pinned.len()].join(", ");
5361            format!("{scope} AND CAST({pk} AS TEXT) NOT IN ({holes})")
5362        };
5363        let base = base_table(table_name);
5364        let visible = visible_table(table_name);
5365        let mut ids: Vec<SqlValue> = Vec::new();
5366        for source in [&base, &visible] {
5367            let mut stmt = self
5368                .conn
5369                .prepare_cached(&format!(
5370                    "SELECT {pk} FROM {source} WHERE {predicate} LIMIT 1024"
5371                ))
5372                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5373            ids = stmt
5374                .query_map(rusqlite::params_from_iter(&params), |row| row.get(0))
5375                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5376                .collect::<Result<_, _>>()
5377                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5378            if !ids.is_empty() {
5379                break;
5380            }
5381        }
5382        if !ids.is_empty() {
5383            for id in &ids {
5384                self.conn
5385                    .execute(
5386                        "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2",
5387                        rusqlite::params![table_name, id],
5388                    )
5389                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5390            }
5391            let holes = vec!["?"; ids.len()].join(", ");
5392            for source in [&base, &visible] {
5393                self.conn
5394                    .execute(
5395                        &format!("DELETE FROM {source} WHERE {pk} IN ({holes})"),
5396                        rusqlite::params_from_iter(&ids),
5397                    )
5398                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5399            }
5400        }
5401        let mut remaining = false;
5402        let mut deferred = false;
5403        for source in [&base, &visible] {
5404            remaining |= self
5405                .conn
5406                .query_row(
5407                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
5408                    rusqlite::params_from_iter(&params),
5409                    |row| row.get::<_, bool>(0),
5410                )
5411                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5412            deferred |= self
5413                .conn
5414                .query_row(
5415                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {scope})"),
5416                    rusqlite::params_from_iter(&params[..scope_params]),
5417                    |row| row.get::<_, bool>(0),
5418                )
5419                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5420        }
5421        Ok((remaining, deferred))
5422    }
5423
5424    /// §4.8 E1: continue deferred evictions after the outbox drains or between
5425    /// chunks, retaining outbox pins and their durable marker. A unit that
5426    /// re-entered the window has no pending entry left.
5427    fn drain_pending_evictions(&mut self) -> Result<(), String> {
5428        let pending = self.load_pending_evictions()?;
5429        if pending.is_empty() {
5430            return Ok(());
5431        }
5432        self.rebuild_overlay_if_dirty()?;
5433        for (unit_id, table_name, effective) in pending {
5434            let Some(table) = self.schema.table(&table_name).cloned() else {
5435                self.delete_pending_evict_table(&unit_id, &table_name)?;
5436                continue;
5437            };
5438            loop {
5439                std::thread::yield_now();
5440                self.begin_observation("syncular_evict")?;
5441                let chunk = (|| {
5442                    let pinned = self.pinned_row_ids(&table_name);
5443                    let owners =
5444                        unit_owners(&self.stored(load_units(&self.conn))?, &table, &unit_id);
5445                    let (remaining, deferred) =
5446                        self.evict_scope_rows(&table_name, &effective, &owners, &pinned)?;
5447                    if !deferred {
5448                        self.delete_pending_evict_table(&unit_id, &table_name)?;
5449                    }
5450                    let mut batch = ChangeAccumulator::default();
5451                    self.record_scope_map(&mut batch, &table_name, &effective);
5452                    self.finish_observation("syncular_evict", batch)?;
5453                    Ok(remaining)
5454                })();
5455                match chunk {
5456                    Ok(true) => {}
5457                    Ok(false) => break,
5458                    Err(error) => {
5459                        self.rollback_observation("syncular_evict");
5460                        return Err(error);
5461                    }
5462                }
5463            }
5464        }
5465        Ok(())
5466    }
5467
5468    /// §4.8 E1: primary keys of `table` referenced by a pending outbox
5469    /// commit — rows that MUST NOT be evicted until the commit drains.
5470    fn pinned_row_ids(&self, table: &str) -> std::collections::HashSet<String> {
5471        let mut pinned = std::collections::HashSet::new();
5472        for commit in self
5473            .outbox
5474            .iter()
5475            .map(|commit| &**commit)
5476            .chain(self.failed_commits.iter().map(|(commit, _)| commit))
5477        {
5478            for op in &commit.ops {
5479                if op.table == table {
5480                    pinned.insert(op.row_id.clone());
5481                }
5482            }
5483        }
5484        pinned
5485    }
5486
5487    fn save_pending_evict(
5488        &self,
5489        unit_id: &str,
5490        table: &str,
5491        effective: &[(String, Vec<String>)],
5492    ) -> Result<(), String> {
5493        self.conn.execute(
5494            "INSERT OR REPLACE INTO _syncular_pending_evictions(unit_id, tbl, effective_scopes) VALUES (?1, ?2, ?3)",
5495            rusqlite::params![unit_id, table, scope_map_to_json(effective).to_string()],
5496        ).map(|_| ()).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5497    }
5498
5499    /// Re-entry cancels every pending eviction of the unit.
5500    fn delete_pending_evict(&self, unit_id: &str) -> Result<(), String> {
5501        self.conn
5502            .execute(
5503                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
5504                [unit_id],
5505            )
5506            .map(|_| ())
5507            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5508    }
5509
5510    fn delete_pending_evict_table(&self, unit_id: &str, table: &str) -> Result<(), String> {
5511        self.conn
5512            .execute(
5513                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1 AND tbl = ?2",
5514                [unit_id, table],
5515            )
5516            .map(|_| ())
5517            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5518    }
5519
5520    fn load_pending_evictions(&self) -> Result<Vec<PendingEvict>, String> {
5521        let mut stmt = self
5522            .conn
5523            .prepare("SELECT unit_id, tbl, effective_scopes FROM _syncular_pending_evictions")
5524            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5525        let rows = stmt
5526            .query_map([], |row| {
5527                Ok((
5528                    row.get::<_, String>(0)?,
5529                    row.get::<_, String>(1)?,
5530                    row.get::<_, String>(2)?,
5531                ))
5532            })
5533            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5534        rows.map(|row| {
5535            let (unit_id, table, json) =
5536                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5537            let value: Value = serde_json::from_str(&json)
5538                .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5539            let effective = json_to_scope_map(&value)
5540                .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5541            Ok((unit_id, table, effective))
5542        })
5543        .collect()
5544    }
5545
5546    /// Select failed-intent retention; reload durable retained aggregates.
5547    pub fn set_retain_failed_commits(&mut self, enabled: bool) -> Result<(), String> {
5548        self.retain_failed_commits = enabled;
5549        for (commit, _) in self.failed_commits.iter() {
5550            for operation in &commit.ops {
5551                self.overlay_dirty.table(&operation.table);
5552            }
5553        }
5554        self.failed_commits = self.load_failed_commits()?.into();
5555        for (commit, _) in self.failed_commits.iter() {
5556            for operation in &commit.ops {
5557                self.overlay_dirty.table(&operation.table);
5558            }
5559        }
5560        Ok(())
5561    }
5562
5563    fn load_failed_commits(&self) -> Result<Vec<FailedCommit>, String> {
5564        let mut statement = self.conn.prepare("SELECT client_commit_id, operations_json, initial_json FROM _syncular_failed_commits ORDER BY seq")
5565            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5566        let rows = statement
5567            .query_map([], |row| {
5568                Ok((
5569                    row.get::<_, String>(0)?,
5570                    row.get::<_, String>(1)?,
5571                    row.get::<_, String>(2)?,
5572                ))
5573            })
5574            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5575        rows.map(|row| {
5576            let (id, operations, initial) =
5577                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5578            let operations: Vec<CommitOperation> =
5579                serde_json::from_str(&operations).map_err(|_| "sync.local_corrupt".to_owned())?;
5580            let initial =
5581                serde_json::from_str(&initial).map_err(|_| "sync.local_corrupt".to_owned())?;
5582            Ok((
5583                OutboxCommit {
5584                    client_commit_id: id,
5585                    ops: operations
5586                        .into_iter()
5587                        .map(|op| OutboxOp {
5588                            upsert: op.op == "upsert",
5589                            table: op.table,
5590                            row_id: op.row_id,
5591                            base_version: op.base_version,
5592                            values: op.values,
5593                            insert: op.insert,
5594                        })
5595                        .collect(),
5596                },
5597                initial,
5598            ))
5599        })
5600        .collect()
5601    }
5602
5603    fn retain_failed_commit(&mut self, id: &str, operations: &[OutboxOp]) -> Result<(), String> {
5604        let mut initial = Map::new();
5605        for operation in operations {
5606            // A table the current schema removed has no rows to retain.
5607            let Some(table) = self.schema.table(&operation.table) else {
5608                continue;
5609            };
5610            let initial_row = match self.stored_row(table, &operation.row_id, true)? {
5611                Some(row) => Some(row),
5612                None => self.visible_row(table, &operation.row_id)?,
5613            };
5614            if let Some((values, _)) = initial_row {
5615                let mut intended: Map<String, Value> = table
5616                    .columns
5617                    .iter()
5618                    .zip(values.iter())
5619                    .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
5620                    .collect();
5621                if let Some(patch) = &operation.values {
5622                    intended.extend(patch.clone());
5623                }
5624                initial.insert(
5625                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5626                        .map_err(|_| "sync.local_corrupt".to_owned())?,
5627                    Value::Object(intended),
5628                );
5629            }
5630        }
5631        self.conn.execute("INSERT INTO _syncular_failed_commits(client_commit_id, operations_json, initial_json) VALUES (?1, ?2, ?3)", rusqlite::params![id,
5632            serde_json::to_string(&operations.iter().map(CommitOperation::from).collect::<Vec<_>>()).map_err(|_| "sync.local_corrupt".to_owned())?,
5633            serde_json::to_string(&initial).map_err(|_| "sync.local_corrupt".to_owned())?])
5634            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5635        self.failed_commits.push((
5636            OutboxCommit {
5637                client_commit_id: id.to_owned(),
5638                ops: operations.to_vec(),
5639            },
5640            initial,
5641        ));
5642        Ok(())
5643    }
5644
5645    fn drop_failed_commits(
5646        &mut self,
5647        matches: impl Fn(&str, &Map<String, Value>) -> bool,
5648    ) -> Result<Vec<OutboxCommit>, String> {
5649        let mut doomed = self.drop_acknowledged_rows(&matches)?;
5650        for (commit, initial) in self.failed_commits.iter() {
5651            for operation in &commit.ops {
5652                let key =
5653                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5654                        .map_err(|_| "sync.local_corrupt".to_owned())?;
5655                if initial
5656                    .get(&key)
5657                    .and_then(Value::as_object)
5658                    .is_some_and(|values| matches(&operation.table, values))
5659                {
5660                    doomed.push(commit.clone());
5661                    break;
5662                }
5663            }
5664        }
5665        for commit in &doomed {
5666            self.conn
5667                .execute(
5668                    "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
5669                    rusqlite::params![commit.client_commit_id],
5670                )
5671                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5672        }
5673        for commit in &doomed {
5674            self.conn.execute("UPDATE _syncular_commit_outcomes SET operations_json = NULL, results_json = '[]' WHERE client_commit_id = ?1", rusqlite::params![commit.client_commit_id]).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5675        }
5676        self.conflicts.retain(|record| {
5677            !doomed
5678                .iter()
5679                .any(|commit| commit.client_commit_id == record.client_commit_id)
5680        });
5681        self.rejections.retain(|record| {
5682            !doomed
5683                .iter()
5684                .any(|commit| commit.client_commit_id == record.client_commit_id)
5685        });
5686        self.failed_commits.retain(|(commit, _)| {
5687            !doomed
5688                .iter()
5689                .any(|dropped| dropped.client_commit_id == commit.client_commit_id)
5690        });
5691        for commit in &doomed {
5692            for operation in &commit.ops {
5693                self.overlay_dirty.table(&operation.table);
5694            }
5695        }
5696        Ok(doomed)
5697    }
5698
5699    /// Record one commit of local mutations. The returned commit ID is the
5700    /// §2.3 idempotency key. Failures are structured so callers read
5701    /// `code`/`message`/`details` instead of parsing a string prefix.
5702    pub fn mutate(&mut self, mutations: Vec<Mutation>) -> Result<String, ClientError> {
5703        let prior = self.storage_failure.borrow_mut().take();
5704        let outcome = (|| -> Result<String, String> {
5705            if mutations.is_empty() {
5706                return Err(
5707                    "sync.invalid_request: a commit must contain at least one operation (§6.1)"
5708                        .to_owned(),
5709                );
5710            }
5711            let mut ops = Vec::with_capacity(mutations.len());
5712            for mutation in mutations {
5713                match mutation {
5714                    Mutation::Patch {
5715                        table,
5716                        values,
5717                        base_version,
5718                    } => {
5719                        let schema_table = self
5720                            .schema
5721                            .table(&table)
5722                            .ok_or_else(|| "sync.unknown_table".to_owned())?;
5723                        let values = normalize_values_casing(schema_table, values)?;
5724                        let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
5725                        ops.push(self.prepare_patch(&table, &row_id, values, base_version)?);
5726                    }
5727                    Mutation::Upsert {
5728                        table,
5729                        values,
5730                        base_version,
5731                    } => {
5732                        let schema_table = self.schema.table(&table).ok_or_else(|| {
5733                            format!("sync.unknown_table: unknown table {table:?}")
5734                        })?;
5735                        // §5: value keys are accepted in snake_case AND the
5736                        // generated row types' camelCase; normalize to SQL truth
5737                        // before the pk lookup / codec see them.
5738                        let values = normalize_values_casing(schema_table, values)?;
5739                        let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
5740                        // §6.7 `mutate` marks every column present: fill missing
5741                        // nullable columns with NULL before the payload is built.
5742                        let values = full_row_values(schema_table, values)?;
5743                        // §5.11: validate the payload encodes with the current
5744                        // codec. A key-selection or unknown-key failure is a
5745                        // durable rejection at the push seam (§10.3), never an
5746                        // author-time error. Full-row `mutate` presents every
5747                        // column, so no stored fallback is needed.
5748                        self.validate_author_encode(schema_table, &row_id, &values)?;
5749                        // §7.1 insert intent: the row is absent from the
5750                        // visible replica at call time, before this batch
5751                        // applies anything.
5752                        let insert = !self.visible_row_exists(schema_table, &row_id)?;
5753                        ops.push(OutboxOp {
5754                            upsert: true,
5755                            table,
5756                            row_id,
5757                            base_version,
5758                            values: Some(values),
5759                            insert,
5760                        });
5761                    }
5762                    Mutation::Delete {
5763                        table,
5764                        row_id,
5765                        base_version,
5766                    } => {
5767                        if self.schema.table(&table).is_none() {
5768                            return Err(format!("sync.unknown_table: unknown table {table:?}"));
5769                        }
5770                        // §2.4: the server rejects a rowId holding U+0000.
5771                        if row_id.contains('\0') {
5772                            return Err(
5773                                "sync.invalid_request: rowId holds U+0000 (§2.4)".to_owned()
5774                            );
5775                        }
5776                        ops.push(OutboxOp {
5777                            upsert: false,
5778                            table,
5779                            row_id,
5780                            base_version,
5781                            values: None,
5782                            insert: false,
5783                        });
5784                    }
5785                }
5786            }
5787            self.record_outbox_commit(ops)
5788        })();
5789        self.finish_authoring(prior, outcome)
5790    }
5791
5792    /// Scope the retained `storage_failure` diagnostic to this call so an
5793    /// earlier operation's failure cannot classify a new one, and surface the
5794    /// call's own classified failure with its details. A fresh classified
5795    /// failure replaces the retained diagnostic; otherwise the earlier one is
5796    /// kept for the next sync.
5797    fn finish_authoring(
5798        &self,
5799        prior: Option<QueryReadFailure>,
5800        outcome: Result<String, String>,
5801    ) -> Result<String, ClientError> {
5802        let fresh = self.storage_failure.borrow_mut().take();
5803        *self.storage_failure.borrow_mut() = fresh.clone().or(prior);
5804        match outcome {
5805            Ok(id) => Ok(id),
5806            Err(message) => Err(fresh
5807                .map(ClientError::from)
5808                .unwrap_or_else(|| ClientError::from(message))),
5809        }
5810    }
5811
5812    fn record_outbox_commit(&mut self, ops: Vec<OutboxOp>) -> Result<String, String> {
5813        let commit = OutboxCommit {
5814            client_commit_id: uuid::Uuid::new_v4().to_string(),
5815            ops,
5816        };
5817        self.begin_observation("syncular_mutation")?;
5818        let mut batch = ChangeAccumulator::default();
5819        for op in &commit.ops {
5820            let mut precise = self.record_row_scopes(&mut batch, &op.table, &op.row_id, false);
5821            if let Some(values) = &op.values {
5822                if let Some(table) = self.schema.table(&op.table) {
5823                    for scope in &table.scope_variables {
5824                        if let Some(Value::String(value)) = values.get(&scope.column) {
5825                            batch.scope(&op.table, format!("{}:{value}", scope.prefix));
5826                            precise = true;
5827                        }
5828                    }
5829                }
5830            }
5831            if !precise {
5832                batch.table(&op.table);
5833            }
5834        }
5835        if let Err(error) = self.persist_outbox_insert(&commit) {
5836            self.rollback_observation("syncular_mutation");
5837            return Err(error);
5838        }
5839        // A clean overlay contains the FIFO fold of every previous commit, so
5840        // the new commit applies over it. §7.1: an operation that does not
5841        // apply (a secondary unique collision) fails the whole commit; the
5842        // savepoint rollback removes the outbox entry and every visible write.
5843        // The append undoes itself: a rollback capture would copy the outbox.
5844        let was_dirty = self.overlay_dirty.snapshot();
5845        let id = commit.client_commit_id.clone();
5846        let appended = self.rebuild_overlay_if_dirty().and_then(|()| {
5847            commit
5848                .ops
5849                .iter()
5850                .try_for_each(|op| self.apply_outbox_op(op))?;
5851            self.outbox.push(Arc::new(commit));
5852            batch.status = true;
5853            self.finish_observation("syncular_mutation", batch)
5854                .inspect_err(|_| drop(self.outbox.pop()))
5855        });
5856        if let Err(error) = appended {
5857            self.rollback_observation("syncular_mutation");
5858            self.overlay_dirty.restore(was_dirty);
5859            return Err(error);
5860        }
5861        Ok(id)
5862    }
5863
5864    /// Record one §6.1 sparse upsert: the primary key plus the supplied
5865    /// non-scope columns are present; every other column is absent and stays
5866    /// untouched on the server and in the local overlay. An absent local base
5867    /// refuses the whole batch with sync.row_missing before enqueueing (§7.1).
5868    /// Failures are structured so callers read `code`/`message`/`details`.
5869    pub fn patch(
5870        &mut self,
5871        table: &str,
5872        row_id: &str,
5873        partial: Map<String, Value>,
5874        base_version: Option<i64>,
5875    ) -> Result<String, ClientError> {
5876        let prior = self.storage_failure.borrow_mut().take();
5877        let outcome = self.perform_patch(table, row_id, partial, base_version);
5878        self.finish_authoring(prior, outcome)
5879    }
5880
5881    /// The unscoped patch body. Public authoring entry points scope
5882    /// `storage_failure` around the whole operation, including any pre-read.
5883    fn perform_patch(
5884        &mut self,
5885        table: &str,
5886        row_id: &str,
5887        partial: Map<String, Value>,
5888        base_version: Option<i64>,
5889    ) -> Result<String, String> {
5890        let operation = self.prepare_patch(table, row_id, partial, base_version)?;
5891        self.record_outbox_commit(vec![operation])
5892    }
5893
5894    fn prepare_patch(
5895        &self,
5896        table: &str,
5897        row_id: &str,
5898        partial: Map<String, Value>,
5899        base_version: Option<i64>,
5900    ) -> Result<OutboxOp, String> {
5901        let schema_table = self
5902            .schema
5903            .table(table)
5904            .ok_or_else(|| format!("sync.unknown_table: unknown table {table:?}"))?;
5905        let partial = normalize_values_casing(schema_table, partial)?;
5906        if let Some(pk) = partial.get(&schema_table.primary_key) {
5907            if render_row_id_json(Some(pk)).ok().as_deref() != Some(row_id) {
5908                return Err(format!(
5909                    "sync.invalid_request: table {table:?}: patch cannot change the primary key"
5910                ));
5911            }
5912        }
5913        if !self.visible_row_exists(schema_table, row_id)? {
5914            return Err("sync.row_missing: a sparse patch requires a local row".to_owned());
5915        }
5916        // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
5917        // server accepts a present scope column whose value equals the
5918        // stored row and applies it as a no-op, so a decoded envelope
5919        // round-trips. The local row is the only value the client can prove
5920        // equality against; when the row is absent locally the client cannot
5921        // prove equality against the server's stored row and fails closed.
5922        // A primary key that is also a scope column needs no stored-row
5923        // read: the primary key in a sparse payload is by construction the
5924        // row id being patched (§6.1), so its value is proven equal already.
5925        for scope in &schema_table.scope_variables {
5926            if !partial.contains_key(&scope.column) || scope.column == schema_table.primary_key {
5927                continue;
5928            }
5929            let Some(column) = schema_table
5930                .columns
5931                .iter()
5932                .find(|column| column.name == scope.column)
5933            else {
5934                continue;
5935            };
5936            let stored = self
5937                .conn
5938                .query_row(
5939                    &format!(
5940                        "SELECT {} FROM {} WHERE {}",
5941                        quote_ident(&scope.column),
5942                        visible_table(&schema_table.name),
5943                        row_id_predicate(schema_table)
5944                    ),
5945                    rusqlite::params![row_id],
5946                    |row| Ok(sql_ref_to_json(column, row.get_ref(0)?)),
5947                )
5948                .optional()
5949                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5950            // Decode the supplied value through the same column-type path the
5951            // rest of the patch encoding uses, so a value that only equals
5952            // the stored one in another number representation still compares
5953            // equal.
5954            let incoming = json_to_column_value(column, partial.get(&scope.column))
5955                .ok()
5956                .map(|value| column_value_to_json(&value));
5957            // A stored blob never equals a patch value, matching the server's
5958            // scope-column comparison (§3.4): bytes are unstorable as scope
5959            // values.
5960            let equal = stored.as_ref().is_some_and(|stored| {
5961                stored.get("$bytes").is_none() && incoming.as_ref() == Some(stored)
5962            });
5963            if !equal {
5964                return Err(format!(
5965                    "sync.invalid_request: table {table:?}: patch cannot write scope column {:?} (§3.4)",
5966                    scope.column
5967                ));
5968            }
5969        }
5970        let mut values = partial;
5971        // Presence-set semantics: a proven-equal scope column is dropped, so
5972        // the patch leaves the stored value untouched (§6.2).
5973        for scope in &schema_table.scope_variables {
5974            values.remove(&scope.column);
5975        }
5976        let pk_value = match schema_table.columns[schema_table.pk_index].ty {
5977            // §2.4: the rowId of an integer key is its canonical decimal form.
5978            ColumnType::Integer => match row_id.parse::<i64>() {
5979                Ok(v)
5980                    if v.to_string() == row_id
5981                        && (-ssp2::primitives::I64_SAFE_MAX..=ssp2::primitives::I64_SAFE_MAX)
5982                            .contains(&v) =>
5983                {
5984                    Value::from(v)
5985                }
5986                _ => {
5987                    return Err(format!(
5988                    "sync.invalid_request: table {table:?}: invalid integer primary key {row_id:?}"
5989                ))
5990                }
5991            },
5992            ColumnType::Boolean => match row_id {
5993                "true" => Value::Bool(true),
5994                "false" => Value::Bool(false),
5995                _ => {
5996                    return Err(format!(
5997                    "sync.invalid_request: table {table:?}: invalid boolean primary key {row_id:?}"
5998                ))
5999                }
6000            },
6001            _ => Value::from(row_id.to_owned()),
6002        };
6003        values.insert(schema_table.primary_key.clone(), pk_value);
6004        // §5.11: structural validation only; an absent key-id selector is
6005        // resolved at the push seam from the stored local row, and a
6006        // key-selection or unknown-key failure becomes a durable
6007        // `client.encrypt_failed` rejection there (§10.3), never an
6008        // author-time error.
6009        self.validate_author_encode(schema_table, row_id, &values)?;
6010        Ok(OutboxOp {
6011            upsert: true,
6012            table: table.to_owned(),
6013            row_id: row_id.to_owned(),
6014            base_version,
6015            values: Some(values),
6016            insert: false,
6017        })
6018    }
6019
6020    /// §5.11 key-id fallback: the stored local row's selector value as a
6021    /// positional row (only the selector slot filled). Returns None when no
6022    /// selector is configured, the row is locally absent, or the stored
6023    /// value is not a usable key id. A failed storage read is an error.
6024    fn stored_key_fallback(
6025        &self,
6026        table: &TableSchema,
6027        row_id: &str,
6028    ) -> Result<Option<Row>, String> {
6029        let Some(selector) = self.encryption.key_id_columns.get(&table.name) else {
6030            return Ok(None);
6031        };
6032        let Some(index) = table
6033            .columns
6034            .iter()
6035            .position(|column| &column.name == selector)
6036        else {
6037            return Ok(None);
6038        };
6039        let sql = format!(
6040            "SELECT {} FROM {} WHERE {}",
6041            quote_ident(selector),
6042            visible_table(&table.name),
6043            row_id_predicate(table)
6044        );
6045        let key = self
6046            .conn
6047            .query_row(&sql, rusqlite::params![row_id], |row| {
6048                row.get::<_, Option<String>>(0)
6049            })
6050            .optional()
6051            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6052            .flatten()
6053            .filter(|key| !key.is_empty());
6054        let Some(key) = key else {
6055            return Ok(None);
6056        };
6057        let mut fallback: Row = vec![None; table.columns.len()];
6058        fallback[index] = Some(ColumnValue::String(key));
6059        Ok(Some(fallback))
6060    }
6061
6062    /// §5.11/§10.3 author-time encode check: a structural failure (a
6063    /// non-nullable NULL, a value the codec rejects) is an author-time
6064    /// error; a key-selection or unknown-key failure is deferred to the push
6065    /// seam, where it becomes a durable `client.encrypt_failed` rejection.
6066    fn validate_author_encode(
6067        &self,
6068        table: &TableSchema,
6069        row_id: &str,
6070        values: &Map<String, Value>,
6071    ) -> Result<(), String> {
6072        match encode_sparse_row_json(table, row_id, values, &self.encryption, None) {
6073            Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => Ok(()),
6074            result => result.map(|_| ()),
6075        }
6076    }
6077
6078    /// §5.11/§10.3: drop every pending commit whose push encode fails with
6079    /// `client.encrypt_failed` (an unresolvable key id or an unknown key) and
6080    /// raise one durable rejection per commit. `sync()` never aborts for an
6081    /// encode failure. Mirrors §7.4.4's `drop_incompatible_outbox`, including
6082    /// undoing the dropped commit's purely-optimistic rows.
6083    /// §7.1/§7.4.4: drop pending commits whose values the current codec refuses
6084    /// (an envelope or a type an earlier version accepted). `with_encryption`
6085    /// additionally drops commits whose §5.11 encryption cannot resolve a key;
6086    /// the startup boundary leaves those to the send seam, where hosts configure
6087    /// keys after open.
6088    /// Recovery runs as one observation. An enclosing observation (the guarded
6089    /// schema reset) passes its `batch`, so the rejection, outcome, and table
6090    /// domains join that change event instead of publishing a second one.
6091    fn drop_unencodable_outbox(
6092        &mut self,
6093        with_encryption: bool,
6094        batch: Option<&mut ChangeAccumulator>,
6095    ) -> Result<bool, String> {
6096        let mut failures = Vec::new();
6097        for commit in self.outbox.iter() {
6098            for op in &commit.ops {
6099                let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6100                    continue;
6101                };
6102                // An insert lacking a non-nullable column is left to
6103                // `drop_incompatible_outbox` (§7.4.4).
6104                let Some(values) = op.presented_values(table) else {
6105                    continue;
6106                };
6107                let fallback = self.stored_key_fallback(table, &op.row_id)?;
6108                let failure = match encode_sparse_row_json(
6109                    table,
6110                    &op.row_id,
6111                    &values,
6112                    &self.encryption,
6113                    fallback.as_ref(),
6114                ) {
6115                    Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => {
6116                        with_encryption.then_some((error, ENCRYPT_FAILED_CODE))
6117                    }
6118                    // §7.1/§7.4.4: a value the current codec refuses was
6119                    // persisted by a version that accepted it; it leaves
6120                    // through the incompatible-outbox path, so the FIFO
6121                    // queue never wedges.
6122                    Err(error) if error.starts_with(INVALID_REQUEST_CODE) => Some((
6123                        LEGACY_VALUE_REFUSAL_MESSAGE.to_owned(),
6124                        OUTBOX_INCOMPATIBLE_CODE,
6125                    )),
6126                    _ => None,
6127                };
6128                if let Some((error, code)) = failure {
6129                    failures.push((commit.clone(), error, code));
6130                    break;
6131                }
6132            }
6133        }
6134        if failures.is_empty() {
6135            return Ok(false);
6136        }
6137        // §7.4.4: one observation covers the durable outcome writes, the outbox
6138        // removal, the in-memory drop, and the overlay rebuild, so a storage fault
6139        // leaves the replica and the client unchanged, a successful recovery
6140        // publishes one batch with the rejection, outcome, and table domains, and
6141        // an ordinary open with nothing to recover publishes nothing.
6142        let rollback = self.capture();
6143        let owns_observation = batch.is_none();
6144        let owns_transaction = self.conn.is_autocommit();
6145        let mut domains = ChangeAccumulator::default();
6146        if owns_observation {
6147            self.begin_observation("syncular_value_recovery")?;
6148        }
6149        let dropped = (|| -> Result<(), String> {
6150            for (commit, message, code) in failures {
6151                if self.retain_failed_commits && code == ENCRYPT_FAILED_CODE {
6152                    self.retain_failed_commit(&commit.client_commit_id, &commit.ops)?;
6153                }
6154                let representable = commit.ops.iter().all(Self::outbox_op_is_journalable);
6155                let rejection = RejectionRecord {
6156                    client_commit_id: commit.client_commit_id.clone(),
6157                    op_index: 0,
6158                    code: code.to_owned(),
6159                    message,
6160                    retryable: false,
6161                    details: (code == OUTBOX_INCOMPATIBLE_CODE).then(|| RejectionDetails {
6162                        field_paths: None,
6163                        reason: Some(INVALID_STORED_VALUES_REASON.to_owned()),
6164                        required_action: None,
6165                        references: None,
6166                    }),
6167                    operation: representable
6168                        .then(|| commit.ops.first())
6169                        .flatten()
6170                        .map(CommitOperation::from),
6171                };
6172                self.persist_commit_outcome(
6173                    &commit.client_commit_id,
6174                    CommitOutcomeStatus::Rejected,
6175                    &[CommitOperationOutcome::Error {
6176                        rejection: rejection.clone(),
6177                    }],
6178                    representable.then_some(commit.ops.as_slice()),
6179                )?;
6180                self.delete_outbox_persisted(&commit.client_commit_id)?;
6181                self.outbox
6182                    .retain(|candidate| candidate.client_commit_id != commit.client_commit_id);
6183                self.rejections.push(rejection);
6184                for operation in &commit.ops {
6185                    domains.table(operation.table.as_str());
6186                }
6187            }
6188            domains.status = true;
6189            domains.rejections = true;
6190            domains.outcomes = true;
6191            self.prune_commit_outcomes()?;
6192            // The visible projection is re-derived from the surviving base + outbox.
6193            self.overlay_dirty.set(true);
6194            self.rebuild_overlay()?;
6195            Ok(())
6196        })();
6197        let result = match batch {
6198            Some(batch) => {
6199                if dropped.is_ok() {
6200                    for table in domains.tables.keys() {
6201                        batch.table(table.as_str());
6202                    }
6203                    batch.status |= domains.status;
6204                    batch.rejections |= domains.rejections;
6205                    batch.outcomes |= domains.outcomes;
6206                }
6207                dropped
6208            }
6209            None => {
6210                dropped.and_then(|()| self.finish_observation("syncular_value_recovery", domains))
6211            }
6212        };
6213        if let Err(error) = result {
6214            if owns_observation {
6215                if owns_transaction {
6216                    if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
6217                        let mut failure = self.storage_failure.borrow_mut();
6218                        let failure =
6219                            failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
6220                        failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
6221                    }
6222                } else {
6223                    self.rollback_observation("syncular_value_recovery");
6224                }
6225            }
6226            self.restore(rollback);
6227            return Err(error);
6228        }
6229        Ok(true)
6230    }
6231
6232    pub fn pending_commit_ids(&self) -> Vec<String> {
6233        self.outbox
6234            .iter()
6235            .map(|c| c.client_commit_id.clone())
6236            .collect()
6237    }
6238
6239    /// §6.1: the sparse push payload bytes of every pending upsert operation,
6240    /// FIFO — exactly what the next push round would put on the wire. Used by
6241    /// conformance B.21(h) to pin cross-core byte identity.
6242    pub fn pending_payloads(&self) -> Result<Vec<Vec<u8>>, String> {
6243        let mut payloads = Vec::new();
6244        for commit in self.outbox.iter() {
6245            for op in &commit.ops {
6246                let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6247                    continue;
6248                };
6249                let Some(values) = op.presented_values(table) else {
6250                    continue;
6251                };
6252                let fallback = self.stored_key_fallback(table, &op.row_id)?;
6253                if let Ok(payload) = encode_sparse_row_json(
6254                    table,
6255                    &op.row_id,
6256                    &values,
6257                    &self.encryption,
6258                    fallback.as_ref(),
6259                ) {
6260                    payloads.push(payload);
6261                }
6262            }
6263        }
6264        Ok(payloads)
6265    }
6266
6267    pub fn conflicts(&self) -> &[ConflictRecord] {
6268        &self.conflicts
6269    }
6270
6271    pub fn rejections(&self) -> &[RejectionRecord] {
6272        &self.rejections
6273    }
6274
6275    pub fn resolve_commit_outcome(
6276        &mut self,
6277        input: ResolveCommitOutcomeInput,
6278    ) -> Result<CommitOutcome, String> {
6279        let current = self
6280            .commit_outcome(&input.client_commit_id)?
6281            .ok_or_else(|| {
6282                format!(
6283                    "sync.outcome_not_found: no durable outcome exists for {:?}",
6284                    input.client_commit_id
6285                )
6286            })?;
6287        if current.resolution != CommitOutcomeResolution::Active {
6288            return Ok(current);
6289        }
6290        if input.resolution == CommitOutcomeResolution::Active {
6291            return Err("sync.invalid_request: resolution must leave active state".to_owned());
6292        }
6293        match input.resolution {
6294            CommitOutcomeResolution::Superseded => {
6295                let replacement = input
6296                    .replacement_client_commit_id
6297                    .as_deref()
6298                    .filter(|value| !value.is_empty() && *value != input.client_commit_id)
6299                    .ok_or_else(|| {
6300                        "sync.invalid_request: superseded outcomes require a distinct replacementClientCommitId"
6301                            .to_owned()
6302                    })?;
6303                let _ = replacement;
6304            }
6305            _ if input.replacement_client_commit_id.is_some() => {
6306                return Err(
6307                    "sync.invalid_request: replacementClientCommitId is valid only for superseded outcomes"
6308                        .to_owned(),
6309                );
6310            }
6311            _ => {}
6312        }
6313        let allowed = match current.status {
6314            CommitOutcomeStatus::Conflict => matches!(
6315                input.resolution,
6316                CommitOutcomeResolution::ResolvedKeepServer | CommitOutcomeResolution::Superseded
6317            ),
6318            CommitOutcomeStatus::Rejected => {
6319                matches!(
6320                    input.resolution,
6321                    CommitOutcomeResolution::Superseded
6322                        | CommitOutcomeResolution::ResolvedKeepServer
6323                )
6324            }
6325            CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => {
6326                input.resolution == CommitOutcomeResolution::Dismissed
6327            }
6328        };
6329        if !allowed {
6330            return Err(format!(
6331                "sync.invalid_request: resolution {:?} is invalid for {:?} outcome",
6332                input.resolution, current.status
6333            ));
6334        }
6335
6336        let rollback = self.capture();
6337        self.begin_observation("syncular_outcome_resolution")?;
6338        let result = (|| {
6339            self.conn
6340                .execute(
6341                    "UPDATE _syncular_commit_outcomes
6342                        SET resolution = ?1, resolved_at_ms = ?2,
6343                            replacement_client_commit_id = ?3
6344                      WHERE client_commit_id = ?4 AND resolution = 'active'",
6345                    rusqlite::params![
6346                        Self::outcome_resolution_name(input.resolution),
6347                        self.clock_now_ms(),
6348                        input.replacement_client_commit_id,
6349                        input.client_commit_id
6350                    ],
6351                )
6352                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6353            let resolved = self
6354                .commit_outcome(&current.client_commit_id)?
6355                .ok_or_else(|| "sync.outcome_not_found: outcome disappeared".to_owned())?;
6356            self.conn
6357                .execute(
6358                    "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
6359                    rusqlite::params![input.client_commit_id],
6360                )
6361                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6362            for (commit, _) in self.failed_commits.iter() {
6363                if commit.client_commit_id == input.client_commit_id {
6364                    for operation in &commit.ops {
6365                        self.overlay_dirty.table(&operation.table);
6366                    }
6367                }
6368            }
6369            self.failed_commits
6370                .retain(|(commit, _)| commit.client_commit_id != input.client_commit_id);
6371            self.prune_commit_outcomes()?;
6372            Ok(resolved)
6373        })();
6374        let resolved = match result {
6375            Ok(outcome) => outcome,
6376            Err(error) => {
6377                self.rollback_observation("syncular_outcome_resolution");
6378                self.restore(rollback);
6379                return Err(error);
6380            }
6381        };
6382        self.conflicts
6383            .retain(|record| record.client_commit_id != current.client_commit_id);
6384        self.rejections
6385            .retain(|record| record.client_commit_id != current.client_commit_id);
6386        let mut batch = ChangeAccumulator {
6387            conflicts: current.status == CommitOutcomeStatus::Conflict,
6388            rejections: current.status == CommitOutcomeStatus::Rejected,
6389            outcomes: true,
6390            ..ChangeAccumulator::default()
6391        };
6392        if let Some(operations) = &current.operations {
6393            for operation in operations {
6394                batch.table(&operation.table);
6395            }
6396        }
6397        if let Err(error) = self
6398            .rebuild_overlay_if_dirty()
6399            .and_then(|()| self.finish_observation("syncular_outcome_resolution", batch))
6400        {
6401            self.rollback_observation("syncular_outcome_resolution");
6402            self.restore(rollback);
6403            return Err(error);
6404        }
6405        Ok(resolved)
6406    }
6407
6408    pub fn schema_floor(&self) -> Option<&SchemaFloor> {
6409        self.schema_floor.as_ref()
6410    }
6411
6412    /// §7.3.5: the client's opaque auth-lease state, if any.
6413    pub fn lease_state(&self) -> Option<&LeaseState> {
6414        self.lease_state.as_ref()
6415    }
6416
6417    /// §7.3.5: record a request-level lease error (stop-and-surface). Only
6418    /// the two lease codes set it; other errors leave leaseState untouched.
6419    fn record_lease_error(&mut self, code: &str) -> Result<(), String> {
6420        if code != "sync.auth_lease_required" && code != "sync.auth_lease_revoked" {
6421            return Ok(());
6422        }
6423        let mut next = self.lease_state.clone().unwrap_or_default();
6424        next.error_code = Some(code.to_owned());
6425        self.set_lease_state(Some(next))
6426    }
6427
6428    fn set_lease_state(&mut self, next: Option<LeaseState>) -> Result<(), String> {
6429        if self.lease_state == next {
6430            return Ok(());
6431        }
6432        self.begin_observation("syncular_lease")?;
6433        let rollback = self.capture();
6434        self.lease_state = next;
6435        let persisted = match &self.lease_state {
6436            Some(lease) => serde_json::to_string(lease)
6437                .map_err(|error| error.to_string())
6438                .and_then(|json| self.set_meta(LEASE_STATE_KEY, &json)),
6439            None => self.delete_meta(LEASE_STATE_KEY),
6440        };
6441        let batch = ChangeAccumulator {
6442            status: true,
6443            ..ChangeAccumulator::default()
6444        };
6445        if let Err(error) =
6446            persisted.and_then(|()| self.finish_observation("syncular_lease", batch))
6447        {
6448            self.rollback_observation("syncular_lease");
6449            self.restore(rollback);
6450            return Err(error);
6451        }
6452        Ok(())
6453    }
6454
6455    fn set_schema_floor(&mut self, next: Option<SchemaFloor>) -> Result<(), String> {
6456        if self.schema_floor == next {
6457            return Ok(());
6458        }
6459        self.begin_observation("syncular_schema_floor")?;
6460        let rollback = self.capture();
6461        self.stopped = next.is_some();
6462        self.schema_floor = next;
6463        let persisted = match &self.schema_floor {
6464            Some(floor) => serde_json::to_string(floor)
6465                .map_err(|error| error.to_string())
6466                .and_then(|json| self.set_meta(SCHEMA_FLOOR_KEY, &json)),
6467            None => self.delete_meta(SCHEMA_FLOOR_KEY),
6468        };
6469        let batch = ChangeAccumulator {
6470            status: true,
6471            ..ChangeAccumulator::default()
6472        };
6473        if let Err(error) =
6474            persisted.and_then(|()| self.finish_observation("syncular_schema_floor", batch))
6475        {
6476            self.rollback_observation("syncular_schema_floor");
6477            self.restore(rollback);
6478            return Err(error);
6479        }
6480        Ok(())
6481    }
6482
6483    fn set_upgrading(&mut self, value: bool) {
6484        if self.upgrading == value {
6485            return;
6486        }
6487        if self.begin_observation("syncular_upgrading").is_err() {
6488            return;
6489        }
6490        self.upgrading = value;
6491        let batch = ChangeAccumulator {
6492            status: true,
6493            ..ChangeAccumulator::default()
6494        };
6495        if self
6496            .finish_observation("syncular_upgrading", batch)
6497            .is_err()
6498        {
6499            self.rollback_observation("syncular_upgrading");
6500        }
6501    }
6502
6503    pub fn sync_needed(&self) -> bool {
6504        self.sync_needed
6505    }
6506
6507    pub fn read_rows(&self, table: &str) -> Result<Vec<RowState>, String> {
6508        let schema_table = self
6509            .schema
6510            .table(table)
6511            .ok_or_else(|| format!("unknown table {table:?}"))?;
6512        let sql = format!(
6513            "SELECT * FROM {} ORDER BY {} ASC",
6514            visible_table(table),
6515            quote_ident(&schema_table.primary_key)
6516        );
6517        let mut stmt = self
6518            .conn
6519            .prepare(&sql)
6520            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6521        let mut rows = stmt
6522            .query([])
6523            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6524        let mut out = Vec::new();
6525        while let Some(row) = rows
6526            .next()
6527            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6528        {
6529            let mut values = Map::new();
6530            for (i, column) in schema_table.columns.iter().enumerate() {
6531                let value = row
6532                    .get_ref(i)
6533                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6534                values.insert(column.name.clone(), sql_ref_to_json(column, value));
6535            }
6536            let version: i64 = row
6537                .get(schema_table.columns.len())
6538                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6539            let row_id = match values.get(&schema_table.primary_key) {
6540                Some(Value::String(s)) => s.clone(),
6541                Some(Value::Number(n)) => n.to_string(),
6542                Some(Value::Bool(b)) => b.to_string(),
6543                other => format!("{}", other.cloned().unwrap_or(Value::Null)),
6544            };
6545            out.push(RowState {
6546                row_id,
6547                version,
6548                values,
6549            });
6550        }
6551        Ok(out)
6552    }
6553
6554    // -- §5.10.5 native CRDT (the `crdt-yjs` feature) --------------------------
6555    //
6556    // The Rust face of the §5.10.4 client model: a local crdt edit loads the
6557    // current stored (server-merged ⊕ pending-overlay) column bytes, applies
6558    // the op with `yrs`, re-encodes the whole doc state, and records a
6559    // baseVersion-less sparse upsert carrying only the primary key and the
6560    // crdt column (§5.10.3, §6.6). No local merge — merging is server-side;
6561    // the overlay re-materializes the edit immediately (optimistic apply,
6562    // §7.1) and the server-merged bytes arrive on the next pull, idempotently.
6563    // Byte-compatible with `@syncular/crdt-yjs`.
6564
6565    /// The current stored value of a `crdt` column for one row — the visible
6566    /// (optimistic) bytes, or `None` when the row is absent or the column is
6567    /// NULL (the empty document, §5.10.1). Errors if the column is not a
6568    /// `crdt` column (guards the app against a typo'd column name).
6569    #[cfg(feature = "crdt-yjs")]
6570    fn crdt_column_bytes(
6571        &self,
6572        table: &str,
6573        row_id: &str,
6574        column: &str,
6575    ) -> Result<Option<Vec<u8>>, String> {
6576        let schema_table = self
6577            .schema
6578            .table(table)
6579            .ok_or_else(|| format!("unknown table {table:?}"))?;
6580        let col = schema_table
6581            .columns
6582            .iter()
6583            .find(|c| c.name == column)
6584            .ok_or_else(|| format!("table {table:?} has no column {column:?}"))?;
6585        if col.ty != ColumnType::Crdt {
6586            return Err(format!("column {column:?} is not a crdt column (§5.10.1)"));
6587        }
6588        let sql = format!(
6589            "SELECT {} FROM {} WHERE {}",
6590            quote_ident(column),
6591            visible_table(table),
6592            row_id_predicate(schema_table)
6593        );
6594        let bytes: Option<Vec<u8>> = self
6595            .conn
6596            .prepare_cached(&sql)
6597            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6598            .query_row(rusqlite::params![row_id], |row| {
6599                row.get::<_, Option<Vec<u8>>>(0)
6600            })
6601            .map_err(|e| match e {
6602                rusqlite::Error::QueryReturnedNoRows => "no such row".to_owned(),
6603                other => Self::sqlite_failure(&self.storage_failure, other),
6604            })?;
6605        Ok(bytes)
6606    }
6607
6608    /// §5.10.4 materialize: the collaborative text of a `crdt` column, decoded
6609    /// from the stored bytes with `yrs` — `YjsColumn.text(name).toString()`.
6610    /// An absent row / NULL column is the empty document (empty string).
6611    #[cfg(feature = "crdt-yjs")]
6612    pub fn crdt_text(
6613        &self,
6614        table: &str,
6615        row_id: &str,
6616        column: &str,
6617        name: &str,
6618    ) -> Result<String, String> {
6619        let bytes = self
6620            .crdt_column_bytes(table, row_id, column)?
6621            .unwrap_or_default();
6622        crate::crdt::text(&bytes, name)
6623    }
6624
6625    /// §5.10.4 push-an-update: apply a text insert to a `crdt` column and
6626    /// record the resulting crdt-only sparse operation. Returns the enqueued
6627    /// `clientCommitId`.
6628    #[cfg(feature = "crdt-yjs")]
6629    pub fn crdt_insert_text(
6630        &mut self,
6631        table: &str,
6632        row_id: &str,
6633        column: &str,
6634        name: &str,
6635        index: u32,
6636        value: &str,
6637    ) -> Result<String, ClientError> {
6638        let prior = self.storage_failure.borrow_mut().take();
6639        let outcome = (|| -> Result<String, String> {
6640            let current = self
6641                .crdt_column_bytes(table, row_id, column)?
6642                .unwrap_or_default();
6643            let update = crate::crdt::insert_text(&current, name, index, value)?;
6644            self.perform_crdt_push_update(table, row_id, column, &update)
6645        })();
6646        self.finish_authoring(prior, outcome)
6647    }
6648
6649    /// §5.10.4 push-an-update: apply a text delete to a `crdt` column and
6650    /// record the resulting crdt-only sparse operation. Returns the enqueued
6651    /// `clientCommitId`.
6652    #[cfg(feature = "crdt-yjs")]
6653    pub fn crdt_delete_text(
6654        &mut self,
6655        table: &str,
6656        row_id: &str,
6657        column: &str,
6658        name: &str,
6659        index: u32,
6660        len: u32,
6661    ) -> Result<String, ClientError> {
6662        let prior = self.storage_failure.borrow_mut().take();
6663        let outcome = (|| -> Result<String, String> {
6664            let current = self
6665                .crdt_column_bytes(table, row_id, column)?
6666                .unwrap_or_default();
6667            let update = crate::crdt::delete_text(&current, name, index, len)?;
6668            self.perform_crdt_push_update(table, row_id, column, &update)
6669        })();
6670        self.finish_authoring(prior, outcome)
6671    }
6672
6673    /// §5.10.4 generic escape hatch: apply an arbitrary Yjs update onto a
6674    /// `crdt` column's current state and record the resulting crdt-only sparse
6675    /// operation. The app authored the update with its own `yrs` model.
6676    /// Returns the enqueued `clientCommitId`.
6677    #[cfg(feature = "crdt-yjs")]
6678    pub fn crdt_apply_update(
6679        &mut self,
6680        table: &str,
6681        row_id: &str,
6682        column: &str,
6683        update: &[u8],
6684    ) -> Result<String, ClientError> {
6685        let prior = self.storage_failure.borrow_mut().take();
6686        let outcome = (|| -> Result<String, String> {
6687            let current = self
6688                .crdt_column_bytes(table, row_id, column)?
6689                .unwrap_or_default();
6690            let next = crate::crdt::apply_update(&current, update)?;
6691            self.perform_crdt_push_update(table, row_id, column, &next)
6692        })();
6693        self.finish_authoring(prior, outcome)
6694    }
6695
6696    /// Shared tail of the crdt edit methods: record a §6.1 sparse crdt-only
6697    /// upsert — the primary key plus the crdt column, no `baseVersion` — and
6698    /// enqueue it. The server merges the crdt column and leaves every other
6699    /// column untouched (§5.10.3), so a baseVersion-less crdt edit cannot
6700    /// clobber a concurrent edit to another column. A locally absent row
6701    /// records the same partial operation; the server answers per §6.2.
6702    #[cfg(feature = "crdt-yjs")]
6703    fn perform_crdt_push_update(
6704        &mut self,
6705        table: &str,
6706        row_id: &str,
6707        column: &str,
6708        crdt_bytes: &[u8],
6709    ) -> Result<String, String> {
6710        let mut bytes_obj = Map::new();
6711        bytes_obj.insert("$bytes".to_owned(), Value::from(bytes_to_hex(crdt_bytes)));
6712        let mut partial = Map::new();
6713        partial.insert(column.to_owned(), Value::Object(bytes_obj));
6714        self.perform_patch(table, row_id, partial, None)
6715    }
6716
6717    /// Run an arbitrary read-only SQL query against the local database and
6718    /// return each row as a `column-name → JSON value` map. This is the seam
6719    /// the React `useSyncQuery` live-query API needs (it takes app-authored
6720    /// SQL over the visible tables/views, not a fixed table read like
6721    /// [`read_rows`]).
6722    ///
6723    /// Bound `params` are the driver value forms: JSON strings/numbers/bools/
6724    /// null bind directly; a `{"$bytes": hex}` object binds as a BLOB — the
6725    /// same envelope the command surface uses everywhere else. Output BLOB
6726    /// columns come back as `{"$bytes": hex}` to round-trip cleanly.
6727    ///
6728    /// The result column typing is dynamic (SQLite's stored affinity), because
6729    /// arbitrary SQL can alias, join, and compute — there is no schema column
6730    /// to consult per output cell, unlike [`read_rows`].
6731    pub fn query(&self, sql: &str, params: &[QueryValue]) -> Result<Vec<QueryRow>, String> {
6732        query_connection(&self.conn, sql, params).map_err(|failure| failure.to_string())
6733    }
6734
6735    /// Repository benchmark and conformance access, present only with `bench-internals`.
6736    #[cfg(feature = "bench-internals")]
6737    #[doc(hidden)]
6738    pub fn benchmark_connection(&mut self) -> &mut Connection {
6739        &mut self.conn
6740    }
6741
6742    /// Private benchmark intervals; absent from ordinary builds and diagnostics.
6743    #[cfg(feature = "bench-internals")]
6744    #[doc(hidden)]
6745    pub fn benchmark_phases(
6746        &self,
6747        enabled: Option<bool>,
6748        reset: bool,
6749    ) -> Result<Option<Value>, String> {
6750        self.benchmark_phases.configure(enabled, reset)?;
6751        Ok(self.benchmark_phases.snapshot())
6752    }
6753
6754    /// One serialized, read-only authority observation, including durable coverage.
6755    pub fn authority_snapshot(&self) -> Result<Value, String> {
6756        validate_authority_reads(&self.schema, &self.limits.authority_reads)?;
6757        if self.limits.authority_reads.is_empty() {
6758            return Err("client.authority_read_forbidden: no authority reads were declared at client creation".into());
6759        }
6760        self.conn
6761            .execute_batch("SAVEPOINT authority_snapshot")
6762            .map_err(|e| e.to_string())?;
6763        let result = (|| {
6764            let revision = self
6765                .get_meta(LOCAL_REVISION_KEY)?
6766                .ok_or("sync.local_corrupt: authority revision is missing")?;
6767            let parsed_revision = revision
6768                .parse::<u64>()
6769                .map_err(|_| "sync.local_corrupt: authority revision is invalid")?;
6770            if parsed_revision.to_string() != revision {
6771                return Err("sync.local_corrupt: authority revision is invalid".into());
6772            }
6773            let mut tables = Vec::new();
6774            for read in &self.limits.authority_reads {
6775                let table = self
6776                    .schema
6777                    .table(&read.table)
6778                    .ok_or("client.authority_read_forbidden: authority table is not declared")?;
6779                let scalar = |column: &str, value: &Value| -> Result<String, String> {
6780                    let ty = table
6781                        .columns
6782                        .iter()
6783                        .find(|c| c.name == column)
6784                        .expect("validated authority column")
6785                        .ty;
6786                    if ty == ColumnType::Boolean {
6787                        if let Some(value) = value.as_bool() {
6788                            return Ok(value.to_string());
6789                        }
6790                        return match value.as_i64() {
6791                            Some(0) => Ok("false".into()),
6792                            Some(1) => Ok("true".into()),
6793                            _ => Err("sync.local_corrupt: authority boolean is invalid".into()),
6794                        };
6795                    }
6796                    match value {
6797                        Value::String(s) => Ok(s.clone()),
6798                        Value::Number(n) => Ok(n.to_string()),
6799                        Value::Object(o) if ty == ColumnType::Integer && o.len() == 1 => o
6800                            .get("$bigint")
6801                            .and_then(Value::as_str)
6802                            .map(str::to_owned)
6803                            .ok_or("sync.local_corrupt: authority integer is invalid".into()),
6804                        _ => {
6805                            Err("sync.local_corrupt: authority scalar is missing or invalid".into())
6806                        }
6807                    }
6808                };
6809                let matches = |row: &QueryRow| -> Result<bool, String> {
6810                    for (variable, values) in &read.scopes {
6811                        let column = table
6812                            .scope_column(variable)
6813                            .expect("validated authority scope");
6814                        let value = row
6815                            .get(column)
6816                            .ok_or("sync.local_corrupt: authority scope column is missing")?;
6817                        if value.is_null() || !values.contains(&scalar(column, value)?) {
6818                            return Ok(false);
6819                        }
6820                    }
6821                    Ok(true)
6822                };
6823                let selected = read
6824                    .columns
6825                    .iter()
6826                    .map(|c| quote_ident(c))
6827                    .collect::<Vec<_>>()
6828                    .join(",");
6829                let mut intent = BTreeSet::new();
6830                let mut relevant = BTreeSet::new();
6831                for row in query_connection(&self.conn,
6832                    "SELECT id,values_json FROM (SELECT json_extract(value,'$.table') AS tbl,json_extract(value,'$.rowId') AS id,json_extract(value,'$.values') AS values_json FROM _syncular_outbox,json_each(ops_json) UNION ALL SELECT json_extract(value,'$.table'),json_extract(value,'$.rowId'),json_extract(value,'$.values') FROM _syncular_failed_commits,json_each(operations_json) UNION ALL SELECT tbl,id,intent_json FROM _syncular_acked_rows) WHERE tbl=?",
6833                    &[Value::String(read.table.clone())]).map_err(|e| e.to_string())? {
6834                    let id = row.get("id").and_then(Value::as_str).ok_or("sync.local_corrupt: authority intent id is invalid")?.to_owned();
6835                    intent.insert(id.clone());
6836                    if let Some(raw) = row.get("values_json").and_then(Value::as_str) {
6837                        let values: QueryRow = serde_json::from_str(raw).map_err(|_| "sync.local_corrupt: authority intent values are invalid")?;
6838                        if read.scopes.keys().all(|v| values.contains_key(table.scope_column(v).expect("validated scope"))) && matches(&values)? {relevant.insert(id);}
6839                    }
6840                }
6841                let mut rows = BTreeMap::new();
6842                for full in [base_table(&read.table), visible_table(&read.table)] {
6843                    for mut values in query_connection(
6844                        &self.conn,
6845                        &format!(
6846                            "SELECT {selected},_syncular_version AS authority_version FROM {full}"
6847                        ),
6848                        &[],
6849                    )
6850                    .map_err(|e| e.to_string())?
6851                    {
6852                        if !matches(&values)? {
6853                            continue;
6854                        }
6855                        let id = scalar(
6856                            &table.primary_key,
6857                            values
6858                                .get(&table.primary_key)
6859                                .expect("selected primary key"),
6860                        )?;
6861                        relevant.insert(id.clone());
6862                        if full == base_table(&read.table) {
6863                            let version = values
6864                                .remove("authority_version")
6865                                .expect("selected version");
6866                            let version = version
6867                                .as_i64()
6868                                .ok_or("sync.local_corrupt: authority server version is invalid")?;
6869                            if version >= 0 {
6870                                rows.insert(id.clone(), json!({"values": values, "version": version, "hasLocalIntent": intent.contains(&id)}));
6871                            }
6872                        }
6873                    }
6874                }
6875                intent.retain(|id| relevant.contains(id));
6876                let rows = rows.into_values().collect::<Vec<_>>();
6877                // Every unit covering the table, as its (unit, table) pair (§4.4).
6878                let replica = self.stored(replica_cursor(&self.conn))?;
6879                let persisted = self
6880                    .stored(load_units(&self.conn))?
6881                    .into_iter()
6882                    .filter(|unit| covers(table, &unit.scopes))
6883                    .map(|unit| {
6884                        let effective = unit.echo.as_deref().and_then(|echo| {
6885                            pair_scopes(&unit.scopes, &read.table, Some(echo))
6886                        });
6887                        let requested = read
6888                            .scopes
6889                            .keys()
6890                            .map(|v| (v.clone(), json!(unit.scopes.get(v).into_iter().collect::<Vec<_>>())))
6891                            .collect::<Map<_, _>>();
6892                        let complete = effective
6893                            .as_ref()
6894                            .is_some_and(|scopes| scopes.len() == read.scopes.len())
6895                            && unit.status == UnitStatus::Active
6896                            && !unit.bootstrapping();
6897                        let exposed = effective.map(|scopes| {
6898                            read.scopes
6899                                .keys()
6900                                .map(|v| {
6901                                    let held = scopes.iter().find(|(variable, _)| variable == v);
6902                                    (v.clone(), json!(held.map_or(&Vec::new(), |(_, values)| values)))
6903                                })
6904                                .collect::<Map<_, _>>()
6905                        });
6906                        json!({"requestedScopes": requested, "status": unit.status, "cursor": unit.cursor.unwrap_or(replica), "effectiveScopes": exposed, "complete": complete})
6907                    })
6908                    .collect::<Vec<_>>();
6909                fn covered(selectors: &[(&String, &Vec<String>)], candidates: &[&Value]) -> bool {
6910                    match selectors.split_first() {
6911                        None => !candidates.is_empty(),
6912                        Some(((variable, values), rest)) => values.iter().all(|value| {
6913                            covered(
6914                                rest,
6915                                &candidates
6916                                    .iter()
6917                                    .copied()
6918                                    .filter(|p| {
6919                                        p["effectiveScopes"][variable.as_str()]
6920                                            .as_array()
6921                                            .is_some_and(|held| {
6922                                                held.contains(&Value::String(value.clone()))
6923                                                    || held.contains(&Value::String("*".into()))
6924                                            })
6925                                    })
6926                                    .collect::<Vec<_>>(),
6927                            )
6928                        }),
6929                    }
6930                }
6931                let coverage = if covered(
6932                    &read.scopes.iter().collect::<Vec<_>>(),
6933                    &persisted
6934                        .iter()
6935                        .filter(|p| p["complete"] == true)
6936                        .collect::<Vec<_>>(),
6937                ) {
6938                    "complete"
6939                } else if persisted.iter().any(|p| {
6940                    p["status"] == "active"
6941                        && read.scopes.iter().all(|(v, values)| {
6942                            values.iter().any(|value| {
6943                                p["requestedScopes"][v].as_array().is_some_and(|held| {
6944                                    held.contains(&Value::String(value.clone()))
6945                                })
6946                            })
6947                        })
6948                }) {
6949                    "pending"
6950                } else {
6951                    "missing"
6952                };
6953                tables.push(json!({"table": read.table, "rows": rows, "localIntentRowIds": intent, "scopes": read.scopes, "coverage": coverage, "persisted": persisted}));
6954            }
6955            Ok(
6956                json!({"revision": revision, "complete": tables.iter().all(|t| t["coverage"] == "complete"), "tables": tables}),
6957            )
6958        })();
6959        match result {
6960            Ok(snapshot) => {
6961                self.conn
6962                    .execute_batch("RELEASE authority_snapshot")
6963                    .map_err(|e| e.to_string())?;
6964                Ok(snapshot)
6965            }
6966            Err(error) => {
6967                self.conn
6968                    .execute_batch("ROLLBACK TO authority_snapshot; RELEASE authority_snapshot")
6969                    .map_err(|e| format!("{error}; rollback failed: {e}"))?;
6970                Err(error)
6971            }
6972        }
6973    }
6974
6975    /// Rows, coverage, and local revision from one SQLite read snapshot.
6976    /// §7.5 atomic snapshot read. An `owner` records a failure in
6977    /// `diagnostics_snapshot().query_failures` until its next successful read.
6978    pub fn query_snapshot(
6979        &mut self,
6980        sql: &str,
6981        params: &[QueryValue],
6982        coverage: &[WindowCoverage],
6983        owner: Option<QueryOwner<'_>>,
6984    ) -> Result<QuerySnapshot, String> {
6985        let result = snapshot_connection(&self.conn, sql, params, coverage);
6986        if let Some(owner) = owner {
6987            self.record_query_read(owner, result.as_ref().err());
6988        }
6989        result.map_err(|failure| failure.to_string())
6990    }
6991
6992    /// §7.6: record the outcome of one owned snapshot read, including reads a
6993    /// host ran on a separate connection. A success removes the owner's entry;
6994    /// an identical failure leaves it unchanged; a changed failure moves last.
6995    pub fn record_query_read(&mut self, owner: QueryOwner<'_>, failure: Option<&QueryReadFailure>) {
6996        let position = self
6997            .query_failures
6998            .iter()
6999            .position(|entry| entry.id == owner.id);
7000        let Some(failure) = failure else {
7001            if let Some(index) = position {
7002                self.query_failures.remove(index);
7003            }
7004            return;
7005        };
7006        let tables: Vec<String> = BTreeSet::from_iter(owner.tables.iter().copied())
7007            .into_iter()
7008            .map(str::to_owned)
7009            .collect();
7010        let code = failure.code.unwrap_or("client.query_failed").to_owned();
7011        if position.is_some_and(|index| {
7012            let entry = &self.query_failures[index];
7013            entry.tables == tables && entry.code == code && entry.sqlite_code == failure.sqlite_code
7014        }) {
7015            return;
7016        }
7017        if let Some(index) = position {
7018            self.query_failures.remove(index);
7019        }
7020        self.query_failures.push(DiagnosticQueryFailure {
7021            id: owner.id.to_owned(),
7022            tables,
7023            code,
7024            sqlite_code: failure.sqlite_code,
7025            at_ms: self.clock_now_ms(),
7026        });
7027        if self.query_failures.len() > MAX_DIAGNOSTIC_QUERY_FAILURES {
7028            self.query_failures.remove(0);
7029        }
7030    }
7031
7032    // -- request building ---------------------------------------------------------
7033
7034    fn build_request(&self, url_capable: bool) -> Result<(Message, RequestMeta), Box<SyncOutcome>> {
7035        #[cfg(feature = "bench-internals")]
7036        let _phase = self.benchmark_phases.start(Phase::RequestPrepare);
7037        let log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7038            Box::new(SyncOutcome::Failed {
7039                error_code: "storage.failed".into(),
7040                message,
7041                details: None,
7042                recommended_action: None,
7043            })
7044        })?;
7045        let max_commits = self.limits.max_push_commits_per_request;
7046        let max_ops = self
7047            .limits
7048            .max_push_operations_per_request
7049            .unwrap_or(PUSH_OPS_PER_REQUEST);
7050        let byte_cap = self.limits.max_push_request_bytes;
7051        // §4.2/§5.4: bit 3 is advertised iff the transport can fetch a
7052        // bare URL — capability negotiation, decided per transport.
7053        let accept = self.limits.accept.unwrap_or(if url_capable {
7054            DEFAULT_ACCEPT | ACCEPT_SIGNED_URLS
7055        } else {
7056            DEFAULT_ACCEPT
7057        });
7058        let storage_failed = |message: String| {
7059            Box::new(SyncOutcome::Failed {
7060                error_code: "storage.failed".into(),
7061                message,
7062                details: None,
7063                recommended_action: None,
7064            })
7065        };
7066        let header = Frame::ReqHeader {
7067            client_id: self.client_id.clone(),
7068            schema_version: self.schema.version,
7069            log_epoch: log_epoch.clone(),
7070            outbox_id: self.get_meta(OUTBOX_ID_KEY).map_err(storage_failed)?,
7071        };
7072        // §1.5: the lead frames are REQ_HEADER plus the optional ROUND_FAILURE,
7073        // which stays ahead of every push, pull, unit and progress frame; the
7074        // byte-capacity probes below measure this exact sequence.
7075        let mut lead = vec![header];
7076        lead.extend(
7077            self.round_failure
7078                .iter()
7079                .map(|code| Frame::RoundFailure { code: code.clone() }),
7080        );
7081        let registered: Vec<UnitRecord> = self
7082            .stored(load_units(&self.conn))
7083            .map_err(storage_failed)?
7084            .into_iter()
7085            .filter(|unit| unit.status == UnitStatus::Active)
7086            .collect();
7087        let registration_digest = ssp2::registration::registration_digest(
7088            registered
7089                .iter()
7090                .map(|unit| scope_pairs(&unit.scopes))
7091                .collect::<Vec<_>>()
7092                .iter()
7093                .map(Vec::as_slice),
7094        );
7095        let echo_digest = self
7096            .get_meta(ECHO_DIGEST_KEY)
7097            .map_err(storage_failed)?
7098            .filter(|hex| !hex.is_empty())
7099            .map(|hex| {
7100                crate::values::hex_to_bytes(&hex)
7101                    .ok()
7102                    .and_then(|bytes| <[u8; 32]>::try_from(bytes).ok())
7103                    .ok_or_else(|| {
7104                        "sync.local_corrupt: persisted echo digest is invalid".to_owned()
7105                    })
7106            })
7107            .transpose()
7108            .map_err(storage_failed)?;
7109        let pull = Frame::PullHeader {
7110            limit_commits: self.limits.limit_commits.unwrap_or(0),
7111            limit_snapshot_rows: self.limits.limit_snapshot_rows.unwrap_or(0),
7112            max_snapshot_pages: self.limits.max_snapshot_pages.unwrap_or(0),
7113            accept,
7114            cursor: self
7115                .stored(replica_cursor(&self.conn))
7116                .map_err(storage_failed)?,
7117            registration_digest,
7118            echo_digest,
7119        };
7120        let registration_digest = bytes_to_hex(&registration_digest);
7121        // §4.1: the list travels when it changed since the server stored it,
7122        // after `unregistered` and after a reset (both clear the stored digest).
7123        let travels = self
7124            .get_meta(REGISTERED_DIGEST_KEY)
7125            .map_err(storage_failed)?
7126            .as_deref()
7127            != Some(registration_digest.as_str());
7128        let mut sub_frames: Vec<Frame> = Vec::new();
7129        if travels {
7130            sub_frames.extend(registered.iter().map(|unit| Frame::Unit {
7131                scopes: scope_pairs(&unit.scopes),
7132            }));
7133        }
7134        // §4.3: one PROGRESS per catching-up unit, in registration order.
7135        sub_frames.extend(registered.iter().filter_map(|unit| {
7136            Some(Frame::Progress {
7137                id: unit.id.clone(),
7138                cursor: unit.cursor?,
7139                bootstrap_state: unit.bootstrap_state.clone().map(RawJson),
7140            })
7141        }));
7142        // The fixed frames (order-independent size) and the header+pull probe
7143        // both encode canonically, so the byte budget is the exact wire size.
7144        let fixed_bytes = match byte_cap {
7145            Some(_) => {
7146                let mut frames = lead.clone();
7147                frames.push(pull.clone());
7148                frames.extend(sub_frames.iter().cloned());
7149                encode_message(&Message {
7150                    wire_version: WIRE_VERSION,
7151                    msg_kind: MsgKind::Request,
7152                    frames,
7153                })
7154                .len()
7155            }
7156            None => 0,
7157        };
7158        if let Some(cap) = byte_cap {
7159            if fixed_bytes > cap {
7160                return Err(Self::push_capacity_outcome("bytes", cap, fixed_bytes, None));
7161            }
7162        }
7163        let base_bytes = match byte_cap {
7164            Some(_) => {
7165                let mut frames = lead.clone();
7166                frames.push(pull.clone());
7167                encode_message(&Message {
7168                    wire_version: WIRE_VERSION,
7169                    msg_kind: MsgKind::Request,
7170                    frames,
7171                })
7172                .len()
7173            }
7174            None => 0,
7175        };
7176        let total_outbox = if log_epoch.is_some() {
7177            self.outbox.len()
7178        } else {
7179            0
7180        };
7181        let mut push_frames: Vec<Frame> = Vec::new();
7182        let mut pushed_ids = Vec::new();
7183        let mut ops_in_request = 0usize;
7184        let mut bytes_in_request = 0usize;
7185        let mut deferred_commits = 0usize;
7186        #[cfg(feature = "bench-internals")]
7187        let outbox_phase = self.benchmark_phases.start(Phase::OutboxEncode);
7188        for (index, commit) in self.outbox.iter().take(total_outbox).enumerate() {
7189            // §6.1/§7.1: the commit-count and operation caps are hard. A
7190            // first commit over the operation cap is a typed capacity error
7191            // and stays queued; a later one defers with the complete suffix.
7192            if max_commits.is_some_and(|cap| push_frames.len() >= cap) {
7193                deferred_commits = total_outbox - index;
7194                break;
7195            }
7196            if ops_in_request + commit.ops.len() > max_ops {
7197                if push_frames.is_empty() {
7198                    return Err(Self::push_capacity_outcome(
7199                        "operations",
7200                        max_ops,
7201                        commit.ops.len(),
7202                        Some(commit.client_commit_id.as_str()),
7203                    ));
7204                }
7205                deferred_commits = total_outbox - index;
7206                break;
7207            }
7208            let operations = commit
7209                .ops
7210                .iter()
7211                .map(|op| {
7212                    let payload = match self
7213                        .schema
7214                        .table(&op.table)
7215                        .and_then(|table| Some((table, op.presented_values(table)?)))
7216                    {
7217                        Some((table, values)) => {
7218                            // §0: outbox entries encode at send time with the
7219                            // current codec (validated at mutate()). §6.1: the
7220                            // values map's keys are the sparse presence set; an
7221                            // insert-intent operation presents every column (§7.1).
7222                            // §5.11: encrypted columns are encrypted here, with
7223                            // an absent key-id selector read from the stored row.
7224                            // `sync_inner` runs `drop_unencodable_outbox` first,
7225                            // so an encrypt failure cannot reach this encode; the
7226                            // author seam validated every other failure.
7227                            let fallback =
7228                                self.stored_key_fallback(table, &op.row_id)
7229                                    .map_err(|message| {
7230                                        Box::new(SyncOutcome::Failed {
7231                                            error_code: "storage.failed".into(),
7232                                            message,
7233                                            details: None,
7234                                            recommended_action: None,
7235                                        })
7236                                    })?;
7237                            encode_sparse_row_json(
7238                                table,
7239                                &op.row_id,
7240                                &values,
7241                                &self.encryption,
7242                                fallback.as_ref(),
7243                            )
7244                            .ok()
7245                        }
7246                        None => None,
7247                    };
7248                    Ok(ssp2::model::Operation {
7249                        table: op.table.clone(),
7250                        row_id: op.row_id.clone(),
7251                        op: if op.upsert { Op::Upsert } else { Op::Delete },
7252                        base_version: op.base_version,
7253                        payload,
7254                    })
7255                })
7256                .collect::<Result<Vec<_>, Box<SyncOutcome>>>()?;
7257            // §6.3.2, §7.1: the commit's outbox sequence.
7258            let client_seq = self
7259                .conn
7260                .prepare_cached("SELECT seq FROM _syncular_outbox WHERE commit_id = ?1")
7261                .and_then(|mut statement| {
7262                    statement.query_row([&commit.client_commit_id], |row| row.get(0))
7263                })
7264                .map_err(|error| {
7265                    storage_failed(Self::sqlite_failure(&self.storage_failure, error))
7266                })?;
7267            let frame = Frame::PushCommit {
7268                client_commit_id: commit.client_commit_id.clone(),
7269                client_seq,
7270                operations,
7271            };
7272            let frame_bytes = match byte_cap {
7273                Some(_) => {
7274                    let mut frames = lead.clone();
7275                    frames.push(frame.clone());
7276                    frames.push(pull.clone());
7277                    encode_message(&Message {
7278                        wire_version: WIRE_VERSION,
7279                        msg_kind: MsgKind::Request,
7280                        frames,
7281                    })
7282                    .len()
7283                        - base_bytes
7284                }
7285                None => 0,
7286            };
7287            // The head is always encoded so the caller can report the full
7288            // projected request size; a later commit defers once it no longer
7289            // fits.
7290            if let Some(cap) = byte_cap {
7291                if !push_frames.is_empty() && fixed_bytes + bytes_in_request + frame_bytes > cap {
7292                    deferred_commits = total_outbox - index;
7293                    break;
7294                }
7295            }
7296            push_frames.push(frame);
7297            pushed_ids.push(commit.client_commit_id.clone());
7298            ops_in_request += commit.ops.len();
7299            bytes_in_request += frame_bytes;
7300        }
7301        #[cfg(feature = "bench-internals")]
7302        drop(outbox_phase);
7303        if let Some(cap) = byte_cap {
7304            if fixed_bytes + bytes_in_request > cap {
7305                // The head alone does not fit this budget; the commit stays
7306                // queued and no transport round is attempted.
7307                let blocked = if push_frames.is_empty() {
7308                    None
7309                } else {
7310                    self.outbox.first().map(|c| c.client_commit_id.as_str())
7311                };
7312                return Err(Self::push_capacity_outcome(
7313                    "bytes",
7314                    cap,
7315                    fixed_bytes + bytes_in_request,
7316                    blocked,
7317                ));
7318            }
7319        }
7320        let mut frames = lead;
7321        frames.extend(push_frames);
7322        frames.push(pull);
7323        frames.extend(sub_frames);
7324        let message = Message {
7325            wire_version: WIRE_VERSION,
7326            msg_kind: MsgKind::Request,
7327            frames,
7328        };
7329        Ok((
7330            message,
7331            RequestMeta {
7332                pushed_ids,
7333                registration_digest,
7334                accept,
7335                deferred_commits,
7336            },
7337        ))
7338    }
7339
7340    /// §7.1: a configured push capacity limit cannot carry this request.
7341    fn push_capacity_outcome(
7342        kind: &str,
7343        limit: usize,
7344        size: usize,
7345        client_commit_id: Option<&str>,
7346    ) -> Box<SyncOutcome> {
7347        let mut details = Map::new();
7348        details.insert("kind".to_owned(), Value::from(kind));
7349        details.insert("limit".to_owned(), Value::from(limit as u64));
7350        details.insert("size".to_owned(), Value::from(size as u64));
7351        if let Some(id) = client_commit_id {
7352            details.insert("clientCommitId".to_owned(), Value::from(id));
7353        }
7354        Box::new(SyncOutcome::Failed {
7355            error_code: "client.push_request_too_large".into(),
7356            message: "the push request exceeds a configured capacity limit".into(),
7357            details: Some(Value::Object(details)),
7358            recommended_action: None,
7359        })
7360    }
7361
7362    // -- sync -------------------------------------------------------------------
7363
7364    /// Cloneable observation handle; no client lock is needed to read it.
7365    pub fn progress(&self) -> ProgressObserver {
7366        self.progress.clone()
7367    }
7368
7369    pub fn sync(&mut self, transport: &mut dyn Transport) -> SyncOutcome {
7370        let prepared = match self.prepare_sync_round(transport.supports_url_fetch()) {
7371            Ok(prepared) => prepared,
7372            Err(outcome) => return *outcome,
7373        };
7374        // The round's network deadline rides `PreparedSyncRound` and is scoped
7375        // to each exchange, so uploads, continuations, the main request, and
7376        // every segment fetch share one monotonic anchor without leaving
7377        // deadline state on a reused transport.
7378        let mut next = prepared;
7379        loop {
7380            match self.apply_sync_round(next.exchange(transport)) {
7381                crate::AppliedSyncRound::Continue(prepared) => next = prepared,
7382                crate::AppliedSyncRound::Complete {
7383                    outcome, controls, ..
7384                } => {
7385                    if self.transport_enabled {
7386                        for text in controls {
7387                            let _ = transport.realtime_send(&text);
7388                        }
7389                    } else {
7390                        self.disconnect_realtime(transport);
7391                    }
7392                    return outcome;
7393                }
7394            }
7395        }
7396    }
7397
7398    fn finish_sync_round(&mut self, started_at_ms: i64, mut outcome: SyncOutcome) -> SyncOutcome {
7399        if let SyncOutcome::Failed {
7400            error_code,
7401            message,
7402            details,
7403            ..
7404        } = &mut outcome
7405        {
7406            if let Some((failure, code)) = self
7407                .storage_failure
7408                .borrow()
7409                .as_ref()
7410                .and_then(|failure| failure.code.map(|code| (failure, code)))
7411            {
7412                *error_code = code.to_owned();
7413                *message = match code {
7414                    "client.storage_busy" => "local SQLite storage is busy",
7415                    "client.storage_full" => "local SQLite storage is full",
7416                    "client.storage_io" => "local SQLite storage I/O failed",
7417                    "client.storage_corrupt" => "local SQLite storage is corrupt",
7418                    _ => unreachable!("unrecognized classified storage failure"),
7419                }
7420                .to_owned();
7421                *details = failure.details();
7422            }
7423        }
7424        let details = match &outcome {
7425            SyncOutcome::Failed { details, .. } => details.as_ref(),
7426            _ => None,
7427        };
7428        let cause_kind = details
7429            .and_then(|details| details.get("causeKind"))
7430            .and_then(Value::as_str)
7431            .and_then(|cause| match cause {
7432                "network" => Some(crate::TransportCauseKind::Network),
7433                "connect" => Some(crate::TransportCauseKind::Connect),
7434                "tls" => Some(crate::TransportCauseKind::Tls),
7435                "io" => Some(crate::TransportCauseKind::Io),
7436                "request" => Some(crate::TransportCauseKind::Request),
7437                "protocol" => Some(crate::TransportCauseKind::Protocol),
7438                "timeout" => Some(crate::TransportCauseKind::Timeout),
7439                "round_deadline" => Some(crate::TransportCauseKind::RoundDeadline),
7440                "aborted" => Some(crate::TransportCauseKind::Aborted),
7441                "body" => Some(crate::TransportCauseKind::Body),
7442                "status" => Some(crate::TransportCauseKind::Status),
7443                "redirect" => Some(crate::TransportCauseKind::Redirect),
7444                "unknown" => Some(crate::TransportCauseKind::Unknown),
7445                _ => None,
7446            });
7447        let http_status = if matches!(
7448            cause_kind,
7449            Some(
7450                crate::TransportCauseKind::Status
7451                    | crate::TransportCauseKind::Body
7452                    | crate::TransportCauseKind::Redirect
7453            )
7454        ) {
7455            details
7456                .and_then(|details| details.get("httpStatus"))
7457                .and_then(Value::as_f64)
7458                .filter(|status| status.fract() == 0.0 && (100.0..=599.0).contains(status))
7459                .map(|status| status as u16)
7460        } else {
7461            None
7462        };
7463        let retry_delay_ms = self.round_retry_delay_ms;
7464        self.progress.update(|p| match &outcome {
7465            SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report)
7466                if report.failed.is_empty() =>
7467            {
7468                p.state = ProgressState::Complete
7469            }
7470            SyncOutcome::Ok(_) | SyncOutcome::BudgetExhausted(_) => {
7471                p.state = ProgressState::Failed;
7472                p.error_code = Some("sync.scope_revoked".into());
7473            }
7474            SyncOutcome::Failed { error_code, .. } => {
7475                p.state = ProgressState::Failed;
7476                p.error_code = Some(Self::diagnostic_code(error_code));
7477                p.cause_kind = cause_kind;
7478                p.http_status = http_status;
7479                p.retry_delay_ms = retry_delay_ms;
7480            }
7481            SyncOutcome::RealtimeUnavailable { .. } => {
7482                p.state = ProgressState::Failed;
7483                p.error_code = Some(REALTIME_UNAVAILABLE_CODE.to_owned());
7484                p.retry_delay_ms = retry_delay_ms;
7485            }
7486        });
7487        let completed_at_ms = self.clock_now_ms();
7488        self.last_round = Some(match &outcome {
7489            SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report) => DiagnosticLastRound {
7490                status: "succeeded".to_owned(),
7491                started_at_ms,
7492                completed_at_ms,
7493                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7494                counters: Some(DiagnosticRoundCounters {
7495                    pushed: report.pushed,
7496                    applied: report.applied.len(),
7497                    rejected: report.rejected.len(),
7498                    retryable: report.retryable.len(),
7499                    conflicts: report.conflicts,
7500                    commits_applied: report.commits_applied,
7501                    segment_rows_applied: report.segment_rows_applied,
7502                    bootstrapping: report.bootstrapping.len(),
7503                    resets: report.resets.len(),
7504                    revoked: report.revoked.len(),
7505                    failed: report.failed.len(),
7506                    deferred_commits: report.deferred_commits,
7507                }),
7508                error_code: None,
7509                cause_kind: None,
7510                http_status: None,
7511            },
7512            SyncOutcome::Failed { error_code, .. } => DiagnosticLastRound {
7513                status: "failed".to_owned(),
7514                started_at_ms,
7515                completed_at_ms,
7516                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7517                counters: None,
7518                error_code: Some(Self::diagnostic_code(error_code)),
7519                cause_kind,
7520                http_status,
7521            },
7522            SyncOutcome::RealtimeUnavailable { .. } => DiagnosticLastRound {
7523                status: "failed".to_owned(),
7524                started_at_ms,
7525                completed_at_ms,
7526                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7527                counters: None,
7528                error_code: Some(REALTIME_UNAVAILABLE_CODE.to_owned()),
7529                cause_kind: None,
7530                http_status: None,
7531            },
7532        });
7533        outcome
7534    }
7535
7536    /// Capture one request on the client owner. Mutations made after this
7537    /// call remain in the outbox for a later round; no network I/O occurs here.
7538    pub fn prepare_sync_round(
7539        &mut self,
7540        url_capable: bool,
7541    ) -> Result<crate::PreparedSyncRound, Box<SyncOutcome>> {
7542        if !self.transport_enabled {
7543            return Err(Box::new(SyncOutcome::Failed {
7544                error_code: "sync.offline".into(),
7545                message: "transport gate is closed".into(),
7546                details: None,
7547                recommended_action: None,
7548            }));
7549        }
7550        if self.active_round.is_some() {
7551            return Err(Box::new(SyncOutcome::Failed {
7552                error_code: "client.round_in_progress".into(),
7553                message: "a sync round is already in flight".into(),
7554                details: None,
7555                recommended_action: None,
7556            }));
7557        }
7558        self.storage_failure.borrow_mut().take();
7559        self.progress.start();
7560        self.round_retry_delay_ms = None;
7561        let started_at_ms = self.clock_now_ms();
7562        let prepared = (|| {
7563            if self.stopped {
7564                return Err(Box::new(SyncOutcome::Ok(SyncReport {
7565                    schema_floor: self.schema_floor.clone(),
7566                    ..SyncReport::default()
7567                })));
7568            }
7569            if self.security_preflight {
7570                return Err(Box::new(SyncOutcome::Failed {
7571                    error_code: SECURITY_PREFLIGHT_REQUIRED_CODE.into(),
7572                    message: "security preflight must complete before syncing".into(),
7573                    details: None,
7574                    recommended_action: None,
7575                }));
7576            }
7577            self.set_sync_needed(false, false);
7578            self.drain_pending_evictions()
7579                .and_then(|_| self.drop_incompatible_outbox())
7580                .and_then(|_| self.drop_unencodable_outbox(true, None))
7581                .map_err(|message| {
7582                    Box::new(SyncOutcome::Failed {
7583                        error_code: "storage.failed".into(),
7584                        message,
7585                        details: None,
7586                        recommended_action: None,
7587                    })
7588                })?;
7589            let has_log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7590                Box::new(SyncOutcome::Failed {
7591                    error_code: "storage.failed".into(),
7592                    message,
7593                    details: None,
7594                    recommended_action: None,
7595                })
7596            })?;
7597            let uploads = if has_log_epoch.is_some() && self.schema_has_blobs() {
7598                self.pending_blob_uploads().map_err(|e| {
7599                    Box::new(SyncOutcome::Failed {
7600                        error_code: e.code,
7601                        message: e.message,
7602                        details: e.details,
7603                        recommended_action: None,
7604                    })
7605                })?
7606            } else {
7607                Vec::new()
7608            };
7609            if self.realtime_state != RealtimeState::Connected
7610                && self.realtime_policy == RealtimePolicy::Required
7611            {
7612                let retry_delay_ms = self.schedule_background_retry();
7613                self.realtime_retry_delay_ms = Some(retry_delay_ms);
7614                return Err(Box::new(SyncOutcome::RealtimeUnavailable {
7615                    state: self.realtime_state,
7616                    reason_code: self.realtime_reason_code.clone(),
7617                    retry_delay_ms,
7618                }));
7619            }
7620            let (message, meta) = self.build_request(url_capable)?;
7621            let id = uuid::Uuid::new_v4();
7622            self.active_round = Some(id);
7623            let phase = if uploads.is_empty() {
7624                crate::round::RoundPhase::Sync
7625            } else {
7626                crate::round::RoundPhase::UploadGrant
7627            };
7628            Ok(crate::PreparedSyncRound {
7629                id,
7630                started_at_ms,
7631                message,
7632                meta,
7633                uploads: uploads.into(),
7634                phase,
7635                encoded: None,
7636                continuation: None,
7637                completed: None,
7638                realtime: self.realtime_state == RealtimeState::Connected,
7639                // §5.5: the owning unit's scope map, each value a one-element list.
7640                scopes: self
7641                    .stored(load_units(&self.conn))
7642                    .map_err(|message| {
7643                        Box::new(SyncOutcome::Failed {
7644                            error_code: "storage.failed".into(),
7645                            message,
7646                            details: None,
7647                            recommended_action: None,
7648                        })
7649                    })?
7650                    .into_iter()
7651                    .map(|unit| {
7652                        (
7653                            unit.id,
7654                            canonical_scope_json(&unit_scope_lists(&unit.scopes)),
7655                        )
7656                    })
7657                    .collect(),
7658                #[cfg(feature = "bench-internals")]
7659                benchmark_phases: self.benchmark_phases.clone(),
7660                progress: self.progress.clone(),
7661                fixed_now: self.now_ms,
7662                round_deadline_at: None,
7663            })
7664        })();
7665        prepared.map_err(|outcome| Box::new(self.finish_sync_round(started_at_ms, *outcome)))
7666    }
7667
7668    /// Discard the reply of an old authorization or registration context. Its
7669    /// submitted commits stay durable and can be retried with the same ids.
7670    pub fn cancel_sync_round(&mut self) {
7671        self.active_round = None;
7672    }
7673
7674    /// Apply captured network results on the owner, preserving all normal
7675    /// version, schema, content-address and cursor checks. No network I/O.
7676    pub fn apply_sync_round(
7677        &mut self,
7678        completed: crate::CompletedSyncRound,
7679    ) -> crate::AppliedSyncRound {
7680        let mut prepared = completed.prepared;
7681        if self.active_round != Some(prepared.id) || self.security_preflight {
7682            return crate::AppliedSyncRound::Complete {
7683                outcome: SyncOutcome::Failed {
7684                    error_code: "client.round_cancelled".into(),
7685                    message: "sync round belongs to a released client context".into(),
7686                    details: None,
7687                    recommended_action: None,
7688                },
7689                controls: Vec::new(),
7690                more: false,
7691                bootstrap_advanced: false,
7692            };
7693        }
7694        self.storage_failure.borrow_mut().take();
7695        let (response, mut downloads, transport_failed) = match completed.exchange {
7696            crate::round::ExchangeResult::Upload { id, result } => {
7697                let result = match result {
7698                    // §5.9.7: a non-retryable server refusal (`blob.too_large`)
7699                    // is the body's final outcome. The commits naming it take
7700                    // the incompatible-commit path with the server's code and
7701                    // leave this round's request; the round continues.
7702                    Err(error)
7703                        if error
7704                            .details
7705                            .as_ref()
7706                            .and_then(|details| details.get("retryable"))
7707                            == Some(&Value::Bool(false)) =>
7708                    {
7709                        self.conn
7710                            .prepare(
7711                                "SELECT commit_id FROM _syncular_blob_commit_refs WHERE blob_id = ?",
7712                            )
7713                            .and_then(|mut statement| {
7714                                statement
7715                                    .query_map(rusqlite::params![id], |row| row.get::<_, String>(0))?
7716                                    .collect::<Result<HashSet<_>, _>>()
7717                            })
7718                            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
7719                            .and_then(|refused| {
7720                                let commits = self
7721                                    .outbox
7722                                    .iter()
7723                                    .filter(|commit| refused.contains(&commit.client_commit_id))
7724                                    .cloned()
7725                                    .collect::<Vec<_>>();
7726                                if !commits.is_empty() {
7727                                    self.drop_outbox_commits(&commits, &error.code, &error.message)?;
7728                                }
7729                                prepared.message.frames.retain(|frame| {
7730                                    !matches!(frame, Frame::PushCommit { client_commit_id, .. }
7731                                        if refused.contains(client_commit_id))
7732                                });
7733                                prepared.meta.pushed_ids.retain(|id| !refused.contains(id));
7734                                prepared.continuation = Some(crate::round::RoundPhase::UploadGrant);
7735                                Ok(())
7736                            })
7737                            .map_err(|message| TransportError::new("client.failed", message))
7738                    }
7739                    result => result,
7740                };
7741                let result = result.and_then(|()| {
7742                    self.conn
7743                        .execute(
7744                            "DELETE FROM _syncular_blob_uploads WHERE blob_id = ?",
7745                            rusqlite::params![id],
7746                        )
7747                        .map(|_| ())
7748                        .map_err(|error| {
7749                            TransportError::new(
7750                                "client.failed",
7751                                Self::sqlite_failure(&self.storage_failure, error),
7752                            )
7753                        })
7754                });
7755                match result {
7756                    Ok(()) => return crate::AppliedSyncRound::Continue(prepared),
7757                    Err(TransportError {
7758                        code,
7759                        message,
7760                        details,
7761                    }) => {
7762                        self.active_round = None;
7763                        if Self::unreachable_transport(&details) {
7764                            // The round's work is still owed; the host's
7765                            // connectivity resume runs it.
7766                            self.set_sync_needed(true, false);
7767                        } else if Self::retryable_failure_code(&code) {
7768                            self.schedule_background_retry();
7769                        }
7770                        let recommended_action = recommended_action_of(&details);
7771                        let outcome = self.finish_sync_round(
7772                            prepared.started_at_ms,
7773                            SyncOutcome::Failed {
7774                                error_code: code,
7775                                message,
7776                                details,
7777                                recommended_action,
7778                            },
7779                        );
7780                        return crate::AppliedSyncRound::Complete {
7781                            outcome,
7782                            controls: Vec::new(),
7783                            more: false,
7784                            bootstrap_advanced: false,
7785                        };
7786                    }
7787                }
7788            }
7789            crate::round::ExchangeResult::Reply {
7790                response,
7791                downloads,
7792                transport_failed,
7793            } => (response, downloads, transport_failed),
7794        };
7795        self.active_round = None;
7796        let before = self.resume_tokens();
7797        let outcome = (|| {
7798            let response = match response {
7799                Ok(response) => {
7800                    // §1.5: a complete, decodable response ends the report, an
7801                    // in-band ERROR included (the server already recorded it).
7802                    self.round_failure = None;
7803                    response
7804                }
7805                Err(TransportError {
7806                    code,
7807                    message,
7808                    details,
7809                }) => {
7810                    // §1.5: the server cannot see a round whose transport
7811                    // failed or whose response never decoded, so its code rides
7812                    // the following requests. A code the frame grammar rejects
7813                    // is not reportable, and the previous code stays.
7814                    if ssp2::model::valid_round_failure_code(&code) {
7815                        self.round_failure = Some(code.clone());
7816                    }
7817                    if transport_failed {
7818                        if prepared.realtime {
7819                            self.set_realtime_state(RealtimeState::Lost, Some(&code));
7820                        }
7821                        if let Err(message) = self.record_lease_error(&code) {
7822                            return SyncOutcome::Failed {
7823                                error_code: "storage.failed".to_owned(),
7824                                message,
7825                                details: None,
7826                                recommended_action: None,
7827                            };
7828                        }
7829                    }
7830                    if Self::retryable_failure_code(&code) && !Self::unreachable_transport(&details)
7831                    {
7832                        let delay = self.schedule_background_retry();
7833                        if prepared.realtime && transport_failed {
7834                            self.realtime_retry_delay_ms = Some(delay);
7835                        }
7836                    }
7837                    let recommended_action = recommended_action_of(&details);
7838                    return SyncOutcome::Failed {
7839                        error_code: code,
7840                        message,
7841                        details,
7842                        recommended_action,
7843                    };
7844                }
7845            };
7846            let mut outcome = self.process_response(&mut downloads, response, &prepared.meta);
7847            if let SyncOutcome::Ok(report) = &mut outcome {
7848                report.deferred_commits = prepared.meta.deferred_commits;
7849            }
7850            match &outcome {
7851                SyncOutcome::Ok(_) => self.reset_background_retry(),
7852                SyncOutcome::Failed {
7853                    error_code,
7854                    details,
7855                    ..
7856                } if Self::retryable_failure_code(error_code)
7857                    && !Self::unreachable_transport(details) =>
7858                {
7859                    self.schedule_background_retry();
7860                }
7861                _ => {}
7862            }
7863            if prepared.meta.deferred_commits > 0 {
7864                self.set_sync_needed(true, true);
7865            }
7866            self.previous_version_lifetime_check();
7867            outcome
7868        })();
7869        match &outcome {
7870            // §7.1: a unit still catching up needs another round, also when the
7871            // drive that started it ends early.
7872            SyncOutcome::Ok(report) if !report.bootstrapping.is_empty() => {
7873                self.set_sync_needed(true, false)
7874            }
7875            // The round's work is still owed; the host's connectivity resume
7876            // runs it.
7877            SyncOutcome::Failed { details, .. } if Self::unreachable_transport(details) => {
7878                self.set_sync_needed(true, false)
7879            }
7880            _ => {}
7881        }
7882        let more = self.transport_enabled
7883            && matches!(&outcome, SyncOutcome::Ok(report)
7884                if report.schema_floor.is_none()
7885                    && (!report.bootstrapping.is_empty()
7886                        || report.commits_applied > 0
7887                        || report.segment_rows_applied > 0
7888                        || !report.resets.is_empty()
7889                        || report.deferred_commits > 0
7890                        || self.sync_needed));
7891        let bootstrap_advanced = matches!(&outcome, SyncOutcome::Ok(report) if report.segment_rows_applied > 0 && !report.bootstrapping.is_empty())
7892            && before != self.resume_tokens();
7893        crate::AppliedSyncRound::Complete {
7894            outcome: self.finish_sync_round(prepared.started_at_ms, outcome),
7895            controls: if self.transport_enabled {
7896                downloads.controls
7897            } else {
7898                Vec::new()
7899            },
7900            more,
7901            bootstrap_advanced,
7902        }
7903    }
7904
7905    /// Every unit's resume token: a bootstrap that advanced changes one (§4.7).
7906    fn resume_tokens(&self) -> Option<Vec<(String, Option<String>)>> {
7907        load_units(&self.conn).ok().map(|units| {
7908            units
7909                .into_iter()
7910                .map(|unit| (unit.id, unit.bootstrap_state))
7911                .collect()
7912        })
7913    }
7914
7915    /// §7.8: one idle drive's default total deadline, the TS client's value.
7916    pub const SYNC_IDLE_TIMEOUT_MS: u64 = 60_000;
7917
7918    pub fn sync_until_idle(
7919        &mut self,
7920        transport: &mut dyn Transport,
7921        max_rounds: Option<u32>,
7922    ) -> SyncOutcome {
7923        self.sync_until_idle_with_deadline(transport, max_rounds, Some(Self::SYNC_IDLE_TIMEOUT_MS))
7924    }
7925
7926    /// As [`SyncClient::sync_until_idle`], with an explicit total deadline in
7927    /// milliseconds (`None` disables it). The deadline is checked between
7928    /// rounds; one blocking transport call is bounded by the transport's own
7929    /// whole-round deadline (§1.8).
7930    pub fn sync_until_idle_with_deadline(
7931        &mut self,
7932        transport: &mut dyn Transport,
7933        max_rounds: Option<u32>,
7934        timeout_ms: Option<u64>,
7935    ) -> SyncOutcome {
7936        // §7.8: an explicit budget is a strict positive round count. Zero is a
7937        // caller error, not an exhaustion.
7938        if max_rounds == Some(0) {
7939            return SyncOutcome::Failed {
7940                details: None,
7941                error_code: "sync.invalid_request".into(),
7942                message: "maxRounds must be a positive integer".into(),
7943                recommended_action: None,
7944            };
7945        }
7946        if timeout_ms.is_some_and(|ms| ms == 0 || i64::try_from(ms).is_err()) {
7947            return SyncOutcome::Failed {
7948                details: None,
7949                error_code: "sync.invalid_request".into(),
7950                message: "timeoutMs must be a positive integer".into(),
7951                recommended_action: None,
7952            };
7953        }
7954        let started_at_ms = self.clock_now_ms();
7955        let deadline_ms = timeout_ms.map(|ms| started_at_ms.saturating_add(ms as i64));
7956        self.sync_until_idle_bounded(transport, max_rounds, started_at_ms, deadline_ms)
7957    }
7958
7959    fn sync_until_idle_bounded(
7960        &mut self,
7961        transport: &mut dyn Transport,
7962        max_rounds: Option<u32>,
7963        started_at_ms: i64,
7964        deadline_ms: Option<i64>,
7965    ) -> SyncOutcome {
7966        let rounds = max_rounds.unwrap_or(20);
7967        let mut aggregate = SyncReport::default();
7968        let mut spent = 0;
7969        while spent < rounds {
7970            if let Some(deadline_ms) = deadline_ms {
7971                if self.clock_now_ms() >= deadline_ms {
7972                    return SyncOutcome::Failed {
7973                        error_code: "sync.idle_timeout".into(),
7974                        message: "sync_until_idle exceeded its deadline".into(),
7975                        details: Some(serde_json::json!({
7976                            "timeoutMs": deadline_ms
7977                                .saturating_sub(started_at_ms) as u64,
7978                            "rounds": spent,
7979                        })),
7980                        recommended_action: Some("retryLater".into()),
7981                    };
7982                }
7983            }
7984            spent += 1;
7985            let before = self.resume_tokens();
7986            match self.sync(transport) {
7987                SyncOutcome::Failed {
7988                    error_code,
7989                    message,
7990                    details,
7991                    recommended_action,
7992                } => {
7993                    return SyncOutcome::Failed {
7994                        details,
7995                        error_code,
7996                        message,
7997                        recommended_action,
7998                    };
7999                }
8000                outcome @ SyncOutcome::RealtimeUnavailable { .. } => return outcome,
8001                SyncOutcome::BudgetExhausted(_) => {
8002                    unreachable!("sync() never exhausts a round budget")
8003                }
8004                SyncOutcome::Ok(report) => {
8005                    if max_rounds.is_none()
8006                        && report.segment_rows_applied > 0
8007                        && !report.bootstrapping.is_empty()
8008                        && before != self.resume_tokens()
8009                    {
8010                        spent = 0;
8011                    }
8012                    // TS parity: a disabled transport or a schema floor ends
8013                    // the loop. The latest round still merges first.
8014                    let stop = !self.transport_enabled() || report.schema_floor.is_some();
8015                    aggregate.merge(&report);
8016                    if stop {
8017                        return SyncOutcome::Ok(aggregate);
8018                    }
8019                    // §4.5: pull again whenever the response contained
8020                    // commits or segments; resets re-bootstrap; a pending
8021                    // resume token continues paging (§4.7); deferred outbox
8022                    // commits and a raised sync-needed signal push on the next
8023                    // round.
8024                    let more = !report.bootstrapping.is_empty()
8025                        || report.commits_applied > 0
8026                        || report.segment_rows_applied > 0
8027                        || !report.resets.is_empty()
8028                        || report.deferred_commits > 0
8029                        || self.sync_needed;
8030                    if !more {
8031                        return SyncOutcome::Ok(aggregate);
8032                    }
8033                }
8034            }
8035        }
8036        // §7.8: partial success. The aggregate report is retained and the run
8037        // is explicitly not idle.
8038        SyncOutcome::BudgetExhausted(aggregate)
8039    }
8040
8041    fn process_response(
8042        &mut self,
8043        transport: &mut dyn Transport,
8044        response: Message,
8045        meta: &RequestMeta,
8046    ) -> SyncOutcome {
8047        #[cfg(feature = "bench-internals")]
8048        let _phase = self.benchmark_phases.start(Phase::ResponseApply);
8049        let mut report = SyncReport {
8050            pushed: meta.pushed_ids.len() as u32,
8051            ..SyncReport::default()
8052        };
8053        let mut rejection_details_by_commit: HashMap<String, BTreeMap<i32, RejectionDetails>> =
8054            HashMap::new();
8055        let pushed_ids = meta
8056            .pushed_ids
8057            .iter()
8058            .map(String::as_str)
8059            .collect::<HashSet<_>>();
8060        let mut last_final_push_result_id: Option<String> = None;
8061        for frame in &response.frames {
8062            match frame {
8063                Frame::PushResultDetails {
8064                    client_commit_id,
8065                    entries,
8066                } => {
8067                    let details = rejection_details_by_commit
8068                        .entry(client_commit_id.clone())
8069                        .or_default();
8070                    for entry in entries {
8071                        let parsed = match RejectionDetails::parse(&entry.details.0) {
8072                            Ok(value) => value,
8073                            Err(message) => {
8074                                return SyncOutcome::Failed {
8075                                    details: None,
8076                                    error_code: "sync.invalid_request".to_owned(),
8077                                    message,
8078                                    recommended_action: None,
8079                                };
8080                            }
8081                        };
8082                        details.insert(entry.op_index, parsed);
8083                    }
8084                }
8085                Frame::PushResult {
8086                    client_commit_id,
8087                    status,
8088                    results,
8089                    ..
8090                } if pushed_ids.contains(client_commit_id.as_str())
8091                    && Self::push_result_is_final(*status, results) =>
8092                {
8093                    last_final_push_result_id = Some(client_commit_id.clone());
8094                }
8095                _ => {}
8096            }
8097        }
8098        let mut frames = response.frames.into_iter().peekable();
8099        match frames.next() {
8100            Some(Frame::RespHeader {
8101                required_schema_version,
8102                latest_schema_version,
8103                log_epoch,
8104                reset_required,
8105            }) => {
8106                if let Some(required) = required_schema_version {
8107                    // §1.6 schema-floor response: nothing else is processed;
8108                    // stop syncing and surface the upgrade requirement.
8109                    let floor = SchemaFloor {
8110                        required_schema_version: Some(required),
8111                        latest_schema_version,
8112                    };
8113                    if let Err(message) = self.set_schema_floor(Some(floor.clone())) {
8114                        return SyncOutcome::Failed {
8115                            details: None,
8116                            error_code: "storage.failed".to_owned(),
8117                            message,
8118                            recommended_action: None,
8119                        };
8120                    }
8121                    report.schema_floor = Some(floor);
8122                    return SyncOutcome::Ok(report);
8123                }
8124                if reset_required {
8125                    if frames.next().is_some() {
8126                        return SyncOutcome::Failed {
8127                            details: None,
8128                            error_code: "client.invalid_host_response".to_owned(),
8129                            message: "log-epoch reset response contains body frames".to_owned(),
8130                            recommended_action: None,
8131                        };
8132                    }
8133                    match self.run_log_epoch_reset(&log_epoch) {
8134                        Ok(resets) => {
8135                            report.resets = resets;
8136                            return SyncOutcome::Ok(report);
8137                        }
8138                        Err(message) => {
8139                            return SyncOutcome::Failed {
8140                                details: None,
8141                                error_code: "sync.local_corrupt".to_owned(),
8142                                message,
8143                                recommended_action: None,
8144                            };
8145                        }
8146                    }
8147                }
8148                let stored_epoch = match self.get_meta(LOG_EPOCH_KEY) {
8149                    Ok(stored) => stored,
8150                    Err(message) => {
8151                        return SyncOutcome::Failed {
8152                            details: None,
8153                            error_code: "storage.failed".to_owned(),
8154                            message,
8155                            recommended_action: None,
8156                        };
8157                    }
8158                };
8159                if stored_epoch.as_deref() != Some(log_epoch.as_str()) {
8160                    return SyncOutcome::Failed {
8161                        details: None,
8162                        error_code: "client.invalid_host_response".to_owned(),
8163                        message: "server changed logEpoch without requiring a reset".to_owned(),
8164                        recommended_action: None,
8165                    };
8166                }
8167            }
8168            _ => {
8169                return SyncOutcome::Failed {
8170                    details: None,
8171                    error_code: "sync.invalid_request".to_owned(),
8172                    message: "response does not start with RESP_HEADER".to_owned(),
8173                    recommended_action: None,
8174                };
8175            }
8176        }
8177
8178        if let Err(message) = self.begin_coalesced_apply() {
8179            return SyncOutcome::Failed {
8180                details: None,
8181                error_code: "storage.failed".into(),
8182                message,
8183                recommended_action: None,
8184            };
8185        }
8186        let mut failure: Option<(String, String, Option<String>, Option<Value>)> = None;
8187        // §4.5 client application: the units whose persisted echo a live
8188        // change must match, fixed at LIVE_START after every SUB_END persisted.
8189        let mut live: Option<(LiveStatus, String, Vec<UnitRecord>)> = None;
8190        let mut live_ended = false;
8191        while let Some(frame) = frames.next() {
8192            match frame {
8193                frame @ Frame::PushResult { .. } => {
8194                    let successful = matches!(
8195                        &frame,
8196                        Frame::PushResult {
8197                            status: PushStatus::Applied | PushStatus::Cached,
8198                            ..
8199                        }
8200                    );
8201                    let mut results = vec![frame];
8202                    if successful {
8203                        while matches!(
8204                            frames.peek(),
8205                            Some(Frame::PushResult {
8206                                status: PushStatus::Applied | PushStatus::Cached,
8207                                ..
8208                            })
8209                        ) {
8210                            if let Some(next) = frames.next() {
8211                                results.push(next);
8212                            }
8213                        }
8214                    }
8215                    if self
8216                        .handle_push_results(
8217                            &results,
8218                            &pushed_ids,
8219                            &rejection_details_by_commit,
8220                            &mut report,
8221                            last_final_push_result_id.as_deref(),
8222                        )
8223                        .is_err()
8224                    {
8225                        failure = Some((
8226                            "client.outcome_persistence_failed".to_owned(),
8227                            "local commit outcome could not be persisted".to_owned(),
8228                            None,
8229                            None,
8230                        ));
8231                        break;
8232                    }
8233                }
8234                Frame::PushResultDetails { .. } => {}
8235                Frame::SubStart {
8236                    id,
8237                    status,
8238                    reason_code,
8239                    bootstrap,
8240                    fenced,
8241                } => {
8242                    // §1.4 rule 5: an ERROR closes the section; its body still
8243                    // applied, its SUB_END values are never persisted.
8244                    let mut body = Vec::new();
8245                    let mut sub_end: Option<(i64, Option<String>)> = None;
8246                    let mut error: Option<Frame> = None;
8247                    for inner in frames.by_ref() {
8248                        match inner {
8249                            Frame::SubEnd {
8250                                next_cursor,
8251                                bootstrap_state,
8252                            } => {
8253                                sub_end = Some((next_cursor, bootstrap_state.map(|r| r.0)));
8254                                break;
8255                            }
8256                            inner @ Frame::Error { .. } => {
8257                                error = Some(inner);
8258                                break;
8259                            }
8260                            Frame::Unknown { .. } => {}
8261                            other => body.push(other),
8262                        }
8263                    }
8264                    let ended = sub_end.is_some();
8265                    let section = SectionStart {
8266                        id,
8267                        status,
8268                        reason_code,
8269                        bootstrap,
8270                        fenced,
8271                    };
8272                    match self.process_section(
8273                        transport,
8274                        &section,
8275                        body,
8276                        sub_end,
8277                        meta,
8278                        &mut report,
8279                    ) {
8280                        Err(SectionError::Abort(code, message)) => {
8281                            failure = Some((code, message, None, None));
8282                            break;
8283                        }
8284                        Err(SectionError::Transport(error)) => {
8285                            failure = Some((error.code, error.message, None, error.details));
8286                            break;
8287                        }
8288                        _ => {}
8289                    }
8290                    if ended {
8291                        // The counters stay: `complete` and `failed` report them.
8292                        self.progress.update(|p| {
8293                            p.unit_id = None;
8294                            p.table = None;
8295                            p.segment_id = None;
8296                        });
8297                    }
8298                    match error {
8299                        Some(Frame::Error {
8300                            code,
8301                            message,
8302                            recommended_action,
8303                            details,
8304                            ..
8305                        }) => {
8306                            failure = Some(Self::error_frame_failure(
8307                                code,
8308                                message,
8309                                recommended_action,
8310                                details,
8311                            ));
8312                            break;
8313                        }
8314                        Some(_) => unreachable!("only an ERROR closes a section early"),
8315                        None if !ended => {
8316                            failure = Some((
8317                                "sync.invalid_request".to_owned(),
8318                                "unit section without SUB_END".to_owned(),
8319                                None,
8320                                None,
8321                            ));
8322                            break;
8323                        }
8324                        None => {}
8325                    }
8326                }
8327                Frame::LiveStart {
8328                    status,
8329                    reason_code,
8330                } => {
8331                    let receivers = match self.stored(load_units(&self.conn)) {
8332                        Ok(units) => units
8333                            .into_iter()
8334                            .filter(|unit| {
8335                                unit.status == UnitStatus::Active
8336                                    && unit.echo.is_some()
8337                                    && !unit.bootstrapping()
8338                            })
8339                            .collect(),
8340                        Err(message) => {
8341                            failure = Some(("storage.failed".to_owned(), message, None, None));
8342                            break;
8343                        }
8344                    };
8345                    live = Some((status, reason_code, receivers));
8346                }
8347                Frame::Commit {
8348                    commit_seq,
8349                    tables,
8350                    changes,
8351                    ..
8352                } => {
8353                    let Some((LiveStatus::Active, _, receivers)) = &live else {
8354                        continue;
8355                    };
8356                    let receivers = receivers.clone();
8357                    match self.apply_live_commit(
8358                        &receivers,
8359                        &tables,
8360                        changes,
8361                        commit_seq,
8362                        AppliedServerCommitSource::Pull,
8363                    ) {
8364                        Ok(applied) => report.commits_applied += u32::from(applied),
8365                        Err(error) => {
8366                            failure = Some((error.code, error.message, None, error.details));
8367                            break;
8368                        }
8369                    }
8370                }
8371                Frame::LiveEnd {
8372                    through_seq,
8373                    echo_digest,
8374                } => {
8375                    let Some((status, reason_code, _)) = live.take() else {
8376                        continue;
8377                    };
8378                    live_ended = true;
8379                    live = Some((status, String::new(), Vec::new()));
8380                    if let Err(message) = self.finish_live_section(
8381                        status,
8382                        &reason_code,
8383                        through_seq,
8384                        echo_digest,
8385                        &meta.registration_digest,
8386                        &mut report,
8387                    ) {
8388                        failure = Some(("storage.failed".to_owned(), message, None, None));
8389                        break;
8390                    }
8391                }
8392                Frame::Lease {
8393                    lease_id,
8394                    expires_at_ms,
8395                } => {
8396                    // §7.3.5: persist the opaque lease; a fresh lease clears
8397                    // any prior lease error (the outage/revocation is over).
8398                    if let Err(message) = self.set_lease_state(Some(LeaseState {
8399                        lease_id: Some(lease_id),
8400                        expires_at_ms: Some(expires_at_ms),
8401                        error_code: None,
8402                    })) {
8403                        failure = Some(("storage.failed".to_owned(), message, None, None));
8404                        break;
8405                    }
8406                }
8407                Frame::Error {
8408                    code,
8409                    message,
8410                    recommended_action,
8411                    details,
8412                    ..
8413                } => {
8414                    // §1.6: the whole request failed; already-completed
8415                    // units keep their applied data and cursors.
8416                    failure = Some(Self::error_frame_failure(
8417                        code,
8418                        message,
8419                        recommended_action,
8420                        details,
8421                    ));
8422                    break;
8423                }
8424                Frame::Unknown { .. } => {}
8425                _ => {
8426                    failure = Some((
8427                        "sync.invalid_request".to_owned(),
8428                        "unexpected frame in response".to_owned(),
8429                        None,
8430                        None,
8431                    ));
8432                    break;
8433                }
8434            }
8435        }
8436
8437        let applied = match failure {
8438            Some(failure) => Err(failure),
8439            // Local apply boundaries already reconciled their affected overlay.
8440            // Refuse round success if any remaining dirty work fails to
8441            // reconcile. §4.8 E1: the push half may have drained commits that
8442            // pinned rows of a shrunk window unit, so retry deferred evictions.
8443            None => self
8444                .rebuild_overlay_if_dirty()
8445                .and_then(|()| self.drain_pending_evictions())
8446                .map_err(|message| ("storage.failed".to_owned(), message, None, None)),
8447        };
8448        // §1.4 rule 4: frames completed before a failure stay committed; a
8449        // failed COMMIT of the coalesced transaction fails the round.
8450        if let Err(message) = self.finish_coalesced_apply() {
8451            return SyncOutcome::Failed {
8452                details: None,
8453                error_code: "storage.failed".into(),
8454                message,
8455                recommended_action: None,
8456            };
8457        }
8458        if let Err((error_code, message, recommended_action, details)) = applied {
8459            return SyncOutcome::Failed {
8460                details,
8461                error_code,
8462                message,
8463                recommended_action,
8464            };
8465        }
8466        let catching_up = match self.stored(load_units(&self.conn)) {
8467            Ok(units) => units
8468                .into_iter()
8469                .filter(|unit| unit.status == UnitStatus::Active && unit.cursor.is_some())
8470                .map(|unit| unit.id)
8471                .collect::<Vec<_>>(),
8472            Err(message) => {
8473                return SyncOutcome::Failed {
8474                    details: None,
8475                    error_code: "storage.failed".into(),
8476                    message,
8477                    recommended_action: None,
8478                }
8479            }
8480        };
8481        // §7.1: a response without LIVE_END, one answered `unregistered` or
8482        // `reset`, or a unit still catching up leaves sync-needed raised;
8483        // after `unregistered` the next round starts at once.
8484        let status = live.map(|(status, _, _)| status);
8485        if !live_ended || status != Some(LiveStatus::Active) || !catching_up.is_empty() {
8486            self.set_sync_needed(true, status == Some(LiveStatus::Unregistered));
8487        }
8488        self.ack_after_pull(transport);
8489        // §7.4.5: the reset is over once the first post-reset pull round
8490        // leaves no unit catching up: the tables are rebuilt and current.
8491        if self.upgrading && catching_up.is_empty() {
8492            self.set_upgrading(false);
8493        }
8494        report.bootstrapping = catching_up;
8495        SyncOutcome::Ok(report)
8496    }
8497
8498    /// §1.6 / §10.1: the failure an in-band `ERROR` frame reports.
8499    fn error_frame_failure(
8500        code: String,
8501        message: String,
8502        recommended_action: String,
8503        details: Option<RawJson>,
8504    ) -> (String, String, Option<String>, Option<Value>) {
8505        let recommended_action = (!recommended_action.is_empty()).then_some(recommended_action);
8506        let details = details
8507            .and_then(|details| serde_json::from_str::<Value>(&details.0).ok())
8508            .filter(Value::is_object);
8509        (code, message, recommended_action, details)
8510    }
8511
8512    /// §4.5 at `LIVE_END` of a pull: join rule J for an `active` section, the
8513    /// §4.6 replica reset for `reset`, nothing for `unregistered`; then the
8514    /// replica cursor, the echo digest and the digest of the list the server
8515    /// now stores.
8516    fn finish_live_section(
8517        &mut self,
8518        status: LiveStatus,
8519        reason_code: &str,
8520        through_seq: i64,
8521        echo_digest: Option<[u8; 32]>,
8522        registration_digest: &str,
8523        report: &mut SyncReport,
8524    ) -> Result<(), String> {
8525        let rollback = self.capture();
8526        let resets = report.resets.len();
8527        self.begin_observation("syncular_live_end")?;
8528        let finished = (|| {
8529            let mut batch = ChangeAccumulator::default();
8530            let before = self.stored(replica_cursor(&self.conn))?;
8531            let mut cursor = if status == LiveStatus::Unregistered {
8532                before
8533            } else {
8534                -1
8535            };
8536            let joined = before.max(through_seq);
8537            for unit in self.stored(load_units(&self.conn))? {
8538                if unit.status != UnitStatus::Active || unit.bootstrapping() {
8539                    continue;
8540                }
8541                match status {
8542                    // §4.6 replica reset: every live unit bootstraps again;
8543                    // post-bootstrap units keep their cursors.
8544                    LiveStatus::Reset if unit.cursor.is_none() => {
8545                        for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
8546                            batch.window(&base_key, &value);
8547                        }
8548                        report.resets.push(unit.id.clone());
8549                        self.stored(save_unit(
8550                            &self.conn,
8551                            &UnitRecord {
8552                                reason_code: Some(reason_code.to_owned()),
8553                                cursor: Some(-1),
8554                                seeded: Vec::new(),
8555                                ..unit
8556                            },
8557                        ))?;
8558                    }
8559                    // §4.5 join rule J.
8560                    LiveStatus::Active => {
8561                        let next = unit.cursor.unwrap_or(joined).max(through_seq);
8562                        if next >= joined {
8563                            cursor = joined;
8564                        }
8565                        if unit.cursor.is_some() {
8566                            self.stored(save_unit(
8567                                &self.conn,
8568                                &UnitRecord {
8569                                    cursor: (next < joined).then_some(next),
8570                                    ..unit
8571                                },
8572                            ))?;
8573                        }
8574                    }
8575                    _ => {}
8576                }
8577            }
8578            self.set_meta(REPLICA_CURSOR_KEY, &cursor.to_string())?;
8579            self.set_meta(
8580                ECHO_DIGEST_KEY,
8581                &echo_digest
8582                    .map(|digest| bytes_to_hex(&digest))
8583                    .unwrap_or_default(),
8584            )?;
8585            if status == LiveStatus::Unregistered {
8586                self.delete_meta(REGISTERED_DIGEST_KEY)?;
8587            } else {
8588                self.set_meta(REGISTERED_DIGEST_KEY, registration_digest)?;
8589            }
8590            self.finish_observation("syncular_live_end", batch)
8591        })();
8592        if finished.is_err() {
8593            self.rollback_observation("syncular_live_end");
8594            self.restore(rollback);
8595            report.resets.truncate(resets);
8596        }
8597        finished
8598    }
8599
8600    // -- push results (§6.3, §7.2) ------------------------------------------------
8601
8602    fn handle_push_results(
8603        &mut self,
8604        frames: &[Frame],
8605        pushed_ids: &HashSet<&str>,
8606        rejection_details_by_commit: &HashMap<String, BTreeMap<i32, RejectionDetails>>,
8607        report: &mut SyncReport,
8608        last_final_push_result_id: Option<&str>,
8609    ) -> Result<(), String> {
8610        self.begin_observation("syncular_push_results")?;
8611        let rollback = self.capture();
8612        let conflict_count = self.conflicts.len();
8613        let applied_count = report.applied.len();
8614        let rejected_count = report.rejected.len();
8615        let retryable_count = report.retryable.len();
8616        let mut drained = Vec::new();
8617        let mut batch = ChangeAccumulator::default();
8618        let persisted = (|| {
8619            for frame in frames {
8620                let Frame::PushResult {
8621                    client_commit_id,
8622                    status,
8623                    results,
8624                    commit_seq,
8625                } = frame
8626                else {
8627                    return Err("unexpected acknowledgement frame".to_owned());
8628                };
8629                if !pushed_ids.contains(client_commit_id.as_str()) {
8630                    continue;
8631                }
8632                let Some(index) = self
8633                    .outbox
8634                    .iter()
8635                    .position(|commit| commit.client_commit_id == *client_commit_id)
8636                else {
8637                    continue;
8638                };
8639                let status = *status;
8640                let rejection_details = rejection_details_by_commit.get(client_commit_id);
8641                let operations = self.outbox[index].ops.clone();
8642                match status {
8643                    PushStatus::Applied | PushStatus::Cached => {
8644                        // §7.2: a lost ack replays as `cached` — proceed as if the
8645                        // ack had arrived.
8646                        let sequence =
8647                            commit_seq.ok_or_else(|| "ACK lacks a commit sequence".to_owned())?;
8648                        let affected: HashSet<_> = operations
8649                            .iter()
8650                            .map(|op| (op.table.as_str(), op.row_id.as_str()))
8651                            .collect();
8652                        let prior = self.acknowledged_operations(Some(&affected), None)?;
8653                        for (op_index, operation) in operations.iter().enumerate() {
8654                            let delivered: bool = self.conn.query_row("SELECT EXISTS(SELECT 1 FROM _syncular_row_deliveries WHERE tbl=?1 AND id=?2 AND commit_seq>=?3)", rusqlite::params![operation.table, operation.row_id, sequence], |row| row.get(0))
8655                                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
8656                            if delivered {
8657                                continue;
8658                            }
8659                            let table = self
8660                                .schema
8661                                .table(&operation.table)
8662                                .ok_or_else(|| "sync.unknown_table".to_owned())?;
8663                            let mut intended: Map<String, Value> = self
8664                                .stored_row(table, &operation.row_id, true)?
8665                                .map(|(row, _)| {
8666                                    table
8667                                        .columns
8668                                        .iter()
8669                                        .zip(&row)
8670                                        .map(|(column, value)| {
8671                                            (column.name.clone(), column_value_to_json(value))
8672                                        })
8673                                        .collect()
8674                                })
8675                                .unwrap_or_default();
8676                            let mut scope_image = intended.clone();
8677                            for op in prior
8678                                .iter()
8679                                .chain(
8680                                    self.failed_commits
8681                                        .iter()
8682                                        .flat_map(|(commit, _)| &commit.ops),
8683                                )
8684                                .chain(
8685                                    self.outbox
8686                                        .iter()
8687                                        .take(index)
8688                                        .flat_map(|commit| &commit.ops),
8689                                )
8690                                .chain(operations.iter().take(op_index + 1))
8691                            {
8692                                if op.table != operation.table || op.row_id != operation.row_id {
8693                                    continue;
8694                                }
8695                                if let Some(values) = &op.values {
8696                                    intended.extend(values.clone());
8697                                } else {
8698                                    scope_image = intended.clone();
8699                                    intended.clear();
8700                                }
8701                            }
8702                            self.conn.execute("INSERT INTO _syncular_acked_rows(commit_id,idx,tbl,id,commit_seq,op_json,intent_json) VALUES (?1,?2,?3,?4,?5,?6,?7)",
8703                                rusqlite::params![client_commit_id, op_index as i64, operation.table, operation.row_id, sequence,
8704                                    serde_json::to_string(&CommitOperation::from(operation)).map_err(|_| "sync.local_corrupt".to_owned())?,
8705                                    serde_json::to_string(if operation.upsert { &intended } else { &scope_image }).map_err(|_| "sync.local_corrupt".to_owned())?])
8706                                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
8707                        }
8708                        let journal_results = results
8709                            .iter()
8710                            .map(|result| {
8711                                let op_index = match result {
8712                                    OpResult::Applied { op_index }
8713                                    | OpResult::Conflict { op_index, .. }
8714                                    | OpResult::Error { op_index, .. } => *op_index,
8715                                };
8716                                CommitOperationOutcome::Applied { op_index }
8717                            })
8718                            .collect::<Vec<_>>();
8719                        let outcome_status = if status == PushStatus::Applied {
8720                            CommitOutcomeStatus::Applied
8721                        } else {
8722                            CommitOutcomeStatus::Cached
8723                        };
8724                        let persisted = self
8725                            .persist_commit_outcome(
8726                                client_commit_id,
8727                                outcome_status,
8728                                &journal_results,
8729                                None,
8730                            )
8731                            .and_then(|()| self.delete_outbox_persisted(client_commit_id));
8732                        persisted?;
8733                        self.sync_needed = true;
8734                        batch.status = true;
8735                        batch.outcomes = true;
8736                    }
8737                    PushStatus::Rejected => {
8738                        if results.iter().any(|result| {
8739                            matches!(
8740                                result,
8741                                OpResult::Error {
8742                                    code,
8743                                    retryable: true,
8744                                    ..
8745                                } if code == "sync.idempotency_cache_miss"
8746                            )
8747                        }) {
8748                            // §6.3/§7.2: a serving failure, not an outcome — keep the
8749                            // exact commit queued for an identical retry.
8750                            report.retryable.push(client_commit_id.to_owned());
8751                            continue;
8752                        }
8753
8754                        let mut journal_results = Vec::with_capacity(results.len());
8755                        let mut conflicts = Vec::new();
8756                        let mut rejections = Vec::new();
8757                        for result in results {
8758                            match result {
8759                                OpResult::Applied { op_index } => {
8760                                    journal_results.push(CommitOperationOutcome::Applied {
8761                                        op_index: *op_index,
8762                                    });
8763                                }
8764                                OpResult::Conflict {
8765                                    op_index,
8766                                    code,
8767                                    message,
8768                                    server_version,
8769                                    server_row,
8770                                    conflict_columns: conflict_columns_bitmap,
8771                                } => {
8772                                    let operation = operations
8773                                        .get(*op_index as usize)
8774                                        .map(CommitOperation::from);
8775                                    let (table, row_id) = operation
8776                                        .as_ref()
8777                                        .map(|op| (op.table.clone(), op.row_id.clone()))
8778                                        .unwrap_or_default();
8779                                    let server_row_json = self
8780                                        .schema
8781                                        .table(&table)
8782                                        .and_then(|t| {
8783                                            decode_row_bytes(t, server_row, &self.encryption)
8784                                                .ok()
8785                                                .map(|row| (t, row))
8786                                        })
8787                                        .map(|(t, row)| {
8788                                            let mut map = Map::new();
8789                                            for (i, column) in t.columns.iter().enumerate() {
8790                                                map.insert(
8791                                                    column.name.clone(),
8792                                                    column_value_to_json(
8793                                                        row.get(i).unwrap_or(&None),
8794                                                    ),
8795                                                );
8796                                            }
8797                                            map
8798                                        })
8799                                        .unwrap_or_default();
8800                                    // §6.3: decode the presence-layout bitmap
8801                                    // into the marked column names.
8802                                    let conflict_columns = self
8803                                        .schema
8804                                        .table(&table)
8805                                        .map(|t| {
8806                                            t.columns
8807                                                .iter()
8808                                                .enumerate()
8809                                                .filter(|(index, _)| {
8810                                                    conflict_columns_bitmap
8811                                                        .get(index / 8)
8812                                                        .is_some_and(|byte| {
8813                                                            byte & (1 << (index % 8)) != 0
8814                                                        })
8815                                                })
8816                                                .map(|(_, column)| column.name.clone())
8817                                                .collect::<Vec<_>>()
8818                                        })
8819                                        .unwrap_or_default();
8820                                    let conflict = ConflictRecord {
8821                                        client_commit_id: client_commit_id.to_owned(),
8822                                        op_index: *op_index,
8823                                        table,
8824                                        row_id,
8825                                        code: code.clone(),
8826                                        message: message.clone(),
8827                                        server_version: *server_version,
8828                                        server_row: server_row_json,
8829                                        conflict_columns,
8830                                        operation,
8831                                    };
8832                                    journal_results.push(CommitOperationOutcome::Conflict {
8833                                        conflict: conflict.clone(),
8834                                    });
8835                                    conflicts.push(conflict);
8836                                }
8837                                OpResult::Error {
8838                                    op_index,
8839                                    code,
8840                                    message,
8841                                    retryable,
8842                                } => {
8843                                    let rejection = RejectionRecord {
8844                                        client_commit_id: client_commit_id.to_owned(),
8845                                        op_index: *op_index,
8846                                        code: code.clone(),
8847                                        message: message.clone(),
8848                                        retryable: *retryable,
8849                                        details: rejection_details
8850                                            .and_then(|details| details.get(op_index))
8851                                            .cloned(),
8852                                        operation: operations
8853                                            .get(*op_index as usize)
8854                                            .map(CommitOperation::from),
8855                                    };
8856                                    journal_results.push(CommitOperationOutcome::Error {
8857                                        rejection: rejection.clone(),
8858                                    });
8859                                    rejections.push(rejection);
8860                                }
8861                            }
8862                        }
8863                        if self.retain_failed_commits {
8864                            self.retain_failed_commit(client_commit_id, &operations)?;
8865                        }
8866                        let outcome_status = if conflicts.is_empty() {
8867                            CommitOutcomeStatus::Rejected
8868                        } else {
8869                            CommitOutcomeStatus::Conflict
8870                        };
8871                        let persisted = self
8872                            .persist_commit_outcome(
8873                                client_commit_id,
8874                                outcome_status,
8875                                &journal_results,
8876                                Some(&operations),
8877                            )
8878                            .and_then(|()| self.delete_outbox_persisted(client_commit_id));
8879                        persisted?;
8880                        batch.conflicts = !conflicts.is_empty();
8881                        batch.rejections = !rejections.is_empty();
8882                        batch.status = true;
8883                        batch.outcomes = true;
8884                        self.conflicts.extend(conflicts);
8885                        self.rejections.extend(rejections);
8886                    }
8887                }
8888                drained.push(self.outbox.remove(index));
8889                if batch.status {
8890                    for operation in &operations {
8891                        if !self.record_row_scopes(
8892                            &mut batch,
8893                            &operation.table,
8894                            &operation.row_id,
8895                            false,
8896                        ) {
8897                            batch.table(&operation.table);
8898                        }
8899                    }
8900                }
8901                match status {
8902                    PushStatus::Applied | PushStatus::Cached => {
8903                        report.applied.push(client_commit_id.to_owned())
8904                    }
8905                    PushStatus::Rejected => report.rejected.push(client_commit_id.to_owned()),
8906                }
8907            }
8908            if batch.outcomes && frames.iter().any(|frame| matches!(frame, Frame::PushResult { client_commit_id, .. } if Some(client_commit_id.as_str()) == last_final_push_result_id)) {
8909                self.prune_commit_outcomes()?;
8910            }
8911            self.reconcile_rows(&drained)?;
8912            self.rebuild_overlay_if_dirty()?;
8913            self.finish_observation("syncular_push_results", batch)
8914        })();
8915        if let Err(error) = persisted {
8916            self.rollback_observation("syncular_push_results");
8917            self.restore(rollback);
8918            report.applied.truncate(applied_count);
8919            report.rejected.truncate(rejected_count);
8920            report.retryable.truncate(retryable_count);
8921            return Err(error);
8922        }
8923        if !rollback.sync_needed && self.sync_needed {
8924            self.sync_intent_queue.push_back(SyncIntent::Interactive);
8925        }
8926        report.conflicts += (self.conflicts.len() - conflict_count) as u32;
8927        Ok(())
8928    }
8929
8930    fn push_result_is_final(status: PushStatus, results: &[OpResult]) -> bool {
8931        status != PushStatus::Rejected
8932            || !results.iter().any(|result| {
8933                matches!(
8934                    result,
8935                    OpResult::Error {
8936                        code,
8937                        retryable: true,
8938                        ..
8939                    } if code == "sync.idempotency_cache_miss"
8940                )
8941            })
8942    }
8943
8944    // -- unit sections and the live section ------------------------------------------
8945
8946    /// One unit section (§4.4): apply its segments, then persist its
8947    /// `SUB_END` (§4.6 reset, §3.3 revocation and purge, the echo, cursor and
8948    /// resume token). A section of a unit the app released while the round was
8949    /// in flight is skipped; a fail-closed first page fails the unit and skips
8950    /// the rest of its section (§5.6).
8951    fn process_section(
8952        &mut self,
8953        transport: &mut dyn Transport,
8954        start: &SectionStart,
8955        body: Vec<Frame>,
8956        sub_end: Option<(i64, Option<String>)>,
8957        meta: &RequestMeta,
8958        report: &mut SyncReport,
8959    ) -> Result<(), SectionError> {
8960        let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
8961        let unit = self
8962            .stored(get_unit(&self.conn, &start.id))
8963            .map_err(storage)?
8964            .filter(|unit| unit.status == UnitStatus::Active);
8965        // §7.7: a section boundary ends the previous payload.
8966        self.progress.update(|p| {
8967            p.phase = ProgressPhase::Import;
8968            p.unit_id = unit.as_ref().map(|unit| unit.id.clone());
8969            p.table = None;
8970            p.segment_id = None;
8971            p.bytes_received = 0;
8972            p.bytes_total = None;
8973            p.rows_processed = 0;
8974            p.rows_total = None;
8975            p.import_write_ms = None;
8976            p.import_commit_ms = None;
8977        });
8978        let Some(unit) = unit else {
8979            return Ok(());
8980        };
8981        let echo: Vec<EchoRecord> = start
8982            .fenced
8983            .iter()
8984            .map(|record| EchoRecord {
8985                table: record.table.clone(),
8986                status: record.status.name().to_owned(),
8987                scopes: record.scopes.iter().cloned().collect(),
8988            })
8989            .collect();
8990        // §5.6: a resumed bootstrap keeps the tables it already seeded.
8991        let mut seeded: BTreeSet<String> = if unit.bootstrap_state.is_none() {
8992            BTreeSet::new()
8993        } else {
8994            unit.seeded.iter().cloned().collect()
8995        };
8996        let applied = (|| {
8997            for frame in body {
8998                match frame {
8999                    Frame::SegmentInline { payload } => {
9000                        let segment = decode_rows_segment(&payload).map_err(|e| {
9001                            SectionError::Abort(e.code.as_str().to_owned(), e.detail)
9002                        })?;
9003                        self.progress.update(|p| {
9004                            p.phase = ProgressPhase::Import;
9005                            p.unit_id = Some(unit.id.clone());
9006                            p.table = Some(segment.table.clone());
9007                            p.segment_id = None;
9008                            p.bytes_received = payload.len() as u64;
9009                            p.bytes_total = Some(payload.len() as u64);
9010                            p.rows_processed = 0;
9011                            p.rows_total =
9012                                Some(segment.blocks.iter().map(|block| block.len() as u64).sum());
9013                            p.import_write_ms = None;
9014                            p.import_commit_ms = None;
9015                        });
9016                        let (pair, clear, effective) =
9017                            self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
9018                        report.segment_rows_applied +=
9019                            self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
9020                        seeded.insert(segment.table);
9021                    }
9022                    Frame::SegmentRef {
9023                        segment_id,
9024                        byte_length,
9025                        media_type,
9026                        table,
9027                        row_count,
9028                        as_of_commit_seq,
9029                        scope_digest,
9030                        row_cursor,
9031                        next_row_cursor,
9032                        url,
9033                        url_expires_at_ms,
9034                        ..
9035                    } => {
9036                        // §4.2: reject a descriptor whose mediaType was not
9037                        // advertised — never skip or guess.
9038                        let advertised = match media_type {
9039                            MediaType::Rows => {
9040                                meta.accept & ACCEPT_EXTERNAL_ROWS != 0
9041                                    || meta.accept & ACCEPT_INLINE_ROWS != 0
9042                            }
9043                            MediaType::Sqlite => meta.accept & ACCEPT_SQLITE != 0,
9044                        };
9045                        if !advertised {
9046                            return Err(SectionError::Abort(
9047                                "sync.invalid_request".to_owned(),
9048                                format!(
9049                                    "SEGMENT_REF mediaType {} was not advertised in accept (§4.2)",
9050                                    media_type.name()
9051                                ),
9052                            ));
9053                        }
9054                        self.progress.update(|p| {
9055                            p.phase = ProgressPhase::Download;
9056                            p.unit_id = Some(unit.id.clone());
9057                            p.table = Some(table.clone());
9058                            p.segment_id = Some(segment_id.clone());
9059                            p.bytes_received = 0;
9060                            p.bytes_total = u64::try_from(byte_length).ok();
9061                            p.rows_processed = 0;
9062                            p.rows_total = u64::try_from(row_count).ok();
9063                            p.import_write_ms = None;
9064                            p.import_commit_ms = None;
9065                        });
9066                        let observer = self.progress.clone();
9067                        let mut on_progress = |bytes| observer.update(|p| p.bytes_received = bytes);
9068                        let bytes = if let Some(url) = url {
9069                            // §5.4: a url-carrying descriptor MUST be fetched
9070                            // from that URL; failure invalidates the whole
9071                            // descriptor (no fall-through to §5.5 — re-pull
9072                            // recovers, §1.4 rule 5).
9073                            if meta.accept & ACCEPT_SIGNED_URLS == 0 {
9074                                return Err(SectionError::Abort(
9075                                    "sync.invalid_request".to_owned(),
9076                                    "SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)"
9077                                        .to_owned(),
9078                                ));
9079                            }
9080                            // §5.4: MUST NOT start a fetch at/past expiry.
9081                            if url_expires_at_ms.is_some_and(|exp| {
9082                                exp <= transport
9083                                    .segment_fetch_started_at(&url)
9084                                    .unwrap_or_else(|| self.clock_now_ms())
9085                            }) {
9086                                return Err(SectionError::Abort(
9087                                    "sync.segment_expired".to_owned(),
9088                                    format!(
9089                                        "signed URL for segment {segment_id} expired before fetch — re-pull mints fresh descriptors (§5.4)"
9090                                    ),
9091                                ));
9092                            }
9093                            transport
9094                                .fetch_url(
9095                                    &url,
9096                                    u64::try_from(byte_length).unwrap_or(0),
9097                                    &mut on_progress,
9098                                )
9099                                .map_err(|e| self.segment_fetch_failed(e))?
9100                        } else {
9101                            // §5.5: the owning unit's scope map, each value a one-element list.
9102                            let requested_scopes_json =
9103                                canonical_scope_json(&unit_scope_lists(&unit.scopes));
9104                            transport
9105                                .download_segment(
9106                                    &SegmentRequest {
9107                                        segment_id: segment_id.clone(),
9108                                        table: table.clone(),
9109                                        requested_scopes_json,
9110                                        byte_length: u64::try_from(byte_length).unwrap_or(0),
9111                                    },
9112                                    &mut on_progress,
9113                                )
9114                                .map_err(|e| self.segment_fetch_failed(e))?
9115                        };
9116                        // §5.4: the descriptor's byteLength caps the body before
9117                        // §5.1 verifies the content address; the client discards
9118                        // the segment and re-pulls on either failure.
9119                        if bytes.len() as i64 > byte_length {
9120                            self.schedule_background_retry();
9121                            return Err(SectionError::Abort(
9122                                "sync.invalid_request".to_owned(),
9123                                "segment exceeds its byteLength".to_owned(),
9124                            ));
9125                        }
9126                        on_progress(bytes.len() as u64);
9127                        let digest = Sha256::digest(&bytes);
9128                        let expected = segment_id
9129                            .strip_prefix("sha256:")
9130                            .unwrap_or(segment_id.as_str());
9131                        if bytes_to_hex(&digest) != expected {
9132                            // §5.1: the client discards the segment and re-pulls.
9133                            self.schedule_background_retry();
9134                            return Err(SectionError::Abort(
9135                                "sync.invalid_request".to_owned(),
9136                                "segment bytes do not match the content address (§5.1)".to_owned(),
9137                            ));
9138                        }
9139                        self.progress.update(|p| p.phase = ProgressPhase::Import);
9140                        if media_type == MediaType::Sqlite {
9141                            // §5.3: images are whole-table — a paged sqlite
9142                            // descriptor is invalid.
9143                            if row_cursor.is_some() || next_row_cursor.is_some() {
9144                                return Err(SectionError::Abort(
9145                                    "sync.invalid_request".to_owned(),
9146                                    "sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)"
9147                                        .to_owned(),
9148                                ));
9149                            }
9150                            let (pair, clear, effective) =
9151                                self.segment_pair(&unit, &echo, &seeded, &table)?;
9152                            report.segment_rows_applied += self.apply_sqlite_segment(
9153                                &pair,
9154                                &bytes,
9155                                clear,
9156                                &effective,
9157                                &unit.id,
9158                                row_count,
9159                                as_of_commit_seq,
9160                                &scope_digest,
9161                            )?;
9162                            seeded.insert(table);
9163                        } else {
9164                            let segment = decode_rows_segment(&bytes).map_err(|e| {
9165                                SectionError::Abort(e.code.as_str().to_owned(), e.detail)
9166                            })?;
9167                            let (pair, clear, effective) =
9168                                self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
9169                            report.segment_rows_applied +=
9170                                self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
9171                            seeded.insert(segment.table);
9172                        }
9173                    }
9174                    _ => {
9175                        return Err(SectionError::Abort(
9176                            "sync.invalid_request".to_owned(),
9177                            "unexpected frame inside a unit section".to_owned(),
9178                        ));
9179                    }
9180                }
9181            }
9182            Ok(())
9183        })();
9184        match applied {
9185            Ok(()) => {}
9186            Err(SectionError::FailClosed) => {
9187                // §5.6: the failure is unit-local; the rest of the response
9188                // still applies and the failed unit leaves the list.
9189                self.begin_observation("syncular_section_failure")
9190                    .map_err(storage)?;
9191                let failed = (|| {
9192                    let mut batch = ChangeAccumulator::default();
9193                    for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9194                        batch.window(&base_key, &value);
9195                    }
9196                    batch.status = true;
9197                    self.stored(save_unit(
9198                        &self.conn,
9199                        &UnitRecord {
9200                            status: UnitStatus::Failed,
9201                            reason_code: Some("sync.scope_revoked".to_owned()),
9202                            ..unit.clone()
9203                        },
9204                    ))?;
9205                    self.finish_observation("syncular_section_failure", batch)
9206                })();
9207                if let Err(message) = failed {
9208                    self.rollback_observation("syncular_section_failure");
9209                    return Err(storage(message));
9210                }
9211                report.failed.push(unit.id);
9212                return Ok(());
9213            }
9214            Err(error) => return Err(error),
9215        }
9216        let Some((next_cursor, bootstrap_state)) = sub_end else {
9217            return Ok(());
9218        };
9219        let rollback = self.capture();
9220        let counts = (
9221            report.resets.len(),
9222            report.revoked.len(),
9223            report.failed.len(),
9224        );
9225        self.begin_observation("syncular_sub_end")
9226            .map_err(storage)?;
9227        let finished = self
9228            .finish_section(start, echo, next_cursor, bootstrap_state, seeded, report)
9229            .and_then(|batch| {
9230                self.rebuild_overlay_if_dirty()?;
9231                self.finish_observation("syncular_sub_end", batch)
9232            });
9233        if let Err(message) = finished {
9234            self.rollback_observation("syncular_sub_end");
9235            self.restore(rollback);
9236            report.resets.truncate(counts.0);
9237            report.revoked.truncate(counts.1);
9238            report.failed.truncate(counts.2);
9239            return Err(storage(message));
9240        }
9241        Ok(())
9242    }
9243
9244    /// §5.6: the table, first-page flag and effective scopes of one segment
9245    /// of `unit`'s section.
9246    #[allow(clippy::type_complexity)]
9247    fn segment_pair(
9248        &self,
9249        unit: &UnitRecord,
9250        echo: &[EchoRecord],
9251        seeded: &BTreeSet<String>,
9252        name: &str,
9253    ) -> Result<(TableSchema, bool, Vec<(String, Vec<String>)>), SectionError> {
9254        let table = self.schema.table(name).cloned().ok_or_else(|| {
9255            SectionError::Abort(
9256                "sync.schema_mismatch".to_owned(),
9257                format!("segment table {name:?} is not in the client schema"),
9258            )
9259        })?;
9260        let effective = covers(&table, &unit.scopes)
9261            .then(|| pair_scopes(&unit.scopes, name, Some(echo)))
9262            .flatten()
9263            .ok_or_else(|| {
9264                SectionError::Abort(
9265                    "sync.invalid_request".to_owned(),
9266                    "a segment names no active pair of its unit".to_owned(),
9267                )
9268            })?;
9269        Ok((table, !seeded.contains(name), effective))
9270    }
9271
9272    /// §4.4 `SUB_END` of an active, revoked or reset section, inside the
9273    /// caller's observation: a reset discards cursor, resume token and
9274    /// first-page record and keeps the echo; a revoked pair purges by its last
9275    /// echo (§3.3); otherwise the echo replaces the persisted one, a revoked
9276    /// fenced record that turns active again re-bootstraps the unit, and a
9277    /// bootstrap section persists its pin, resume token and seeded tables.
9278    fn finish_section(
9279        &mut self,
9280        start: &SectionStart,
9281        echo: Vec<EchoRecord>,
9282        next_cursor: i64,
9283        bootstrap_state: Option<String>,
9284        seeded: BTreeSet<String>,
9285        report: &mut SyncReport,
9286    ) -> Result<ChangeAccumulator, String> {
9287        #[cfg(feature = "bench-internals")]
9288        let _phase = self.benchmark_phases.start(Phase::CursorPersist);
9289        let mut batch = ChangeAccumulator::default();
9290        // §4.4: SUB_END writes only into a unit that is still registered.
9291        let Some(unit) = self
9292            .stored(get_unit(&self.conn, &start.id))?
9293            .filter(|unit| unit.status == UnitStatus::Active)
9294        else {
9295            return Ok(batch);
9296        };
9297        for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9298            batch.window(&base_key, &value);
9299        }
9300        if start.status == SubStatus::Reset {
9301            // §4.6: staleness, never a purge; the rows stay until the
9302            // bootstrap replaces them.
9303            report.resets.push(unit.id.clone());
9304            self.stored(save_unit(
9305                &self.conn,
9306                &UnitRecord {
9307                    reason_code: Some(start.reason_code.clone()),
9308                    cursor: Some(-1),
9309                    bootstrap_state: None,
9310                    seeded: Vec::new(),
9311                    ..unit
9312                },
9313            ))?;
9314            return Ok(batch);
9315        }
9316        let revoked = start.status == SubStatus::Revoked;
9317        let mut units = None;
9318        let mut failed = false;
9319        let mut rearmed = false;
9320        for table in self.schema.tables.clone() {
9321            if !covers(&table, &unit.scopes) {
9322                continue;
9323            }
9324            let last = unit
9325                .echo
9326                .as_deref()
9327                .and_then(|last| pair_scopes(&unit.scopes, &table.name, Some(last)));
9328            let next = (!revoked)
9329                .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
9330                .flatten();
9331            // §3.3: a revoked fenced record that turns active again re-bootstraps.
9332            rearmed |= unit.echo.is_some() && last.is_none() && next.is_some();
9333            // §3.3: purge a pair the response revokes, keyed on the echo the
9334            // client persisted while the pair was active.
9335            if let (Some(last), None) = (&last, &next) {
9336                let units = match units {
9337                    Some(ref units) => units,
9338                    None => units.insert(self.stored(load_units(&self.conn))?),
9339                };
9340                let owners = unit_owners(units, &table, &unit.id);
9341                failed |= !self.purge_pair(&mut batch, &table, last, &owners)?;
9342            }
9343        }
9344        if revoked || failed {
9345            if revoked {
9346                report.revoked.push(unit.id.clone());
9347            }
9348            if failed {
9349                report.failed.push(unit.id.clone());
9350            }
9351            batch.status = true;
9352            self.stored(save_unit(
9353                &self.conn,
9354                &UnitRecord {
9355                    status: if failed {
9356                        UnitStatus::Failed
9357                    } else {
9358                        UnitStatus::Revoked
9359                    },
9360                    reason_code: Some(if failed {
9361                        "sync.scope_revoked".to_owned()
9362                    } else {
9363                        start.reason_code.clone()
9364                    }),
9365                    cursor: Some(-1),
9366                    bootstrap_state: None,
9367                    seeded: Vec::new(),
9368                    echo: None,
9369                    ..unit
9370                },
9371            ))?;
9372            return Ok(batch);
9373        }
9374        let completed = start.bootstrap && !rearmed && bootstrap_state.is_none();
9375        let (cursor, bootstrap_state, seeded) = if rearmed {
9376            (Some(-1), None, Vec::new())
9377        } else if start.bootstrap {
9378            let seeded = if bootstrap_state.is_none() {
9379                Vec::new()
9380            } else {
9381                seeded.into_iter().collect()
9382            };
9383            (Some(next_cursor), bootstrap_state, seeded)
9384        } else {
9385            (
9386                unit.cursor,
9387                unit.bootstrap_state.clone(),
9388                unit.seeded.clone(),
9389            )
9390        };
9391        self.stored(save_unit(
9392            &self.conn,
9393            &UnitRecord {
9394                reason_code: None,
9395                echo: Some(echo.clone()),
9396                cursor,
9397                bootstrap_state,
9398                seeded,
9399                ..unit.clone()
9400            },
9401        ))?;
9402        if !completed {
9403            return Ok(batch);
9404        }
9405        // §7.1: a completed bootstrap covers acknowledged intent of its pairs
9406        // at or below its pin.
9407        for table in self.schema.tables.clone() {
9408            let Some(effective) = covers(&table, &unit.scopes)
9409                .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
9410                .flatten()
9411            else {
9412                continue;
9413            };
9414            let mut statement = self
9415                .conn
9416                .prepare("SELECT id,intent_json FROM _syncular_acked_rows WHERE tbl=?1 AND commit_seq<=?2")
9417                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9418            let rows = statement
9419                .query_map(rusqlite::params![table.name, next_cursor], |row| {
9420                    Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
9421                })
9422                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9423            let mut covered = HashSet::new();
9424            for row in rows {
9425                let (id, intent) =
9426                    row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9427                let values: Map<String, Value> =
9428                    serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
9429                if owns_local_row(&table, &effective, &[], &values) {
9430                    covered.insert(id);
9431                }
9432            }
9433            drop(statement);
9434            for id in covered {
9435                self.conn
9436                    .execute(
9437                        "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3",
9438                        rusqlite::params![table.name, id, next_cursor],
9439                    )
9440                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9441                self.overlay_dirty.table(&table.name);
9442                batch.table(&table.name);
9443            }
9444        }
9445        Ok(batch)
9446    }
9447
9448    /// §3.3: purge one revoked pair inside the caller's observation: delete
9449    /// the rows matching its last effective scopes that no owner holds, drop
9450    /// the retained intent and every pending commit that provably writes into
9451    /// them, and delete now-unauthorized blob bodies. `Ok(false)` when the
9452    /// table has no local scope-column mapping (fail closed: nothing deleted).
9453    fn purge_pair(
9454        &mut self,
9455        batch: &mut ChangeAccumulator,
9456        table: &TableSchema,
9457        last: &[(String, Vec<String>)],
9458        owners: &[Vec<(String, Vec<String>)>],
9459    ) -> Result<bool, String> {
9460        if local_scope_predicate(table, last, owners).is_err() {
9461            return Ok(false);
9462        }
9463        for commit in self.drop_failed_commits(|name, values| {
9464            name == table.name && owns_local_row(table, last, owners, values)
9465        })? {
9466            batch.conflicts = true;
9467            batch.rejections = true;
9468            batch.outcomes = true;
9469            for operation in commit.ops {
9470                batch.table(&operation.table);
9471            }
9472        }
9473        if !self.purge_scope_rows(&table.name, last, owners)? {
9474            return Err("storage.failed: the revoked scope purge failed".to_owned());
9475        }
9476        self.record_scope_map(batch, &table.name, last);
9477        if self.drop_doomed_outbox(table, last, owners)? {
9478            batch.status = true;
9479            batch.rejections = true;
9480            batch.outcomes = true;
9481        }
9482        // §5.9.7 B2: revocation deletes now-unauthorized blob bodies.
9483        self.delete_unreferenced_cached_blobs()?;
9484        Ok(true)
9485    }
9486
9487    /// §4.5 client application: apply one live-section or delta `COMMIT`
9488    /// with only the changes that match the persisted echo of a receiving
9489    /// unit; every applied change then goes through the version guard.
9490    /// Returns whether any change of the frame applied.
9491    fn apply_live_commit(
9492        &mut self,
9493        receivers: &[UnitRecord],
9494        tables: &[String],
9495        changes: Vec<ssp2::model::Change>,
9496        commit_seq: i64,
9497        source: AppliedServerCommitSource,
9498    ) -> Result<bool, TransportError> {
9499        let changes: Vec<ssp2::model::Change> = changes
9500            .into_iter()
9501            .filter(|change| {
9502                // An unknown table fails loud in the apply below.
9503                let Some(table) = tables
9504                    .get(change.table_index as usize)
9505                    .and_then(|name| self.schema.table(name))
9506                else {
9507                    return true;
9508                };
9509                receivers.iter().any(|unit| {
9510                    covers(table, &unit.scopes)
9511                        && pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()).is_some_and(
9512                            |scopes| {
9513                                scopes.iter().all(|(variable, values)| {
9514                                    change
9515                                        .scopes
9516                                        .iter()
9517                                        .find(|(key, _)| key == variable)
9518                                        .is_some_and(|(_, value)| values.contains(value))
9519                                })
9520                            },
9521                        )
9522                })
9523            })
9524            .collect();
9525        if changes.is_empty() {
9526            return Ok(false);
9527        }
9528        let affected_tables = changes
9529            .iter()
9530            .filter_map(|change| tables.get(change.table_index as usize))
9531            .cloned()
9532            .collect::<BTreeSet<_>>();
9533        let previous_batches = self.change_queue.len();
9534        self.apply_commit_frame(tables, &changes, commit_seq)?;
9535        if self.change_queue.len() > previous_batches {
9536            if let Some(batch) = self.change_queue.back_mut() {
9537                batch
9538                    .applied_commits
9539                    .extend(
9540                        affected_tables
9541                            .into_iter()
9542                            .map(|table| AppliedServerCommit {
9543                                table,
9544                                commit_seq,
9545                                source,
9546                            }),
9547                    );
9548            }
9549        }
9550        Ok(true)
9551    }
9552
9553    // Both pull and realtime frames use the same durable observation boundary.
9554    fn apply_commit_frame(
9555        &mut self,
9556        tables: &[String],
9557        changes: &[ssp2::model::Change],
9558        sequence: i64,
9559    ) -> Result<(), TransportError> {
9560        #[cfg(feature = "bench-internals")]
9561        let _phase = self.benchmark_phases.start(Phase::CommitApply);
9562        let rollback = self.capture();
9563        self.coalesce_unit(changes.len())
9564            .and_then(|()| self.begin_observation("syncular_commit"))
9565            .map_err(|message| TransportError::new("storage.failed", message))?;
9566        let applied = (|| {
9567            let mut batch = ChangeAccumulator::default();
9568            self.record_commit_changes(&mut batch, tables, changes);
9569            {
9570                let storage_failed = |error| {
9571                    TransportError::new(
9572                        "storage.failed",
9573                        Self::sqlite_failure(&self.storage_failure, error),
9574                    )
9575                };
9576                let pinned: HashSet<(&str, &str)> = self
9577                    .outbox
9578                    .iter()
9579                    .flat_map(|commit| &commit.ops)
9580                    .map(|op| (op.table.as_str(), op.row_id.as_str()))
9581                    .collect();
9582                for change in changes {
9583                    let table = tables.get(change.table_index as usize).ok_or_else(|| {
9584                        TransportError::new(
9585                            "sync.invalid_request",
9586                            "change tableIndex out of range".to_owned(),
9587                        )
9588                    })?;
9589                    if pinned.contains(&(table.as_str(), change.row_id.as_str())) {
9590                        self.conn.prepare_cached("INSERT INTO _syncular_row_deliveries(tbl,id,commit_seq) VALUES (?1,?2,?3) ON CONFLICT(tbl,id) DO UPDATE SET commit_seq=MAX(commit_seq,excluded.commit_seq)")
9591                            .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
9592                            .map_err(storage_failed)?;
9593                    }
9594                    self.conn.prepare_cached("DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3")
9595                        .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
9596                        .map_err(storage_failed)?;
9597                }
9598            }
9599            self.apply_commit_changes(tables, changes)?;
9600            self.rebuild_overlay_if_dirty()
9601                .map_err(|message| TransportError::new("storage.failed", message))?;
9602            self.finish_observation("syncular_commit", batch)
9603                .map_err(|message| TransportError::new("storage.failed", message))
9604        })();
9605        if applied.is_err() {
9606            self.rollback_observation("syncular_commit");
9607            self.restore(rollback);
9608        }
9609        applied
9610    }
9611
9612    fn apply_commit_changes(
9613        &mut self,
9614        tables: &[String],
9615        changes: &[ssp2::model::Change],
9616    ) -> Result<(), TransportError> {
9617        // A clean overlay can reconcile changed primary keys independently
9618        // when their tables have no secondary unique constraints. Such a
9619        // constraint can change whether another row's write succeeds, so a
9620        // table with one and any local intent takes the table rebuild.
9621        let changed_tables: BTreeSet<&str> = changes
9622            .iter()
9623            .filter_map(|change| tables.get(change.table_index as usize))
9624            .map(String::as_str)
9625            .collect();
9626        let mut mirror_visible = !self.overlay_dirty.get();
9627        for name in &changed_tables {
9628            if mirror_visible
9629                && self
9630                    .schema
9631                    .table(name)
9632                    .is_some_and(|table| table.indexes.iter().any(|index| index.unique))
9633            {
9634                let (pending, protected) = self
9635                    .table_intent(name)
9636                    .map_err(|message| TransportError::new("storage.failed", message))?;
9637                mirror_visible = !pending && !protected;
9638            }
9639        }
9640        for change in changes {
9641            let table_name = tables.get(change.table_index as usize).ok_or_else(|| {
9642                TransportError::new(
9643                    "sync.invalid_request",
9644                    "change tableIndex out of range".to_owned(),
9645                )
9646            })?;
9647            let table = self.schema.table(table_name).ok_or_else(|| {
9648                TransportError::new(
9649                    "sync.schema_mismatch",
9650                    format!("change targets unknown table {table_name:?}"),
9651                )
9652            })?;
9653            let landed = match change.op {
9654                Op::Upsert => {
9655                    let payload = change.row.as_ref().ok_or_else(|| {
9656                        TransportError::new(
9657                            "sync.invalid_request",
9658                            "upsert change without row payload".to_owned(),
9659                        )
9660                    })?;
9661                    // §5.11: decrypt encrypted columns on apply.
9662                    let row = {
9663                        #[cfg(feature = "bench-internals")]
9664                        let _phase = self.benchmark_phases.start(Phase::RowDecode);
9665                        // §5.11: a decrypt failure keeps its own identity.
9666                        decode_row_bytes(table, payload, &self.encryption)?
9667                    };
9668                    let table_name = table.name.clone();
9669                    // §4.5 version guard: only a newer upsert lands.
9670                    let landed = self
9671                        .write_base_row(&table_name, &row, change.row_version)
9672                        .map_err(|m| TransportError::new("sync.invalid_request", m))?;
9673                    if mirror_visible && landed {
9674                        self.write_row(
9675                            &visible_table(&table_name),
9676                            &table_name,
9677                            &row,
9678                            change.row_version,
9679                        )
9680                        .map_err(|m| TransportError::new("sync.invalid_request", m))?;
9681                    }
9682                    landed
9683                }
9684                // §4.5 version guard: a delete at or below the local version
9685                // is skipped, a delete of an absent row is a no-op.
9686                Op::Delete => self
9687                    .delete_base_row(table_name, &change.row_id, change.row_version)
9688                    .map_err(|m| TransportError::new("sync.invalid_request", m))?,
9689            };
9690            // The change dropped the row's acknowledged intent either way
9691            // (§7.1), so the overlay of a skipped change rebuilds from the
9692            // unchanged base.
9693            self.overlay_dirty.table(table_name);
9694            if mirror_visible && !(landed && change.op == Op::Upsert) {
9695                let predicate = row_id_predicate(table);
9696                let visible = visible_table(table_name);
9697                let mut statements = vec![format!("DELETE FROM {visible} WHERE {predicate}")];
9698                if !landed {
9699                    statements.push(format!(
9700                        "INSERT INTO {visible} SELECT * FROM {} WHERE {predicate}",
9701                        base_table(table_name)
9702                    ));
9703                }
9704                for statement in &statements {
9705                    self.conn
9706                        .prepare_cached(statement)
9707                        .and_then(|mut statement| {
9708                            statement.execute(rusqlite::params![change.row_id])
9709                        })
9710                        .map_err(|error| {
9711                            TransportError::new("sync.invalid_request", error.to_string())
9712                        })?;
9713                }
9714            }
9715        }
9716        if mirror_visible {
9717            let changed_rows: HashSet<(&str, &str)> = changes
9718                .iter()
9719                .map(|change| {
9720                    (
9721                        tables[change.table_index as usize].as_str(),
9722                        change.row_id.as_str(),
9723                    )
9724                })
9725                .collect();
9726            self.replay_overlay(&changed_tables, Some(&changed_rows))
9727                .map_err(|message| TransportError::new("storage.failed", message))?;
9728            self.overlay_dirty.set(false);
9729        }
9730        Ok(())
9731    }
9732
9733    /// §5.6 segment application: validate against the generated schema,
9734    /// clear the pair's scope on the table's first page (fail closed
9735    /// without a mapping), then upsert each row with its segment-carried
9736    /// server version under the §4.5 version guard (§5.2).
9737    fn apply_segment(
9738        &mut self,
9739        table: &TableSchema,
9740        segment: &RowsSegment,
9741        first_page: bool,
9742        effective: &[(String, Vec<String>)],
9743        unit_id: &str,
9744    ) -> Result<u32, SectionError> {
9745        // §5.2: the column table validates against the generated schema —
9746        // order, names, types, nullability; mismatch is fatal. §5.11: the
9747        // server sends the WIRE types (bytes for an encrypted column), so
9748        // validate against wire_columns.
9749        let column = if segment.columns.len() != table.wire_columns.len() {
9750            Some(Value::from("count"))
9751        } else {
9752            segment
9753                .columns
9754                .iter()
9755                .zip(table.wire_columns.iter())
9756                .position(|(a, b)| a.name != b.name || a.ty != b.ty || a.nullable != b.nullable)
9757                .map(Value::from)
9758        };
9759        if segment.table != table.name
9760            || segment.schema_version != self.schema.version
9761            || column.is_some()
9762        {
9763            let mut details = Map::new();
9764            details.insert("table".to_owned(), Value::from(table.name.as_str()));
9765            if let Some(column) = column {
9766                details.insert("column".to_owned(), column);
9767            }
9768            return Err(SectionError::Transport(TransportError {
9769                code: "sync.schema_mismatch".to_owned(),
9770                message: "rows segment columns do not match the generated schema (§5.2)".to_owned(),
9771                details: Some(Value::Object(details)),
9772            }));
9773        }
9774        let mut applied = 0u32;
9775        let empty = Vec::new();
9776        let blocks = if segment.blocks.is_empty() {
9777            std::slice::from_ref(&empty)
9778        } else {
9779            &segment.blocks
9780        };
9781        for (index, block) in blocks.iter().enumerate() {
9782            let clear = first_page && index == 0;
9783            if !clear && block.is_empty() {
9784                continue;
9785            }
9786            let rollback = self.capture();
9787            let (pending, protected) = self
9788                .table_intent(&table.name)
9789                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9790            let reconcile_pending =
9791                !protected && pending && table.indexes.iter().any(|index| index.unique);
9792            let mirror_visible = !protected && !reconcile_pending;
9793            self.coalesce_unit(block.len())
9794                .and_then(|()| self.begin_observation("syncular_segment_block"))
9795                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9796            let outcome = (|| {
9797                self.rebuild_overlay_if_dirty()
9798                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9799                let mut changed_keys = Vec::new();
9800                let mut batch = ChangeAccumulator::default();
9801                if clear && self.clear_scope(table, effective, unit_id)? || !block.is_empty() {
9802                    batch.table(&table.name);
9803                }
9804                for (row_index, row) in block.iter().enumerate() {
9805                    let decrypted;
9806                    let values = if table.has_encrypted_columns() {
9807                        let mut values = row.values.clone();
9808                        crate::values::decrypt_segment_row(table, &mut values, &self.encryption)
9809                            .map_err(SectionError::Transport)?;
9810                        decrypted = values;
9811                        &decrypted
9812                    } else {
9813                        &row.values
9814                    };
9815                    if !self
9816                        .write_base_row(&table.name, values, row.server_version)
9817                        .map_err(|message| {
9818                            SectionError::Abort("sync.invalid_request".into(), message)
9819                        })?
9820                    {
9821                        continue;
9822                    }
9823                    if reconcile_pending {
9824                        changed_keys.push(
9825                            owned_sql_value(RowParam::Cell(&values[table.pk_index])).map_err(
9826                                |message| SectionError::Abort("storage.failed".into(), message),
9827                            )?,
9828                        );
9829                    }
9830                    if mirror_visible {
9831                        self.write_row(
9832                            &visible_table(&table.name),
9833                            &table.name,
9834                            values,
9835                            row.server_version,
9836                        )
9837                        .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9838                    }
9839                    let processed = u64::from(applied) + row_index as u64 + 1;
9840                    if processed.is_multiple_of(1024) {
9841                        self.progress.update(|p| p.rows_processed = processed);
9842                    }
9843                }
9844                self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
9845                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9846                self.finish_observation("syncular_segment_block", batch)
9847                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))
9848            })();
9849            if let Err(error) = outcome {
9850                self.rollback_observation("syncular_segment_block");
9851                self.restore(rollback);
9852                return Err(error);
9853            }
9854            applied += block.len() as u32;
9855            self.progress
9856                .update(|p| p.rows_processed = u64::from(applied));
9857            std::thread::yield_now();
9858        }
9859        self.progress
9860            .update(|p| p.rows_processed = u64::from(applied));
9861        Ok(applied)
9862    }
9863
9864    /// §5.3 sqlite-image application: validate the in-file metadata
9865    /// against the descriptor, validate column names/order against the
9866    /// generated schema, run the §5.6 first-page clear when fresh, then
9867    /// replace-or-upsert every image row with its `_syncular_version`.
9868    /// Mechanics: the image lands in a temp file read through a second
9869    /// rusqlite connection, equivalent to ATTACH + INSERT…SELECT.
9870    /// Each image chunk commits its writes and revision before readers continue.
9871    #[allow(clippy::too_many_arguments)]
9872    fn apply_sqlite_segment(
9873        &mut self,
9874        table: &TableSchema,
9875        bytes: &[u8],
9876        first_page: bool,
9877        effective: &[(String, Vec<String>)],
9878        unit_id: &str,
9879        row_count: i64,
9880        as_of_commit_seq: i64,
9881        scope_digest: &str,
9882    ) -> Result<u32, SectionError> {
9883        let invalid = |detail: &str| {
9884            SectionError::Abort(
9885                "sync.invalid_request".to_owned(),
9886                format!("sqlite segment rejected: {detail} (§5.3)"),
9887            )
9888        };
9889        // §5.11: an image bypasses the decrypt seam, so a server cannot serve
9890        // one for a table with encrypted columns.
9891        if table.has_encrypted_columns() {
9892            return Err(invalid("table has encrypted columns"));
9893        }
9894
9895        // The image lands beside the replica so it shares the replica's
9896        // directory permissions and volume; an in-memory replica has no
9897        // directory and uses the system temp dir. The file is owner-only.
9898        let directory = self
9899            .previous_version_replica_path()
9900            .and_then(|replica| std::path::Path::new(&replica).parent().map(Into::into))
9901            .unwrap_or_else(std::env::temp_dir);
9902        let path = directory.join(format!(".syncular-image-{}.tmp", uuid::Uuid::new_v4()));
9903        let outcome = (|| {
9904            let mut options = std::fs::OpenOptions::new();
9905            options.write(true).create_new(true);
9906            #[cfg(unix)]
9907            std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);
9908            std::io::Write::write_all(
9909                &mut options
9910                    .open(&path)
9911                    .map_err(|_| invalid("image temp file write failed"))?,
9912                bytes,
9913            )
9914            .map_err(|_| invalid("image temp file write failed"))?;
9915            let img = rusqlite::Connection::open_with_flags(
9916                &path,
9917                rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
9918            )
9919            .map_err(|_| invalid("bytes do not open as a SQLite database"))?;
9920            self.apply_sqlite_image(
9921                &img,
9922                table,
9923                first_page,
9924                effective,
9925                unit_id,
9926                row_count,
9927                as_of_commit_seq,
9928                scope_digest,
9929            )
9930        })();
9931        let _ = std::fs::remove_file(&path);
9932        outcome
9933    }
9934
9935    #[allow(clippy::too_many_arguments)]
9936    fn apply_sqlite_image(
9937        &mut self,
9938        img: &rusqlite::Connection,
9939        table: &crate::schema::TableSchema,
9940        first_fresh_page: bool,
9941        effective: &[(String, Vec<String>)],
9942        unit_id: &str,
9943        row_count: i64,
9944        as_of_commit_seq: i64,
9945        scope_digest: &str,
9946    ) -> Result<u32, SectionError> {
9947        let invalid = |detail: String| {
9948            SectionError::Abort(
9949                "sync.invalid_request".to_owned(),
9950                format!("sqlite segment rejected: {detail} (§5.3)"),
9951            )
9952        };
9953
9954        // 1. Metadata vs descriptor + client state (§5.3 rule 2; exactly
9955        //    one row).
9956        type MetaRow = (i64, String, i64, i64, String, i64, i64);
9957        let meta: MetaRow = img
9958            .query_row(
9959                "SELECT format, \"table\", \"schemaVersion\", \"asOfCommitSeq\",
9960                        \"scopeDigest\", \"rowCount\",
9961                        (SELECT count(*) FROM _syncular_segment)
9962                 FROM _syncular_segment",
9963                [],
9964                |row| {
9965                    Ok((
9966                        row.get(0)?,
9967                        row.get(1)?,
9968                        row.get(2)?,
9969                        row.get(3)?,
9970                        row.get(4)?,
9971                        row.get(5)?,
9972                        row.get(6)?,
9973                    ))
9974                },
9975            )
9976            .map_err(|_| invalid("missing or unreadable _syncular_segment metadata".to_owned()))?;
9977        let (format, meta_table, schema_version, pin, digest, meta_rows, meta_count) = meta;
9978        if meta_count != 1 {
9979            return Err(invalid(format!(
9980                "_syncular_segment must contain exactly one row, found {meta_count}"
9981            )));
9982        }
9983        if format != 1 {
9984            return Err(invalid(format!("format {format}")));
9985        }
9986        if meta_table != table.name {
9987            return Err(invalid(format!("image table {meta_table:?}")));
9988        }
9989        if schema_version != i64::from(self.schema.version) {
9990            return Err(invalid(format!("schemaVersion {schema_version}")));
9991        }
9992        if pin != as_of_commit_seq {
9993            return Err(invalid(format!("asOfCommitSeq {pin}")));
9994        }
9995        if digest != scope_digest {
9996            return Err(invalid("scopeDigest mismatch".to_owned()));
9997        }
9998        if meta_rows != row_count {
9999            return Err(invalid(format!("rowCount {meta_rows}")));
10000        }
10001
10002        // 2. Column names and order vs the generated schema (§5.3 rule 3).
10003        let mut names: Vec<String> = Vec::new();
10004        let mut primary_keys: Vec<String> = Vec::new();
10005        {
10006            let mut stmt = img
10007                .prepare(&format!("PRAGMA table_info({})", quote_ident(&table.name)))
10008                .map_err(|_| invalid("image data table missing".to_owned()))?;
10009            let mut rows = stmt
10010                .query([])
10011                .map_err(|_| invalid("image data table unreadable".to_owned()))?;
10012            while let Some(row) = rows
10013                .next()
10014                .map_err(|_| invalid("image data table unreadable".to_owned()))?
10015            {
10016                if row
10017                    .get::<_, i64>(5)
10018                    .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?
10019                    > 0
10020                {
10021                    primary_keys.push(row.get(1).map_err(|error| {
10022                        invalid(Self::sqlite_failure(&self.storage_failure, error))
10023                    })?);
10024                }
10025                names.push(
10026                    row.get::<_, String>(1)
10027                        .map_err(|_| invalid("image data table unreadable".to_owned()))?,
10028                );
10029            }
10030        }
10031        let mut expected: Vec<&str> = table.columns.iter().map(|c| c.name.as_str()).collect();
10032        expected.push("_syncular_version");
10033        if names.len() != expected.len() || names.iter().zip(expected.iter()).any(|(a, b)| a != b) {
10034            return Err(SectionError::Transport(TransportError {
10035                code: "sync.schema_mismatch".to_owned(),
10036                message: "sqlite segment columns do not match the generated schema (§5.3)"
10037                    .to_owned(),
10038                details: Some(serde_json::json!({ "table": table.name })),
10039            }));
10040        }
10041
10042        if primary_keys != vec![table.primary_key.clone()] {
10043            return Err(invalid(
10044                "image primary key does not match generated schema".into(),
10045            ));
10046        }
10047        let actual_count: i64 = img
10048            .query_row(
10049                &format!("SELECT count(*) FROM {}", quote_ident(&table.name)),
10050                [],
10051                |row| row.get(0),
10052            )
10053            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10054        if actual_count != row_count {
10055            return Err(invalid("image row count does not match descriptor".into()));
10056        }
10057        let insert = self.insert_row_sql(&base_table(&table.name), table);
10058        let visible_insert = self.insert_row_sql(&visible_table(&table.name), table);
10059        let column_list = names
10060            .iter()
10061            .map(|n| quote_ident(n))
10062            .collect::<Vec<_>>()
10063            .join(", ");
10064        let mut stmt = img
10065            .prepare(&format!(
10066                "SELECT {column_list} FROM {} ORDER BY {}",
10067                quote_ident(&table.name),
10068                quote_ident(&table.primary_key)
10069            ))
10070            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10071        let mut rows = stmt
10072            .query([])
10073            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10074        let mut applied = 0u32;
10075        let mut limit = 1024u32;
10076        let (mut write, mut commit) = (std::time::Duration::ZERO, std::time::Duration::ZERO);
10077        loop {
10078            let clear = applied == 0 && first_fresh_page;
10079            let rollback = self.capture();
10080            let (pending, protected) = self
10081                .table_intent(&table.name)
10082                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10083            let reconcile_pending =
10084                !protected && pending && table.indexes.iter().any(|index| index.unique);
10085            let mirror_visible = !protected && !reconcile_pending;
10086            // §5.3: a chunk holds 1,024 rows at first and doubles after each
10087            // commit up to 65,536; a chunk that replays local writes holds 1,024.
10088            let chunk = if pending || protected { 1024 } else { limit };
10089            self.coalesce_unit(chunk as usize)
10090                .and_then(|()| self.begin_observation("syncular_image_chunk"))
10091                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10092            let started = std::time::Instant::now();
10093            let result = (|| {
10094                self.rebuild_overlay_if_dirty()
10095                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10096                let mut changed_keys = Vec::new();
10097                let mut batch = ChangeAccumulator::default();
10098                if clear && self.clear_scope(table, effective, unit_id)? {
10099                    batch.table(&table.name);
10100                }
10101                let mut processed = 0u32;
10102                {
10103                    let mut ins = self.conn.prepare_cached(&insert).map_err(|error| {
10104                        invalid(Self::sqlite_failure(&self.storage_failure, error))
10105                    })?;
10106                    let mut mirror = if mirror_visible {
10107                        Some(self.conn.prepare_cached(&visible_insert).map_err(|error| {
10108                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10109                        })?)
10110                    } else {
10111                        None
10112                    };
10113                    for _ in 0..chunk {
10114                        let Some(row) = rows.next().map_err(|error| {
10115                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10116                        })?
10117                        else {
10118                            break;
10119                        };
10120                        for (i, column) in table.columns.iter().enumerate() {
10121                            let cell = row.get_ref(i).map_err(|error| {
10122                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10123                            })?;
10124                            let param = image_cell_param(column, cell).map_err(invalid)?;
10125                            ins.raw_bind_parameter(i + 1, &param).map_err(|error| {
10126                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10127                            })?;
10128                            if let Some(mirror) = &mut mirror {
10129                                mirror.raw_bind_parameter(i + 1, &param).map_err(|error| {
10130                                    invalid(Self::sqlite_failure(&self.storage_failure, error))
10131                                })?;
10132                            }
10133                        }
10134                        let version_index = table.columns.len();
10135                        let version: i64 = row.get(version_index).map_err(|error| {
10136                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10137                        })?;
10138                        if version < 1 {
10139                            return Err(invalid("image row version must be positive".into()));
10140                        }
10141                        ins.raw_bind_parameter(version_index + 1, version)
10142                            .map_err(|error| {
10143                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10144                            })?;
10145                        // §4.5 version guard: the base upsert decides.
10146                        let landed = ins.raw_execute().map_err(|error| {
10147                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10148                        })? > 0;
10149                        processed += 1;
10150                        if processed.is_multiple_of(1024) && processed < chunk {
10151                            self.progress
10152                                .update(|p| p.rows_processed = u64::from(applied + processed));
10153                        }
10154                        if !landed {
10155                            continue;
10156                        }
10157                        if let Some(mirror) = &mut mirror {
10158                            mirror
10159                                .raw_bind_parameter(version_index + 1, version)
10160                                .map_err(|error| {
10161                                    invalid(Self::sqlite_failure(&self.storage_failure, error))
10162                                })?;
10163                            mirror.raw_execute().map_err(|error| {
10164                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10165                            })?;
10166                        }
10167                        if reconcile_pending {
10168                            changed_keys.push(row.get::<_, SqlValue>(table.pk_index).map_err(
10169                                |error| invalid(Self::sqlite_failure(&self.storage_failure, error)),
10170                            )?);
10171                        }
10172                    }
10173                }
10174                if processed > 0 {
10175                    batch.table(&table.name);
10176                    self.overlay_dirty.table(&table.name);
10177                }
10178                self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
10179                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10180                let written = std::time::Instant::now();
10181                self.finish_observation("syncular_image_chunk", batch)
10182                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10183                Ok((processed, written))
10184            })();
10185            let (processed, written) = match result {
10186                Ok(done) => done,
10187                Err(error) => {
10188                    self.rollback_observation("syncular_image_chunk");
10189                    self.restore(rollback);
10190                    return Err(error);
10191                }
10192            };
10193            // The chunk commits before the yield, also inside a coalesced apply.
10194            let coalesced = self.coalesced.is_some();
10195            if coalesced {
10196                self.commit_coalesced_apply()
10197                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10198            }
10199            write += written - started;
10200            commit += written.elapsed();
10201            applied += processed;
10202            let last = processed < chunk || i64::from(applied) == actual_count;
10203            // A file replica's WAL keeps its high-water size until truncated.
10204            if last && self.conn.is_autocommit() {
10205                self.conn
10206                    .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
10207                    .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10208            }
10209            if coalesced {
10210                self.begin_coalesced_apply()
10211                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10212            }
10213            self.progress.update(|p| {
10214                p.rows_processed = u64::from(applied);
10215                p.import_write_ms = u64::try_from(write.as_millis()).ok();
10216                p.import_commit_ms = u64::try_from(commit.as_millis()).ok();
10217            });
10218            std::thread::yield_now();
10219            if last {
10220                break;
10221            }
10222            limit = (limit * 2).min(65_536);
10223        }
10224        if i64::from(applied) != actual_count {
10225            return Err(invalid(format!(
10226                "image yielded {applied} rows, expected {actual_count}"
10227            )));
10228        }
10229        Ok(applied)
10230    }
10231
10232    /// §7.1 keyed reconciliation of the rows `drained` commits touch: restore
10233    /// them from the base and replay their remaining intent. A table with a
10234    /// secondary unique index restores and replays every row with intent,
10235    /// since one row's value can admit or defer another row's write.
10236    fn reconcile_rows(&self, drained: &[Arc<OutboxCommit>]) -> Result<(), String> {
10237        let names: BTreeSet<&str> = drained
10238            .iter()
10239            .flat_map(|commit| &commit.ops)
10240            .map(|op| op.table.as_str())
10241            .collect();
10242        for name in names {
10243            let Some(table) = self.schema.table(name) else {
10244                continue;
10245            };
10246            let ops = drained.iter().flat_map(|commit| &commit.ops);
10247            let tables = BTreeSet::from([name]);
10248            let rows: HashSet<_> = ops
10249                .clone()
10250                .map(|op| (op.table.as_str(), op.row_id.as_str()))
10251                .collect();
10252            let unique = table.indexes.iter().any(|index| index.unique);
10253            let acknowledged = if unique {
10254                self.acknowledged_operations(None, Some(&tables))?
10255            } else {
10256                Vec::new()
10257            };
10258            let peers = acknowledged
10259                .iter()
10260                .chain(
10261                    self.failed_commits
10262                        .iter()
10263                        .flat_map(|(commit, _)| &commit.ops),
10264                )
10265                .chain(self.outbox.iter().flat_map(|commit| &commit.ops))
10266                .filter(|_| unique);
10267            self.restore_base_rows(table, &mut Vec::new(), peers.chain(ops.clone()))?;
10268            self.replay_overlay(&tables, (!unique).then_some(&rows))?;
10269        }
10270        Ok(())
10271    }
10272
10273    /// Whether `table` has pending outbox intent, and whether it has protected
10274    /// (acknowledged or retained failed) intent.
10275    fn table_intent(&self, table: &str) -> Result<(bool, bool), String> {
10276        let touches = |op: &OutboxOp| op.table == table;
10277        Ok((
10278            self.outbox
10279                .iter()
10280                .flat_map(|commit| &commit.ops)
10281                .any(touches),
10282            self.failed_commits
10283                .iter()
10284                .flat_map(|(commit, _)| &commit.ops)
10285                .any(touches)
10286                || self
10287                    .conn
10288                    .query_row(
10289                        "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows WHERE tbl=?1)",
10290                        [table],
10291                        |row| row.get(0),
10292                    )
10293                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10294        ))
10295    }
10296
10297    /// §7.1 reconciliation after an import block or chunk. Keyed replay covers
10298    /// only pending intent, so a table with protected intent rebuilds; a
10299    /// `restore` restores the imported `keys` and every pending row first.
10300    fn reconcile_import(
10301        &mut self,
10302        table: &TableSchema,
10303        keys: &mut Vec<SqlValue>,
10304        protected: bool,
10305        restore: bool,
10306    ) -> Result<(), String> {
10307        if protected {
10308            return self.rebuild_overlay_if_dirty();
10309        }
10310        let pending = self.outbox.iter().flat_map(|commit| &commit.ops);
10311        if restore {
10312            self.restore_base_rows(table, keys, pending.clone())?;
10313        }
10314        self.apply_outbox_ops(pending.filter(|op| op.table == table.name))?;
10315        self.overlay_dirty.set(false);
10316        Ok(())
10317    }
10318
10319    /// Restore the visible rows of `keys` and of the rows `ops` touch in
10320    /// `table` from the base before the caller replays their intent. The
10321    /// caller owns the transaction and publishes its revision after replay.
10322    fn restore_base_rows<'a>(
10323        &self,
10324        table: &TableSchema,
10325        keys: &mut Vec<SqlValue>,
10326        ops: impl IntoIterator<Item = &'a OutboxOp>,
10327    ) -> Result<(), String> {
10328        let visible = visible_table(&table.name);
10329        let base = base_table(&table.name);
10330        let pk = quote_ident(&table.primary_key);
10331        let predicate = row_id_predicate(table);
10332        let mut lookup = self.conn.prepare_cached(&format!(
10333            "SELECT {pk} FROM {base} WHERE {predicate} UNION SELECT {pk} FROM {visible} WHERE {predicate}"
10334        )).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10335        let mut deleted = HashSet::new();
10336        for op in ops.into_iter().filter(|op| op.table == table.name) {
10337            if op.upsert {
10338                if let Some(values) = &op.values {
10339                    let key = json_to_column_value(
10340                        &table.columns[table.pk_index],
10341                        values.get(&table.primary_key),
10342                    )?;
10343                    keys.push(owned_sql_value(RowParam::Cell(&key))?);
10344                }
10345            } else if deleted.insert(&op.row_id) {
10346                keys.extend(
10347                    lookup
10348                        .query_map([&op.row_id], |row| row.get::<_, SqlValue>(0))
10349                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
10350                        .collect::<Result<Vec<_>, _>>()
10351                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10352                );
10353            }
10354        }
10355        // Delete the complete affected set before restoring any base value, so
10356        // old optimistic unique values cannot collide with the new server rows.
10357        for chunk in keys.chunks(400) {
10358            let holes = vec!["?"; chunk.len()].join(",");
10359            self.conn
10360                .prepare_cached(&format!("DELETE FROM {visible} WHERE {pk} IN ({holes})"))
10361                .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
10362                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10363        }
10364        let updates = table
10365            .columns
10366            .iter()
10367            .map(|column| column.name.as_str())
10368            .chain(std::iter::once("_syncular_version"))
10369            .filter(|name| *name != table.primary_key)
10370            .map(|name| {
10371                let name = quote_ident(name);
10372                format!("{name}=excluded.{name}")
10373            })
10374            .collect::<Vec<_>>()
10375            .join(",");
10376        for chunk in keys.chunks(400) {
10377            let holes = vec!["?"; chunk.len()].join(",");
10378            self.conn.prepare_cached(&format!("INSERT INTO {visible} SELECT * FROM {base} WHERE {pk} IN ({holes}) ON CONFLICT ({pk}) DO UPDATE SET {updates}"))
10379                .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
10380                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10381        }
10382        Ok(())
10383    }
10384
10385    // -- application-authorized local purge ---------------------------------------
10386
10387    fn compile_local_data_purge(
10388        &self,
10389        input: &LocalDataPurgeInput,
10390    ) -> Result<(Vec<CompiledLocalDataPurgeTarget>, String), String> {
10391        let invalid = |message: String| format!("sync.invalid_request: {message}");
10392        if input.purge_id.is_empty()
10393            || input.purge_id.len() > 128
10394            || !is_local_operation_code_like(&input.purge_id)
10395        {
10396            return Err(invalid(
10397                "local purge purgeId must be a 1–128 character code-like identifier".to_owned(),
10398            ));
10399        }
10400        if input.targets.is_empty() || input.targets.len() > MAX_LOCAL_PURGE_TARGETS {
10401            return Err(invalid(format!(
10402                "local purge needs between 1 and {MAX_LOCAL_PURGE_TARGETS} targets"
10403            )));
10404        }
10405
10406        let mut deduplicated: BTreeMap<
10407            String,
10408            (CompiledLocalDataPurgeTarget, LocalDataPurgeTarget),
10409        > = BTreeMap::new();
10410        for target in &input.targets {
10411            let table = self.schema.table(&target.table).ok_or_else(|| {
10412                invalid(format!(
10413                    "local purge names unknown table {:?}",
10414                    target.table
10415                ))
10416            })?;
10417            if target.selectors.is_empty() || target.selectors.len() > MAX_LOCAL_PURGE_SELECTORS {
10418                return Err(invalid(format!(
10419                    "local purge target {:?} needs between 1 and {MAX_LOCAL_PURGE_SELECTORS} selectors",
10420                    target.table
10421                )));
10422            }
10423            let mut selectors = Vec::with_capacity(target.selectors.len());
10424            let mut canonical_selectors = BTreeMap::new();
10425            for (column_name, raw_values) in &target.selectors {
10426                let Some((column_index, column)) = table
10427                    .columns
10428                    .iter()
10429                    .enumerate()
10430                    .find(|(_, column)| column.name == *column_name)
10431                else {
10432                    return Err(invalid(format!(
10433                        "local purge target {:?} names unknown column {:?}",
10434                        target.table, column_name
10435                    )));
10436                };
10437                let encrypted = table
10438                    .encrypted_columns
10439                    .iter()
10440                    .any(|candidate| candidate.index == column_index);
10441                if column.ty != ColumnType::String || encrypted {
10442                    return Err(invalid(format!(
10443                        "local purge selector {:?}.{:?} must be a plaintext string column",
10444                        target.table, column_name
10445                    )));
10446                }
10447                if raw_values.is_empty() || raw_values.len() > MAX_LOCAL_PURGE_VALUES {
10448                    return Err(invalid(format!(
10449                        "local purge selector {:?}.{:?} needs between 1 and {MAX_LOCAL_PURGE_VALUES} values",
10450                        target.table, column_name
10451                    )));
10452                }
10453                let mut values = raw_values.clone();
10454                values.sort();
10455                values.dedup();
10456                if values.iter().any(|value| {
10457                    value.is_empty()
10458                        || value.len() > MAX_LOCAL_PURGE_VALUE_LENGTH
10459                        || !is_local_operation_code_like(value)
10460                }) {
10461                    return Err(invalid(format!(
10462                        "local purge selector values must be 1–{MAX_LOCAL_PURGE_VALUE_LENGTH} character code-like identifiers"
10463                    )));
10464                }
10465                selectors.push((column_name.clone(), values.clone()));
10466                canonical_selectors.insert(column_name.clone(), values);
10467            }
10468            let canonical = LocalDataPurgeTarget {
10469                table: target.table.clone(),
10470                selectors: canonical_selectors,
10471            };
10472            let key = serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
10473            deduplicated.insert(
10474                key,
10475                (
10476                    CompiledLocalDataPurgeTarget {
10477                        table: target.table.clone(),
10478                        selectors,
10479                    },
10480                    canonical,
10481                ),
10482            );
10483        }
10484        let targets = deduplicated
10485            .values()
10486            .map(|(compiled, _)| compiled.clone())
10487            .collect::<Vec<_>>();
10488        let canonical = deduplicated
10489            .values()
10490            .map(|(_, target)| target.clone())
10491            .collect::<Vec<_>>();
10492        let canonical_plan =
10493            serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
10494        Ok((targets, canonical_plan))
10495    }
10496
10497    fn local_purge_base_row_ids(
10498        &self,
10499        targets: &[CompiledLocalDataPurgeTarget],
10500    ) -> Result<BTreeMap<String, BTreeSet<String>>, String> {
10501        let mut by_table: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
10502        for target in targets {
10503            let table = self
10504                .schema
10505                .table(&target.table)
10506                .ok_or_else(|| format!("sync.invalid_request: unknown table {:?}", target.table))?;
10507            let mut clauses = Vec::with_capacity(target.selectors.len());
10508            let mut params = Vec::new();
10509            for (column, values) in &target.selectors {
10510                clauses.push(format!(
10511                    "{} IN ({})",
10512                    quote_ident(column),
10513                    values.iter().map(|_| "?").collect::<Vec<_>>().join(", ")
10514                ));
10515                params.extend(values.iter().cloned().map(SqlValue::Text));
10516            }
10517            let sql = format!(
10518                "SELECT CAST({} AS TEXT) FROM {} WHERE {}",
10519                quote_ident(&table.primary_key),
10520                base_table(&target.table),
10521                clauses.join(" AND ")
10522            );
10523            let mut statement = self
10524                .conn
10525                .prepare(&sql)
10526                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10527            let rows = statement
10528                .query_map(rusqlite::params_from_iter(params), |row| {
10529                    let value = sql_ref_to_json(&table.columns[table.pk_index], row.get_ref(0)?);
10530                    render_row_id_json(Some(&value))
10531                        .map_err(|message| rusqlite::Error::ToSqlConversionFailure(message.into()))
10532                })
10533                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10534            let ids = by_table.entry(target.table.clone()).or_default();
10535            for row in rows {
10536                ids.insert(
10537                    row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10538                );
10539            }
10540        }
10541        Ok(by_table)
10542    }
10543
10544    fn local_purge_values_match(
10545        target: &CompiledLocalDataPurgeTarget,
10546        values: &Map<String, Value>,
10547    ) -> bool {
10548        target.selectors.iter().all(|(column, allowed)| {
10549            values
10550                .get(column)
10551                .and_then(Value::as_str)
10552                .is_some_and(|value| allowed.iter().any(|candidate| candidate == value))
10553        })
10554    }
10555
10556    /// Apply one host-authorized local security purge. The host MUST gate the
10557    /// corresponding subscriptions first; this primitive owns local SQLite
10558    /// cleanup and never grants/revokes server authority by itself.
10559    pub fn purge_local_data(
10560        &mut self,
10561        input: &LocalDataPurgeInput,
10562    ) -> Result<LocalDataPurgeResult, String> {
10563        let (targets, canonical_plan) = self.compile_local_data_purge(input)?;
10564        let meta_key = format!("localPurge:{}", input.purge_id);
10565        let applied_plan = self
10566            .conn
10567            .query_row(
10568                "SELECT value FROM _syncular_meta WHERE key = ?1",
10569                rusqlite::params![meta_key],
10570                |row| row.get::<_, String>(0),
10571            )
10572            .optional()
10573            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10574        if let Some(applied_plan) = applied_plan {
10575            if applied_plan != canonical_plan {
10576                return Err(format!(
10577                    "sync.invalid_request: local purge id {:?} was already used with a different plan",
10578                    input.purge_id
10579                ));
10580            }
10581            return Ok(LocalDataPurgeResult {
10582                already_applied: true,
10583                purged_rows: 0,
10584                dropped_commits: 0,
10585            });
10586        }
10587
10588        // RFC 0005 D7: the container file cannot be a purge target (its name is
10589        // not in the running schema), so purge drops it as a fixed step, before
10590        // any mirror row is touched and unconditionally.
10591        let _ = self.drop_previous_version();
10592
10593        let rollback = self.capture();
10594        self.begin_observation("syncular_local_purge")?;
10595        let applied = (|| -> Result<(ChangeAccumulator, LocalDataPurgeResult), String> {
10596            let row_ids = self.local_purge_base_row_ids(&targets)?;
10597            let retained_dropped = self.drop_failed_commits(|table, values| {
10598                targets.iter().any(|target| {
10599                    target.table == table && Self::local_purge_values_match(target, values)
10600                })
10601            })?;
10602            let doomed = self
10603                .outbox
10604                .iter()
10605                .filter(|commit| {
10606                    commit.ops.iter().any(|operation| {
10607                        let matching_targets = targets
10608                            .iter()
10609                            .filter(|target| target.table == operation.table)
10610                            .collect::<Vec<_>>();
10611                        if matching_targets.is_empty() {
10612                            return false;
10613                        }
10614                        if row_ids
10615                            .get(&operation.table)
10616                            .is_some_and(|ids| ids.contains(&operation.row_id))
10617                        {
10618                            return true;
10619                        }
10620                        operation.values.as_ref().is_some_and(|values| {
10621                            matching_targets
10622                                .iter()
10623                                .any(|target| Self::local_purge_values_match(target, values))
10624                        })
10625                    })
10626                })
10627                .cloned()
10628                .collect::<Vec<_>>();
10629            let doomed_ids = doomed
10630                .iter()
10631                .map(|commit| commit.client_commit_id.clone())
10632                .collect::<BTreeSet<_>>();
10633            let mut batch = ChangeAccumulator::default();
10634            for commit in &retained_dropped {
10635                batch.conflicts = true;
10636                batch.rejections = true;
10637                batch.outcomes = true;
10638                for operation in &commit.ops {
10639                    batch.table(&operation.table);
10640                }
10641            }
10642            let mut rejections = Vec::new();
10643            for commit in &doomed {
10644                for operation in &commit.ops {
10645                    batch.table(&operation.table);
10646                    self.overlay_dirty.table(&operation.table);
10647                }
10648                let results = commit
10649                    .ops
10650                    .iter()
10651                    .enumerate()
10652                    .map(|(op_index, operation)| {
10653                        let rejection = RejectionRecord {
10654                            client_commit_id: commit.client_commit_id.clone(),
10655                            op_index: op_index as i32,
10656                            code: "client.local_data_purged".to_owned(),
10657                            message: "the commit was dropped by an application-authorized local data purge".to_owned(),
10658                            retryable: false,
10659                            details: None,
10660                            operation: Some(CommitOperation::from(operation)),
10661                        };
10662                        rejections.push(rejection.clone());
10663                        CommitOperationOutcome::Error { rejection }
10664                    })
10665                    .collect::<Vec<_>>();
10666                self.persist_commit_outcome(
10667                    &commit.client_commit_id,
10668                    CommitOutcomeStatus::Rejected,
10669                    &results,
10670                    Some(&commit.ops),
10671                )?;
10672                self.delete_outbox_persisted(&commit.client_commit_id)?;
10673            }
10674            if !doomed.is_empty() {
10675                self.outbox
10676                    .retain(|commit| !doomed_ids.contains(&commit.client_commit_id));
10677                self.rejections.extend(rejections);
10678                self.prune_commit_outcomes()?;
10679                batch.status = true;
10680                batch.rejections = true;
10681                batch.outcomes = true;
10682            }
10683
10684            let mut purged_rows = 0usize;
10685            for (table, ids) in &row_ids {
10686                if ids.is_empty() {
10687                    continue;
10688                }
10689                batch.table(table);
10690                self.overlay_dirty.table(table);
10691                for row_id in ids {
10692                    self.delete_base_row(table, row_id, i64::MAX)?;
10693                    purged_rows += 1;
10694                }
10695            }
10696            self.rebuild_overlay_if_dirty()?;
10697            self.delete_unreferenced_cached_blobs()?;
10698            self.conn
10699                .execute(
10700                    "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
10701                    rusqlite::params![meta_key, canonical_plan],
10702                )
10703                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10704            Ok((
10705                batch,
10706                LocalDataPurgeResult {
10707                    already_applied: false,
10708                    purged_rows,
10709                    dropped_commits: doomed.len(),
10710                },
10711            ))
10712        })()
10713        .and_then(|(batch, result)| {
10714            self.finish_observation("syncular_local_purge", batch)
10715                .map(|()| result)
10716        });
10717        let result = match applied {
10718            Ok(result) => result,
10719            Err(error) => {
10720                self.rollback_observation("syncular_local_purge");
10721                self.restore(rollback);
10722                return Err(error);
10723            }
10724        };
10725        self.cancel_sync_round();
10726        Ok(result)
10727    }
10728
10729    /// Application-authorized recovery of the replicated projection. Unlike a
10730    /// local security purge, this retains the entire outbox, device identity,
10731    /// lease, outcomes, unit registrations, and protected bookkeeping.
10732    /// The projection reset, unit rewind, optimistic replay, and
10733    /// idempotency marker share one savepoint for interruption safety.
10734    pub fn rebootstrap_local_data(
10735        &mut self,
10736        input: &LocalDataRebootstrapInput,
10737    ) -> Result<LocalDataRebootstrapResult, String> {
10738        if input.rebootstrap_id.is_empty()
10739            || input.rebootstrap_id.len() > 128
10740            || !is_local_operation_code_like(&input.rebootstrap_id)
10741        {
10742            return Err(
10743                "sync.invalid_request: local rebootstrap rebootstrapId must be a 1–128 character code-like identifier"
10744                    .to_owned(),
10745            );
10746        }
10747        let meta_key = format!("localRebootstrap:{}", input.rebootstrap_id);
10748        if let Some(persisted) = meta_get(&self.conn, &meta_key).map_err(|_| {
10749            "sync.local_corrupt: persisted local rebootstrap receipt is unreadable".to_owned()
10750        })? {
10751            let (retained_commits, reset_subscriptions) =
10752                decode_local_rebootstrap_receipt(&persisted)?;
10753            return Ok(LocalDataRebootstrapResult {
10754                already_applied: true,
10755                retained_commits,
10756                reset_subscriptions,
10757            });
10758        }
10759        if self.stopped || self.schema_floor.is_some() {
10760            return Err(
10761                "sync.invalid_request: local rebootstrap cannot bypass an active schema-floor stop; update the application first"
10762                    .to_owned(),
10763            );
10764        }
10765
10766        let retained_commits = self.outbox.len();
10767        let reset_subscriptions = self.stored(load_units(&self.conn))?.len();
10768        let receipt = encode_local_rebootstrap_receipt(retained_commits, reset_subscriptions)?;
10769        let rollback = self.capture();
10770        self.begin_observation("syncular_local_rebootstrap")?;
10771        let mut batch = ChangeAccumulator::default();
10772        let applied = (|| -> Result<(), String> {
10773            self.run_schema_reset_observed(&mut batch, false)?;
10774            self.conn
10775                .execute(
10776                    "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
10777                    rusqlite::params![meta_key, receipt],
10778                )
10779                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10780            self.sync_needed = true;
10781            self.sync_intent_queue.push_back(SyncIntent::Interactive);
10782            batch.status = true;
10783            Ok(())
10784        })()
10785        .and_then(|()| self.finish_observation("syncular_local_rebootstrap", batch));
10786        if let Err(error) = applied {
10787            self.rollback_observation("syncular_local_rebootstrap");
10788            self.restore(rollback);
10789            return Err(error);
10790        }
10791
10792        Ok(LocalDataRebootstrapResult {
10793            already_applied: false,
10794            retained_commits,
10795            reset_subscriptions,
10796        })
10797    }
10798
10799    // -- scope purge + doomed outbox (§3.3) ----------------------------------------
10800
10801    /// Delete base and visible rows owned by the effective scopes
10802    /// ([`local_scope_predicate`]); `Ok(false)` = no local scope-column
10803    /// mapping for a key (the fail-closed case). A SQLite failure is an error.
10804    fn purge_scope_rows(
10805        &mut self,
10806        table_name: &str,
10807        effective: &[(String, Vec<String>)],
10808        owners: &[Vec<(String, Vec<String>)>],
10809    ) -> Result<bool, String> {
10810        let Some(table) = self.schema.table(table_name) else {
10811            return Ok(false);
10812        };
10813        let Ok(predicate) = local_scope_predicate(table, effective, owners) else {
10814            return Ok(false);
10815        };
10816        let Some((predicate, params)) = predicate else {
10817            return Ok(true);
10818        };
10819        self.overlay_dirty.table(table_name);
10820        for source in [base_table(table_name), visible_table(table_name)] {
10821            self.conn
10822                .execute(
10823                    &format!("DELETE FROM {source} WHERE {predicate}"),
10824                    rusqlite::params_from_iter(&params),
10825                )
10826                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10827        }
10828        Ok(true)
10829    }
10830
10831    /// §3.3: drop pending commits whose upserts provably land in the
10832    /// revoked effective scopes and no other owner covers (row ownership)
10833    /// — whole-commit, never per-operation.
10834    fn drop_doomed_outbox(
10835        &mut self,
10836        table: &TableSchema,
10837        effective: &[(String, Vec<String>)],
10838        owners: &[Vec<(String, Vec<String>)>],
10839    ) -> Result<bool, String> {
10840        let doomed: Vec<_> =
10841            self.outbox
10842                .iter()
10843                .filter(|commit| {
10844                    commit.ops.iter().any(|op| {
10845                        op.upsert
10846                            && op.table == table.name
10847                            && op.values.as_ref().is_some_and(|values| {
10848                                owns_local_row(table, effective, owners, values)
10849                            })
10850                    })
10851                })
10852                .cloned()
10853                .collect();
10854        if doomed.is_empty() {
10855            return Ok(false);
10856        }
10857        let mut rejections = Vec::new();
10858        for commit in &doomed {
10859            let results = commit
10860                .ops
10861                .iter()
10862                .enumerate()
10863                .map(|(op_index, operation)| {
10864                    self.overlay_dirty.table(&operation.table);
10865                    let rejection = RejectionRecord {
10866                        client_commit_id: commit.client_commit_id.clone(),
10867                        op_index: op_index as i32,
10868                        code: "sync.scope_revoked".to_owned(),
10869                        message: "the commit was dropped because its effective scope was revoked"
10870                            .to_owned(),
10871                        retryable: false,
10872                        details: None,
10873                        operation: Some(CommitOperation::from(operation)),
10874                    };
10875                    rejections.push(rejection.clone());
10876                    CommitOperationOutcome::Error { rejection }
10877                })
10878                .collect::<Vec<_>>();
10879            self.persist_commit_outcome(
10880                &commit.client_commit_id,
10881                CommitOutcomeStatus::Rejected,
10882                &results,
10883                Some(&commit.ops),
10884            )?;
10885            self.delete_outbox_persisted(&commit.client_commit_id)?;
10886        }
10887        self.prune_commit_outcomes()?;
10888        let doomed_ids = doomed
10889            .iter()
10890            .map(|commit| commit.client_commit_id.as_str())
10891            .collect::<BTreeSet<_>>();
10892        self.outbox
10893            .retain(|commit| !doomed_ids.contains(commit.client_commit_id.as_str()));
10894        self.rejections.extend(rejections);
10895        Ok(true)
10896    }
10897
10898    // -- blobs (§5.9) ----------------------------------------------------------------
10899
10900    /// §5.9.7: hash bytes into the content address, cache them, queue the
10901    /// upload (flushed before the next push, B4). Returns the canonical
10902    /// BlobRef JSON `{blobId, byteLength, mediaType?}` for a `blob_ref`
10903    /// column value.
10904    pub fn upload_blob(
10905        &mut self,
10906        bytes: &[u8],
10907        media_type: Option<String>,
10908        name: Option<String>,
10909    ) -> Result<Value, String> {
10910        let blob_id = blob_id_for(bytes);
10911        let now = self.clock_now_ms();
10912        let tx = self
10913            .conn
10914            .transaction()
10915            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10916        tx.execute(
10917            "INSERT INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,?,?)
10918             ON CONFLICT(blob_id) DO NOTHING",
10919            rusqlite::params![blob_id, bytes, bytes.len() as i64, media_type, now],
10920        )
10921        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10922        tx.execute(
10923            "INSERT OR IGNORE INTO _syncular_blob_uploads(blob_id, media_type, created_at_ms) VALUES (?,?,?)",
10924            rusqlite::params![blob_id, media_type, now],
10925        )
10926        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10927        tx.commit()
10928            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10929        self.enforce_blob_cache_cap();
10930        let mut obj = Map::new();
10931        obj.insert("blobId".to_owned(), Value::from(blob_id));
10932        obj.insert("byteLength".to_owned(), Value::from(bytes.len() as i64));
10933        if let Some(mt) = media_type {
10934            obj.insert("mediaType".to_owned(), Value::from(mt));
10935        }
10936        if let Some(n) = name {
10937            obj.insert("name".to_owned(), Value::from(n));
10938        }
10939        Ok(Value::Object(obj))
10940    }
10941
10942    /// §5.9.7: resolve an owned blob body without driver encoding. A
10943    /// content-addressed cache hit serves with no fetch (B1); a miss downloads
10944    /// (§5.9.5), verifies the address, caches the bytes, and returns them.
10945    pub fn fetch_blob_bytes(
10946        &mut self,
10947        transport: &mut dyn Transport,
10948        blob_id_or_ref: &str,
10949    ) -> Result<FetchedBlob, (String, String)> {
10950        let simple = |m: String| ("client.failed".to_owned(), m);
10951        // A BlobRef declares the size that caps the download (§5.9.5); a bare
10952        // blobId declares none.
10953        let (blob_id, byte_length) = if blob_id_or_ref.starts_with("sha256:") {
10954            (blob_id_or_ref.to_owned(), None)
10955        } else {
10956            let value: Value = serde_json::from_str(blob_id_or_ref)
10957                .map_err(|_| simple("blob ref is not JSON".to_owned()))?;
10958            (
10959                value
10960                    .get("blobId")
10961                    .and_then(Value::as_str)
10962                    .ok_or_else(|| simple("blob ref has no blobId".to_owned()))?
10963                    .to_owned(),
10964                value.get("byteLength").and_then(Value::as_u64),
10965            )
10966        };
10967        if let Some(cached) = self.get_cached_blob_bytes(&blob_id).map_err(simple)? {
10968            return Ok(cached);
10969        }
10970        if !self.transport_enabled {
10971            return Err(("sync.offline".into(), "transport gate is closed".into()));
10972        }
10973        // §5.9.5: propagate the server's blob.* code (blob.forbidden /
10974        // blob.not_found) verbatim so the harness can assert on it. The
10975        // authorized endpoint serves bytes inline OR (always-issue, presign
10976        // configured) a signed url the client fetches directly — no host auth,
10977        // no fall-through: failure => re-request (the caller's next fetch_blob_bytes).
10978        #[cfg(feature = "bench-internals")]
10979        let download_phase = self.benchmark_phases.start(Phase::BlobDownload);
10980        let bytes = match transport
10981            .blob_download(&blob_id, byte_length)
10982            .map_err(|e| (e.code, e.message))?
10983        {
10984            BlobDownload::Bytes(bytes) => bytes,
10985            BlobDownload::Url {
10986                url,
10987                url_expires_at_ms,
10988            } => {
10989                // §5.9.5: MUST NOT start a fetch at/past expiry.
10990                if url_expires_at_ms.is_some_and(|exp| exp <= self.clock_now_ms()) {
10991                    return Err((
10992                        "sync.segment_expired".to_owned(),
10993                        format!(
10994                            "blob url for {blob_id} expired before fetch — re-request mints a fresh url (§5.9.5)"
10995                        ),
10996                    ));
10997                }
10998                transport
10999                    .fetch_blob_url(&url, byte_length)
11000                    .map_err(|e| (e.code, e.message))?
11001            }
11002        };
11003        #[cfg(feature = "bench-internals")]
11004        drop(download_phase);
11005        #[cfg(feature = "bench-internals")]
11006        let validate_phase = self.benchmark_phases.start(Phase::BlobValidate);
11007        // §5.9.5 inherits §5.1: the declared size caps the body before the
11008        // content address is verified.
11009        if byte_length.is_some_and(|cap| bytes.len() as u64 > cap) {
11010            return Err((
11011                "sync.invalid_request".to_owned(),
11012                "blob exceeds its byteLength".to_owned(),
11013            ));
11014        }
11015        if blob_id_for(&bytes) != blob_id {
11016            return Err(simple(format!(
11017                "blob content address mismatch for {blob_id}"
11018            )));
11019        }
11020        #[cfg(feature = "bench-internals")]
11021        drop(validate_phase);
11022        #[cfg(feature = "bench-internals")]
11023        let insert_phase = self.benchmark_phases.start(Phase::BlobCacheInsert);
11024        let now = self.clock_now_ms();
11025        self.conn
11026            .execute(
11027                "INSERT OR IGNORE INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,NULL,?)",
11028                rusqlite::params![blob_id, bytes, bytes.len() as i64, now],
11029            )
11030            .map_err(|e| simple(e.to_string()))?;
11031        self.conn
11032            .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
11033            .map_err(|e| simple(e.to_string()))?;
11034        self.enforce_blob_cache_cap();
11035        #[cfg(feature = "bench-internals")]
11036        drop(insert_phase);
11037        self.get_cached_blob_bytes(&blob_id)
11038            .map_err(simple)?
11039            .ok_or_else(|| simple("blob cache write failed".to_owned()))
11040    }
11041
11042    fn get_cached_blob_bytes(&self, blob_id: &str) -> Result<Option<FetchedBlob>, String> {
11043        #[cfg(feature = "bench-internals")]
11044        let _phase = self.benchmark_phases.start(Phase::BlobCacheRead);
11045        let mut stmt = self
11046            .conn
11047            .prepare("SELECT bytes, byte_length, media_type FROM _syncular_blobs WHERE blob_id = ?")
11048            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11049        let mut rows = stmt
11050            .query(rusqlite::params![blob_id])
11051            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11052        if let Some(row) = rows
11053            .next()
11054            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11055        {
11056            let bytes: Vec<u8> = row
11057                .get(0)
11058                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11059            let byte_length: i64 = row
11060                .get(1)
11061                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11062            let media_type: Option<String> = row
11063                .get(2)
11064                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11065            return Ok(Some(FetchedBlob {
11066                blob_id: blob_id.to_owned(),
11067                byte_length,
11068                bytes,
11069                media_type,
11070            }));
11071        }
11072        Ok(None)
11073    }
11074
11075    /// §5.9.7 B4: upload every queued blob before push.
11076    fn pending_blob_uploads(&self) -> Result<Vec<crate::round::PendingUpload>, TransportError> {
11077        let pending: Vec<(String, Option<String>)> = {
11078            let mut stmt = self
11079                .conn
11080                .prepare(
11081                    "SELECT blob_id, media_type FROM (
11082                      SELECT blob_id, media_type, created_at_ms FROM _syncular_blob_uploads
11083                      UNION ALL
11084                      SELECT DISTINCT r.blob_id, b.media_type, 9223372036854775807 AS created_at_ms
11085                      FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id = r.blob_id
11086                      WHERE NOT EXISTS (SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id = r.blob_id)
11087                    ) ORDER BY created_at_ms, blob_id",
11088                )
11089                .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11090            let rows = stmt
11091                .query_map([], |row| {
11092                    Ok((row.get::<_, String>(0)?, row.get::<_, Option<String>>(1)?))
11093                })
11094                .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11095            rows.collect::<Result<_, _>>()
11096                .map_err(|error| match error {
11097                    rusqlite::Error::InvalidColumnType(..)
11098                    | rusqlite::Error::FromSqlConversionFailure(..) => TransportError::new(
11099                        "sync.local_corrupt",
11100                        "Pending blob upload metadata is invalid",
11101                    ),
11102                    _ => TransportError::new("client.failed", error.to_string()),
11103                })?
11104        };
11105        let mut uploads = Vec::new();
11106        for (blob_id, media_type) in pending {
11107            let bytes = (|| {
11108                let stored: Option<(SqlValue, SqlValue)> = self
11109                    .conn
11110                    .query_row(
11111                        "SELECT bytes, byte_length FROM _syncular_blobs WHERE blob_id = ?",
11112                        rusqlite::params![blob_id],
11113                        |row| Ok((row.get(0)?, row.get(1)?)),
11114                    )
11115                    .optional()
11116                    .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11117                let Some((SqlValue::Blob(bytes), SqlValue::Integer(byte_length))) = stored else {
11118                    return Err(TransportError::new(
11119                        "sync.local_corrupt",
11120                        "Pending blob upload body is missing or corrupt",
11121                    ));
11122                };
11123                if byte_length != bytes.len() as i64 || blob_id_for(&bytes) != blob_id {
11124                    return Err(TransportError::new(
11125                        "sync.local_corrupt",
11126                        "Pending blob upload body is missing or corrupt",
11127                    ));
11128                }
11129                Ok(bytes)
11130            })();
11131            let failed = bytes.is_err();
11132            uploads.push(crate::round::PendingUpload {
11133                id: blob_id,
11134                bytes,
11135                media_type,
11136            });
11137            if failed {
11138                break;
11139            }
11140        }
11141        Ok(uploads)
11142    }
11143
11144    fn visible_blob_ids_sql(&self) -> String {
11145        let mut selects = Vec::new();
11146        for table in &self.schema.tables {
11147            for column in table
11148                .columns
11149                .iter()
11150                .filter(|column| column.ty == ColumnType::BlobRef)
11151            {
11152                let identifier = quote_ident(&column.name);
11153                selects.push(format!(
11154                    "SELECT json_extract({identifier}, '$.blobId') AS blob_id FROM {} \
11155                     WHERE typeof({identifier}) = 'text' AND json_valid({identifier}) \
11156                     AND json_type({identifier}, '$.blobId') = 'text'",
11157                    quote_ident(&table.name),
11158                ));
11159            }
11160        }
11161        if selects.is_empty() {
11162            "SELECT NULL AS blob_id WHERE 0".to_owned()
11163        } else {
11164            selects.join(" UNION ")
11165        }
11166    }
11167
11168    /// §5.9.7 B1 size cap. Visible rows, pending commits, and
11169    /// staged uploads pin bodies directly; no derived refcount is stored.
11170    fn enforce_blob_cache_cap(&self) {
11171        let Some(max_bytes) = self.limits.blob_cache_max_bytes else {
11172            return;
11173        };
11174        let mut total: i64 = self
11175            .conn
11176            .query_row(
11177                "SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs",
11178                [],
11179                |row| row.get(0),
11180            )
11181            .unwrap_or(0);
11182        if total <= max_bytes {
11183            return;
11184        }
11185        let query = format!(
11186            "SELECT blob_id, byte_length FROM _syncular_blobs
11187             WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
11188               AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
11189               AND blob_id NOT IN ({})
11190             ORDER BY created_at_ms ASC, blob_id ASC",
11191            self.visible_blob_ids_sql(),
11192        );
11193        let candidates: Vec<(String, i64)> = {
11194            let Ok(mut stmt) = self.conn.prepare(&query) else {
11195                return;
11196            };
11197            let Ok(rows) = stmt.query_map([], |row| {
11198                Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
11199            }) else {
11200                return;
11201            };
11202            rows.filter_map(Result::ok).collect()
11203        };
11204        for (blob_id, byte_length) in candidates {
11205            if total <= max_bytes {
11206                break;
11207            }
11208            let _ = self.conn.execute(
11209                "DELETE FROM _syncular_blobs WHERE blob_id = ?",
11210                rusqlite::params![blob_id],
11211            );
11212            total -= byte_length;
11213        }
11214    }
11215
11216    fn delete_unreferenced_cached_blobs(&mut self) -> Result<(), String> {
11217        #[cfg(feature = "bench-internals")]
11218        let _phase = self.benchmark_phases.start(Phase::BlobRetention);
11219        if !self.schema_has_blobs() {
11220            return Ok(());
11221        }
11222        self.rebuild_overlay_if_dirty()?;
11223        self.conn
11224            .execute(
11225                &format!(
11226                    "DELETE FROM _syncular_blobs
11227                 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
11228                   AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
11229                   AND blob_id NOT IN ({})",
11230                    self.visible_blob_ids_sql(),
11231                ),
11232                [],
11233            )
11234            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11235        Ok(())
11236    }
11237
11238    // -- local row storage ----------------------------------------------------------
11239
11240    /// The cached per-table primary-key upsert SQL for `full_table` (see
11241    /// the `insert_sql` field: built once, reused per row).
11242    fn insert_row_sql(&self, full_table: &str, table: &crate::schema::TableSchema) -> String {
11243        if let Some(sql) = self.insert_sql.borrow().get(full_table) {
11244            return sql.clone();
11245        }
11246        let mut columns: Vec<String> = table.columns.iter().map(|c| quote_ident(&c.name)).collect();
11247        columns.push(quote_ident("_syncular_version"));
11248        let placeholders: Vec<&str> = columns.iter().map(|_| "?").collect();
11249        let primary_key = quote_ident(&table.primary_key);
11250        let updates = columns
11251            .iter()
11252            .filter(|column| **column != primary_key)
11253            .map(|column| format!("{column}=excluded.{column}"))
11254            .collect::<Vec<_>>()
11255            .join(", ");
11256        // §4.5 version guard: server state lands in the base table only above
11257        // the stored version; the visible overlay takes every write.
11258        let guard = if full_table == base_table(&table.name) {
11259            format!(" WHERE excluded._syncular_version > {full_table}._syncular_version")
11260        } else {
11261            String::new()
11262        };
11263        let sql = format!(
11264            "INSERT INTO {full_table} ({}) VALUES ({}) ON CONFLICT ({primary_key}) DO UPDATE SET {updates}{guard}",
11265            columns.join(", "),
11266            placeholders.join(", ")
11267        );
11268        self.insert_sql
11269            .borrow_mut()
11270            .insert(full_table.to_owned(), sql.clone());
11271        sql
11272    }
11273
11274    /// §4.5: write a server row under the version guard; returns whether it
11275    /// landed.
11276    fn write_base_row(&self, table_name: &str, row: &Row, version: i64) -> Result<bool, String> {
11277        let landed = self.write_row(&base_table(table_name), table_name, row, version)?;
11278        if landed {
11279            self.overlay_dirty.table(table_name);
11280        }
11281        Ok(landed)
11282    }
11283
11284    fn write_row(
11285        &self,
11286        full_table: &str,
11287        table_name: &str,
11288        row: &Row,
11289        version: i64,
11290    ) -> Result<bool, String> {
11291        #[cfg(feature = "bench-internals")]
11292        let _phase = self.benchmark_phases.start(Phase::RowWrite);
11293        let table = self
11294            .schema
11295            .table(table_name)
11296            .ok_or_else(|| format!("unknown table {table_name:?}"))?;
11297        let sql = self.insert_row_sql(full_table, table);
11298        let mut stmt = self
11299            .conn
11300            .prepare_cached(&sql)
11301            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11302        let params = row
11303            .iter()
11304            .map(RowParam::Cell)
11305            .chain(std::iter::once(RowParam::Version(version)));
11306        stmt.execute(rusqlite::params_from_iter(params))
11307            .map(|changed| changed > 0)
11308            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11309    }
11310
11311    /// §4.5: delete a server row whose stored version lies below `version`;
11312    /// returns whether a row left.
11313    fn delete_base_row(
11314        &self,
11315        table_name: &str,
11316        row_id: &str,
11317        version: i64,
11318    ) -> Result<bool, String> {
11319        let table = self
11320            .schema
11321            .table(table_name)
11322            .ok_or_else(|| format!("unknown table {table_name:?}"))?;
11323        let sql = format!(
11324            "DELETE FROM {} WHERE {} AND _syncular_version < ?2",
11325            base_table(table_name),
11326            row_id_predicate(table)
11327        );
11328        let mut stmt = self
11329            .conn
11330            .prepare_cached(&sql)
11331            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11332        let landed = stmt
11333            .execute(rusqlite::params![row_id, version])
11334            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11335            > 0;
11336        if landed {
11337            self.overlay_dirty.table(table_name);
11338        }
11339        Ok(landed)
11340    }
11341
11342    fn has_acknowledged_rows(&self) -> Result<bool, String> {
11343        self.conn
11344            .query_row(
11345                "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows)",
11346                [],
11347                |row| row.get(0),
11348            )
11349            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11350    }
11351
11352    fn acknowledged_operations(
11353        &self,
11354        rows: Option<&HashSet<(&str, &str)>>,
11355        tables: Option<&BTreeSet<&str>>,
11356    ) -> Result<Vec<OutboxOp>, String> {
11357        let keys = rows.map(|rows| serde_json::to_string(&rows).expect("row keys"));
11358        let mut statement = self
11359            .conn
11360            .prepare_cached(if keys.is_some() {
11361                ACKED_ROWS_BY_ROW
11362            } else {
11363                "SELECT op_json,intent_json FROM _syncular_acked_rows WHERE ?1 IS NULL AND (?2 IS NULL OR tbl IN(SELECT value FROM json_each(?2))) ORDER BY commit_seq,idx"
11364            })
11365            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11366        let rows = statement
11367            .query_map(
11368                rusqlite::params![
11369                    keys,
11370                    tables.map(|tables| serde_json::to_string(tables).expect("table keys"))
11371                ],
11372                |row| {
11373                    #[cfg(test)]
11374                    self.acknowledged_replay_count
11375                        .set(self.acknowledged_replay_count.get() + 1);
11376                    Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
11377                },
11378            )
11379            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11380        rows.map(|row| {
11381            let (op, intent) =
11382                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11383            let op: CommitOperation =
11384                serde_json::from_str(&op).map_err(|_| "sync.local_corrupt".to_owned())?;
11385            let table = self
11386                .schema
11387                .table(&op.table)
11388                .ok_or_else(|| "sync.unknown_table".to_owned())?;
11389            let values = if op.op == "upsert" && self.visible_row(table, &op.row_id)?.is_none() {
11390                Some(serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?)
11391            } else {
11392                op.values
11393            };
11394            Ok(OutboxOp {
11395                table: op.table,
11396                row_id: op.row_id,
11397                upsert: op.op == "upsert",
11398                base_version: op.base_version,
11399                values,
11400                insert: op.insert,
11401            })
11402        })
11403        .collect()
11404    }
11405
11406    fn drop_acknowledged_rows(
11407        &self,
11408        matches: impl Fn(&str, &Map<String, Value>) -> bool,
11409    ) -> Result<Vec<OutboxCommit>, String> {
11410        let mut statement = self
11411            .conn
11412            .prepare("SELECT commit_id,tbl,intent_json,id FROM _syncular_acked_rows")
11413            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11414        let rows = statement
11415            .query_map([], |row| {
11416                Ok((
11417                    row.get::<_, String>(0)?,
11418                    row.get::<_, String>(1)?,
11419                    row.get::<_, String>(2)?,
11420                    row.get::<_, String>(3)?,
11421                ))
11422            })
11423            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11424        let mut doomed = HashSet::new();
11425        for row in rows {
11426            let (id, table, intent, row_id) =
11427                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11428            let values =
11429                serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
11430            let base_matches = self
11431                .schema
11432                .table(&table)
11433                .map(|schema| self.stored_row(schema, &row_id, true))
11434                .transpose()?
11435                .flatten()
11436                .is_some_and(|(base, _)| {
11437                    let schema = self.schema.table(&table).expect("acknowledged table");
11438                    let values = schema
11439                        .columns
11440                        .iter()
11441                        .zip(base.iter())
11442                        .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
11443                        .collect();
11444                    matches(&table, &values)
11445                });
11446            if matches(&table, &values) || base_matches {
11447                doomed.insert(id);
11448            }
11449        }
11450        let mut dropped = Vec::new();
11451        for id in doomed {
11452            let mut statement = self
11453                .conn
11454                .prepare("SELECT op_json FROM _syncular_acked_rows WHERE commit_id=?1 ORDER BY idx")
11455                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11456            let operations = statement
11457                .query_map([&id], |row| row.get::<_, String>(0))
11458                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11459            let mut ops = Vec::new();
11460            for operation in operations {
11461                let json = operation
11462                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11463                let op: CommitOperation =
11464                    serde_json::from_str(&json).map_err(|_| "sync.local_corrupt".to_owned())?;
11465                self.overlay_dirty.table(&op.table);
11466                ops.push(OutboxOp {
11467                    table: op.table,
11468                    row_id: op.row_id,
11469                    upsert: op.op == "upsert",
11470                    base_version: op.base_version,
11471                    values: op.values,
11472                    insert: op.insert,
11473                });
11474            }
11475            dropped.push(OutboxCommit {
11476                client_commit_id: id.clone(),
11477                ops,
11478            });
11479            self.conn
11480                .execute("DELETE FROM _syncular_acked_rows WHERE commit_id=?1", [id])
11481                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11482        }
11483        Ok(dropped)
11484    }
11485
11486    /// [`Self::rebuild_overlay`], skipped when neither the base tables nor
11487    /// the outbox changed since the last rebuild (the no-op sync round).
11488    fn rebuild_overlay_if_dirty(&mut self) -> Result<(), String> {
11489        if self.overlay_dirty.get() {
11490            self.rebuild_overlay()?;
11491        }
11492        Ok(())
11493    }
11494
11495    /// §7.1: local reads see outbox state applied optimistically — rebuild
11496    /// every visible table as (base server state) + (pending outbox replay
11497    /// on top). Optimistic rows carry version `-1`.
11498    fn rebuild_overlay(&mut self) -> Result<(), String> {
11499        #[cfg(feature = "bench-internals")]
11500        let _phase = self.benchmark_phases.start(Phase::OverlayRebuild);
11501        #[cfg(test)]
11502        self.overlay_rebuild_count
11503            .set(self.overlay_rebuild_count.get() + 1);
11504        let dirty = self.overlay_dirty.snapshot();
11505        let tables: Vec<_> = self
11506            .schema
11507            .tables
11508            .iter()
11509            .filter(|table| {
11510                dirty
11511                    .as_ref()
11512                    .is_none_or(|names| names.is_empty() || names.contains(&table.name))
11513            })
11514            .cloned()
11515            .collect();
11516        let names: BTreeSet<_> = tables.iter().map(|table| table.name.as_str()).collect();
11517        self.begin_observation("syncular_overlay")?;
11518        let rebuilt = (|| {
11519            for table in &tables {
11520                for index in &table.fts_indexes {
11521                    self.drop_fts_triggers(index)?;
11522                }
11523                let visible = visible_table(&table.name);
11524                let base = base_table(&table.name);
11525                self.conn
11526                    .execute_batch(&format!(
11527                        "DELETE FROM {visible}; INSERT INTO {visible} SELECT * FROM {base}"
11528                    ))
11529                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11530            }
11531            self.replay_overlay(&names, None)?;
11532            for table in &tables {
11533                for index in &table.fts_indexes {
11534                    self.rebuild_fts_projection(table, index)?;
11535                    self.create_fts_triggers(table, index)?;
11536                }
11537            }
11538            self.conn
11539                .execute_batch("RELEASE syncular_overlay")
11540                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11541            Ok(())
11542        })();
11543        if rebuilt.is_err() {
11544            self.conn
11545                .execute_batch("ROLLBACK TO syncular_overlay; RELEASE syncular_overlay")
11546                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11547        } else {
11548            self.overlay_dirty.set(false);
11549        }
11550        rebuilt
11551    }
11552
11553    /// §7.1 replay of acknowledged, retained failed and pending intent, in
11554    /// that order, for the operations of `tables` on `rows` (every row for
11555    /// `None`) over their current visible state.
11556    fn replay_overlay(
11557        &self,
11558        tables: &BTreeSet<&str>,
11559        rows: Option<&HashSet<(&str, &str)>>,
11560    ) -> Result<(), String> {
11561        let replays = |op: &&OutboxOp| {
11562            tables.contains(op.table.as_str())
11563                && rows.is_none_or(|rows| rows.contains(&(op.table.as_str(), op.row_id.as_str())))
11564        };
11565        self.apply_outbox_ops(&self.acknowledged_operations(rows, Some(tables))?)?;
11566        for (commit, initial) in self.failed_commits.iter() {
11567            for operation in commit.ops.iter().filter(replays) {
11568                let Some(table) = self.schema.table(&operation.table) else {
11569                    continue;
11570                };
11571                if operation.upsert
11572                    && self.visible_row(table, &operation.row_id)?.is_none()
11573                    && operation.presented_values(table).is_some_and(|values| {
11574                        table
11575                            .columns
11576                            .iter()
11577                            .all(|column| values.contains_key(&column.name))
11578                    })
11579                {
11580                    let key = serde_json::to_string(&(&operation.table, &operation.row_id))
11581                        .expect("row key serialization");
11582                    if let Some(Value::Object(values)) = initial.get(&key) {
11583                        self.apply_outbox_ops(&[OutboxOp {
11584                            values: Some(values.clone()),
11585                            ..operation.clone()
11586                        }])?;
11587                    }
11588                }
11589            }
11590            self.apply_outbox_ops(commit.ops.iter().filter(replays))?;
11591        }
11592        self.apply_outbox_ops(
11593            self.outbox
11594                .iter()
11595                .flat_map(|commit| &commit.ops)
11596                .filter(replays),
11597        )
11598    }
11599
11600    /// §7.1 replay: every operation is applied over the current visible
11601    /// state. An operation that no longer applies (a server row now holds its
11602    /// unique value) stays pending and invisible until a later replay admits
11603    /// it or the server answers its push.
11604    fn apply_outbox_ops<'a>(
11605        &self,
11606        ops: impl IntoIterator<Item = &'a OutboxOp>,
11607    ) -> Result<(), String> {
11608        #[cfg(feature = "bench-internals")]
11609        let mut phase = self.benchmark_phases.start(Phase::PendingReplay);
11610        for op in ops {
11611            #[cfg(feature = "bench-internals")]
11612            if let Some(phase) = &mut phase {
11613                phase.unit();
11614            }
11615            if op.upsert {
11616                if let Some((table, values)) = self
11617                    .schema
11618                    .table(&op.table)
11619                    .filter(|table| table.indexes.iter().any(|index| index.unique))
11620                    .and_then(|table| Some((table, op.presented_values(table)?)))
11621                {
11622                    let mut intended: Map<String, Value> = self
11623                        .visible_row(table, &op.row_id)?
11624                        .map(|(row, _)| {
11625                            table
11626                                .columns
11627                                .iter()
11628                                .zip(&row)
11629                                .map(|(column, value)| {
11630                                    (column.name.clone(), column_value_to_json(value))
11631                                })
11632                                .collect()
11633                        })
11634                        .unwrap_or_default();
11635                    intended.extend(values.into_owned());
11636                    if !self.unique_conflicts(table, &intended, false)?.is_empty() {
11637                        continue;
11638                    }
11639                }
11640            }
11641            self.apply_outbox_op(op)?;
11642        }
11643        Ok(())
11644    }
11645
11646    fn apply_outbox_op(&self, op: &OutboxOp) -> Result<(), String> {
11647        let Some(table) = self.schema.table(&op.table) else {
11648            return Ok(());
11649        };
11650        let visible = visible_table(&table.name);
11651        if !op.upsert {
11652            let sql = format!("DELETE FROM {visible} WHERE {}", row_id_predicate(table));
11653            self.conn
11654                .prepare_cached(&sql)
11655                .and_then(|mut statement| statement.execute(rusqlite::params![op.row_id]))
11656                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11657            return Ok(());
11658        }
11659        // §7.1: an insert-intent operation that lacks a non-nullable column
11660        // cannot encode; it stays invisible until the send-time prepass drops
11661        // it as sync.outbox_incompatible (§7.4.4).
11662        let Some(values) = op.presented_values(table) else {
11663            return Ok(());
11664        };
11665        // §7.1: the overlay applies the operation's PRESENT columns
11666        // over the current local row. A partial operation over an
11667        // absent local row leaves it absent — the server answers it
11668        // with sync.row_deleted or sync.row_missing (§6.2). An
11669        // insert-intent operation presents every column.
11670        let full = table
11671            .columns
11672            .iter()
11673            .all(|column| values.contains_key(&column.name));
11674        let local = self.visible_row(table, &op.row_id)?;
11675        if local.is_none() && !full {
11676            return Ok(());
11677        }
11678        let mut row: Row = Vec::with_capacity(table.columns.len());
11679        for (index, column) in table.columns.iter().enumerate() {
11680            let incoming = match values.get(&column.name) {
11681                Some(raw) => json_to_column_value(
11682                    if raw.get("$bytes").is_some()
11683                        && table
11684                            .encrypted_columns
11685                            .iter()
11686                            .any(|encrypted| encrypted.index == index)
11687                    {
11688                        &table.wire_columns[index]
11689                    } else {
11690                        column
11691                    },
11692                    Some(raw),
11693                ),
11694                None => Ok(local
11695                    .as_ref()
11696                    .and_then(|(values, _)| values.get(index).cloned())
11697                    .flatten()),
11698            };
11699            row.push(incoming.map_err(|_| {
11700                "sync.local_corrupt: persisted optimistic row value is invalid".to_owned()
11701            })?);
11702        }
11703        let version = local.as_ref().map_or(-1, |(_, version)| *version);
11704        self.write_row(&visible, &table.name, &row, version)
11705            .map(|_| ())
11706            .map_err(|error| {
11707                if error.starts_with("UNIQUE constraint failed:") {
11708                    "sync.constraint_violation: local write violates a unique constraint".to_owned()
11709                } else {
11710                    error
11711                }
11712            })
11713    }
11714
11715    /// Whether the row is present in the overlay. Existence reads only the
11716    /// key: locked encrypted values stay opaque, and decoding the complete row
11717    /// would reject a valid plain write.
11718    fn visible_row_exists(&self, table: &TableSchema, row_id: &str) -> Result<bool, String> {
11719        self.conn
11720            .query_row(
11721                &format!(
11722                    "SELECT EXISTS(SELECT 1 FROM {} WHERE {})",
11723                    visible_table(&table.name),
11724                    row_id_predicate(table)
11725                ),
11726                rusqlite::params![row_id],
11727                |row| row.get(0),
11728            )
11729            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11730    }
11731
11732    /// The visible (optimistic) row's values plus version, or `None` when the
11733    /// row is absent from the overlay.
11734    fn visible_row(&self, table: &TableSchema, row_id: &str) -> Result<Option<(Row, i64)>, String> {
11735        self.stored_row(table, row_id, false)
11736    }
11737
11738    fn stored_row(
11739        &self,
11740        table: &TableSchema,
11741        row_id: &str,
11742        base: bool,
11743    ) -> Result<Option<(Row, i64)>, String> {
11744        let sql = format!(
11745            "SELECT * FROM {} WHERE {}",
11746            if base {
11747                base_table(&table.name)
11748            } else {
11749                visible_table(&table.name)
11750            },
11751            row_id_predicate(table)
11752        );
11753        let mut stmt = self
11754            .conn
11755            .prepare_cached(&sql)
11756            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11757        let mut rows = stmt
11758            .query(rusqlite::params![row_id])
11759            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11760        let Some(row) = rows
11761            .next()
11762            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11763        else {
11764            return Ok(None);
11765        };
11766        let mut values = Vec::with_capacity(table.columns.len());
11767        for (index, column) in table.columns.iter().enumerate() {
11768            let raw = row
11769                .get_ref(index)
11770                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11771            if let rusqlite::types::ValueRef::Blob(bytes) = raw {
11772                if table
11773                    .encrypted_columns
11774                    .iter()
11775                    .any(|encrypted| encrypted.index == index)
11776                {
11777                    values.push(Some(ColumnValue::Bytes(bytes.to_vec())));
11778                    continue;
11779                }
11780            }
11781            let json = sql_ref_to_json(column, raw);
11782            values.push(json_to_column_value(column, Some(&json)).map_err(|_| {
11783                "sync.local_corrupt: persisted local row value is invalid".to_owned()
11784            })?);
11785        }
11786        let version: i64 = row
11787            .get(table.columns.len())
11788            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11789        Ok(Some((values, version)))
11790    }
11791
11792    // -- realtime (§8) ---------------------------------------------------------------
11793
11794    /// §8.8: the configured realtime policy.
11795    #[must_use]
11796    pub fn realtime_policy(&self) -> RealtimePolicy {
11797        self.realtime_policy
11798    }
11799
11800    /// §8.8: the explicit realtime availability state.
11801    #[must_use]
11802    pub fn realtime_state(&self) -> RealtimeState {
11803        self.realtime_state
11804    }
11805
11806    /// §8.8: set the realtime policy. Refused while the socket is connected:
11807    /// a policy change never silently re-routes an ownership state.
11808    pub fn set_realtime_policy(&mut self, policy: RealtimePolicy) -> Result<(), String> {
11809        if self.realtime_state == RealtimeState::Connected && policy != self.realtime_policy {
11810            return Err(
11811                "sync.invalid_request: disconnect realtime before changing the realtime policy"
11812                    .to_owned(),
11813            );
11814        }
11815        self.realtime_policy = policy;
11816        match policy {
11817            RealtimePolicy::Off => self.set_realtime_state(RealtimeState::Disabled, None),
11818            RealtimePolicy::Required | RealtimePolicy::Optional
11819                if self.realtime_state == RealtimeState::Disabled =>
11820            {
11821                self.set_realtime_state(RealtimeState::Disconnected, None);
11822            }
11823            RealtimePolicy::Required | RealtimePolicy::Optional => {}
11824        }
11825        Ok(())
11826    }
11827
11828    /// Record an availability transition, keeping the reason code bounded and
11829    /// code-like (§7.6) and clearing it where it cannot apply.
11830    fn set_realtime_state(&mut self, state: RealtimeState, reason_code: Option<&str>) {
11831        self.realtime_state = state;
11832        self.realtime_reason_code = reason_code.map(Self::diagnostic_code);
11833        if matches!(state, RealtimeState::Connected | RealtimeState::Disabled) {
11834            self.realtime_reason_code = None;
11835            self.realtime_retry_delay_ms = None;
11836        }
11837    }
11838
11839    #[must_use]
11840    fn realtime_connected(&self) -> bool {
11841        self.realtime_state == RealtimeState::Connected
11842    }
11843
11844    pub fn connect_realtime(&mut self, transport: &mut dyn Transport) -> Result<(), String> {
11845        if !self.transport_enabled {
11846            return Err("sync.offline: transport gate is closed".into());
11847        }
11848        if self.realtime_policy == RealtimePolicy::Off {
11849            return Err(
11850                "sync.invalid_request: realtime is off; realtime connect is refused".to_owned(),
11851            );
11852        }
11853        if self.realtime_connected() {
11854            return Ok(());
11855        }
11856        self.realtime_state = RealtimeState::Connecting;
11857        match transport.realtime_connect_for_client(&self.client_id) {
11858            Ok(()) => {
11859                self.set_realtime_state(RealtimeState::Connected, None);
11860                Ok(())
11861            }
11862            Err(error) => {
11863                self.set_realtime_state(RealtimeState::Refused, Some(&error.code));
11864                Err(format!("{}: {}", error.code, error.message))
11865            }
11866        }
11867    }
11868
11869    pub fn disconnect_realtime(&mut self, transport: &mut dyn Transport) {
11870        self.cancel_sync_round();
11871        // A deliberately disconnected or policy-disabled client has nothing
11872        // to release; a `lost` socket still does (the host owns the handle).
11873        if self.realtime_state == RealtimeState::Disconnected
11874            || self.realtime_state == RealtimeState::Disabled
11875        {
11876            return;
11877        }
11878        let _ = transport.realtime_close();
11879        self.set_realtime_state(
11880            if self.realtime_policy == RealtimePolicy::Off {
11881                RealtimeState::Disabled
11882            } else {
11883                RealtimeState::Disconnected
11884            },
11885            None,
11886        );
11887        self.presence.clear(); // §8.6.1: presence is per-connection
11888    }
11889
11890    /// §8.8: the host observed the socket end without disconnecting it (a
11891    /// peer close, an I/O error, a failed send; the native transport reports
11892    /// these as `Inbound::Disconnected`). Releases the transport, moves a
11893    /// `Connected` state to `Lost` with the transport's code as the reason, and schedules
11894    /// one background retry intent so the host reconnects and catches up.
11895    pub fn realtime_lost(&mut self, transport: &mut dyn Transport, error: &TransportError) {
11896        if self.realtime_state != RealtimeState::Connected {
11897            return;
11898        }
11899        self.cancel_sync_round();
11900        let _ = transport.realtime_close();
11901        self.set_realtime_state(RealtimeState::Lost, Some(&error.code));
11902        self.realtime_retry_delay_ms = Some(self.schedule_background_retry());
11903        self.presence.clear();
11904    }
11905
11906    /// §8.6.2: publish (or clear, `doc: None`) this client's presence
11907    /// document for `scope_key`. Requires a live socket; the document is
11908    /// ephemeral (lost on disconnect). Authorization is the connection's
11909    /// registration (§8.6.3) — an unheld key is rejected loudly by the
11910    /// server with `presence.forbidden`.
11911    pub fn set_presence(
11912        &mut self,
11913        transport: &mut dyn Transport,
11914        scope_key: &str,
11915        doc: Option<&Value>,
11916    ) -> Result<(), String> {
11917        if !self.transport_enabled {
11918            return Err("sync.offline: transport gate is closed".into());
11919        }
11920        if !self.realtime_connected() {
11921            return Err("setPresence requires a connected realtime socket (§8.6)".to_string());
11922        }
11923        let text = encode_presence_publish(scope_key, doc);
11924        transport
11925            .realtime_send(&text)
11926            .map_err(|e| format!("{}: {}", e.code, e.message))
11927    }
11928
11929    /// §8.6: the peers currently present on a scope key (ephemeral).
11930    pub fn presence(&self, scope_key: &str) -> Vec<PresencePeer> {
11931        self.presence
11932            .get(scope_key)
11933            .map(|peers| peers.values().cloned().collect())
11934            .unwrap_or_default()
11935    }
11936
11937    /// §8.6 apply an inbound presence fanout to the local map.
11938    fn apply_presence(
11939        &mut self,
11940        scope_key: String,
11941        kind: Option<PresenceKind>,
11942        actor_id: Option<String>,
11943        client_id: Option<String>,
11944        doc: Option<Value>,
11945        error: Option<String>,
11946    ) {
11947        // A refused publish (§8.6.2) changes no peer; the native host surfaces
11948        // it as a `presence` event carrying the server's `error` code.
11949        if error.is_some() {
11950            return;
11951        }
11952        let (Some(kind), Some(actor_id), Some(client_id)) = (kind, actor_id, client_id) else {
11953            return;
11954        };
11955        let peer_key = format!("{actor_id} {client_id}");
11956        match kind {
11957            PresenceKind::Leave => {
11958                if let Some(peers) = self.presence.get_mut(&scope_key) {
11959                    peers.remove(&peer_key);
11960                    if peers.is_empty() {
11961                        self.presence.remove(&scope_key);
11962                    }
11963                }
11964            }
11965            _ => {
11966                let doc = match doc {
11967                    Some(Value::Object(_)) => doc.unwrap(),
11968                    _ => return,
11969                };
11970                self.presence.entry(scope_key).or_default().insert(
11971                    peer_key,
11972                    PresencePeer {
11973                        actor_id,
11974                        client_id,
11975                        doc,
11976                    },
11977                );
11978            }
11979        }
11980    }
11981
11982    /// Inbound JSON control message (§8.1). Unknown events are tolerated.
11983    pub fn on_realtime_text(&mut self, text: &str) {
11984        if self.stopped || !self.transport_enabled || self.security_preflight {
11985            return;
11986        }
11987        match parse_control(text) {
11988            Ok(ControlMessage::Hello { requires_sync, .. }) => {
11989                if requires_sync {
11990                    // §8.1: pull before trusting the socket for continuity.
11991                    self.set_sync_needed(true, true);
11992                }
11993            }
11994            Ok(ControlMessage::Presence {
11995                scope_key,
11996                kind,
11997                actor_id,
11998                client_id,
11999                doc,
12000                error,
12001                ..
12002            }) => {
12003                self.apply_presence(scope_key, kind, actor_id, client_id, doc, error);
12004            }
12005            Ok(ControlMessage::Wake { .. }) => {
12006                // §8.3: any wake-up means "run a pull soon", never data.
12007                self.set_sync_needed(true, true);
12008            }
12009            _ => {}
12010        }
12011    }
12012
12013    /// Inbound binary delta: a complete SSP2 response (§8.2), applied like
12014    /// a pull response per section; an unapplied delta is a wake-up.
12015    /// Mailbox hosts send durable acknowledgements on their I/O executor.
12016    pub fn on_realtime_binary_queued(&mut self, bytes: &[u8]) -> Vec<String> {
12017        let mut transport = crate::round::DownloadResults::default();
12018        self.on_realtime_binary(&mut transport, bytes);
12019        transport.controls
12020    }
12021
12022    /// §8.2: a delta applies exactly like a live section and sets the replica
12023    /// cursor to its `throughSeq`; one at or below the replica cursor is a
12024    /// duplicate. A delta the client does not apply (no live unit, a status
12025    /// other than `active`, a decode or apply failure) is a drop and raises
12026    /// sync-needed.
12027    pub fn on_realtime_binary(&mut self, transport: &mut dyn Transport, bytes: &[u8]) {
12028        if self.stopped || !self.transport_enabled || self.security_preflight {
12029            return;
12030        }
12031        #[cfg(feature = "bench-internals")]
12032        let decode_phase = self.benchmark_phases.start(Phase::ResponseDecode);
12033        let message = match decode_message(bytes) {
12034            Ok(m) if m.msg_kind == MsgKind::Response => m,
12035            _ => {
12036                self.set_sync_needed(true, true);
12037                return;
12038            }
12039        };
12040        #[cfg(feature = "bench-internals")]
12041        drop(decode_phase);
12042        // §8.2: a delta's header means what a pull response's header means. A
12043        // schema floor (§1.6) is recorded, stops syncing and applies nothing.
12044        if let Some(Frame::RespHeader {
12045            required_schema_version: Some(required),
12046            latest_schema_version,
12047            ..
12048        }) = message.frames.first()
12049        {
12050            let floor = SchemaFloor {
12051                required_schema_version: Some(*required),
12052                latest_schema_version: *latest_schema_version,
12053            };
12054            if self.set_schema_floor(Some(floor)).is_err() {
12055                self.set_sync_needed(true, true);
12056            }
12057            return;
12058        }
12059        let through = message.frames.iter().find_map(|frame| match frame {
12060            Frame::LiveEnd { through_seq, .. } => Some(*through_seq),
12061            _ => None,
12062        });
12063        let epoch = self.get_meta(LOG_EPOCH_KEY).ok().flatten();
12064        let mut dropped = !matches!(message.frames.first(), Some(Frame::RespHeader {
12065                reset_required: false,
12066                log_epoch,
12067                ..
12068            }) if Some(log_epoch) == epoch.as_ref());
12069        let mut applied: Option<i64> = None;
12070        dropped |= self.begin_coalesced_apply().is_err();
12071        let mut receivers: Option<Vec<UnitRecord>> = None;
12072        for frame in message.frames {
12073            if dropped {
12074                break;
12075            }
12076            match frame {
12077                Frame::LiveStart { status, .. } => {
12078                    let Ok(cursor) = self.stored(replica_cursor(&self.conn)) else {
12079                        dropped = true;
12080                        break;
12081                    };
12082                    if status != LiveStatus::Active || cursor < 0 {
12083                        dropped = true;
12084                    } else if !through.is_some_and(|through| through <= cursor) {
12085                        // A catching-up unit receives no delta (§8.2).
12086                        receivers = self.stored(load_units(&self.conn)).ok().map(|units| {
12087                            units
12088                                .into_iter()
12089                                .filter(|unit| {
12090                                    unit.status == UnitStatus::Active
12091                                        && unit.echo.is_some()
12092                                        && unit.cursor.is_none()
12093                                })
12094                                .collect()
12095                        });
12096                        dropped = receivers.is_none();
12097                    }
12098                }
12099                Frame::Commit {
12100                    commit_seq,
12101                    tables,
12102                    changes,
12103                    ..
12104                } => {
12105                    let Some(receivers) = receivers.clone() else {
12106                        continue;
12107                    };
12108                    dropped = self
12109                        .apply_live_commit(
12110                            &receivers,
12111                            &tables,
12112                            changes,
12113                            commit_seq,
12114                            AppliedServerCommitSource::Delta,
12115                        )
12116                        .is_err();
12117                }
12118                Frame::LiveEnd { through_seq, .. } if receivers.is_some() => {
12119                    dropped = self
12120                        .set_meta(REPLICA_CURSOR_KEY, &through_seq.to_string())
12121                        .is_err();
12122                    applied = Some(through_seq);
12123                }
12124                Frame::Error { .. } => dropped = true,
12125                _ => {}
12126            }
12127        }
12128        // §1.4 rule 4: the ack follows the COMMIT. A failed COMMIT restored
12129        // the replica cursor, so the delta counts as a drop.
12130        if self.finish_coalesced_apply().is_err() || dropped {
12131            applied = None;
12132            dropped = true;
12133        }
12134        if let Some(cursor) = applied {
12135            // §8.2 ack point: the delta's throughSeq.
12136            let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
12137            let _ = transport.realtime_send(&ack);
12138        }
12139        if dropped {
12140            self.set_sync_needed(true, true);
12141        }
12142    }
12143
12144    /// §8.2 ack point after a pull round on a live connection: the replica
12145    /// cursor while it is at least `0`.
12146    fn ack_after_pull(&mut self, transport: &mut dyn Transport) {
12147        if !self.realtime_connected() {
12148            return;
12149        }
12150        if let Ok(cursor @ 0..) = self.stored(replica_cursor(&self.conn)) {
12151            let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
12152            let _ = transport.realtime_send(&ack);
12153        }
12154    }
12155}
12156
12157#[cfg(test)]
12158mod previous_version_wiring_tests;
12159
12160#[cfg(test)]
12161mod identity_tests;
12162
12163#[cfg(test)]
12164mod insert_intent_tests;
12165
12166#[cfg(test)]
12167mod robustness_tests;