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, SealedRow,
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<CommitOperation> for OutboxOp {
222    fn from(operation: CommitOperation) -> Self {
223        Self {
224            upsert: operation.op == "upsert",
225            table: operation.table,
226            row_id: operation.row_id,
227            base_version: operation.base_version,
228            values: operation.values,
229            insert: operation.insert,
230        }
231    }
232}
233
234/// §7.5 static authoring refusal; the table and column travel in details.
235fn invalid_authoring(message: &str, details: Value) -> ClientError {
236    ClientError {
237        code: "sync.invalid_request".to_owned(),
238        message: message.to_owned(),
239        details: Some(details),
240        retryable: false,
241    }
242}
243
244/// §7.1 chained base: `later` repeats `earlier`'s positive base on the same
245/// row and presents only columns `earlier` presents.
246fn chains_on(earlier: &OutboxOp, later: &OutboxOp) -> bool {
247    // Only an upsert carries values, and it always carries its primary key.
248    earlier.row_id == later.row_id
249        && earlier.table == later.table
250        && later.base_version.is_some_and(|base| base > 0)
251        && earlier.base_version == later.base_version
252        && later.values.as_ref().is_some_and(|values| {
253            values.keys().all(|column| {
254                earlier
255                    .values
256                    .as_ref()
257                    .is_some_and(|earlier| earlier.contains_key(column))
258            })
259        })
260}
261
262impl From<&OutboxOp> for CommitOperation {
263    fn from(operation: &OutboxOp) -> Self {
264        Self {
265            table: operation.table.clone(),
266            row_id: operation.row_id.clone(),
267            op: if operation.upsert { "upsert" } else { "delete" }.to_owned(),
268            base_version: operation.base_version,
269            values: operation.values.clone(),
270            insert: operation.insert,
271        }
272    }
273}
274
275#[derive(Debug, Clone)]
276struct OutboxCommit {
277    client_commit_id: String,
278    ops: Vec<OutboxOp>,
279}
280
281/// One commit's `(table, value keys, insert intent)` per upsert operation — the classification
282/// shape the §7.4.4 send-time drop and the RFC 0005 D6 audit share, so the two
283/// can never disagree about which commits cannot re-encode.
284fn commit_audit_operations(commit: &OutboxCommit) -> Vec<(&str, Vec<&str>, bool)> {
285    commit
286        .ops
287        .iter()
288        .filter(|operation| operation.upsert)
289        .map(|operation| {
290            (
291                operation.table.as_str(),
292                operation
293                    .values
294                    .as_ref()
295                    .map(|values| values.keys().map(String::as_str).collect())
296                    .unwrap_or_default(),
297                operation.insert,
298            )
299        })
300        .collect()
301}
302
303type FailedCommit = (OutboxCommit, Map<String, Value>);
304
305#[derive(Debug, Clone)]
306struct CompiledLocalDataPurgeTarget {
307    table: String,
308    selectors: Vec<(String, Vec<String>)>,
309}
310
311struct StoredCommitOutcomeRow {
312    sequence: i64,
313    client_commit_id: String,
314    status: String,
315    recorded_at_ms: i64,
316    results_json: String,
317    operations_json: Option<String>,
318    resolution: String,
319    resolved_at_ms: Option<i64>,
320    replacement_client_commit_id: Option<String>,
321}
322
323impl StoredCommitOutcomeRow {
324    fn from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<Self> {
325        Ok(Self {
326            sequence: row.get(0)?,
327            client_commit_id: row.get(1)?,
328            status: row.get(2)?,
329            recorded_at_ms: row.get(3)?,
330            results_json: row.get(4)?,
331            operations_json: row.get(5)?,
332            resolution: row.get(6)?,
333            resolved_at_ms: row.get(7)?,
334            replacement_client_commit_id: row.get(8)?,
335        })
336    }
337}
338
339/// Section outcome distinguishing the §5.6 unit-local fail-closed
340/// path from a round-aborting failure (§1.4 rule 5).
341/// §4.4 a unit section's `SUB_START`.
342struct SectionStart {
343    id: String,
344    status: SubStatus,
345    reason_code: String,
346    bootstrap: bool,
347    fenced: Vec<FencedRecord>,
348}
349
350enum SectionError {
351    FailClosed,
352    /// §5.5: the server refused a segment with `sync.forbidden`.
353    Refused,
354    /// §5.3 client memory: the round deferred this image's body to a later
355    /// pull of the same resume token.
356    Deferred,
357    Abort(String, String),
358    Transport(TransportError),
359}
360
361#[derive(Debug)]
362pub(crate) struct RequestMeta {
363    pushed_ids: Vec<String>,
364    /// Hex of the registration digest this pull carried; the server stores
365    /// that list once the round completes (§4.1).
366    registration_digest: String,
367    pub(crate) accept: u8,
368    /// §6.1 splitBatch: outbox commits held back from THIS request because
369    /// the running operation count reached the push cap — the next round
370    /// pushes them (`sync_needed` stays set while any remain).
371    deferred_commits: usize,
372    /// §5.6 applied-segment rule: per unit presenting its recorded cursor
373    /// and token, the segment ids neither downloaded nor applied again.
374    pub(crate) applied: BTreeMap<String, BTreeSet<String>>,
375    /// §5.3 client memory: (unit, segment id) of the first image whose body
376    /// the round did not fetch because the batch already holds two images.
377    /// That unit's section stops there without persisting `SUB_END`.
378    pub(crate) deferred: BTreeSet<(String, String)>,
379}
380
381#[derive(Default)]
382struct ChangeAccumulator {
383    /// None means table-wide; Some is the exact scoped domain.
384    tables: BTreeMap<String, Option<BTreeSet<String>>>,
385    windows: BTreeMap<String, BTreeSet<String>>,
386    status: bool,
387    conflicts: bool,
388    rejections: bool,
389    outcomes: bool,
390}
391
392impl ChangeAccumulator {
393    fn table(&mut self, table: &str) {
394        self.tables.insert(table.to_owned(), None);
395    }
396
397    fn scope(&mut self, table: &str, key: String) {
398        match self.tables.get_mut(table) {
399            Some(None) => {}
400            Some(Some(keys)) => {
401                keys.insert(key);
402            }
403            None => {
404                self.tables
405                    .insert(table.to_owned(), Some(BTreeSet::from([key])));
406            }
407        }
408    }
409
410    fn window(&mut self, base_key: &str, value: &str) {
411        self.windows
412            .entry(base_key.to_owned())
413            .or_default()
414            .insert(value.to_owned());
415    }
416
417    fn touched(&self) -> bool {
418        !self.tables.is_empty()
419            || !self.windows.is_empty()
420            || self.status
421            || self.conflicts
422            || self.rejections
423            || self.outcomes
424    }
425}
426
427/// §6.1: the server caps total operations per request (reference default
428/// 500) and rejects the whole batch with `sync.too_many_operations`; the
429/// client "splits and retries". Splitting happens at build time: commits are
430/// included IN ORDER until the operation budget is spent, the rest wait for
431/// the next round.
432const PUSH_OPS_PER_REQUEST: usize = 500;
433const MAX_LOCAL_PURGE_TARGETS: usize = 64;
434const MAX_LOCAL_PURGE_SELECTORS: usize = 8;
435const MAX_LOCAL_PURGE_VALUES: usize = 128;
436const MAX_LOCAL_PURGE_VALUE_LENGTH: usize = 256;
437pub const SECURITY_PREFLIGHT_REQUIRED_CODE: &str = "client.security_preflight_required";
438
439/// Dirty visible tables; `None` means a whole-replica recovery/reset.
440struct OverlayDirty(RefCell<Option<BTreeSet<String>>>);
441
442impl OverlayDirty {
443    fn clean() -> Self {
444        Self(RefCell::new(Some(BTreeSet::new())))
445    }
446    fn get(&self) -> bool {
447        self.0
448            .borrow()
449            .as_ref()
450            .is_none_or(|tables| !tables.is_empty())
451    }
452    fn set(&self, dirty: bool) {
453        *self.0.borrow_mut() = if dirty { None } else { Some(BTreeSet::new()) };
454    }
455    fn table(&self, table: &str) {
456        if let Some(tables) = self.0.borrow_mut().as_mut() {
457            tables.insert(table.to_owned());
458        }
459    }
460    fn snapshot(&self) -> Option<BTreeSet<String>> {
461        self.0.borrow().clone()
462    }
463    fn restore(&self, tables: Option<BTreeSet<String>>) {
464        *self.0.borrow_mut() = tables;
465    }
466}
467
468/// A copy-on-write in-memory mirror: a [`Rollback`] shares it, and the first
469/// write after a capture copies it once.
470#[derive(Debug, Clone, Default)]
471struct Shared<T>(Arc<T>);
472
473impl<T> std::ops::Deref for Shared<T> {
474    type Target = T;
475    fn deref(&self) -> &T {
476        &self.0
477    }
478}
479
480impl<T: Clone> std::ops::DerefMut for Shared<T> {
481    fn deref_mut(&mut self) -> &mut T {
482        Arc::make_mut(&mut self.0)
483    }
484}
485
486impl<T> From<T> for Shared<T> {
487    fn from(value: T) -> Self {
488        Self(Arc::new(value))
489    }
490}
491
492/// The in-memory mirrors of durable state, captured before a local
493/// transaction and restored when it rolls back. Queues only grow inside a
494/// transaction, so their lengths suffice.
495#[derive(Debug, Clone)]
496struct Rollback {
497    outbox: Shared<Vec<Arc<OutboxCommit>>>,
498    failed_commits: Shared<Vec<FailedCommit>>,
499    conflicts: Shared<Vec<ConflictRecord>>,
500    rejections: Shared<Vec<RejectionRecord>>,
501    schema_floor: Option<SchemaFloor>,
502    lease_state: Option<LeaseState>,
503    stopped: bool,
504    upgrading: bool,
505    sync_needed: bool,
506    active_round: Option<uuid::Uuid>,
507    overlay_dirty: Option<BTreeSet<String>>,
508    change_queue: usize,
509    sync_intent_queue: usize,
510    last_change: Option<DiagnosticLastChange>,
511}
512
513pub struct SyncClient {
514    #[cfg(feature = "bench-internals")]
515    benchmark_phases: Recorder,
516    conn: Connection,
517    schema: ClientSchema,
518    client_id: String,
519    limits: ClientLimits,
520    outbox: Shared<Vec<Arc<OutboxCommit>>>,
521    failed_commits: Shared<Vec<FailedCommit>>,
522    retain_failed_commits: bool,
523    conflicts: Shared<Vec<ConflictRecord>>,
524    rejections: Shared<Vec<RejectionRecord>>,
525    schema_floor: Option<SchemaFloor>,
526    /// §7.3.5: the opaque auth-lease state (from LEASE frames + lease errors).
527    lease_state: Option<LeaseState>,
528    /// §1.6: the schema-floor response stops syncing until an upgrade.
529    stopped: bool,
530    /// §7.4.5: true while a schema-bump reset + first re-bootstrap is in flight.
531    upgrading: bool,
532    /// §8.4 coalesced sync-needed signal.
533    sync_needed: bool,
534    /// §8.8: how sync rounds treat the realtime binding, and its exact
535    /// availability state with the evidence behind a lost or refused one.
536    realtime_policy: RealtimePolicy,
537    realtime_state: RealtimeState,
538    realtime_reason_code: Option<String>,
539    realtime_retry_delay_ms: Option<u64>,
540    /// §8.6 presence: scopeKey → (`actorId clientId` peer key → peer).
541    presence: HashMap<String, HashMap<String, PresencePeer>>,
542    /// Client clock (epoch ms) for the §5.4 `urlExpiresAtMs` check; the
543    /// host may pin it (conformance runs on a virtual clock).
544    now_ms: Option<i64>,
545    /// §5.11 client-side encryption keys (`keyId → key bytes`). Empty ⇒ E2EE
546    /// off. The encrypt/decrypt seam (`values.rs`) is compiled only under the
547    /// `e2ee` feature; without it, a schema with encrypted columns fails loud.
548    encryption: crate::values::EncryptionConfig,
549    /// Fail-closed host bootstrap gate. While set, command hosts permit only
550    /// status/lifecycle inspection and an exact authorized local purge.
551    security_preflight: bool,
552    security_epoch: u64,
553    transport_enabled: bool,
554    transport_epoch: u64,
555    /// Raised by every registration change; a current-base proof spanning
556    /// one reports missing coverage.
557    registration_epoch: u64,
558    /// RFC 0005 D2/D8: the previous-version capture config. `None` (default)
559    /// means the feature is off; the descriptor write and the container orphan
560    /// sweep still happen.
561    previous_version: Option<PreviousVersionContextConfig>,
562    /// Per-table primary-key upsert SQL, built once per (full table name) —
563    /// the row write path runs per row during bootstrap (§5.6), so the SQL
564    /// string (and, via `prepare_cached`, its compiled statement) is reused
565    /// instead of being rebuilt and re-prepared per row. Cleared on a §7.4.3
566    /// schema reset (the column lists may have changed).
567    insert_sql: RefCell<HashMap<String, String>>,
568    /// §7.1: reconcile only tables whose base/outbox changed. Whole-replica
569    /// reset and restart explicitly invalidate every table.
570    overlay_dirty: OverlayDirty,
571    // First SQLite failure of the current operation, before savepoint cleanup.
572    storage_failure: RefCell<Option<QueryReadFailure>>,
573    /// Test-only structural performance signal: response processing must not
574    /// turn a batch of acknowledgements into one full overlay rebuild each.
575    #[cfg(test)]
576    overlay_rebuild_count: Cell<usize>,
577    #[cfg(test)]
578    acknowledged_replay_count: Cell<usize>,
579    /// Test-only structural performance signal: outcome retention is enforced
580    /// once per response rather than once per acknowledgement.
581    #[cfg(test)]
582    outcome_prune_count: Cell<usize>,
583    /// Test-only pinned duration of every §5.3 image chunk, in ms.
584    #[cfg(test)]
585    image_chunk_ms: Cell<Option<f64>>,
586    /// Exact observer-transaction output drained by command/FFI hosts.
587    progress: ProgressObserver,
588    change_queue: VecDeque<ClientChangeBatch>,
589    sync_intent_queue: VecDeque<SyncIntent>,
590    /// Explicit exponential retry policy for transient transport failures.
591    retry_delay_ms: u64,
592    /// §7.7: the background retry the current round scheduled, if any.
593    round_retry_delay_ms: Option<u64>,
594    /// §5.6 applied-segment rule: per unit, the cursor and resume token it
595    /// presented and the `SEGMENT_REF`s applied completely in sections whose
596    /// `SUB_END` did not persist.
597    #[allow(clippy::type_complexity)]
598    applied_segments: HashMap<String, (Option<i64>, Option<String>, BTreeSet<String>)>,
599    /// §5.3: a table's next image chunk size, carried from one range image
600    /// of the table to the next.
601    image_chunk_rows: HashMap<String, u32>,
602    /// A round whose response never completed (§1.5): the client keeps its
603    /// code and reports it on every following request until a round receives a
604    /// complete, decodable response. The server already recorded the round, so
605    /// nothing else can tell it the round failed on this side.
606    round_failure: Option<String>,
607    active_round: Option<uuid::Uuid>,
608    last_round: Option<DiagnosticLastRound>,
609    last_change: Option<DiagnosticLastChange>,
610    /// §7.6: latest failed owned snapshot read per owner id, oldest first.
611    query_failures: Vec<DiagnosticQueryFailure>,
612    /// SPEC §1.4 rule 4: the open coalesced apply transaction of a response.
613    coalesced: Option<CoalescedApply>,
614    /// A coalesced apply transaction of the current response failed; every
615    /// later observation of that response fails until it ends.
616    coalesced_failure: Option<String>,
617}
618
619/// SPEC §1.4 rule 4: the frames and blocks of one response share one local
620/// write transaction of at most `COALESCED_APPLY_ROWS` rows. The in-memory
621/// state captured at its `BEGIN` is restored when its `COMMIT` fails.
622struct CoalescedApply {
623    rows: usize,
624    rollback: Rollback,
625}
626
627const COALESCED_APPLY_ROWS: usize = 1024;
628
629pub(crate) fn quote_ident(name: &str) -> String {
630    format!("\"{}\"", name.replace('"', "\"\""))
631}
632/// §7.4.1 `_syncular_meta` helpers. Free functions so RFC 0005's
633/// previous-version module reads and writes the SAME records as the client
634/// instead of growing a parallel meta layer.
635pub(crate) fn meta_get(conn: &Connection, key: &str) -> rusqlite::Result<Option<String>> {
636    conn.query_row(
637        "SELECT value FROM _syncular_meta WHERE key = ?1",
638        rusqlite::params![key],
639        |row| row.get::<_, String>(0),
640    )
641    .optional()
642}
643
644pub(crate) fn meta_set(conn: &Connection, key: &str, value: &str) -> rusqlite::Result<()> {
645    conn.execute(
646        "INSERT OR REPLACE INTO _syncular_meta (key, value) VALUES (?1, ?2)",
647        rusqlite::params![key, value],
648    )
649    .map(|_| ())
650}
651
652pub(crate) fn meta_delete(conn: &Connection, key: &str) -> rusqlite::Result<()> {
653    conn.execute(
654        "DELETE FROM _syncular_meta WHERE key = ?1",
655        rusqlite::params![key],
656    )
657    .map(|_| ())
658}
659
660/// Seek by the existing key while retaining the exact legacy text match.
661fn row_id_predicate(table: &TableSchema) -> String {
662    let key = quote_ident(&table.primary_key);
663    let text_match = format!("CAST({key} AS TEXT) = ?1");
664    match table.columns[table.pk_index].ty {
665        ColumnType::String | ColumnType::Json => {
666            format!("{key} = ?1 AND {text_match}")
667        }
668        // Native columns have no declared SQLite affinity. Match the stored
669        // integer bind type explicitly. Unary + removes expression affinity so
670        // SQLite can seek the typeless key; the text check preserves exact IDs.
671        ColumnType::Integer | ColumnType::Boolean => {
672            format!("{key} = +CAST(?1 AS INTEGER) AND {text_match}")
673        }
674        // REAL-to-text conversion can round distinct values to the same text.
675        // Narrowing those matches by numeric equality would change behavior.
676        _ => text_match,
677    }
678}
679
680/// §3.3/§4.8/§5.6 row ownership: rows whose local scope columns match
681/// `effective` and that no entry of `owners` matches. `owners` holds the
682/// pair scopes of every owner of the table (§3.3 row ownership); a scoped delete never removes a row one of them still covers.
683/// Scope values bind by the column's declared type, as `row_id_predicate`
684/// does. `Ok(None)` matches nothing (an empty map or value list); `Err(())`
685/// is a missing local scope-column mapping (the fail-closed case).
686fn local_scope_predicate(
687    table: &TableSchema,
688    effective: &[(String, Vec<String>)],
689    owners: &[Vec<(String, Vec<String>)>],
690) -> Result<Option<(String, Vec<SqlValue>)>, ()> {
691    if effective.is_empty() || effective.iter().any(|(_, values)| values.is_empty()) {
692        return Ok(None);
693    }
694    let column = |variable: &str| {
695        let name = table.scope_column(variable).ok_or(())?;
696        let column = table
697            .columns
698            .iter()
699            .find(|column| column.name == name)
700            .ok_or(())?;
701        Ok((quote_ident(name), column.ty == ColumnType::Integer))
702    };
703    let mut clauses = Vec::new();
704    let mut params = Vec::new();
705    for (variable, values) in effective {
706        let (key, integer) = column(variable)?;
707        let holes = vec!["?"; values.len()].join(", ");
708        clauses.push(if integer {
709            params.extend(values.iter().cloned().map(SqlValue::Text));
710            let seek = vec!["+CAST(? AS INTEGER)"; values.len()].join(", ");
711            format!("{key} IN ({seek}) AND CAST({key} AS TEXT) IN ({holes})")
712        } else {
713            format!("{key} IN ({holes})")
714        });
715        params.extend(values.iter().cloned().map(SqlValue::Text));
716    }
717    // Owners bind as one JSON parameter per variable set, so the statement
718    // keeps its size at any owner count; owners of one variable bind the
719    // union of their values. An owner holding other values of a variable
720    // `effective` names owns none of its rows and drops out. Values compare
721    // as text, the exact semantics of the effective clauses.
722    let mut groups: BTreeMap<Vec<&str>, Vec<Vec<&[String]>>> = BTreeMap::new();
723    for owner in owners {
724        if owner.is_empty()
725            || owner.iter().any(|(variable, values)| {
726                values.is_empty()
727                    || effective.iter().any(|(name, wanted)| {
728                        name == variable && wanted.iter().all(|value| !values.contains(value))
729                    })
730            })
731        {
732            continue;
733        }
734        let mut owner: Vec<_> = owner.iter().collect();
735        owner.sort_by(|a, b| a.0.cmp(&b.0));
736        groups
737            .entry(
738                owner
739                    .iter()
740                    .map(|(variable, _)| variable.as_str())
741                    .collect(),
742            )
743            .or_default()
744            .push(owner.iter().map(|(_, values)| values.as_slice()).collect());
745    }
746    let within = |variable: &str, list: &str| {
747        let (key, integer) = column(variable)?;
748        let key = if integer {
749            format!("CAST({key} AS TEXT)")
750        } else {
751            key
752        };
753        Ok(format!("{key} IN (SELECT value FROM json_each({list}))"))
754    };
755    for (variables, tuples) in groups {
756        if let [variable] = variables[..] {
757            let values: BTreeSet<&String> = tuples.iter().flatten().copied().flatten().collect();
758            params.push(SqlValue::Text(
759                Value::from_iter(values.into_iter().cloned()).to_string(),
760            ));
761            clauses.push(format!("NOT {}", within(variable, "?")?));
762        } else {
763            params.push(SqlValue::Text(
764                serde_json::to_string(&tuples).expect("owner tuples serialize"),
765            ));
766            let matches = variables
767                .iter()
768                .enumerate()
769                .map(|(index, variable)| within(variable, &format!("o.value,'$[{index}]'")))
770                .collect::<Result<Vec<_>, ()>>()?;
771            clauses.push(format!(
772                "NOT EXISTS (SELECT 1 FROM json_each(?) o WHERE {})",
773                matches.join(" AND ")
774            ));
775        }
776    }
777    Ok(Some((clauses.join(" AND "), params)))
778}
779
780/// [`local_scope_predicate`] over decoded row values (retained rows).
781fn owns_local_row(
782    table: &TableSchema,
783    effective: &[(String, Vec<String>)],
784    owners: &[Vec<(String, Vec<String>)>],
785    values: &Map<String, Value>,
786) -> bool {
787    let matches = |scopes: &[(String, Vec<String>)]| {
788        !scopes.is_empty()
789            && scopes.iter().all(|(variable, allowed)| {
790                table
791                    .scope_column(variable)
792                    .and_then(|column| values.get(column))
793                    .filter(|value| !value.is_null())
794                    .is_some_and(|value| {
795                        allowed.contains(
796                            &value
797                                .as_str()
798                                .map_or_else(|| value.to_string(), str::to_owned),
799                        )
800                    })
801            })
802    };
803    matches(effective) && !owners.iter().any(|owner| matches(owner))
804}
805
806fn is_local_operation_code_like(value: &str) -> bool {
807    let bytes = value.as_bytes();
808    bytes.first().is_some_and(u8::is_ascii_alphanumeric)
809        && bytes
810            .iter()
811            .all(|byte| byte.is_ascii_alphanumeric() || matches!(*byte, b'.' | b'_' | b':' | b'-'))
812}
813
814fn base_table(name: &str) -> String {
815    quote_ident(&format!("_syncular_base_{name}"))
816}
817
818/// §4.8 deferred eviction record: (unit id, table, effective scope map).
819type PendingEvict = (String, String, Vec<(String, Vec<String>)>);
820
821/// §4.8: a stable key for a window base: variable + canonical fixed scopes.
822fn window_base_key(base: &WindowBase) -> String {
823    format!(
824        "{}\0{}",
825        base.variable,
826        ssp2::registration::canonical_unit_json(&scope_pairs(&base.fixed_scopes))
827    )
828}
829
830/// The unit of one window value: the fixed scopes plus the value.
831fn window_unit_scopes(base: &WindowBase, value: &str) -> UnitScopes {
832    let mut scopes = base.fixed_scopes.clone();
833    scopes.insert(base.variable.clone(), value.to_owned());
834    scopes
835}
836
837/// A unit's scope map as the codec and the digests take it.
838fn scope_pairs(scopes: &UnitScopes) -> Vec<(String, String)> {
839    let mut pairs: Vec<(String, String)> = scopes
840        .iter()
841        .map(|(variable, value)| (variable.clone(), value.clone()))
842        .collect();
843    pairs.sort_by(|a, b| a.0.encode_utf16().cmp(b.0.encode_utf16()));
844    pairs
845}
846
847/// §4.1: the unit covers every table declaring all of its variables.
848fn covers(table: &TableSchema, scopes: &UnitScopes) -> bool {
849    scopes
850        .keys()
851        .all(|variable| table.scope_column(variable).is_some())
852}
853
854/// §4.4: the effective scopes of the (unit, table) pair under `echo`: the
855/// scope map as one-element lists plus the fenced lists. `None` when the
856/// fence revoked the pair.
857fn pair_scopes(
858    scopes: &UnitScopes,
859    table: &str,
860    echo: Option<&[EchoRecord]>,
861) -> Option<Vec<(String, Vec<String>)>> {
862    let fenced = echo.and_then(|echo| echo.iter().find(|record| record.table == table));
863    if fenced.is_some_and(|record| record.status == "revoked") {
864        return None;
865    }
866    let mut effective: BTreeMap<String, Vec<String>> = fenced
867        .map(|record| record.scopes.clone())
868        .unwrap_or_default();
869    for (variable, value) in scopes {
870        effective.insert(variable.clone(), vec![value.clone()]);
871    }
872    Some(effective.into_iter().collect())
873}
874
875/// §3.3 row ownership: the pair scopes of every owner of `table` except
876/// `except_id`. An owner is active with a persisted echo and live or
877/// post-bootstrap, or bootstrapping with a segment of the table in its
878/// current bootstrap.
879fn unit_owners(
880    units: &[UnitRecord],
881    table: &TableSchema,
882    except_id: &str,
883) -> Vec<Vec<(String, Vec<String>)>> {
884    units
885        .iter()
886        .filter(|unit| {
887            unit.id != except_id
888                && unit.status == UnitStatus::Active
889                && unit.echo.is_some()
890                && (!unit.bootstrapping() || unit.seeded.contains(&table.name))
891                && covers(table, &unit.scopes)
892        })
893        .filter_map(|unit| pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()))
894        .collect()
895}
896
897/// §5.5 / §5.6: the unit's scope map, each value a one-element list.
898fn unit_scope_lists(scopes: &UnitScopes) -> Vec<(String, Vec<String>)> {
899    scopes
900        .iter()
901        .map(|(variable, value)| (variable.clone(), vec![value.clone()]))
902        .collect()
903}
904
905/// §7.1 acknowledged intent of the rows `?1` names (`[[table, id], ...]`).
906/// It joins through the (tbl, id) index: a scan per acknowledgement would
907/// make draining a batch quadratic.
908const 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";
909
910const UNIT_COLUMNS: &str =
911    "id, scopes, explicit, status, reason_code, cursor, bootstrap_state, seeded, echo";
912
913/// A unit row; a field that does not parse is a conversion failure, which
914/// both read paths classify as `sync.local_corrupt`.
915fn unit_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<UnitRecord> {
916    fn json<T: serde::de::DeserializeOwned>(index: usize, raw: &str) -> rusqlite::Result<T> {
917        serde_json::from_str(raw).map_err(|error| {
918            rusqlite::Error::FromSqlConversionFailure(
919                index,
920                rusqlite::types::Type::Text,
921                Box::new(error),
922            )
923        })
924    }
925    Ok(UnitRecord {
926        id: row.get(0)?,
927        scopes: json(1, &row.get::<_, String>(1)?)?,
928        explicit: row.get::<_, i64>(2)? == 1,
929        status: json(
930            3,
931            &serde_json::to_string(&row.get::<_, String>(3)?).expect("text"),
932        )?,
933        reason_code: row.get(4)?,
934        cursor: row.get(5)?,
935        bootstrap_state: row.get(6)?,
936        seeded: json(7, &row.get::<_, String>(7)?)?,
937        echo: row
938            .get::<_, Option<String>>(8)?
939            .map(|echo| json::<Vec<EchoRecord>>(8, &echo))
940            .transpose()?
941            .map(|echo| {
942                if echo
943                    .iter()
944                    .all(|record| record.status == "active" || record.status == "revoked")
945                {
946                    Ok(echo)
947                } else {
948                    Err(rusqlite::Error::FromSqlConversionFailure(
949                        8,
950                        rusqlite::types::Type::Text,
951                        "echo status is neither active nor revoked".into(),
952                    ))
953                }
954            })
955            .transpose()?,
956    })
957}
958
959/// Every unit in registration order (§4.1).
960fn load_units(conn: &Connection) -> rusqlite::Result<Vec<UnitRecord>> {
961    conn.prepare_cached(&format!(
962        "SELECT {UNIT_COLUMNS} FROM _syncular_units ORDER BY rowid"
963    ))?
964    .query_map([], unit_from_row)?
965    .collect()
966}
967
968fn get_unit(conn: &Connection, id: &str) -> rusqlite::Result<Option<UnitRecord>> {
969    conn.query_row(
970        &format!("SELECT {UNIT_COLUMNS} FROM _syncular_units WHERE id = ?1"),
971        [id],
972        unit_from_row,
973    )
974    .optional()
975}
976
977/// Insert or update in place: an update keeps the registration order.
978fn save_unit(conn: &Connection, unit: &UnitRecord) -> rusqlite::Result<()> {
979    conn.prepare_cached(&format!(
980        "INSERT INTO _syncular_units({UNIT_COLUMNS}) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9)
981         ON CONFLICT(id) DO UPDATE SET explicit=excluded.explicit, status=excluded.status,
982           reason_code=excluded.reason_code, cursor=excluded.cursor,
983           bootstrap_state=excluded.bootstrap_state, seeded=excluded.seeded, echo=excluded.echo"
984    ))?
985    .execute(rusqlite::params![
986        unit.id,
987        serde_json::to_string(&unit.scopes).expect("scope map serializes"),
988        i64::from(unit.explicit),
989        unit.status.name(),
990        unit.reason_code,
991        unit.cursor,
992        unit.bootstrap_state,
993        serde_json::to_string(&unit.seeded).expect("table list serializes"),
994        unit.echo
995            .as_ref()
996            .map(|echo| serde_json::to_string(echo).expect("echo serializes")),
997    ])
998    .map(|_| ())
999}
1000
1001/// §4.1 references: every window registry entry `(base, value)` holding a unit.
1002fn window_refs(conn: &Connection, unit_id: &str) -> rusqlite::Result<Vec<(String, String)>> {
1003    conn.prepare_cached("SELECT base, unit FROM _syncular_windows WHERE sub_id = ?1")?
1004        .query_map([unit_id], |row| Ok((row.get(0)?, row.get(1)?)))?
1005        .collect()
1006}
1007
1008/// §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
1009/// registrations and discard every synced state, so the next round sends the
1010/// list and fresh-bootstraps every unit. The caller owns the transaction.
1011fn reset_units(conn: &Connection) -> rusqlite::Result<()> {
1012    conn.execute_batch(
1013        "UPDATE _syncular_units SET status='active', reason_code=NULL, cursor=-1,
1014           bootstrap_state=NULL, seeded='[]', echo=NULL;
1015         DELETE FROM _syncular_meta WHERE key IN ('replicaCursor','echoDigest','registrationDigest');",
1016    )
1017}
1018
1019/// §4.5: the replica cursor, `-1` while no unit is live.
1020fn replica_cursor(conn: &Connection) -> rusqlite::Result<i64> {
1021    meta_get(conn, REPLICA_CURSOR_KEY)?.map_or(Ok(-1), |raw| {
1022        raw.parse().map_err(|error| {
1023            rusqlite::Error::FromSqlConversionFailure(
1024                0,
1025                rusqlite::types::Type::Text,
1026                Box::new(error),
1027            )
1028        })
1029    })
1030}
1031
1032fn visible_table(name: &str) -> String {
1033    quote_ident(name)
1034}
1035
1036const FTS_SOURCE_ID_COLUMN: &str = "_syncular_source_id";
1037
1038/// §7.4.3: is a `sqlite_master` table name a synced table (visible or base),
1039/// i.e. NOT one of the durable bookkeeping tables the reset preserves?
1040fn is_synced_table_name(name: &str) -> bool {
1041    if name.starts_with("sqlite_") {
1042        return false;
1043    }
1044    if name.starts_with("_syncular_base_") {
1045        return true; // the base half of a synced table pair
1046    }
1047    // Bookkeeping: outbox, units, meta, blob cache/uploads.
1048    !name.starts_with("_syncular_")
1049}
1050
1051/// `"sha256:" + hex` of the bytes — the content address (§5.9.1).
1052fn blob_id_for(bytes: &[u8]) -> String {
1053    let digest = Sha256::digest(bytes);
1054    format!("sha256:{}", bytes_to_hex(&digest))
1055}
1056
1057/// One [`SyncClient::write_row`] bind parameter, borrowing the row-codec
1058/// value it wraps — strings/JSON/bytes bind as borrowed TEXT/BLOB (no copy
1059/// per row on the §5.6 bootstrap path), scalars bind owned.
1060enum RowParam<'a> {
1061    Cell(&'a Option<ColumnValue>),
1062    Version(i64),
1063    Text(Option<&'a str>),
1064}
1065
1066impl rusqlite::ToSql for RowParam<'_> {
1067    fn to_sql(&self) -> rusqlite::Result<ToSqlOutput<'_>> {
1068        Ok(match self {
1069            RowParam::Version(v) => ToSqlOutput::Owned(SqlValue::Integer(*v)),
1070            RowParam::Text(text) => match text {
1071                Some(text) => ToSqlOutput::Borrowed(ValueRef::Text(text.as_bytes())),
1072                None => ToSqlOutput::Owned(SqlValue::Null),
1073            },
1074            RowParam::Cell(cell) => match cell {
1075                None => ToSqlOutput::Owned(SqlValue::Null),
1076                Some(ColumnValue::String(s)) => ToSqlOutput::Borrowed(ValueRef::Text(s.as_bytes())),
1077                Some(ColumnValue::Integer(i)) => ToSqlOutput::Owned(SqlValue::Integer(*i)),
1078                Some(ColumnValue::Float(f)) => ToSqlOutput::Owned(SqlValue::Real(*f)),
1079                Some(ColumnValue::Boolean(b)) => {
1080                    ToSqlOutput::Owned(SqlValue::Integer(i64::from(*b)))
1081                }
1082                Some(ColumnValue::Json(raw)) | Some(ColumnValue::BlobRef(raw)) => {
1083                    ToSqlOutput::Borrowed(ValueRef::Text(raw.0.as_bytes()))
1084                }
1085                // §5.10: crdt bytes store as BLOB, like bytes.
1086                Some(ColumnValue::Bytes(b)) | Some(ColumnValue::Crdt(b)) => {
1087                    ToSqlOutput::Borrowed(ValueRef::Blob(b))
1088                }
1089            },
1090        })
1091    }
1092}
1093
1094// Retain a typed primary key across the current import chunk without copying row payloads.
1095fn owned_sql_value(param: impl rusqlite::ToSql) -> Result<SqlValue, String> {
1096    match param.to_sql().map_err(|error| error.to_string())? {
1097        ToSqlOutput::Owned(value) => Ok(value),
1098        ToSqlOutput::Borrowed(value) => {
1099            SqlValue::try_from(value).map_err(|error| error.to_string())
1100        }
1101        _ => Err("sync.invalid_request: unsupported SQLite key parameter".into()),
1102    }
1103}
1104
1105/// §5.3 image cell → bind parameter, strict per the declared column type
1106/// (`boolean` from INTEGER 0/1, `json` from its raw TEXT, NULL only when
1107/// nullable). Mismatches are image-producer violations. Returns the cell
1108/// borrowed when the stored representation already matches what the row
1109/// codec would write, or the normalized scalar (boolean → 0/1, float from
1110/// INTEGER → REAL) otherwise — the local write is byte-identical to the
1111/// old convert-then-insert path without allocating per cell.
1112fn image_cell_param<'a>(column: &Column, value: ValueRef<'a>) -> Result<ToSqlOutput<'a>, String> {
1113    use ssp2::segment::ColumnType;
1114    let mismatch = || {
1115        Err(format!(
1116            "image column {:?} holds a value of the wrong type",
1117            column.name
1118        ))
1119    };
1120    match value {
1121        ValueRef::Null => {
1122            if !column.nullable {
1123                return Err(format!(
1124                    "image column {:?} is NULL but not nullable",
1125                    column.name
1126                ));
1127            }
1128            Ok(ToSqlOutput::Owned(SqlValue::Null))
1129        }
1130        ValueRef::Integer(i) => match column.ty {
1131            ColumnType::Integer => Ok(ToSqlOutput::Borrowed(value)),
1132            ColumnType::Boolean => Ok(ToSqlOutput::Owned(SqlValue::Integer(i64::from(i != 0)))),
1133            ColumnType::Float => Ok(ToSqlOutput::Owned(SqlValue::Real(i as f64))),
1134            _ => mismatch(),
1135        },
1136        ValueRef::Real(_) => match column.ty {
1137            ColumnType::Float => Ok(ToSqlOutput::Borrowed(value)),
1138            _ => mismatch(),
1139        },
1140        ValueRef::Text(t) => {
1141            std::str::from_utf8(t)
1142                .map_err(|_| format!("image column {:?} is not UTF-8", column.name))?;
1143            match column.ty {
1144                ColumnType::String | ColumnType::Json | ColumnType::BlobRef => {
1145                    Ok(ToSqlOutput::Borrowed(value))
1146                }
1147                _ => mismatch(),
1148            }
1149        }
1150        ValueRef::Blob(_) => match column.ty {
1151            // §5.10: a crdt column stores its opaque bytes as BLOB, like bytes.
1152            ColumnType::Bytes | ColumnType::Crdt => Ok(ToSqlOutput::Borrowed(value)),
1153            _ => mismatch(),
1154        },
1155    }
1156}
1157
1158pub(crate) fn sql_ref_to_json(column: &Column, value: rusqlite::types::ValueRef<'_>) -> Value {
1159    use rusqlite::types::ValueRef;
1160    match value {
1161        ValueRef::Null => Value::Null,
1162        ValueRef::Integer(i) => match column.ty {
1163            ssp2::segment::ColumnType::Boolean => Value::Bool(i != 0),
1164            ssp2::segment::ColumnType::Float => {
1165                serde_json::Number::from_f64(i as f64).map_or(Value::Null, Value::Number)
1166            }
1167            _ => Value::from(i),
1168        },
1169        ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1170        ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1171        ValueRef::Blob(b) => {
1172            let mut map = Map::new();
1173            map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1174            Value::Object(map)
1175        }
1176    }
1177}
1178
1179/// Bind a driver JSON value form as a rusqlite parameter for [`SyncClient::query`].
1180/// Objects are accepted in lossless `{"$bytes": hex}` and
1181/// `{"$bigint": decimal}` envelope forms.
1182fn json_param_to_sql(value: &Value) -> Result<SqlValue, String> {
1183    Ok(match value {
1184        Value::Null => SqlValue::Null,
1185        Value::Bool(b) => SqlValue::Integer(i64::from(*b)),
1186        Value::Number(n) => {
1187            if let Some(i) = n.as_i64() {
1188                SqlValue::Integer(i)
1189            } else if let Some(f) = n.as_f64() {
1190                SqlValue::Real(f)
1191            } else {
1192                return Err(format!("query param number {n} is out of range"));
1193            }
1194        }
1195        Value::String(s) => SqlValue::Text(s.clone()),
1196        Value::Object(_) => {
1197            if let Some(hex) = value.get("$bytes").and_then(Value::as_str) {
1198                SqlValue::Blob(crate::values::hex_to_bytes(hex)?)
1199            } else if let Some(decimal) = value.get("$bigint").and_then(Value::as_str) {
1200                SqlValue::Integer(decimal.parse::<i64>().map_err(|_| {
1201                    format!("query bigint param {decimal:?} is outside SQLite's i64 range")
1202                })?)
1203            } else {
1204                return Err(
1205                    "query object param must be a {$bytes: hex} or {$bigint: decimal} value"
1206                        .to_owned(),
1207                );
1208            }
1209        }
1210        Value::Array(_) => return Err("query array params are not supported".to_owned()),
1211    })
1212}
1213
1214/// Map a rusqlite value with no schema column to consult (arbitrary query
1215/// output): integers/reals/text pass through by stored affinity, blobs ride
1216/// as `{"$bytes": hex}`. Distinct from [`sql_ref_to_json`], which uses the
1217/// schema column type to recover booleans/floats/json.
1218fn sql_ref_to_json_dynamic(value: rusqlite::types::ValueRef<'_>) -> Value {
1219    use rusqlite::types::ValueRef;
1220    match value {
1221        ValueRef::Null => Value::Null,
1222        ValueRef::Integer(i) => {
1223            // JSON/Tauri IPC cannot represent every SQLite i64 exactly. Keep
1224            // ordinary UI-sized integers ergonomic and envelope only values
1225            // beyond JavaScript's safe range.
1226            const MAX_SAFE_INTEGER: i64 = 9_007_199_254_740_991;
1227            if (-MAX_SAFE_INTEGER..=MAX_SAFE_INTEGER).contains(&i) {
1228                Value::from(i)
1229            } else {
1230                let mut map = Map::new();
1231                map.insert("$bigint".to_owned(), Value::from(i.to_string()));
1232                Value::Object(map)
1233            }
1234        }
1235        ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1236        ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1237        ValueRef::Blob(b) => {
1238            let mut map = Map::new();
1239            map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1240            Value::Object(map)
1241        }
1242    }
1243}
1244
1245/// §7.5: SQLite failures classify by result code into [`QueryReadFailure`].
1246fn query_connection(
1247    conn: &Connection,
1248    sql: &str,
1249    params: &[QueryValue],
1250) -> Result<Vec<QueryRow>, QueryReadFailure> {
1251    let lowered_sql = crate::query_guard::lower_public_query_sql(sql);
1252    let mut stmt = crate::query_guard::prepare_read_only(conn, &lowered_sql)?;
1253    let bound: Vec<SqlValue> = params
1254        .iter()
1255        .map(json_param_to_sql)
1256        .collect::<Result<_, _>>()?;
1257    // §2.4: an unaliased physical version column stays engine-internal, so a
1258    // `SELECT *` row feeds straight back into mutation values. An explicit
1259    // alias (`_sync_version AS v`) returns it as ordinary query data. The
1260    // §5.11 sealed columns follow the same rule.
1261    let columns: Vec<(usize, String)> = stmt
1262        .column_names()
1263        .enumerate()
1264        .filter(|(_, name)| {
1265            !matches!(
1266                *name,
1267                "_syncular_version" | "_sync_sealed_key" | "_sync_sealed"
1268            )
1269        })
1270        .map(|(i, name)| (i, name.to_owned()))
1271        .collect();
1272    let bound_refs: Vec<&dyn rusqlite::ToSql> =
1273        bound.iter().map(|v| v as &dyn rusqlite::ToSql).collect();
1274    let mut sql_rows = stmt.query(bound_refs.as_slice())?;
1275    let mut out = Vec::new();
1276    while let Some(row) = sql_rows.next()? {
1277        let mut record = Map::new();
1278        for (i, name) in &columns {
1279            let value = row.get_ref(*i)?;
1280            record.insert(name.clone(), sql_ref_to_json_dynamic(value));
1281        }
1282        out.push(record);
1283    }
1284    Ok(out)
1285}
1286
1287fn persisted_window_state(
1288    conn: &Connection,
1289    base: &WindowBase,
1290) -> Result<WindowState, QueryReadFailure> {
1291    let mut stmt = conn.prepare(
1292        "SELECT windows.unit, units.status, units.cursor, units.bootstrap_state
1293           FROM _syncular_windows AS windows
1294           LEFT JOIN _syncular_units AS units ON units.id = windows.sub_id
1295          WHERE windows.base = ?1
1296          ORDER BY windows.unit ASC",
1297    )?;
1298    let rows = stmt.query_map(rusqlite::params![window_base_key(base)], |row| {
1299        Ok((
1300            row.get::<_, String>(0)?,
1301            row.get::<_, Option<String>>(1)?,
1302            row.get::<_, Option<i64>>(2)?,
1303            row.get::<_, Option<String>>(3)?,
1304        ))
1305    })?;
1306    let mut units = Vec::new();
1307    let mut pending = Vec::new();
1308    for row in rows {
1309        let (unit, status, cursor, bootstrap_state) = row?;
1310        // §4.8: complete iff registered, active and not bootstrapping.
1311        if status.as_deref() != Some("active")
1312            || cursor.is_some_and(|cursor| cursor < 0 || bootstrap_state.is_some())
1313        {
1314            pending.push(unit.clone());
1315        }
1316        units.push(unit);
1317    }
1318    Ok(WindowState { units, pending })
1319}
1320
1321/// One read-only statement in a §7.5 snapshot read.
1322#[derive(Debug, Clone, Copy)]
1323pub struct SnapshotStatement<'a> {
1324    pub sql: &'a str,
1325    pub params: &'a [Value],
1326}
1327
1328/// A §7.5 atomic read request: read-only statements, window coverage, unit
1329/// catch-up states, and commit deliveries, all resolved from one SQLite read
1330/// transaction and one revision.
1331#[derive(Debug, Clone, Default)]
1332pub struct SnapshotReadRequest<'a> {
1333    pub statements: Vec<SnapshotStatement<'a>>,
1334    pub coverage: &'a [WindowCoverage],
1335    pub units: Vec<String>,
1336    pub commit_ids: Vec<String>,
1337}
1338
1339#[cfg(test)]
1340thread_local! {
1341    /// Test-only rendezvous that runs between the statements of one snapshot
1342    /// read. A test uses it to commit on another connection mid-read and prove
1343    /// the read transaction's snapshot and revision stay stable.
1344    static SNAPSHOT_READ_HOOK: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
1345        std::cell::RefCell::new(None);
1346}
1347
1348#[cfg(test)]
1349fn run_snapshot_read_hook() {
1350    SNAPSHOT_READ_HOOK.with(|slot| {
1351        if let Some(hook) = slot.borrow_mut().take() {
1352            hook();
1353        }
1354    });
1355}
1356
1357/// §7.5: resolve a request over one SQLite read transaction. The revision,
1358/// every statement's rows, coverage, catch-up states, and deliveries are
1359/// captured under one `SAVEPOINT`; any statement's failure rolls the whole
1360/// read back and releases the connection.
1361fn snapshot_read_connection(
1362    conn: &Connection,
1363    request: &SnapshotReadRequest<'_>,
1364) -> Result<SnapshotRead, QueryReadFailure> {
1365    conn.execute_batch("SAVEPOINT syncular_snapshot_read")?;
1366    let corrupt = |message: &str| QueryReadFailure {
1367        code: Some("sync.local_corrupt"),
1368        sqlite_code: None,
1369        sqlite_message: None,
1370        rollback_failure: None,
1371        message: message.to_owned(),
1372    };
1373    let stored_failure = |error: rusqlite::Error, message: &str| match error {
1374        rusqlite::Error::Utf8Error(..)
1375        | rusqlite::Error::InvalidColumnType(..)
1376        | rusqlite::Error::FromSqlConversionFailure(..)
1377        | rusqlite::Error::IntegralValueOutOfRange(..) => corrupt(message),
1378        _ => QueryReadFailure::from(error),
1379    };
1380    let result: Result<SnapshotRead, QueryReadFailure> = (|| {
1381        // The durable revision as a canonical decimal `u64`; a missing marker
1382        // is the legacy zero, and any other non-canonical value is corrupt.
1383        let revision: Option<String> = conn
1384            .query_row(
1385                "SELECT value FROM _syncular_meta WHERE key = ?1",
1386                rusqlite::params![LOCAL_REVISION_KEY],
1387                |row| row.get(0),
1388            )
1389            .optional()
1390            .map_err(|error| stored_failure(error, "persisted local revision is invalid"))?;
1391        let revision = match revision {
1392            None => "0".to_owned(),
1393            Some(value)
1394                if value == "0"
1395                    || (matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1396                        && value.bytes().all(|b| b.is_ascii_digit())
1397                        && value.parse::<u64>().is_ok()) =>
1398            {
1399                value
1400            }
1401            Some(_) => return Err(corrupt("persisted local revision is invalid")),
1402        };
1403        let mut queries = Vec::with_capacity(request.statements.len());
1404        for statement in &request.statements {
1405            queries.push(query_connection(conn, statement.sql, statement.params)?);
1406            #[cfg(test)]
1407            run_snapshot_read_hook();
1408        }
1409        let mut pending = Vec::new();
1410        let mut missing = Vec::new();
1411        for requested in request.coverage {
1412            let base_key = window_base_key(&requested.base);
1413            let state = persisted_window_state(conn, &requested.base)?;
1414            for unit in BTreeSet::from_iter(requested.units.iter().cloned()) {
1415                let reference = WindowUnitRef {
1416                    base_key: base_key.clone(),
1417                    unit: unit.clone(),
1418                };
1419                if !state.units.iter().any(|held| held == &unit) {
1420                    missing.push(reference);
1421                } else if state.pending.iter().any(|held| held == &unit) {
1422                    pending.push(reference);
1423                }
1424            }
1425        }
1426        let mut units = Vec::with_capacity(request.units.len());
1427        for id in &request.units {
1428            let exists: bool = conn.query_row(
1429                "SELECT EXISTS(SELECT 1 FROM _syncular_units WHERE id = ?1)",
1430                [id],
1431                |row| row.get(0),
1432            )?;
1433            if !exists {
1434                units.push(UnitCatchup::Unknown { id: id.clone() });
1435                continue;
1436            }
1437            // Every persisted field is required to be well typed; a corrupt
1438            // record fails typed instead of inventing a state.
1439            let unit = get_unit(conn, id)
1440                .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?
1441                .ok_or_else(|| corrupt("persisted unit state is invalid"))?;
1442            let cursor = match unit.cursor {
1443                Some(cursor) => cursor,
1444                None => replica_cursor(conn)
1445                    .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?,
1446            };
1447            if cursor.unsigned_abs() > MAX_JS_SAFE_INTEGER {
1448                return Err(corrupt("persisted unit state is invalid"));
1449            }
1450            let active = unit.status == UnitStatus::Active;
1451            let pending = unit.bootstrapping();
1452            units.push(UnitCatchup::Known {
1453                id: id.clone(),
1454                status: unit.status,
1455                live: unit.cursor.is_none(),
1456                cursor,
1457                has_resume_token: unit.bootstrap_state.is_some(),
1458                bootstrap_complete: active && !pending,
1459                known_pending_pages: active && pending,
1460                reason_code: unit.reason_code,
1461            });
1462        }
1463        let mut deliveries = Vec::with_capacity(request.commit_ids.len());
1464        for id in &request.commit_ids {
1465            let pending: bool = conn.query_row(
1466                "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id = ?1)",
1467                rusqlite::params![id],
1468                |row| row.get(0),
1469            )?;
1470            if pending {
1471                deliveries.push(CommitDelivery::Pending {
1472                    client_commit_id: id.clone(),
1473                });
1474                continue;
1475            }
1476            let row = conn
1477                .query_row(
1478                    "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
1479                            resolution, resolved_at_ms, replacement_client_commit_id
1480                       FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
1481                    rusqlite::params![id],
1482                    StoredCommitOutcomeRow::from_row,
1483                )
1484                .optional()
1485                .map_err(|error| stored_failure(error, "persisted commit outcome is invalid"))?;
1486            deliveries.push(match row {
1487                Some(row) => CommitDelivery::Known {
1488                    client_commit_id: id.clone(),
1489                    outcome: SyncClient::outcome_from_row(row)
1490                        .map_err(|_| corrupt("persisted commit outcome is invalid"))?,
1491                },
1492                None => CommitDelivery::Unknown {
1493                    client_commit_id: id.clone(),
1494                },
1495            });
1496        }
1497        Ok(SnapshotRead {
1498            revision,
1499            queries,
1500            coverage: CoverageSnapshot {
1501                complete: pending.is_empty() && missing.is_empty(),
1502                pending,
1503                missing,
1504            },
1505            units,
1506            deliveries,
1507        })
1508    })();
1509    match result {
1510        Ok(read) => {
1511            conn.execute_batch("RELEASE syncular_snapshot_read")?;
1512            Ok(read)
1513        }
1514        Err(mut error) => {
1515            if let Err(rollback) = conn
1516                .execute_batch("ROLLBACK TO syncular_snapshot_read; RELEASE syncular_snapshot_read")
1517            {
1518                error.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
1519            }
1520            Err(error)
1521        }
1522    }
1523}
1524
1525fn snapshot_connection(
1526    conn: &Connection,
1527    sql: &str,
1528    params: &[Value],
1529    coverage: &[WindowCoverage],
1530) -> Result<QuerySnapshot, QueryReadFailure> {
1531    let read = snapshot_read_connection(
1532        conn,
1533        &SnapshotReadRequest {
1534            statements: vec![SnapshotStatement { sql, params }],
1535            coverage,
1536            units: Vec::new(),
1537            commit_ids: Vec::new(),
1538        },
1539    )?;
1540    Ok(QuerySnapshot {
1541        revision: read.revision,
1542        rows: read
1543            .queries
1544            .into_iter()
1545            .next()
1546            .expect("single-query snapshot returns one result"),
1547        coverage: read.coverage,
1548    })
1549}
1550
1551/// A long-lived read-only SQLite sidecar for latency-critical native views.
1552/// Network rounds stay serialized on the mutable core owner, while atomic
1553/// query snapshots use this independent connection and therefore never queue
1554/// behind HTTP/WebSocket latency.
1555pub struct FileQuerySnapshotReader {
1556    path: String,
1557    conn: Option<Connection>,
1558}
1559
1560impl FileQuerySnapshotReader {
1561    #[must_use]
1562    pub fn new(path: impl Into<String>) -> Self {
1563        Self {
1564            path: path.into(),
1565            conn: None,
1566        }
1567    }
1568
1569    fn connection(&mut self) -> Result<&Connection, QueryReadFailure> {
1570        if self.conn.is_none() {
1571            let conn = Connection::open_with_flags(
1572                &self.path,
1573                OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
1574            )
1575            .map_err(QueryReadFailure::from)?;
1576            conn.busy_timeout(std::time::Duration::from_millis(250))
1577                .map_err(QueryReadFailure::from)?;
1578            self.conn = Some(conn);
1579        }
1580        self.conn
1581            .as_ref()
1582            .ok_or_else(|| QueryReadFailure::from("read sidecar connection missing".to_owned()))
1583    }
1584
1585    /// One atomic read over the shared primitive: every statement, coverage,
1586    /// catch-up, and delivery under one `SAVEPOINT` and one revision.
1587    pub fn snapshot_read(
1588        &mut self,
1589        request: &SnapshotReadRequest<'_>,
1590    ) -> Result<SnapshotRead, QueryReadFailure> {
1591        snapshot_read_connection(self.connection()?, request)
1592    }
1593
1594    /// The current durable local revision. A host can skip a read when it is
1595    /// unchanged; a corrupt or unreadable marker fails typed.
1596    pub fn local_revision(&mut self) -> Result<String, QueryReadFailure> {
1597        Ok(self
1598            .snapshot_read(&SnapshotReadRequest::default())?
1599            .revision)
1600    }
1601
1602    /// One unit's persisted catch-up state (see the §7.5 contract).
1603    pub fn unit_catchup(&mut self, id: &str) -> Result<UnitCatchup, QueryReadFailure> {
1604        let read = self.snapshot_read(&SnapshotReadRequest {
1605            units: vec![id.to_owned()],
1606            ..Default::default()
1607        })?;
1608        Ok(read
1609            .units
1610            .into_iter()
1611            .next()
1612            .expect("one requested catch-up"))
1613    }
1614
1615    /// One client commit's delivery status: pending, its retained outcome, or
1616    /// an explicit unknown (never held, or pruned by retention).
1617    pub fn commit_delivery(&mut self, id: &str) -> Result<CommitDelivery, QueryReadFailure> {
1618        let read = self.snapshot_read(&SnapshotReadRequest {
1619            commit_ids: vec![id.to_owned()],
1620            ..Default::default()
1621        })?;
1622        Ok(read
1623            .deliveries
1624            .into_iter()
1625            .next()
1626            .expect("one requested delivery"))
1627    }
1628
1629    /// Hosts report an owned failure, and the first success after it, to the
1630    /// owning core through [`SyncClient::record_query_read`] (§7.6).
1631    pub fn query_snapshot(
1632        &mut self,
1633        sql: &str,
1634        params: &[Value],
1635        coverage: &[WindowCoverage],
1636    ) -> Result<QuerySnapshot, QueryReadFailure> {
1637        snapshot_connection(self.connection()?, sql, params, coverage)
1638    }
1639}
1640
1641fn validate_authority_reads(
1642    schema: &ClientSchema,
1643    declarations: &[crate::api::AuthorityReadDeclaration],
1644) -> Result<(), String> {
1645    let mut seen = BTreeSet::new();
1646    for read in declarations {
1647        let table = schema
1648            .table(&read.table)
1649            .ok_or("client.authority_read_forbidden: authority table is not declared")?;
1650        let plain = |name: &str| {
1651            table.columns.iter().enumerate().any(|(i, c)| {
1652                c.name == name
1653                    && name != "authority_version"
1654                    && !name.starts_with("_sync")
1655                    && !table.encrypted_columns.iter().any(|e| e.index == i)
1656                    && matches!(
1657                        c.ty,
1658                        ssp2::segment::ColumnType::String
1659                            | ssp2::segment::ColumnType::Integer
1660                            | ssp2::segment::ColumnType::Float
1661                            | ssp2::segment::ColumnType::Boolean
1662                            | ssp2::segment::ColumnType::Json
1663                    )
1664            })
1665        };
1666        if !seen.insert(&read.table)
1667            || read.columns.is_empty()
1668            || read.columns.iter().collect::<BTreeSet<_>>().len() != read.columns.len()
1669            || !read.columns.contains(&table.primary_key)
1670            || !read.columns.iter().all(|c| plain(c))
1671            || read.scopes.is_empty()
1672            || !read.scopes.iter().all(|(v, values)| {
1673                table
1674                    .scope_column(v)
1675                    .is_some_and(|c| read.columns.iter().any(|column| column == c) && plain(c))
1676                    && !values.is_empty()
1677                    && values.iter().all(|v| !v.is_empty() && v != "*")
1678            })
1679        {
1680            return Err("client.authority_read_forbidden: authority reads require plain columns, a primary key and nonempty plain scope selectors".into());
1681        }
1682    }
1683    Ok(())
1684}
1685
1686// §7.4.2: every open and recreation checks before any persistent writes.
1687/// A marker read that hit a recognized SQLite storage failure keeps that
1688/// classification (BUSY/LOCKED stay retryable); only an unclassified read
1689/// failure is the invalid-marker `sync.local_corrupt`.
1690fn schema_marker_read_failure(error: rusqlite::Error) -> String {
1691    let failure = QueryReadFailure::from(error);
1692    if failure.code.is_some() {
1693        failure.to_string()
1694    } else {
1695        "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned()
1696    }
1697}
1698
1699/// §7.1: reject an invalid configured client limit before any storage is
1700/// opened or written. Zero would wedge the push queue and an out-of-range
1701/// value would differ per target; the TS core enforces the same bounds.
1702fn validate_client_limits(limits: &crate::api::ClientLimits) -> Result<(), String> {
1703    if limits.outcome_retention_max_entries == Some(0) {
1704        return Err("sync.invalid_request: outcomeRetentionMaxEntries must be positive".to_owned());
1705    }
1706    if [
1707        limits.max_push_commits_per_request,
1708        limits.max_push_operations_per_request,
1709        limits.max_push_request_bytes,
1710    ]
1711    .into_iter()
1712    .flatten()
1713    .any(|value| value == 0 || value > u32::MAX as usize)
1714    {
1715        return Err(
1716            "sync.invalid_request: push limit must be an integer in 1..=4294967295".to_owned(),
1717        );
1718    }
1719    Ok(())
1720}
1721
1722fn read_local_schema_version(conn: &Connection, requested: i32) -> Result<Option<i32>, String> {
1723    let corrupt =
1724        || "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned();
1725    let table_type: Option<String> = conn
1726        .query_row(
1727            "SELECT type FROM sqlite_master WHERE name = '_syncular_meta'",
1728            [],
1729            |row| row.get(0),
1730        )
1731        .optional()
1732        .map_err(schema_marker_read_failure)?;
1733    let Some(table_type) = table_type else {
1734        return Ok(None);
1735    };
1736    if table_type != "table" {
1737        return Err(corrupt());
1738    }
1739    // §7.4.2: a duplicated marker cannot be resolved. `query_row` would take
1740    // whichever row SQLite returns first, and an older one would drive a
1741    // destructive reset over a newer replica.
1742    let mut statement = conn
1743        .prepare("SELECT value FROM _syncular_meta WHERE key = ?1")
1744        .map_err(schema_marker_read_failure)?;
1745    let mut rows = statement
1746        .query([LOCAL_SCHEMA_VERSION_KEY])
1747        .map_err(schema_marker_read_failure)?;
1748    let value: Option<String> = rows
1749        .next()
1750        .map_err(schema_marker_read_failure)?
1751        .map(|row| row.get(0))
1752        .transpose()
1753        .map_err(schema_marker_read_failure)?;
1754    if rows.next().map_err(schema_marker_read_failure)?.is_some() {
1755        return Err(corrupt());
1756    }
1757    let Some(value) = value else {
1758        let has_descriptor = conn
1759            .query_row(
1760                "SELECT 1 FROM _syncular_meta WHERE key = ?1 LIMIT 1",
1761                [crate::previous_version::LOCAL_SCHEMA_DESCRIPTOR_KEY],
1762                |_| Ok(()),
1763            )
1764            .optional()
1765            .map_err(schema_marker_read_failure)?
1766            .is_some();
1767        if has_descriptor {
1768            return Err(corrupt());
1769        }
1770        return Ok(None);
1771    };
1772    if !matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1773        || !value.bytes().all(|b| b.is_ascii_digit())
1774    {
1775        return Err(corrupt());
1776    }
1777    let version = value.parse::<i32>().map_err(|_| corrupt())?;
1778    if version > requested {
1779        return Err(
1780            "client.schema_downgrade: persisted local schema is newer than the requested schema"
1781                .to_owned(),
1782        );
1783    }
1784    Ok(Some(version))
1785}
1786
1787/// A file replica on a browser worker must recover a hot journal before any
1788/// statement reads it. `wasm_vfs` replaces the installed OPFS VFS's reserved
1789/// lock callback, so install it before the connection opens its file.
1790#[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
1791fn prepare_wasm_replica(path: &str) -> Result<(), String> {
1792    if path.is_empty() || path == ":memory:" {
1793        return Ok(());
1794    }
1795    crate::wasm_vfs::disable_foreign_lock_check()
1796}
1797
1798#[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
1799fn prepare_wasm_replica(_path: &str) -> Result<(), String> {
1800    Ok(())
1801}
1802
1803impl SyncClient {
1804    pub fn new_with_identity(
1805        client_id: Option<String>,
1806        schema_json: &Value,
1807        limits: ClientLimits,
1808    ) -> Result<Self, String> {
1809        let resolved = client_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
1810        let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1811        Self::with_connection(resolved, schema_json, limits, conn)
1812    }
1813
1814    pub fn new(
1815        client_id: String,
1816        schema_json: &Value,
1817        limits: ClientLimits,
1818    ) -> Result<Self, String> {
1819        let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1820        Self::with_connection(client_id, schema_json, limits, conn)
1821    }
1822
1823    /// Build a client backed by an on-disk SQLite database at `path` — the
1824    /// seam a native host (Tauri plugin, FFI file-DB variant) uses to persist
1825    /// across process restarts. `create_tables` runs `IF NOT EXISTS`, so
1826    /// re-opening the same file reuses the persisted rows. Keeps rusqlite out
1827    /// of the command router's dependency set (the router only holds a path).
1828    pub fn open_path(
1829        client_id: String,
1830        schema_json: &Value,
1831        limits: ClientLimits,
1832        path: &str,
1833    ) -> Result<Self, String> {
1834        validate_client_limits(&limits)?;
1835        parse_schema_json(schema_json)?;
1836        prepare_wasm_replica(path)?;
1837        let conn = Connection::open(path).map_err(|e| format!("open db {path:?}: {e}"))?;
1838        Self::with_connection(client_id, schema_json, limits, conn)
1839    }
1840
1841    /// Open a file replica and resolve its client id. Native targets require
1842    /// WAL for the independent snapshot reader; `wasm32-unknown-unknown`
1843    /// accepts the sqlite-wasm worker journal instead.
1844    pub fn open_path_with_identity(
1845        client_id: Option<String>,
1846        schema_json: &Value,
1847        limits: ClientLimits,
1848        path: &str,
1849    ) -> Result<Self, String> {
1850        Self::open_path_with_identity_journal(
1851            client_id,
1852            schema_json,
1853            limits,
1854            path,
1855            !cfg!(all(target_arch = "wasm32", target_os = "unknown")),
1856        )
1857    }
1858
1859    fn open_path_with_identity_journal(
1860        client_id: Option<String>,
1861        schema_json: &Value,
1862        limits: ClientLimits,
1863        path: &str,
1864        require_wal: bool,
1865    ) -> Result<Self, String> {
1866        validate_client_limits(&limits)?;
1867        // §7.4.2: an invalid requested version is refused before the replica is
1868        // even created, so a rejected constructor leaves no file behind.
1869        parse_schema_json(schema_json)?;
1870        prepare_wasm_replica(path)?;
1871        let conn = Connection::open(path).map_err(|e| format!("open db {path:?}: {e}"))?;
1872        // A file-backed native client uses an independent read connection for
1873        // latency-critical snapshots. WAL is SQLite's intended reader/writer
1874        // concurrency mode: a view read never holds a rollback-journal lock
1875        // that delays the client's next commit. The busy timeout must precede
1876        // this replica's own startup transaction; WAL is applied only after
1877        // startup succeeded, because a refused open must leave the replica's
1878        // journal mode and contents untouched (§7.4.2).
1879        conn.busy_timeout(std::time::Duration::from_millis(250))
1880            .map_err(|error| format!("configure db {path:?} busy timeout: {error}"))?;
1881        // Durability is the caller's contract here, not the VFS default: a
1882        // rollback-journal commit needs FULL before it writes the database
1883        // pages, or a killed worker can leave a half-written image behind.
1884        // WAL below inherits the same setting.
1885        conn.pragma_update(None, "synchronous", "FULL")
1886            .map_err(|error| format!("configure db {path:?} synchronous: {error}"))?;
1887        let client = Self::with_connection_identity(client_id, schema_json, limits, conn)?;
1888        // A browser worker's sqlite-wasm VFS has no WAL mode, and the wasm
1889        // host has no independent snapshot reader. The WAL requirement exists
1890        // for native file replicas, where it is the reader/writer boundary.
1891        if require_wal {
1892            let journal_mode: String = client
1893                .conn
1894                .pragma_update_and_check(None, "journal_mode", "WAL", |row| row.get(0))
1895                .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
1896            if journal_mode != "wal" {
1897                return Err(
1898                    "sync.invalid_request: file-backed client requires WAL journal mode".to_owned(),
1899                );
1900            }
1901        }
1902        Ok(client)
1903    }
1904
1905    /// Delete a file replica at `path`, including its `-journal`, `-wal`, and
1906    /// `-shm` sidecars, through the VFS that owns it. Use this after
1907    /// `client.storage_corrupt`: an OPFS SAH pool stores those files under
1908    /// opaque names, so deleting the pool directory behind SQLite bypasses the
1909    /// pool's slot accounting.
1910    ///
1911    /// Close the client and every [`FileQuerySnapshotReader`] on `path` first;
1912    /// a VFS cannot delete a file another handle still owns. A file that does
1913    /// not exist counts as deleted, so a cleanly closed replica without
1914    /// sidecars resets. The next open
1915    /// creates a fresh replica (new client id) and re-bootstraps from the
1916    /// server. A memory replica has nothing to delete and fails with
1917    /// `sync.invalid_request`.
1918    pub fn reset_replica(path: &str) -> Result<(), String> {
1919        if path.is_empty() || path == ":memory:" {
1920            return Err("sync.invalid_request: a memory replica has nothing to reset".to_owned());
1921        }
1922        // SAFETY: a null VFS name asks SQLite for its process-wide default VFS,
1923        // the same one `Connection::open(path)` above selects. `xDelete` is
1924        // that VFS's own function pointer, and `c_name` outlives the call.
1925        let vfs = unsafe { rusqlite::ffi::sqlite3_vfs_find(std::ptr::null()) };
1926        if vfs.is_null() {
1927            return Err("client.storage_io: no SQLite VFS is registered".to_owned());
1928        }
1929        let delete = unsafe { (*vfs).xDelete }
1930            .ok_or_else(|| "client.storage_io: the SQLite VFS cannot delete files".to_owned())?;
1931        for suffix in ["-wal", "-shm", "-journal", ""] {
1932            let file_name = format!("{path}{suffix}");
1933            let c_name = std::ffi::CString::new(file_name.as_str()).map_err(|_| {
1934                format!("sync.invalid_request: replica path {file_name:?} contains a NUL byte")
1935            })?;
1936            // SAFETY: `vfs` and its `xDelete` pointer come from the live
1937            // SQLite library; `c_name` is a valid NUL-terminated path.
1938            let code = unsafe { delete(vfs, c_name.as_ptr(), 1) };
1939            // A cleanly closed WAL replica has no sidecars; a missing file is
1940            // already deleted.
1941            if code != rusqlite::ffi::SQLITE_OK && code != rusqlite::ffi::SQLITE_IOERR_DELETE_NOENT
1942            {
1943                return Err(format!(
1944                    "client.storage_io: deleting replica file {file_name:?} failed with SQLite code {code}"
1945                ));
1946            }
1947        }
1948        Ok(())
1949    }
1950
1951    #[must_use]
1952    pub fn client_id(&self) -> &str {
1953        &self.client_id
1954    }
1955
1956    /// Rotate the caller's client id (§1.5) and return the new one. Use it
1957    /// after a `sync.invalid_client_id` refusal (`recommendedAction:
1958    /// resetClientId`): the next round carries the new id. A live realtime
1959    /// socket is closed so the next connection registers with the new id.
1960    /// The replica and its outbox stay in place; wipe them yourself when the
1961    /// stored data belongs to the account that signed out.
1962    pub fn reset_client_id(&mut self, transport: &mut dyn Transport) -> Result<String, String> {
1963        self.disconnect_realtime(transport);
1964        let client_id = uuid::Uuid::new_v4().to_string();
1965        self.set_meta(CLIENT_ID_KEY, &client_id)?;
1966        self.client_id.clone_from(&client_id);
1967        self.round_failure = None;
1968        Ok(client_id)
1969    }
1970
1971    /// Build a client over a caller-supplied rusqlite connection — the seam a
1972    /// native host (Tauri plugin, FFI file-DB variant) uses to back the core
1973    /// with an on-disk database (`Connection::open(path)`) rather than the
1974    /// default `:memory:`. The connection MUST be fresh (no pre-existing
1975    /// syncular tables); `create_tables` runs `IF NOT EXISTS`, so re-opening
1976    /// the same file across process restarts reuses the persisted rows.
1977    pub fn with_connection(
1978        client_id: String,
1979        schema_json: &Value,
1980        limits: ClientLimits,
1981        conn: Connection,
1982    ) -> Result<Self, String> {
1983        Self::with_connection_identity(Some(client_id), schema_json, limits, conn)
1984    }
1985
1986    /// [`Self::with_connection`] for `open_path_with_identity`: no requested id
1987    /// means a durable replica's persisted `clientId` wins over a fresh one.
1988    fn with_connection_identity(
1989        client_id: Option<String>,
1990        schema_json: &Value,
1991        limits: ClientLimits,
1992        conn: Connection,
1993    ) -> Result<Self, String> {
1994        validate_client_limits(&limits)?;
1995        let schema = parse_schema_json(schema_json)?;
1996        validate_authority_reads(&schema, &limits.authority_reads)?;
1997        // RFC 0005 D8: resolve the previous-version config before the opening
1998        // reset runs — the capture happens inside it. Bad bounds fail loud.
1999        let previous_version = match limits.previous_version_context {
2000            Some(config) => {
2001                config.validate()?;
2002                Some(config)
2003            }
2004            None => None,
2005        };
2006        let mut client = SyncClient {
2007            #[cfg(feature = "bench-internals")]
2008            benchmark_phases: Recorder::default(),
2009            conn,
2010            schema,
2011            client_id: client_id
2012                .clone()
2013                .unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
2014            limits,
2015            outbox: Shared::default(),
2016            failed_commits: Shared::default(),
2017            retain_failed_commits: false,
2018            conflicts: Shared::default(),
2019            rejections: Shared::default(),
2020            schema_floor: None,
2021            lease_state: None,
2022            stopped: false,
2023            upgrading: false,
2024            sync_needed: false,
2025            realtime_policy: RealtimePolicy::Optional,
2026            realtime_state: RealtimeState::Disconnected,
2027            realtime_reason_code: None,
2028            realtime_retry_delay_ms: None,
2029            presence: HashMap::new(),
2030            now_ms: None,
2031            encryption: crate::values::EncryptionConfig::default(),
2032            security_preflight: false,
2033            security_epoch: 0,
2034            transport_enabled: true,
2035            transport_epoch: 0,
2036            registration_epoch: 0,
2037            previous_version,
2038            insert_sql: RefCell::new(HashMap::new()),
2039            overlay_dirty: OverlayDirty::clean(),
2040            storage_failure: RefCell::new(None),
2041            #[cfg(test)]
2042            overlay_rebuild_count: Cell::new(0),
2043            #[cfg(test)]
2044            acknowledged_replay_count: Cell::new(0),
2045            #[cfg(test)]
2046            outcome_prune_count: Cell::new(0),
2047            #[cfg(test)]
2048            image_chunk_ms: Cell::new(None),
2049            progress: ProgressObserver::default(),
2050            change_queue: VecDeque::new(),
2051            sync_intent_queue: VecDeque::new(),
2052            retry_delay_ms: 250,
2053            round_retry_delay_ms: None,
2054            applied_segments: HashMap::new(),
2055            image_chunk_rows: HashMap::new(),
2056            round_failure: None,
2057            active_round: None,
2058            last_round: None,
2059            last_change: None,
2060            query_failures: Vec::new(),
2061            coalesced: None,
2062            coalesced_failure: None,
2063        };
2064        // The row write path leans on the prepared-statement cache (two
2065        // insert statements per synced table, plus the bookkeeping
2066        // statements); size it so a multi-table schema never thrashes.
2067        client
2068            .conn
2069            .set_prepared_statement_cache_capacity(64.max(client.schema.tables.len() * 4));
2070        // §7.4.2: one write transaction (SQLite `BEGIN IMMEDIATE`, a reserved
2071        // writer) covers the marker read, the identity check, and every
2072        // bookkeeping/schema write, so a concurrent open that upgraded the
2073        // replica cannot interleave between the guard and the writes, and a
2074        // refusal leaves the replica unchanged.
2075        client
2076            .conn
2077            .execute_batch("BEGIN IMMEDIATE")
2078            .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2079        let startup = (|| -> Result<(), String> {
2080            // The marker guard runs inside the write transaction, so the version
2081            // it validates is the version every write below commits under.
2082            let marker = read_local_schema_version(&client.conn, client.schema.version)?;
2083            // New app indexes may reference columns that only exist after a
2084            // version-bump reset.
2085            client.create_bookkeeping_tables()?;
2086            match client.get_meta(CLIENT_ID_KEY)? {
2087                Some(existing) => match client_id {
2088                    Some(requested) if existing != requested => {
2089                        return Err(format!(
2090                            "client.identity_mismatch: this database belongs to {existing:?}; refusing to rebind it to {requested:?}"
2091                        ))
2092                    }
2093                    _ => client.client_id = existing,
2094                },
2095                None => client.set_meta(CLIENT_ID_KEY, &client.client_id)?,
2096            }
2097            client.restore_persisted_state()?;
2098            client.failed_commits = client.load_failed_commits()?.into();
2099            match marker {
2100                None => {
2101                    client.create_synced_tables()?;
2102                    client.persist_schema_version()?;
2103                    client.save_unit_scope_schema()?;
2104                }
2105                Some(version) if version == client.schema.version => {
2106                    client.create_synced_tables()?;
2107                    // RFC 0005 D1: the same-version open backfills the descriptor
2108                    // for a database first opened by an unaware binary, so the
2109                    // NEXT bump can capture without needing a schema bump first.
2110                    set_local_schema_descriptor(&client.conn, &client.schema)
2111                        .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2112                    client.save_unit_scope_schema()?;
2113                }
2114                Some(_) => client.run_schema_reset()?,
2115            }
2116            // RFC 0005 D9: the reset sweep cannot see a container whose capture
2117            // committed in its OWN file while the replica's savepoint never
2118            // released — a crash at that seam leaves a container beside a matching
2119            // OLD marker, and the next open at that version runs no reset. Discard
2120            // it before anything can read it. No-op when no container exists.
2121            client.reconcile_previous_version_at_boot()?;
2122            client.clear_satisfied_persisted_schema_floor()?;
2123            client.prune_unknown_units(false)?;
2124            // §7.1/§7.4.4: recover intrinsically codec-invalid persisted values at
2125            // the full startup/reset reconciliation boundary, inside this open
2126            // transaction and after the schema and identity guards, so a commit
2127            // an earlier version accepted is dropped with durable rejection
2128            // evidence before any replay. A table the current schema removed
2129            // keeps the §7.4.4 send-time classification, and an unresolved
2130            // encryption key stays with the send seam because hosts configure
2131            // keys after open.
2132            client.drop_unencodable_outbox(false, None)?;
2133            if marker == Some(client.schema.version)
2134                && (!client.outbox.is_empty()
2135                    || !client.failed_commits.is_empty()
2136                    || client.has_acknowledged_rows()?)
2137            {
2138                // Reconstruct the visible optimistic overlay from the durable
2139                // base plus outbox instead of trusting a process-interrupted
2140                // mirror.
2141                client.overlay_dirty.set(true);
2142                client.rebuild_overlay()?;
2143            }
2144            // Every persisted active unit needs one catch-up pull on
2145            // open: realtime only covers changes after connection, while an
2146            // idempotent setWindow correctly creates no fresh command effect.
2147            // Pending outbox work has the same restart requirement. The core
2148            // owns this intent so native hosts never poll or require an
2149            // application-issued sync().
2150            client.enqueue_startup_sync_if_needed()?;
2151            Ok(())
2152        })();
2153        match startup {
2154            Ok(()) => match client.conn.execute_batch("COMMIT") {
2155                // §4.8: an eviction a crash interrupted finishes before any
2156                // read, with or without a transport; a replica reopened in
2157                // preflight finishes it at activation.
2158                Ok(()) => {
2159                    if !client.security_preflight {
2160                        client.drain_pending_evictions()?;
2161                    }
2162                    Ok(client)
2163                }
2164                Err(error) => {
2165                    let failure = Self::sqlite_failure(&client.storage_failure, error);
2166                    if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2167                        // Keep a failed rollback's typed storage classification.
2168                        let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2169                    }
2170                    Err(failure)
2171                }
2172            },
2173            Err(error) => {
2174                if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2175                    // Keep a failed rollback's typed storage classification.
2176                    let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2177                }
2178                Err(error)
2179            }
2180        }
2181    }
2182
2183    /// Pin the client clock (epoch ms) — the §5.4 expiry check runs
2184    /// against this instead of system time (conformance virtual clock).
2185    pub fn set_now_ms(&mut self, now_ms: i64) {
2186        self.now_ms = Some(now_ms);
2187    }
2188
2189    /// §5.11: install the client-side encryption keys (`keyId → key bytes`).
2190    /// The command router parses these from the `create` command's
2191    /// `encryption` config (keys as `{$bytes: hex}`).
2192    pub fn set_encryption(&mut self, encryption: crate::values::EncryptionConfig) {
2193        self.encryption = encryption;
2194    }
2195
2196    #[must_use]
2197    pub fn security_lifecycle(&self) -> &'static str {
2198        if self.security_preflight {
2199            "preflight"
2200        } else {
2201            "active"
2202        }
2203    }
2204
2205    #[must_use]
2206    pub fn security_preflight(&self) -> bool {
2207        self.security_preflight
2208    }
2209
2210    /// Host-owned, non-persisted network gate. Local operations remain available.
2211    pub fn set_transport_enabled(&mut self, transport: &mut dyn Transport, enabled: bool) {
2212        if self.transport_enabled != enabled {
2213            self.transport_enabled = enabled;
2214            self.transport_epoch = self.transport_epoch.wrapping_add(1);
2215            self.sync_intent_queue.clear();
2216            self.sync_intent_queue
2217                .push_back(if enabled && !self.security_preflight {
2218                    SyncIntent::Interactive
2219                } else {
2220                    SyncIntent::None
2221                });
2222        }
2223        // A captured reply keeps its normal apply/revocation semantics.
2224        if !enabled && self.active_round.is_none() {
2225            self.disconnect_realtime(transport);
2226        }
2227    }
2228
2229    pub fn transport_enabled(&self) -> bool {
2230        self.transport_enabled
2231    }
2232
2233    /// Quarantine this replica: enter the fail-closed gate, release all
2234    /// core-owned key material, and record the gate in the database so
2235    /// reopening re-enters preflight until `activate_security` clears it.
2236    ///
2237    /// Use [`SyncClient::seal_security_on_teardown`] for the shutdown barrier,
2238    /// which must NOT leave that durable mark.
2239    pub fn begin_security_preflight(&mut self) -> Result<(), String> {
2240        let entering = !self.security_preflight;
2241        self.seal_security_on_teardown();
2242        // Persist the quarantine so it survives handle teardown and restart:
2243        // reopening this replica re-enters preflight until activation clears it.
2244        self.set_meta(SECURITY_PREFLIGHT_PENDING_KEY, "1")?;
2245        if entering {
2246            self.emit_status_batch()?;
2247        }
2248        Ok(())
2249    }
2250
2251    /// One change batch carrying the status snapshot (§5.11 lifecycle).
2252    fn emit_status_batch(&mut self) -> Result<(), String> {
2253        self.begin_observation("syncular_status")?;
2254        let batch = ChangeAccumulator {
2255            status: true,
2256            ..ChangeAccumulator::default()
2257        };
2258        self.finish_observation("syncular_status", batch)
2259            .inspect_err(|_| self.rollback_observation("syncular_status"))
2260    }
2261
2262    /// Release core-owned key material as a host tears the client down,
2263    /// WITHOUT recording a quarantine.
2264    ///
2265    /// Shutting an activated client down is not a quarantine event. Persisting
2266    /// the gate here marks every cleanly closed replica as pending, and the
2267    /// next plain `create` is then refused permanently: the reopen path
2268    /// restores the flag from the marker and the create guard rejects it. The
2269    /// in-memory flag still closes the gate for anything still holding this
2270    /// instance, which is all a teardown barrier needs.
2271    pub fn seal_security_on_teardown(&mut self) {
2272        self.cancel_sync_round();
2273        self.security_preflight = true;
2274        self.security_epoch = self.security_epoch.wrapping_add(1);
2275        self.encryption = crate::values::EncryptionConfig::default();
2276        self.sync_intent_queue.clear();
2277    }
2278
2279    /// Install the post-authentication keyring and release the host loop.
2280    pub fn activate_security(
2281        &mut self,
2282        encryption: crate::values::EncryptionConfig,
2283    ) -> Result<(), String> {
2284        if !self.security_preflight {
2285            return Err(
2286                "sync.invalid_request: activateSecurity requires security preflight".to_owned(),
2287            );
2288        }
2289        // §4.8: an interrupted eviction finishes before protected reads open.
2290        self.drain_pending_evictions()?;
2291        self.enqueue_startup_sync_if_needed()?;
2292        self.delete_meta(SECURITY_PREFLIGHT_PENDING_KEY)?;
2293        self.encryption = encryption;
2294        self.security_preflight = false;
2295        // §5.11: rows sealed under a key this keyring now holds open at once.
2296        self.reveal_sealed_rows()
2297            .map_err(|error| format!("{}: {}", error.code, error.message))?;
2298        self.emit_status_batch()
2299    }
2300
2301    fn clock_now_ms(&self) -> i64 {
2302        self.now_ms.unwrap_or_else(crate::wall_clock_ms)
2303    }
2304
2305    fn create_bookkeeping_tables(&self) -> Result<(), String> {
2306        let exists = |name: &str| {
2307            self.conn
2308                .query_row(
2309                    "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1)",
2310                    [name],
2311                    |row| row.get::<_, bool>(0),
2312                )
2313                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2314        };
2315        let outbox_existed = exists("_syncular_outbox")?;
2316        // Durable client bookkeeping (outbox + units + meta).
2317        self.conn
2318            .execute_batch(
2319                "CREATE TABLE IF NOT EXISTS _syncular_outbox (
2320                   seq INTEGER PRIMARY KEY AUTOINCREMENT,
2321                   commit_id TEXT NOT NULL UNIQUE, ops_json TEXT NOT NULL);
2322                 CREATE TABLE IF NOT EXISTS _syncular_row_deliveries (
2323                   tbl TEXT NOT NULL, id TEXT NOT NULL, commit_seq INTEGER NOT NULL, PRIMARY KEY(tbl,id));
2324                 CREATE TABLE IF NOT EXISTS _syncular_acked_rows (
2325                   commit_id TEXT NOT NULL, idx INTEGER NOT NULL, tbl TEXT NOT NULL, id TEXT NOT NULL,
2326                   commit_seq INTEGER NOT NULL, op_json TEXT NOT NULL, intent_json TEXT,
2327                   PRIMARY KEY(commit_id, idx));
2328                 CREATE INDEX IF NOT EXISTS _syncular_acked_rows_row
2329                   ON _syncular_acked_rows(tbl, id);
2330                 CREATE TABLE IF NOT EXISTS _syncular_failed_commits (
2331                   seq INTEGER PRIMARY KEY AUTOINCREMENT, client_commit_id TEXT NOT NULL UNIQUE,
2332                   operations_json TEXT NOT NULL, initial_json TEXT NOT NULL);
2333                 CREATE TABLE IF NOT EXISTS _syncular_commit_outcomes (
2334                   seq INTEGER PRIMARY KEY AUTOINCREMENT,
2335                   client_commit_id TEXT NOT NULL UNIQUE,
2336                   status TEXT NOT NULL CHECK(status IN ('applied', 'cached', 'conflict', 'rejected')),
2337                   recorded_at_ms INTEGER NOT NULL,
2338                   results_json TEXT NOT NULL,
2339                   operations_json TEXT,
2340                   resolution TEXT NOT NULL DEFAULT 'active'
2341                     CHECK(resolution IN ('active', 'resolved_keep_server', 'superseded', 'dismissed')),
2342                   resolved_at_ms INTEGER,
2343                   replacement_client_commit_id TEXT);
2344                 CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq
2345                   ON _syncular_commit_outcomes(resolution, seq);
2346                 CREATE TABLE IF NOT EXISTS _syncular_units (
2347                   id TEXT PRIMARY KEY, scopes TEXT NOT NULL,
2348                   explicit INTEGER NOT NULL DEFAULT 0,
2349                   status TEXT NOT NULL DEFAULT 'active', reason_code TEXT,
2350                   cursor INTEGER DEFAULT -1, bootstrap_state TEXT,
2351                   seeded TEXT NOT NULL DEFAULT '[]', echo TEXT);
2352                 CREATE TABLE IF NOT EXISTS _syncular_meta (
2353                   key TEXT PRIMARY KEY, value TEXT NOT NULL);
2354                 CREATE TABLE IF NOT EXISTS _syncular_windows (
2355                   base TEXT NOT NULL, unit TEXT NOT NULL, sub_id TEXT NOT NULL,
2356                   PRIMARY KEY (base, unit));
2357                 CREATE INDEX IF NOT EXISTS _syncular_windows_unit ON _syncular_windows(sub_id);
2358                 CREATE TABLE IF NOT EXISTS _syncular_pending_evictions (
2359                   unit_id TEXT NOT NULL, tbl TEXT NOT NULL,
2360                   effective_scopes TEXT NOT NULL, PRIMARY KEY (unit_id, tbl));
2361                 CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
2362                   commit_id TEXT NOT NULL, blob_id TEXT NOT NULL,
2363                   PRIMARY KEY(commit_id, blob_id));
2364                 CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body
2365                   ON _syncular_blob_commit_refs(blob_id);",
2366            )
2367            .map_err(|e| e.to_string())?;
2368        // Migrate an outcome journal created before failed aggregate
2369        // envelopes were retained. Historical rows intentionally stay NULL.
2370        let _ = self
2371            .conn
2372            .execute_batch("ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations_json TEXT");
2373        if self.get_meta(LOCAL_REVISION_KEY)?.is_none() {
2374            self.set_meta(LOCAL_REVISION_KEY, "0")?;
2375        }
2376        // §7.1: `outboxId` names the outbox sequence. A new outbox table starts
2377        // a new sequence, so it replaces the id in the same transaction.
2378        if !outbox_existed || self.get_meta(OUTBOX_ID_KEY)?.is_none() {
2379            self.set_meta(OUTBOX_ID_KEY, &uuid::Uuid::new_v4().to_string())?;
2380        }
2381        // §9: a replica written under wire version 3 keeps its outbox, journal,
2382        // rows and pending evictions and registers its units fresh. Its
2383        // subscriptions, cursors, echoes, resume tokens and window entries go;
2384        // units left from an earlier version 4 life restart.
2385        if exists("_syncular_window_pending_evict")? {
2386            let invalid: bool = self
2387                .conn
2388                .query_row(
2389                    "SELECT EXISTS(SELECT 1 FROM _syncular_window_pending_evict
2390                       WHERE NOT json_valid(effective_scopes)
2391                          OR json_type(effective_scopes) <> 'object'
2392                          OR EXISTS(SELECT 1 FROM json_each(effective_scopes)
2393                               WHERE type <> 'array'
2394                                  OR EXISTS(SELECT 1 FROM json_each(value) AS v
2395                                       WHERE v.type <> 'text')))",
2396                    [],
2397                    |row| row.get(0),
2398                )
2399                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2400            if invalid {
2401                return Err(
2402                    "sync.local_corrupt: a version 3 pending eviction cannot be upgraded"
2403                        .to_owned(),
2404                );
2405            }
2406            self.conn
2407                .execute_batch(
2408                    "INSERT OR REPLACE INTO _syncular_pending_evictions
2409                       SELECT sub_id, tbl, effective_scopes FROM _syncular_window_pending_evict;
2410                     DROP TABLE _syncular_window_pending_evict;
2411                     DROP TABLE IF EXISTS _syncular_subscriptions;
2412                     DELETE FROM _syncular_windows;",
2413                )
2414                .and_then(|()| reset_units(&self.conn))
2415                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2416        }
2417        // §5.9.7 blob cache. Mutable upload state stays off the body row so
2418        // completing a large upload does not rewrite its BLOB record.
2419        if self.schema_has_blobs() {
2420            if exists("_syncular_blobs")? {
2421                let mut statement = self
2422                    .conn
2423                    .prepare("PRAGMA table_info(_syncular_blobs)")
2424                    .map_err(|e| e.to_string())?;
2425                let mut columns = statement
2426                    .query_map([], |row| row.get::<_, String>(1))
2427                    .map_err(|e| e.to_string())?
2428                    .collect::<Result<Vec<_>, _>>()
2429                    .map_err(|e| e.to_string())?;
2430                columns.sort();
2431                let mut expected = vec![
2432                    "blob_id",
2433                    "byte_length",
2434                    "bytes",
2435                    "created_at_ms",
2436                    "media_type",
2437                ];
2438                expected.sort_unstable();
2439                if columns != expected {
2440                    return Err(
2441                        "sync.schema_mismatch: Local blob schema is incompatible".to_owned()
2442                    );
2443                }
2444            } else {
2445                self.conn
2446                    .execute_batch(
2447                        "CREATE TABLE _syncular_blobs(
2448                           blob_id TEXT PRIMARY KEY,
2449                           bytes BLOB NOT NULL,
2450                           byte_length INTEGER NOT NULL,
2451                           media_type TEXT,
2452                           created_at_ms INTEGER NOT NULL);",
2453                    )
2454                    .map_err(|e| e.to_string())?;
2455            }
2456            self.conn
2457                .execute_batch(
2458                    "CREATE TABLE IF NOT EXISTS _syncular_blob_uploads(
2459                       blob_id TEXT PRIMARY KEY,
2460                       media_type TEXT,
2461                       created_at_ms INTEGER NOT NULL);",
2462                )
2463                .map_err(|e| e.to_string())?;
2464        }
2465        Ok(())
2466    }
2467
2468    /// True iff any synced table declares a `blob_ref` column (§5.9).
2469    fn schema_has_blobs(&self) -> bool {
2470        self.schema
2471            .tables
2472            .iter()
2473            .any(|t| t.columns.iter().any(|c| c.ty == ColumnType::BlobRef))
2474    }
2475
2476    // -- meta (§7.4.1 marker, bookkeeping) ------------------------------------
2477
2478    fn get_meta(&self, key: &str) -> Result<Option<String>, String> {
2479        meta_get(&self.conn, key)
2480            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2481    }
2482
2483    // The caller holds the startup/reset transaction. Either both schema
2484    // records persist or the enclosing operation fails and rolls back.
2485    fn persist_schema_version(&self) -> Result<(), String> {
2486        self.conn
2487            .execute(
2488                "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
2489                rusqlite::params![LOCAL_SCHEMA_VERSION_KEY, self.schema.version.to_string()],
2490            )
2491            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2492        set_local_schema_descriptor(&self.conn, &self.schema)
2493            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2494    }
2495
2496    pub(crate) fn set_meta(&self, key: &str, value: &str) -> Result<(), String> {
2497        meta_set(&self.conn, key, value)
2498            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2499    }
2500
2501    fn delete_meta(&self, key: &str) -> Result<(), String> {
2502        meta_delete(&self.conn, key)
2503            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2504    }
2505
2506    /// §7.1: the durable outbox in FIFO order, in schema-agnostic local form.
2507    fn load_outbox(&self) -> Result<Vec<Arc<OutboxCommit>>, String> {
2508        let mut stmt = self
2509            .conn
2510            .prepare("SELECT commit_id, ops_json FROM _syncular_outbox ORDER BY seq ASC")
2511            .map_err(|error| error.to_string())?;
2512        let rows = stmt
2513            .query_map([], |row| {
2514                Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
2515            })
2516            .map_err(|error| error.to_string())?;
2517        let mut commits = Vec::new();
2518        for row in rows {
2519            let (client_commit_id, raw) = row.map_err(|error| error.to_string())?;
2520            let entries: Vec<Value> = serde_json::from_str(&raw).map_err(|error| {
2521                format!("invalid persisted outbox {client_commit_id:?}: {error}")
2522            })?;
2523            let mut ops = Vec::with_capacity(entries.len());
2524            for entry in entries {
2525                let op = entry.get("op").and_then(Value::as_str).unwrap_or("delete");
2526                ops.push(OutboxOp {
2527                    upsert: op == "upsert",
2528                    table: entry
2529                        .get("table")
2530                        .and_then(Value::as_str)
2531                        .ok_or_else(|| "persisted outbox operation missing table".to_owned())?
2532                        .to_owned(),
2533                    row_id: entry
2534                        .get("rowId")
2535                        .and_then(Value::as_str)
2536                        .ok_or_else(|| "persisted outbox operation missing rowId".to_owned())?
2537                        .to_owned(),
2538                    base_version: entry.get("baseVersion").and_then(Value::as_i64),
2539                    // A legacy entry's `changedFields` key is ignored:
2540                    // the values map is the presence set (§6.1).
2541                    values: entry.get("values").and_then(Value::as_object).cloned(),
2542                    insert: entry.get("insert") == Some(&Value::Bool(true)),
2543                });
2544            }
2545            commits.push(Arc::new(OutboxCommit {
2546                client_commit_id,
2547                ops,
2548            }));
2549        }
2550        Ok(commits)
2551    }
2552
2553    fn restore_persisted_state(&mut self) -> Result<(), String> {
2554        self.outbox = self.load_outbox()?.into();
2555
2556        self.prune_commit_outcomes()?;
2557        let active = self.commit_outcomes(CommitOutcomeQuery {
2558            active_only: true,
2559            ..CommitOutcomeQuery::default()
2560        })?;
2561        self.conflicts = active
2562            .iter()
2563            .flat_map(|outcome| outcome.results.iter())
2564            .filter_map(|result| match result {
2565                CommitOperationOutcome::Conflict { conflict } => Some(conflict.clone()),
2566                _ => None,
2567            })
2568            .collect::<Vec<_>>()
2569            .into();
2570        self.rejections = active
2571            .iter()
2572            .flat_map(|outcome| outcome.results.iter())
2573            .filter_map(|result| match result {
2574                CommitOperationOutcome::Error { rejection } => Some(rejection.clone()),
2575                _ => None,
2576            })
2577            .collect::<Vec<_>>()
2578            .into();
2579
2580        self.lease_state = self
2581            .get_meta(LEASE_STATE_KEY)?
2582            .map(|raw| serde_json::from_str(&raw))
2583            .transpose()
2584            .map_err(|error| format!("invalid persisted lease state: {error}"))?;
2585        self.schema_floor = self
2586            .get_meta(SCHEMA_FLOOR_KEY)?
2587            .map(|raw| serde_json::from_str(&raw))
2588            .transpose()
2589            .map_err(|error| format!("invalid persisted schema floor: {error}"))?;
2590        self.stopped = self.schema_floor.is_some();
2591        // A replica left in unactivated preflight reopens gated: the quarantine
2592        // decision persists with the data across handle teardown and restart.
2593        if self.get_meta(SECURITY_PREFLIGHT_PENDING_KEY)?.as_deref() == Some("1") {
2594            self.security_preflight = true;
2595        }
2596        Ok(())
2597    }
2598
2599    fn save_unit_scope_schema(&self) -> Result<(), String> {
2600        let declarations: BTreeMap<_, BTreeMap<_, _>> = self
2601            .schema
2602            .tables
2603            .iter()
2604            .map(|table| {
2605                (
2606                    table.name.clone(),
2607                    table
2608                        .scope_variables
2609                        .iter()
2610                        .map(|scope| {
2611                            (
2612                                scope.variable.clone(),
2613                                [scope.prefix.clone(), scope.column.clone()],
2614                            )
2615                        })
2616                        .collect(),
2617                )
2618            })
2619            .collect();
2620        self.set_meta(
2621            "subscriptionScopeSchema",
2622            &serde_json::to_string(&declarations).expect("scope schema serialization"),
2623        )
2624    }
2625
2626    /// Drop units that cover no table of the running schema, with their window
2627    /// registry rows and pending evictions; never translate scopes. At a bump
2628    /// (§7.4.3) a unit also needs every variable unchanged in prefix and column
2629    /// on every table it covered before.
2630    fn prune_unknown_units(&mut self, bump: bool) -> Result<(), String> {
2631        let previous: Option<BTreeMap<String, BTreeMap<String, [String; 2]>>> = if bump {
2632            self.get_meta("subscriptionScopeSchema")?
2633                .map(|raw| serde_json::from_str(&raw))
2634                .transpose()
2635                .map_err(|_| "sync.local_corrupt: invalid persisted scope schema".to_owned())?
2636        } else {
2637            None
2638        };
2639        // A table keeps the variables' meaning when each has the same prefix
2640        // and column as before. An old binary stored no declaration evidence;
2641        // matching names cannot prove unchanged meaning, so the app registers
2642        // again.
2643        let unchanged = |name: &str, variables: &[&String]| {
2644            let (Some(old), Some(table)) = (
2645                previous.as_ref().and_then(|previous| previous.get(name)),
2646                self.schema.table(name),
2647            ) else {
2648                return false;
2649            };
2650            variables.iter().all(|variable| {
2651                table
2652                    .scope_variables
2653                    .iter()
2654                    .find(|scope| &scope.variable == *variable)
2655                    .is_some_and(|scope| {
2656                        old.get(*variable) == Some(&[scope.prefix.clone(), scope.column.clone()])
2657                    })
2658            })
2659        };
2660        let compatible = |scopes: &UnitScopes| {
2661            if !self.schema.tables.iter().any(|table| covers(table, scopes)) {
2662                return false;
2663            }
2664            if !bump {
2665                return true;
2666            }
2667            let Some(previous) = &previous else {
2668                return false;
2669            };
2670            previous.iter().all(|(name, old)| {
2671                !scopes.keys().all(|variable| old.contains_key(variable))
2672                    || unchanged(name, &scopes.keys().collect::<Vec<_>>())
2673            })
2674        };
2675        let mut stale: BTreeSet<String> = self
2676            .stored(load_units(&self.conn))?
2677            .into_iter()
2678            .filter(|unit| !compatible(&unit.scopes))
2679            .map(|unit| unit.id)
2680            .collect();
2681        // A shrunk window's deferred eviction outlives its unit row and keeps
2682        // its per-table scopes. A table the schema no longer has cannot be
2683        // evicted, and at a bump a table whose scope declarations changed must
2684        // not be evicted by the outdated rule.
2685        for (id, table, effective) in self.load_pending_evictions()? {
2686            if self.schema.table(&table).is_none()
2687                || (bump
2688                    && !unchanged(
2689                        &table,
2690                        &effective
2691                            .iter()
2692                            .map(|(variable, _)| variable)
2693                            .collect::<Vec<_>>(),
2694                    ))
2695            {
2696                stale.insert(id);
2697            }
2698        }
2699        for id in &stale {
2700            for sql in [
2701                "DELETE FROM _syncular_windows WHERE sub_id = ?1",
2702                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
2703                "DELETE FROM _syncular_units WHERE id = ?1",
2704            ] {
2705                self.conn
2706                    .execute(sql, rusqlite::params![id])
2707                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2708            }
2709        }
2710        Ok(())
2711    }
2712
2713    pub fn local_revision(&self) -> Result<u64, String> {
2714        Ok(self
2715            .get_meta(LOCAL_REVISION_KEY)?
2716            .and_then(|value| value.parse().ok())
2717            .unwrap_or(0))
2718    }
2719
2720    /// §7.5: resolve a snapshot read on the mutable owner connection through
2721    /// the same primitive the read-only sidecar uses, so the command surface
2722    /// and the file sidecar return one revision, rows, coverage, catch-up, and
2723    /// delivery shape. The structured [`QueryReadFailure`] is preserved; an
2724    /// `owner` records its failure (and its next success) in diagnostics.
2725    pub fn snapshot_read(
2726        &mut self,
2727        request: &SnapshotReadRequest<'_>,
2728        owner: Option<QueryOwner<'_>>,
2729    ) -> Result<SnapshotRead, QueryReadFailure> {
2730        let result = snapshot_read_connection(&self.conn, request);
2731        if let Some(owner) = owner {
2732            self.record_query_read(owner, result.as_ref().err());
2733        }
2734        result
2735    }
2736
2737    #[must_use]
2738    pub fn status_snapshot(&self) -> SyncStatusSnapshot {
2739        SyncStatusSnapshot {
2740            current_schema_version: self.schema.version,
2741            outbox: self.outbox.len(),
2742            upgrading: self.upgrading,
2743            lease_state: self.lease_state.clone(),
2744            schema_floor: self.schema_floor.clone(),
2745            sync_needed: self.sync_needed,
2746            previous_version_context: self.previous_version_status(),
2747            security_lifecycle: self.security_lifecycle(),
2748        }
2749    }
2750
2751    /// RFC 0005 A2: container presence for a host that must act on it (Diego's
2752    /// rollback precondition), read without creating the file.
2753    fn previous_version_status(&self) -> PreviousVersionStatus {
2754        let Some(replica_path) = self.previous_version_replica_path() else {
2755            return PreviousVersionStatus {
2756                present: false,
2757                created_at_ms: None,
2758            };
2759        };
2760        match crate::previous_version::read_previous_version_record(&replica_path) {
2761            Ok(Some(record)) => PreviousVersionStatus {
2762                present: true,
2763                created_at_ms: Some(record.created_at_ms),
2764            },
2765            _ => PreviousVersionStatus {
2766                present: std::path::Path::new(
2767                    &crate::previous_version::previous_version_container_path(&replica_path),
2768                )
2769                .exists(),
2770                created_at_ms: None,
2771            },
2772        }
2773    }
2774
2775    /// RFC 0005 D7: read captured rows from the previous local schema. `state`
2776    /// is always `previousVersion`; the container never makes
2777    /// `query_snapshot()` coverage complete. Lease stop/expiry, scope
2778    /// revocation, coverage completion and the TTL DISCARD the container and
2779    /// close the read with their own reason.
2780    pub fn previous_version_snapshot(
2781        &self,
2782        spec: &PreviousVersionReadSpec,
2783    ) -> Result<PreviousVersionSnapshot, String> {
2784        let now_ms = self.clock_now_ms();
2785        crate::previous_version::previous_version_snapshot(
2786            &self.conn,
2787            self.previous_version_replica_path().as_deref(),
2788            self.previous_version.as_ref(),
2789            PreviousVersionLifecycle {
2790                lease_inactive: self.previous_version_lease_inactive(now_ms),
2791                scope_revoked: self
2792                    .stored(load_units(&self.conn))?
2793                    .iter()
2794                    .any(|unit| unit.status == UnitStatus::Revoked),
2795                coverage_complete: self.previous_version_coverage_complete()?,
2796            },
2797            now_ms,
2798            self.schema.version,
2799            spec,
2800        )
2801    }
2802
2803    /// RFC 0005 D6: the advisory pre-reset compatibility audit.
2804    pub fn previous_version_audit(
2805        &self,
2806    ) -> Result<Option<crate::previous_version::PreviousVersionAudit>, String> {
2807        crate::previous_version::stored_previous_version_audit(&self.conn)
2808            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2809    }
2810
2811    /// RFC 0005 A2/D9: the executable downgrade step. Drop the container file
2812    /// and both metadata records, and report whether anything was present.
2813    /// Idempotent: absence is a successful no-op.
2814    pub fn previous_version_discard(
2815        &self,
2816    ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2817        self.drop_previous_version()
2818    }
2819
2820    fn drop_previous_version(
2821        &self,
2822    ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2823        let Some(replica_path) = self.previous_version_replica_path() else {
2824            return Ok(crate::previous_version::PreviousVersionDiscardOutcome {
2825                present: false,
2826                discarded: false,
2827            });
2828        };
2829        crate::previous_version::discard_previous_version(&self.conn, &replica_path)
2830    }
2831
2832    /// RFC 0005 D7: `leaseState.errorCode` or an expired lease.
2833    fn previous_version_lease_inactive(&self, now_ms: i64) -> bool {
2834        let Some(lease) = &self.lease_state else {
2835            return false;
2836        };
2837        if lease.error_code.is_some() {
2838            return true;
2839        }
2840        lease.expires_at_ms.is_some_and(|expires| expires <= now_ms)
2841    }
2842
2843    /// RFC 0005 D7: §7.4.5 replacement coverage — no active unit is
2844    /// bootstrapping. An empty active set is not completion (mirrors the TS
2845    /// predicate exactly).
2846    fn previous_version_coverage_complete(&self) -> Result<bool, String> {
2847        let units = self.stored(load_units(&self.conn))?;
2848        let mut active = units
2849            .iter()
2850            .filter(|unit| unit.status == UnitStatus::Active)
2851            .peekable();
2852        Ok(active.peek().is_some() && !active.any(UnitRecord::bootstrapping))
2853    }
2854
2855    /// RFC 0005 D7: lifetime triggers evaluated once per sync round, after the
2856    /// apply. A container that no longer has a reason to exist is discarded so
2857    /// the rows do not outlive the window they were kept for.
2858    fn previous_version_lifetime_check(&self) {
2859        let Some(config) = self.previous_version.filter(|config| config.enabled) else {
2860            return;
2861        };
2862        let now_ms = self.clock_now_ms();
2863        if self.previous_version_lease_inactive(now_ms) {
2864            let _ = self.drop_previous_version();
2865            return;
2866        }
2867        let Some(replica_path) = self.previous_version_replica_path() else {
2868            return;
2869        };
2870        let Ok(Some(record)) = crate::previous_version::read_previous_version_record(&replica_path)
2871        else {
2872            return;
2873        };
2874        let Ok(units) = load_units(&self.conn) else {
2875            return;
2876        };
2877        if units.iter().any(|unit| unit.status == UnitStatus::Revoked) {
2878            let _ = self.drop_previous_version();
2879            return;
2880        }
2881        if now_ms - record.created_at_ms > config.max_age_ms {
2882            let _ = self.drop_previous_version();
2883            return;
2884        }
2885        if self.previous_version_coverage_complete() == Ok(true) {
2886            let _ = self.drop_previous_version();
2887        }
2888    }
2889
2890    pub fn diagnostics_snapshot(&self) -> Result<ClientDiagnosticsSnapshot, String> {
2891        let registered = self.stored(load_units(&self.conn))?;
2892        // Both meta values in one statement: the FFI host recomputes
2893        // diagnostics after every command.
2894        let (local_revision, replica_cursor): (Option<String>, Option<String>) = self.stored(
2895            self.conn
2896                .prepare_cached(
2897                    "SELECT (SELECT value FROM _syncular_meta WHERE key = ?1),
2898                            (SELECT value FROM _syncular_meta WHERE key = ?2)",
2899                )
2900                .and_then(|mut statement| {
2901                    statement.query_row([LOCAL_REVISION_KEY, REPLICA_CURSOR_KEY], |row| {
2902                        Ok((row.get(0)?, row.get(1)?))
2903                    })
2904                }),
2905        )?;
2906        let mut units = DiagnosticUnits::default();
2907        for unit in &registered {
2908            *match unit.status {
2909                UnitStatus::Revoked => &mut units.revoked,
2910                UnitStatus::Failed => &mut units.failed,
2911                UnitStatus::Active if !unit.bootstrapping() => &mut units.complete,
2912                UnitStatus::Active
2913                    if unit.reason_code.as_deref() == Some("sync.cursor_expired") =>
2914                {
2915                    &mut units.reset
2916                }
2917                UnitStatus::Active => &mut units.bootstrapping,
2918            } += 1;
2919        }
2920        units.reason_codes = registered
2921            .iter()
2922            .filter_map(|unit| unit.reason_code.as_deref().map(Self::diagnostic_code))
2923            .collect::<BTreeSet<_>>()
2924            .into_iter()
2925            .collect();
2926        let captured_at_ms = self.clock_now_ms();
2927        let lease = if let Some(error_code) = self
2928            .lease_state
2929            .as_ref()
2930            .and_then(|state| state.error_code.clone())
2931        {
2932            ClientDiagnosticsLease {
2933                state: "stopped".to_owned(),
2934                expires_at_ms: self
2935                    .lease_state
2936                    .as_ref()
2937                    .and_then(|state| state.expires_at_ms),
2938                error_code: Some(Self::diagnostic_code(&error_code)),
2939            }
2940        } else if let Some(expires_at_ms) = self
2941            .lease_state
2942            .as_ref()
2943            .and_then(|state| state.expires_at_ms)
2944        {
2945            ClientDiagnosticsLease {
2946                state: if expires_at_ms <= captured_at_ms {
2947                    "expired".to_owned()
2948                } else {
2949                    "active".to_owned()
2950                },
2951                expires_at_ms: Some(expires_at_ms),
2952                error_code: None,
2953            }
2954        } else {
2955            ClientDiagnosticsLease {
2956                state: "none".to_owned(),
2957                expires_at_ms: None,
2958                error_code: None,
2959            }
2960        };
2961        let connectivity = match self.last_round.as_ref() {
2962            _ if !self.transport_enabled && self.active_round.is_none() => "offline",
2963            Some(round) if round.status == "succeeded" => "online",
2964            Some(round)
2965                if round.status == "failed"
2966                    && matches!(
2967                        round.cause_kind,
2968                        Some(
2969                            crate::TransportCauseKind::Network | crate::TransportCauseKind::Connect
2970                        )
2971                    ) =>
2972            {
2973                "offline"
2974            }
2975            Some(round) if round.status == "failed" && round.http_status.is_some() => "online",
2976            _ => "unknown",
2977        };
2978        Ok(ClientDiagnosticsSnapshot {
2979            version: CLIENT_DIAGNOSTICS_VERSION,
2980            captured_at_ms,
2981            host: ClientDiagnosticsHost {
2982                kind: "direct".to_owned(),
2983                role: "single".to_owned(),
2984                connectivity: connectivity.to_owned(),
2985                realtime: self.realtime_state,
2986                realtime_policy: self.realtime_policy,
2987                realtime_reason_code: self.realtime_reason_code.clone(),
2988                realtime_retry_delay_ms: self.realtime_retry_delay_ms,
2989            },
2990            security_lifecycle: self.security_lifecycle().to_owned(),
2991            schema: ClientDiagnosticsSchema {
2992                current_version: self.schema.version,
2993                upgrading: self.upgrading,
2994                required_version: self
2995                    .schema_floor
2996                    .as_ref()
2997                    .and_then(|floor| floor.required_schema_version),
2998                latest_version: self
2999                    .schema_floor
3000                    .as_ref()
3001                    .and_then(|floor| floor.latest_schema_version),
3002            },
3003            replica: ClientDiagnosticsReplica {
3004                local_revision: local_revision
3005                    .and_then(|value| value.parse::<u64>().ok())
3006                    .unwrap_or(0)
3007                    .to_string(),
3008                sync_needed: self.sync_needed,
3009                pending_outbox: self.outbox.len(),
3010            },
3011            lease,
3012            active_units: registered
3013                .iter()
3014                .filter(|unit| unit.status == UnitStatus::Active)
3015                .count(),
3016            units,
3017            replica_cursor: replica_cursor.map_or(Ok(-1), |raw| {
3018                raw.parse()
3019                    .map_err(|_| "sync.local_corrupt: persisted unit state is invalid".to_owned())
3020            })?,
3021            last_round: self.last_round.clone(),
3022            last_change: self.last_change.clone(),
3023            storage: self.diagnostics_storage(),
3024            query_failures: self.query_failures.clone(),
3025        })
3026    }
3027
3028    fn diagnostics_storage(&self) -> ClientDiagnosticsStorage {
3029        let read = || -> Result<ClientDiagnosticsStorage, rusqlite::Error> {
3030            let page_count: i64 = self
3031                .conn
3032                .query_row("PRAGMA page_count", [], |row| row.get(0))?;
3033            let page_size: i64 = self
3034                .conn
3035                .query_row("PRAGMA page_size", [], |row| row.get(0))?;
3036            // One cached aggregate, since the FFI host recomputes diagnostics
3037            // after every command; every invocation still reads current storage.
3038            let (outbox_bytes, outcome_entries, outcome_bytes): (i64, i64, i64) = self
3039                .conn
3040                .prepare_cached(
3041                    "SELECT (SELECT COALESCE(SUM(LENGTH(ops_json)), 0) FROM _syncular_outbox),
3042                            COUNT(*), COALESCE(SUM(LENGTH(results_json) + COALESCE(LENGTH(operations_json), 0)), 0)
3043                       FROM _syncular_commit_outcomes",
3044                )?
3045                .query_row([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?;
3046            let blob_bytes = if self.schema_has_blobs() {
3047                self.conn
3048                    .prepare_cached("SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs")?
3049                    .query_row([], |row| row.get(0))?
3050            } else {
3051                0
3052            };
3053            let pressure = self
3054                .limits
3055                .blob_cache_max_bytes
3056                .is_some_and(|limit| blob_bytes > limit);
3057            Ok(ClientDiagnosticsStorage {
3058                status: if pressure { "pressure" } else { "healthy" }.to_owned(),
3059                database_bytes_approx: Some(page_count.saturating_mul(page_size).max(0)),
3060                pending_outbox_bytes_approx: Some(outbox_bytes.max(0)),
3061                retained_outcome_bytes_approx: Some(outcome_bytes.max(0)),
3062                retained_outcome_entries: Some(outcome_entries.max(0)),
3063                blob_cache_bytes_approx: Some(blob_bytes.max(0)),
3064                pressure_reason_code: pressure.then(|| "client.blob_cache_over_limit".to_owned()),
3065            })
3066        };
3067        read().unwrap_or_else(|_| ClientDiagnosticsStorage {
3068            status: "unreadable".to_owned(),
3069            database_bytes_approx: None,
3070            pending_outbox_bytes_approx: None,
3071            retained_outcome_bytes_approx: None,
3072            retained_outcome_entries: None,
3073            blob_cache_bytes_approx: None,
3074            pressure_reason_code: None,
3075        })
3076    }
3077
3078    pub fn drain_change_batches(&mut self) -> Vec<ClientChangeBatch> {
3079        self.change_queue.drain(..).collect()
3080    }
3081
3082    pub fn drain_sync_intents(&mut self) -> Vec<SyncIntent> {
3083        let intents = self.sync_intent_queue.drain(..).collect();
3084        if self.transport_enabled {
3085            intents
3086        } else {
3087            vec![SyncIntent::None]
3088        }
3089    }
3090
3091    fn schedule_background_retry(&mut self) -> u64 {
3092        let delay_ms = self.retry_delay_ms;
3093        self.sync_intent_queue
3094            .push_back(SyncIntent::Background { delay_ms });
3095        self.retry_delay_ms = (self.retry_delay_ms * 2).min(30_000);
3096        self.round_retry_delay_ms = Some(delay_ms);
3097        delay_ms
3098    }
3099
3100    fn reset_background_retry(&mut self) {
3101        self.retry_delay_ms = 250;
3102    }
3103
3104    fn retryable_transport_code(code: &str) -> bool {
3105        code == "transport.failed"
3106            || code == "transport.timeout"
3107            || code == "transport.unavailable"
3108            || code == "sync.transport_failed"
3109    }
3110
3111    /// §1.8: the transport reported a refused or unreachable endpoint. The
3112    /// native transport says `connect` (DNS failure, connection refused,
3113    /// reset, or aborted); a browser fetch transport says `network`. Repeating
3114    /// the request on a backoff repairs neither, so no retry is scheduled.
3115    fn unreachable_transport(details: &Option<serde_json::Value>) -> bool {
3116        matches!(
3117            details
3118                .as_ref()
3119                .and_then(|details| details.get("causeKind"))
3120                .and_then(serde_json::Value::as_str),
3121            Some("connect" | "network")
3122        )
3123    }
3124
3125    /// §1.5: a segment fetch that fails inside an otherwise complete round is
3126    /// invisible to the server (the round response arrived whole), so its code
3127    /// rides the following requests like a socket-round failure. A code the
3128    /// frame grammar rejects is not reportable and the previous code stays.
3129    fn segment_fetch_failed(&mut self, error: TransportError) -> SectionError {
3130        if ssp2::model::valid_round_failure_code(&error.code) {
3131            self.round_failure = Some(error.code.clone());
3132        }
3133        SectionError::Transport(error)
3134    }
3135
3136    /// A failed round worth a background retry: a transport failure, or a
3137    /// §10.2 code the catalog marks retryable (clients may hardcode the
3138    /// catalog metadata, §10.1). Matches the TypeScript core, which retries
3139    /// on the server's `retryable` flag.
3140    fn retryable_failure_code(code: &str) -> bool {
3141        Self::retryable_transport_code(code)
3142            || matches!(
3143                code,
3144                "sync.auth_required"
3145                    | "sync.auth_lease_required"
3146                    | "sync.auth_lease_revoked"
3147                    | "sync.internal_error"
3148                    | "sync.idempotency_cache_miss"
3149                    | "sync.schema_not_ready"
3150                    | "sync.segment_expired"
3151                    | "sync.rate_limited"
3152                    | "sync.websocket_connection_limit"
3153            )
3154    }
3155
3156    fn diagnostic_code(code: &str) -> String {
3157        let valid = !code.is_empty()
3158            && code.len() <= 96
3159            && code.contains('.')
3160            && code
3161                .bytes()
3162                .next()
3163                .is_some_and(|byte| byte.is_ascii_lowercase())
3164            && code.bytes().all(|byte| {
3165                byte.is_ascii_lowercase()
3166                    || byte.is_ascii_digit()
3167                    || matches!(byte, b'.' | b'_' | b'-')
3168            });
3169        if valid {
3170            code.to_owned()
3171        } else {
3172            "client.unknown_failure".to_owned()
3173        }
3174    }
3175
3176    fn set_sync_needed(&mut self, value: bool, interactive: bool) {
3177        if self.sync_needed != value {
3178            if self.begin_observation("syncular_status").is_ok() {
3179                self.sync_needed = value;
3180                let batch = ChangeAccumulator {
3181                    status: true,
3182                    ..ChangeAccumulator::default()
3183                };
3184                if self.finish_observation("syncular_status", batch).is_err() {
3185                    self.rollback_observation("syncular_status");
3186                }
3187            } else {
3188                self.sync_needed = value;
3189            }
3190        }
3191        if value && interactive {
3192            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3193        }
3194    }
3195
3196    /// A unit-store result: a row that does not parse is `sync.local_corrupt`;
3197    /// every other SQLite error keeps its storage classification.
3198    fn stored<T>(&self, result: rusqlite::Result<T>) -> Result<T, String> {
3199        result.map_err(|error| match error {
3200            rusqlite::Error::FromSqlConversionFailure(..) => {
3201                "sync.local_corrupt: persisted unit state is invalid".to_owned()
3202            }
3203            error => Self::sqlite_failure(&self.storage_failure, error),
3204        })
3205    }
3206
3207    fn sqlite_failure(
3208        storage_failure: &RefCell<Option<QueryReadFailure>>,
3209        error: rusqlite::Error,
3210    ) -> String {
3211        let message = error.to_string();
3212        let failure = QueryReadFailure::from(error);
3213        let code = failure.code;
3214        if code.is_some() && storage_failure.borrow().is_none() {
3215            *storage_failure.borrow_mut() = Some(failure);
3216        }
3217        match code {
3218            Some(code) => format!("{code}: {message}"),
3219            None => message,
3220        }
3221    }
3222
3223    fn begin_observation(&self, name: &str) -> Result<(), String> {
3224        if let Some(failure) = &self.coalesced_failure {
3225            return Err(failure.clone());
3226        }
3227        // SQLite rolls a whole transaction back on some I/O and capacity
3228        // errors; later frames must not commit on their own after that.
3229        if self.coalesced.is_some() && self.conn.is_autocommit() {
3230            return Err("the coalesced apply transaction was rolled back".to_owned());
3231        }
3232        self.conn
3233            .execute_batch(&format!("SAVEPOINT {name}"))
3234            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3235    }
3236
3237    /// SPEC §1.4 rule 4: open a coalesced apply transaction unless a caller
3238    /// already owns one.
3239    fn begin_coalesced_apply(&mut self) -> Result<(), String> {
3240        if self.coalesced.is_some() || !self.conn.is_autocommit() {
3241            return Ok(());
3242        }
3243        self.conn
3244            .execute_batch("BEGIN")
3245            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3246        self.coalesced = Some(CoalescedApply {
3247            rows: 0,
3248            rollback: self.capture(),
3249        });
3250        Ok(())
3251    }
3252
3253    fn capture(&self) -> Rollback {
3254        Rollback {
3255            outbox: self.outbox.clone(),
3256            failed_commits: self.failed_commits.clone(),
3257            conflicts: self.conflicts.clone(),
3258            rejections: self.rejections.clone(),
3259            schema_floor: self.schema_floor.clone(),
3260            lease_state: self.lease_state.clone(),
3261            stopped: self.stopped,
3262            upgrading: self.upgrading,
3263            sync_needed: self.sync_needed,
3264            active_round: self.active_round,
3265            overlay_dirty: self.overlay_dirty.snapshot(),
3266            change_queue: self.change_queue.len(),
3267            sync_intent_queue: self.sync_intent_queue.len(),
3268            last_change: self.last_change.clone(),
3269        }
3270    }
3271
3272    fn restore(&mut self, rollback: Rollback) {
3273        self.outbox = rollback.outbox;
3274        self.failed_commits = rollback.failed_commits;
3275        self.conflicts = rollback.conflicts;
3276        self.rejections = rollback.rejections;
3277        self.schema_floor = rollback.schema_floor;
3278        self.lease_state = rollback.lease_state;
3279        self.stopped = rollback.stopped;
3280        self.upgrading = rollback.upgrading;
3281        self.sync_needed = rollback.sync_needed;
3282        self.active_round = rollback.active_round;
3283        self.overlay_dirty.restore(rollback.overlay_dirty);
3284        self.change_queue.truncate(rollback.change_queue);
3285        self.sync_intent_queue.truncate(rollback.sync_intent_queue);
3286        self.last_change = rollback.last_change;
3287    }
3288
3289    /// Account the rows of the next frame or block. A unit that would take the
3290    /// coalesced transaction past the bound commits the earlier units first.
3291    fn coalesce_unit(&mut self, rows: usize) -> Result<(), String> {
3292        let Some(open) = &self.coalesced else {
3293            return Ok(());
3294        };
3295        if open.rows > 0 && open.rows + rows > COALESCED_APPLY_ROWS {
3296            self.commit_coalesced_apply()?;
3297            self.begin_coalesced_apply()?;
3298        }
3299        if let Some(open) = &mut self.coalesced {
3300            open.rows += rows;
3301        }
3302        Ok(())
3303    }
3304
3305    /// COMMIT the coalesced transaction. A failed COMMIT rolls every coalesced
3306    /// frame back, restores the in-memory state of its `BEGIN`, drops the
3307    /// change batches and sync intents queued since, and fails the rest of the
3308    /// response.
3309    fn commit_coalesced_apply(&mut self) -> Result<(), String> {
3310        let Some(open) = self.coalesced.take() else {
3311            return Ok(());
3312        };
3313        let committed = if self.conn.is_autocommit() {
3314            Err("the coalesced apply transaction was rolled back".to_owned())
3315        } else {
3316            self.conn
3317                .execute_batch("COMMIT")
3318                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3319        };
3320        let Err(error) = committed else {
3321            return Ok(());
3322        };
3323        if !self.conn.is_autocommit() {
3324            if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3325                let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3326            }
3327        }
3328        self.restore(open.rollback);
3329        self.coalesced_failure = Some(error.clone());
3330        Err(error)
3331    }
3332
3333    /// End the response's coalescing: COMMIT what is open and clear a failure.
3334    fn finish_coalesced_apply(&mut self) -> Result<(), String> {
3335        let committed = self.commit_coalesced_apply();
3336        match self.coalesced_failure.take() {
3337            Some(failure) => Err(failure),
3338            None => committed,
3339        }
3340    }
3341
3342    fn rollback_observation(&self, name: &str) {
3343        if let Err(error) = self
3344            .conn
3345            .execute_batch(&format!("ROLLBACK TO {name}; RELEASE {name}"))
3346        {
3347            if let Some(failure) = self.storage_failure.borrow_mut().as_mut() {
3348                if failure.rollback_failure.is_none() {
3349                    failure.rollback_failure = Some(Box::new(QueryReadFailure::from(error)));
3350                }
3351            }
3352        }
3353    }
3354
3355    fn finish_observation(
3356        &mut self,
3357        name: &str,
3358        mut batch: ChangeAccumulator,
3359    ) -> Result<(), String> {
3360        #[cfg(feature = "bench-internals")]
3361        let _phase = self.benchmark_phases.start(Phase::ObservationCommit);
3362        if self.failed_commits.iter().any(|(commit, _)| {
3363            commit
3364                .ops
3365                .iter()
3366                .any(|operation| batch.tables.contains_key(&operation.table))
3367        }) {
3368            batch.outcomes = true;
3369        }
3370        if !batch.touched() {
3371            self.conn
3372                .execute_batch(&format!("RELEASE {name}"))
3373                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3374            return Ok(());
3375        }
3376        let revision = self
3377            .local_revision()?
3378            .checked_add(1)
3379            .ok_or_else(|| "local revision exhausted u64".to_owned())?;
3380        self.conn
3381            .execute(
3382                "INSERT OR REPLACE INTO _syncular_meta(key, value) VALUES (?1, ?2)",
3383                rusqlite::params![LOCAL_REVISION_KEY, revision.to_string()],
3384            )
3385            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3386        let status = batch.status.then(|| self.status_snapshot());
3387        let event = ClientChangeBatch {
3388            revision: revision.to_string(),
3389            tables: batch
3390                .tables
3391                .into_iter()
3392                .map(|(table, scope_keys)| TableChange {
3393                    table,
3394                    scope_keys: scope_keys.map(|keys| keys.into_iter().collect()),
3395                })
3396                .collect(),
3397            windows: batch
3398                .windows
3399                .into_iter()
3400                .map(|(base_key, units)| WindowChange {
3401                    base_key,
3402                    units: units.into_iter().collect(),
3403                })
3404                .collect(),
3405            status,
3406            conflicts_changed: batch.conflicts,
3407            rejections_changed: batch.rejections,
3408            outcomes_changed: batch.outcomes,
3409            applied_commits: Vec::new(),
3410        };
3411        self.conn
3412            .execute_batch(&format!("RELEASE {name}"))
3413            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3414        let mut diagnostic_tables = event
3415            .tables
3416            .iter()
3417            .map(|entry| entry.table.clone())
3418            .collect::<BTreeSet<_>>()
3419            .into_iter()
3420            .collect::<Vec<_>>();
3421        // §7.6: the selected variables of the changed window bases.
3422        let mut diagnostic_windows = event
3423            .windows
3424            .iter()
3425            .map(|entry| {
3426                entry
3427                    .base_key
3428                    .split('\0')
3429                    .next()
3430                    .unwrap_or_default()
3431                    .to_owned()
3432            })
3433            .collect::<BTreeSet<_>>()
3434            .into_iter()
3435            .collect::<Vec<_>>();
3436        let domains_truncated = diagnostic_tables.len() > MAX_DIAGNOSTIC_DOMAINS
3437            || diagnostic_windows.len() > MAX_DIAGNOSTIC_DOMAINS;
3438        diagnostic_tables.truncate(MAX_DIAGNOSTIC_DOMAINS);
3439        diagnostic_windows.truncate(MAX_DIAGNOSTIC_DOMAINS);
3440        self.last_change = Some(DiagnosticLastChange {
3441            revision: event.revision.clone(),
3442            recorded_at_ms: self.clock_now_ms(),
3443            tables: diagnostic_tables,
3444            windows: diagnostic_windows,
3445            domains_truncated,
3446            status_changed: event.status.is_some(),
3447            conflicts_changed: event.conflicts_changed,
3448            rejections_changed: event.rejections_changed,
3449            outcomes_changed: event.outcomes_changed,
3450        });
3451        self.change_queue.push_back(event);
3452        Ok(())
3453    }
3454
3455    fn record_scope_map(
3456        &self,
3457        batch: &mut ChangeAccumulator,
3458        table_name: &str,
3459        scopes: &[(String, Vec<String>)],
3460    ) {
3461        let Some(table) = self.schema.table(table_name) else {
3462            return;
3463        };
3464        // A bulk scoped delete whose map leaves a declared variable unnamed
3465        // cannot list the deleted rows' keys for it: the change is table-wide.
3466        if table.scope_variables.iter().any(|scope| {
3467            !scopes
3468                .iter()
3469                .any(|(variable, _)| *variable == scope.variable)
3470        }) {
3471            batch.table(table_name);
3472            return;
3473        }
3474        for (variable, values) in scopes {
3475            let Some(scope) = table
3476                .scope_variables
3477                .iter()
3478                .find(|scope| &scope.variable == variable)
3479            else {
3480                continue;
3481            };
3482            for value in values {
3483                batch.scope(table_name, format!("{}:{value}", scope.prefix));
3484            }
3485        }
3486    }
3487
3488    /// Record a row's current scope keys from the base or visible table.
3489    fn record_row_scopes(
3490        &self,
3491        batch: &mut ChangeAccumulator,
3492        table_name: &str,
3493        row_id: &str,
3494        base: bool,
3495    ) -> bool {
3496        let Some(table) = self.schema.table(table_name) else {
3497            return false;
3498        };
3499        if table.scope_variables.is_empty() {
3500            return false;
3501        }
3502        let columns = table
3503            .scope_variables
3504            .iter()
3505            .map(|scope| quote_ident(&scope.column))
3506            .collect::<Vec<_>>()
3507            .join(", ");
3508        let full_table = if base {
3509            base_table(table_name)
3510        } else {
3511            visible_table(table_name)
3512        };
3513        let sql = format!(
3514            "SELECT {columns} FROM {full_table} WHERE {} LIMIT 1",
3515            row_id_predicate(table)
3516        );
3517        let Ok(mut stmt) = self.conn.prepare_cached(&sql) else {
3518            return false;
3519        };
3520        let values = stmt.query_row(rusqlite::params![row_id], |row| {
3521            let mut values = Vec::with_capacity(table.scope_variables.len());
3522            for index in 0..table.scope_variables.len() {
3523                values.push(row.get::<_, Option<String>>(index)?);
3524            }
3525            Ok(values)
3526        });
3527        let Ok(values) = values else {
3528            return false;
3529        };
3530        let mut recorded = false;
3531        for (scope, value) in table.scope_variables.iter().zip(values) {
3532            if let Some(value) = value {
3533                batch.scope(table_name, format!("{}:{value}", scope.prefix));
3534                recorded = true;
3535            }
3536        }
3537        recorded
3538    }
3539
3540    fn record_commit_changes(
3541        &self,
3542        batch: &mut ChangeAccumulator,
3543        tables: &[String],
3544        changes: &[ssp2::model::Change],
3545    ) {
3546        #[cfg(feature = "bench-internals")]
3547        let _phase = self.benchmark_phases.start(Phase::ObservationPrepare);
3548        for change in changes {
3549            let Some(table_name) = tables.get(change.table_index as usize) else {
3550                continue;
3551            };
3552            let mut precise = self.record_row_scopes(batch, table_name, &change.row_id, true);
3553            if let Some(table) = self.schema.table(table_name) {
3554                for (variable, value) in &change.scopes {
3555                    if let Some(scope) = table
3556                        .scope_variables
3557                        .iter()
3558                        .find(|scope| &scope.variable == variable)
3559                    {
3560                        batch.scope(table_name, format!("{}:{value}", scope.prefix));
3561                        precise = true;
3562                    }
3563                }
3564            }
3565            if !precise {
3566                batch.table(table_name);
3567            }
3568        }
3569    }
3570
3571    /// Whether a base or visible row matches the scope predicate; `false`
3572    /// without a local scope-column mapping. A SQLite failure is an error.
3573    fn scoped_rows_exist(
3574        &self,
3575        table_name: &str,
3576        effective: &[(String, Vec<String>)],
3577        owners: &[Vec<(String, Vec<String>)>],
3578    ) -> Result<bool, String> {
3579        let Some(table) = self.schema.table(table_name) else {
3580            return Ok(false);
3581        };
3582        let Ok(Some((predicate, params))) = local_scope_predicate(table, effective, owners) else {
3583            return Ok(false);
3584        };
3585        for source in [base_table(table_name), visible_table(table_name)] {
3586            if self
3587                .conn
3588                .query_row(
3589                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
3590                    rusqlite::params_from_iter(&params),
3591                    |row| row.get::<_, bool>(0),
3592                )
3593                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
3594            {
3595                return Ok(true);
3596            }
3597        }
3598        Ok(false)
3599    }
3600
3601    /// §5.6 first-page clear of `unit_id`'s pair: delete its rows except
3602    /// those another owner covers (§3.3), failing closed without a local
3603    /// scope-column mapping. Owners are read only when a row matches, inside
3604    /// the caller's transaction. Returns whether rows matched.
3605    fn clear_scope(
3606        &mut self,
3607        table: &TableSchema,
3608        effective: &[(String, Vec<String>)],
3609        unit_id: &str,
3610    ) -> Result<bool, SectionError> {
3611        let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
3612        let matched = self
3613            .scoped_rows_exist(&table.name, effective, &[])
3614            .map_err(storage)?;
3615        let owners = if matched {
3616            unit_owners(
3617                &self.stored(load_units(&self.conn)).map_err(storage)?,
3618                table,
3619                unit_id,
3620            )
3621        } else {
3622            Vec::new()
3623        };
3624        let changed = matched
3625            && (owners.is_empty()
3626                || self
3627                    .scoped_rows_exist(&table.name, effective, &owners)
3628                    .map_err(storage)?);
3629        if !self
3630            .purge_scope_rows(&table.name, effective, &owners)
3631            .map_err(storage)?
3632        {
3633            return Err(SectionError::FailClosed);
3634        }
3635        Ok(changed)
3636    }
3637
3638    /// §7.4.5: true while a schema-bump reset + first re-bootstrap runs.
3639    pub fn upgrading(&self) -> bool {
3640        self.upgrading
3641    }
3642
3643    /// §7.4.2 "app ships new code": swap to a NEW generated schema while
3644    /// keeping this client's local database (identity, outbox, tables). The
3645    /// §7.4.1 marker check then fires the wipe/re-bootstrap flow when the
3646    /// version increases. Recreation runs the same marker guard as opening
3647    /// a durable replica, holds the guard and every write it authorizes under
3648    /// one write transaction, and preserves the current client (compiled
3649    /// schema, outbox, tables) on refusal.
3650    pub fn recreate_with_schema(&mut self, schema_json: &Value) -> Result<(), String> {
3651        let new_schema = parse_schema_json(schema_json)?;
3652        validate_authority_reads(&new_schema, &self.limits.authority_reads)?;
3653        self.conn
3654            .execute_batch("BEGIN IMMEDIATE")
3655            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3656        let prior_schema = std::mem::replace(&mut self.schema, new_schema);
3657        // §7.4.3/§7.4.4: a reset inside this transaction mutates in-memory
3658        // state (dropped outbox commits, rejections, upgrade and floor flags,
3659        // overlay dirtiness) and appends change/intent batches. A COMMIT that
3660        // fails after the reset succeeded rolls the database back, so every
3661        // one of those fields is captured here and restored with it.
3662        let rollback = self.capture();
3663        let guarded = (|| -> Result<(), String> {
3664            // §7.4.2: the marker is re-read under the write lock the caller
3665            // holds, so a replica another process upgraded meanwhile refuses
3666            // this recreation instead of having its marker and tables
3667            // downgraded.
3668            let marker = read_local_schema_version(&self.conn, self.schema.version)?;
3669            self.create_bookkeeping_tables()?;
3670            match marker {
3671                Some(version) if version < self.schema.version => self.run_schema_reset()?,
3672                None => {
3673                    self.create_synced_tables()?;
3674                    self.persist_schema_version()?;
3675                }
3676                _ => {}
3677            }
3678            // §7.4.2: recreation IS the boot for the in-memory core, so reload the
3679            // durable outbox the same-version path is about to replay. Only the
3680            // outbox is reloaded: the recovery below reads it, and the caller's
3681            // rollback snapshot already covers this field.
3682            self.outbox = self.load_outbox()?.into();
3683            // §7.1/§7.4.4: recover intrinsically codec-invalid persisted values at
3684            // this guarded boundary once the schema and marker agree. A bump went
3685            // through `run_schema_reset`, which performs the same recovery after
3686            // it creates the new physical tables and before its final replay.
3687            self.drop_unencodable_outbox(false, None)?;
3688            if marker == Some(self.schema.version)
3689                && (!self.outbox.is_empty()
3690                    || !self.failed_commits.is_empty()
3691                    || self.has_acknowledged_rows()?)
3692            {
3693                self.overlay_dirty.set(true);
3694                self.rebuild_overlay()?;
3695            }
3696            self.prune_unknown_units(false)?;
3697            self.save_unit_scope_schema()?;
3698            // The conformance recreate is the in-memory equivalent of reopening
3699            // a durable client. Apply the same startup catch-up contract even
3700            // when the schema itself did not change.
3701            self.enqueue_startup_sync_if_needed()?;
3702            Ok(())
3703        })();
3704        let outcome = match guarded {
3705            Ok(()) => self
3706                .conn
3707                .execute_batch("COMMIT")
3708                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error)),
3709            Err(error) => Err(error),
3710        };
3711        if let Err(error) = outcome {
3712            if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3713                // Keep a failed rollback's typed storage classification.
3714                let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3715            }
3716            self.schema = prior_schema;
3717            self.restore(rollback);
3718            // Prepared insert statements were derived from the reverted schema.
3719            self.insert_sql.borrow_mut().clear();
3720            return Err(error);
3721        }
3722        if !self.security_preflight {
3723            self.drain_pending_evictions()?;
3724        }
3725        Ok(())
3726    }
3727
3728    fn enqueue_startup_sync_if_needed(&mut self) -> Result<(), String> {
3729        let startup_work = !self.stopped
3730            && (!self.outbox.is_empty()
3731                || self.has_acknowledged_rows()?
3732                || !self.load_pending_evictions()?.is_empty()
3733                || self
3734                    .stored(load_units(&self.conn))?
3735                    .iter()
3736                    .any(|unit| unit.status == UnitStatus::Active));
3737        if startup_work {
3738            self.sync_needed = true;
3739            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3740        }
3741        Ok(())
3742    }
3743
3744    /// A native client persists schema-floor stops across process restarts.
3745    /// Once the running app already satisfies that floor, the persisted stop
3746    /// is only stale evidence from an older server round (for example, the
3747    /// server was restarted after catching up to an app that was ahead).
3748    /// Clear it and let the normal startup pull re-negotiate. If the server is
3749    /// still incompatible it will return the floor again in that first round.
3750    fn clear_satisfied_persisted_schema_floor(&mut self) -> Result<(), String> {
3751        let satisfied = self
3752            .schema_floor
3753            .as_ref()
3754            .and_then(|floor| floor.required_schema_version)
3755            .is_some_and(|required| self.schema.version >= required);
3756        if !satisfied {
3757            return Ok(());
3758        }
3759        self.delete_meta(SCHEMA_FLOOR_KEY)?;
3760        self.schema_floor = None;
3761        self.stopped = false;
3762        Ok(())
3763    }
3764
3765    /// RFC 0005 D1: discard an orphan or stale container at boot. The reset
3766    /// path already swept it; this covers a same-version or fresh-install open,
3767    /// which runs no reset and therefore no sweep — plus the D7 TTL, which only
3768    /// an aware binary can apply.
3769    fn reconcile_previous_version_at_boot(&self) -> Result<(), String> {
3770        let Some(replica_path) = self.previous_version_replica_path() else {
3771            return Ok(());
3772        };
3773        let max_age_ms = self
3774            .previous_version
3775            .filter(|config| config.enabled)
3776            .map(|config| config.max_age_ms);
3777        reconcile_previous_version_at_boot(
3778            &self.conn,
3779            &replica_path,
3780            self.schema.version,
3781            max_age_ms,
3782            self.clock_now_ms(),
3783        )
3784    }
3785
3786    /// RFC 0005 D3: the sibling container path, or `None` when the replica has
3787    /// no file — an in-memory replica returns an empty path, and a `file:` URI
3788    /// has no plain sibling path — so the feature resolves as off there.
3789    fn previous_version_replica_path(&self) -> Option<String> {
3790        let path = self.conn.path()?;
3791        if path.is_empty() || path.starts_with("file:") {
3792            return None;
3793        }
3794        Some(path.to_owned())
3795    }
3796
3797    /// §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
3798    /// and leaseState. Drops/recreates every synced table from the new
3799    /// schema, resets unit sync state (keeping registrations), clears
3800    /// the schema-floor stop state, rewrites the marker, drops outbox commits
3801    /// that cannot re-encode (§7.4.4), and replays the survivors on top.
3802    fn run_schema_reset(&mut self) -> Result<(), String> {
3803        self.begin_observation("syncular_schema_reset")?;
3804        let rollback = self.capture();
3805        let mut batch = ChangeAccumulator::default();
3806        let result = self
3807            .run_schema_reset_observed(&mut batch, true)
3808            .and_then(|()| self.finish_observation("syncular_schema_reset", batch));
3809        if let Err(error) = result {
3810            self.rollback_observation("syncular_schema_reset");
3811            self.restore(rollback);
3812            return Err(error);
3813        }
3814        Ok(())
3815    }
3816
3817    fn run_log_epoch_reset(&mut self, log_epoch: &str) -> Result<Vec<String>, String> {
3818        if self.get_meta(LOG_EPOCH_KEY)?.is_none() {
3819            self.begin_observation("syncular_epoch_acquisition")?;
3820            let rollback = self.capture();
3821            if let Err(error) = self.conn.execute(
3822                "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3823                rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3824            ) {
3825                self.rollback_observation("syncular_epoch_acquisition");
3826                return Err(Self::sqlite_failure(&self.storage_failure, error));
3827            }
3828            self.sync_needed = true;
3829            let batch = ChangeAccumulator {
3830                status: true,
3831                ..ChangeAccumulator::default()
3832            };
3833            if let Err(error) = self.finish_observation("syncular_epoch_acquisition", batch) {
3834                self.rollback_observation("syncular_epoch_acquisition");
3835                self.restore(rollback);
3836                return Err(error);
3837            }
3838            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3839            return Ok(Vec::new());
3840        }
3841        let resets = self
3842            .stored(load_units(&self.conn))?
3843            .into_iter()
3844            .map(|unit| unit.id)
3845            .collect();
3846        self.begin_observation("syncular_log_epoch_reset")?;
3847        let rollback = self.capture();
3848        let mut batch = ChangeAccumulator::default();
3849        let result = self
3850            .run_schema_reset_observed(&mut batch, false)
3851            .and_then(|()| {
3852                self.conn
3853                    .execute(
3854                        "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3855                        rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3856                    )
3857                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3858                self.sync_needed = true;
3859                batch.status = true;
3860                self.finish_observation("syncular_log_epoch_reset", batch)
3861            });
3862        if let Err(error) = result {
3863            self.rollback_observation("syncular_log_epoch_reset");
3864            self.restore(rollback);
3865            return Err(error);
3866        }
3867        self.sync_intent_queue.push_back(SyncIntent::Interactive);
3868        Ok(resets)
3869    }
3870
3871    fn run_schema_reset_observed(
3872        &mut self,
3873        batch: &mut ChangeAccumulator,
3874        capture: bool,
3875    ) -> Result<(), String> {
3876        // §7.4.2: the reset is the only path that wipes local tables for a
3877        // version bump, and it rewrites the marker last. Re-read the marker
3878        // under this reset's transaction: a replica another process upgraded
3879        // meanwhile refuses here instead of being reset to this client's
3880        // older schema.
3881        read_local_schema_version(&self.conn, self.schema.version)?;
3882        self.conn
3883            .execute_batch(
3884                "DELETE FROM _syncular_acked_rows; DELETE FROM _syncular_row_deliveries;",
3885            )
3886            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3887        self.cancel_sync_round();
3888        self.upgrading = true;
3889        batch.status = true;
3890        // RFC 0005 D6: classify the pending outbox against the NEW compiled
3891        // schema BEFORE the wipe, and record the advisory audit. This pass
3892        // drops nothing, so the audit sees the original pending intent; the
3893        // §7.4.4 send-time drop and the intrinsic value recovery later in this
3894        // reset are the paths that remove a commit. The classification is
3895        // shared with the send-time drop so the two cannot disagree about what
3896        // is incompatible.
3897        if self.previous_version.is_some_and(|config| config.enabled) {
3898            let previous_version = self
3899                .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
3900                .and_then(|value| value.parse::<i32>().ok())
3901                .unwrap_or(self.schema.version);
3902            let pending = self
3903                .outbox
3904                .iter()
3905                .map(|commit| PendingCommitAudit {
3906                    commit_id: &commit.client_commit_id,
3907                    operations: commit_audit_operations(commit),
3908                })
3909                .collect::<Vec<_>>();
3910            crate::previous_version::write_previous_version_audit(
3911                &self.conn,
3912                &crate::previous_version::build_previous_version_audit(
3913                    &self.schema,
3914                    &pending,
3915                    previous_version,
3916                    self.schema.version,
3917                    self.clock_now_ms(),
3918                ),
3919            )?;
3920        }
3921        // RFC 0005 D5: the container lives in its own FILE, so the reset can
3922        // never reach it. Sweep first (unconditional — also on the log-epoch
3923        // reset, which captures nothing), then capture BEFORE the wipe drops
3924        // any row. A refused capture records its reason and leaves no file.
3925        if let Some(replica_path) = self.previous_version_replica_path() {
3926            sweep_previous_version_container(&self.conn, &replica_path)?;
3927            if capture {
3928                if let Some(config) = self.previous_version.filter(|config| config.enabled) {
3929                    let previous_version = self
3930                        .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
3931                        .and_then(|value| value.parse::<i32>().ok())
3932                        .unwrap_or(self.schema.version);
3933                    capture_previous_version_from_replica(
3934                        &self.conn,
3935                        &replica_path,
3936                        previous_version,
3937                        self.schema.version,
3938                        &config,
3939                        self.clock_now_ms(),
3940                    )?;
3941                }
3942            }
3943        }
3944        for table in &self.schema.tables {
3945            batch.table(&table.name);
3946        }
3947        for (base_key, value) in self.load_window_registry()? {
3948            batch.window(&base_key, &value);
3949        }
3950        if capture {
3951            self.prune_unknown_units(true)?;
3952        }
3953        // The per-table insert SQL is derived from the OLD column lists.
3954        self.insert_sql.borrow_mut().clear();
3955        self.overlay_dirty.set(true);
3956        // Drop every synced table (base + visible) that currently exists —
3957        // discovered from sqlite_master so a bump that adds/removes tables is
3958        // handled. Bookkeeping tables (`_syncular_outbox/_units/_meta`
3959        // and the blob cache) are preserved; base tables are `_syncular_base_*`
3960        // so they are matched explicitly, not by the bookkeeping filter.
3961        // Drop virtual tables first so SQLite removes every FTS shadow table
3962        // atomically instead of the generic discovery tearing it apart.
3963        let virtual_tables: Vec<String> = {
3964            let mut stmt = self
3965                .conn
3966                .prepare(
3967                    "SELECT name FROM sqlite_master WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%'",
3968                )
3969                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3970            let rows = stmt
3971                .query_map([], |row| row.get::<_, String>(0))
3972                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3973            rows.filter_map(Result::ok)
3974                .filter(|name| is_synced_table_name(name))
3975                .collect()
3976        };
3977        for name in virtual_tables {
3978            self.conn
3979                .execute_batch(&format!(
3980                    "DROP TABLE IF EXISTS {}",
3981                    quote_ident(&format!("_syncular_fts_{name}"))
3982                ))
3983                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3984            self.conn
3985                .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
3986                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3987        }
3988        let existing: Vec<String> = {
3989            let mut stmt = self
3990                .conn
3991                .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
3992                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3993            let rows = stmt
3994                .query_map([], |row| row.get::<_, String>(0))
3995                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3996            rows.filter_map(Result::ok)
3997                .filter(|name| is_synced_table_name(name))
3998                .collect()
3999        };
4000        for name in &existing {
4001            if let Some(table) = name.strip_prefix("_syncular_base_") {
4002                batch.table(table);
4003            } else if !name.starts_with("_syncular_") {
4004                batch.table(name);
4005            }
4006        }
4007        for name in existing {
4008            self.conn
4009                .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
4010                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4011        }
4012        // Recreate the synced tables from the NEW schema.
4013        self.create_synced_tables()?;
4014        // Reset every unit's sync state, keeping the registration.
4015        reset_units(&self.conn)
4016            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4017        // The stop state is over: this client now ships a servable schema.
4018        self.stopped = false;
4019        self.schema_floor = None;
4020        self.delete_meta(SCHEMA_FLOOR_KEY)?;
4021        // Rewrite the marker LAST so a crash mid-reset re-runs the reset.
4022        self.persist_schema_version()?;
4023        self.save_unit_scope_schema()?;
4024        // §7.1/§7.4.4: the previous-version capture and audit above saw the
4025        // original pending intent; the synced tables now carry the new schema, so
4026        // recover intrinsically codec-invalid persisted values here, before the
4027        // final replay. A pending upsert that names a column the new schema
4028        // removed stays pending for the send-time `drop_incompatible_outbox`
4029        // prepass. The reset wrapper snapshots and restores the outbox,
4030        // rejections, and change queues, so a failed commit rolls this recovery
4031        // back with the rest of the reset.
4032        // §7.4.4: the enclosing reset observation owns the publication, so the
4033        // recovery contributes its rejection, outcome, and table domains to it.
4034        self.drop_unencodable_outbox(false, Some(batch))?;
4035        // Re-apply the surviving outbox optimistically over the empty tables.
4036        self.rebuild_overlay()?;
4037        Ok(())
4038    }
4039
4040    /// §7.4.4 send-time prepass: a persisted upsert whose values reference a
4041    /// column the current schema lacks (or a removed table) cannot be encoded
4042    /// (`commit_audit_operations` inspects upserts, so a value-free delete stays
4043    /// encodable and is validated by the server), nor can an insert-intent
4044    /// upsert that lacks a non-nullable column (§7.1, the audit's
4045    /// `missing-required-column`). Drop the commit, undo
4046    /// its optimistic projection, and raise a client-local
4047    /// `sync.outbox_incompatible` rejection.
4048    fn drop_incompatible_outbox(&mut self) -> Result<bool, String> {
4049        let incompatible = self
4050            .outbox
4051            .iter()
4052            .filter(|commit| {
4053                first_incompatibility(&self.schema, &commit_audit_operations(commit)).is_some()
4054            })
4055            .cloned()
4056            .collect::<Vec<_>>();
4057        if incompatible.is_empty() {
4058            return Ok(false);
4059        }
4060        self.drop_outbox_commits(
4061            &incompatible,
4062            OUTBOX_INCOMPATIBLE_CODE,
4063            "the persisted commit cannot encode under the current schema",
4064        )?;
4065        Ok(true)
4066    }
4067
4068    /// §7.4.4 incompatible-commit path, also taken by a refused blob upload
4069    /// (§5.9.7) with the server's code: reject every operation of `commits`,
4070    /// remove them from the outbox, and undo their optimistic rows.
4071    fn drop_outbox_commits(
4072        &mut self,
4073        incompatible: &[Arc<OutboxCommit>],
4074        code: &str,
4075        message: &str,
4076    ) -> Result<(), String> {
4077        // §7.4.4: one observation covers the durable outcome writes, the outbox
4078        // removal, the in-memory drop, and the overlay rebuild, so a storage
4079        // fault leaves the replica and the client unchanged and publishes no
4080        // change; a successful drop publishes exactly one batch carrying the
4081        // rejections, outcomes, status, and the tables whose projection changed.
4082        let rollback = self.capture();
4083        let owns_transaction = self.conn.is_autocommit();
4084        self.begin_observation("syncular_outbox_drop")?;
4085        let mut batch = ChangeAccumulator::default();
4086        let dropped = (|| -> Result<(), String> {
4087            let mut rejections = Vec::new();
4088            for commit in incompatible {
4089                let results = commit
4090                    .ops
4091                    .iter()
4092                    .enumerate()
4093                    .map(|(op_index, operation)| {
4094                        let rejection = RejectionRecord {
4095                            client_commit_id: commit.client_commit_id.clone(),
4096                            op_index: op_index as i32,
4097                            code: code.to_owned(),
4098                            message: message.to_owned(),
4099                            retryable: false,
4100                            details: None,
4101                            operation: Some(CommitOperation::from(operation)),
4102                        };
4103                        rejections.push(rejection.clone());
4104                        CommitOperationOutcome::Error { rejection }
4105                    })
4106                    .collect::<Vec<_>>();
4107                self.persist_commit_outcome(
4108                    &commit.client_commit_id,
4109                    CommitOutcomeStatus::Rejected,
4110                    &results,
4111                    Some(&commit.ops),
4112                )?;
4113                self.delete_outbox_persisted(&commit.client_commit_id)?;
4114                // A removed table has no local projection to invalidate; every
4115                // surviving table the dropped commit touched does.
4116                for operation in &commit.ops {
4117                    if self.schema.table(&operation.table).is_some() {
4118                        batch.table(&operation.table);
4119                    }
4120                }
4121            }
4122            self.prune_commit_outcomes()?;
4123            let incompatible_ids = incompatible
4124                .iter()
4125                .map(|commit| commit.client_commit_id.as_str())
4126                .collect::<BTreeSet<_>>();
4127            self.outbox
4128                .retain(|commit| !incompatible_ids.contains(commit.client_commit_id.as_str()));
4129            self.rejections.extend(rejections);
4130            // The dropped commits' purely-optimistic rows are undone: the
4131            // visible projection is re-derived from the surviving base + outbox.
4132            self.overlay_dirty.set(true);
4133            self.rebuild_overlay()?;
4134            batch.status = true;
4135            batch.rejections = true;
4136            batch.outcomes = true;
4137            Ok(())
4138        })();
4139        let result = dropped.and_then(|()| self.finish_observation("syncular_outbox_drop", batch));
4140        if let Err(error) = result {
4141            // An outer RELEASE is the COMMIT. Roll back that transaction
4142            // directly: retrying RELEASE after ROLLBACK TO still needs the
4143            // reader's lock. A nested observation only rolls back its savepoint.
4144            if owns_transaction {
4145                if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
4146                    let mut failure = self.storage_failure.borrow_mut();
4147                    let failure =
4148                        failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
4149                    failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
4150                }
4151            } else {
4152                self.rollback_observation("syncular_outbox_drop");
4153            }
4154            self.restore(rollback);
4155            return Err(error);
4156        }
4157        Ok(())
4158    }
4159
4160    /// §7.4.3: (re)create the base + visible table pair for every synced
4161    /// table in the CURRENT schema (idempotent — `IF NOT EXISTS`).
4162    fn create_synced_tables(&self) -> Result<(), String> {
4163        for table in &self.schema.tables {
4164            // The base half + the visible half form the synced-table pair. An
4165            // index name is global in SQLite, so the base half's indexes are
4166            // name-prefixed (`_syncular_base_<index>`) to stay distinct.
4167            for (full, index_prefix) in [
4168                (base_table(&table.name), "_syncular_base_"),
4169                (visible_table(&table.name), ""),
4170            ] {
4171                let mut cols: Vec<String> =
4172                    table.columns.iter().map(|c| quote_ident(&c.name)).collect();
4173                cols.push("\"_syncular_version\" INTEGER NOT NULL".to_owned());
4174                cols.extend(
4175                    table
4176                        .sealed_columns()
4177                        .iter()
4178                        .map(|name| format!("{} TEXT", quote_ident(name))),
4179                );
4180                let sql = format!(
4181                    "CREATE TABLE IF NOT EXISTS {full} ({} , PRIMARY KEY ({}))",
4182                    cols.join(", "),
4183                    quote_ident(&table.primary_key)
4184                );
4185                self.conn
4186                    .execute(&sql, [])
4187                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4188                // §5.11: a replica created before sealed apply gains the
4189                // reserved columns in place, on both halves in the same order,
4190                // so data, indexes and the FTS projection stay.
4191                for name in table.sealed_columns() {
4192                    let present: bool = self
4193                        .conn
4194                        .query_row(
4195                            "SELECT EXISTS(SELECT 1 FROM pragma_table_info(?1) WHERE name = ?2)",
4196                            rusqlite::params![format!("{index_prefix}{}", table.name), name],
4197                            |row| row.get(0),
4198                        )
4199                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4200                    if !present {
4201                        self.conn
4202                            .execute(
4203                                &format!(
4204                                    "ALTER TABLE {full} ADD COLUMN {} TEXT",
4205                                    quote_ident(name)
4206                                ),
4207                                [],
4208                            )
4209                            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4210                    }
4211                }
4212                // The reveal at every round start reads the sealed rows of the
4213                // base half through this partial index.
4214                if table.has_encrypted_columns() && !index_prefix.is_empty() {
4215                    self.conn
4216                        .execute(
4217                            &format!(
4218                                "CREATE INDEX IF NOT EXISTS {} ON {full} (\"_sync_sealed_key\") WHERE \"_sync_sealed_key\" IS NOT NULL",
4219                                quote_ident(&format!("_syncular_sealed_{}", table.name))
4220                            ),
4221                            [],
4222                        )
4223                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4224                }
4225                // Local secondary indexes (CREATE INDEX subset). Created on
4226                // both halves so mirror reads hit an index on either. Runs on
4227                // both the initial create and the §7.4.3 reset recreate path.
4228                for index in &table.indexes {
4229                    let unique = if index.unique { "UNIQUE " } else { "" };
4230                    let index_name = quote_ident(&format!("{index_prefix}{}", index.name));
4231                    let cols_sql = index
4232                        .columns
4233                        .iter()
4234                        .map(|c| quote_ident(c))
4235                        .collect::<Vec<_>>()
4236                        .join(", ");
4237                    let index_sql = format!(
4238                        "CREATE {unique}INDEX IF NOT EXISTS {index_name} ON {full} ({cols_sql})"
4239                    );
4240                    self.conn
4241                        .execute(&index_sql, [])
4242                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4243                }
4244            }
4245        }
4246        // FTS exists only on the visible half. It is a local search
4247        // projection, never a synced/base table or a wire-schema member.
4248        for table in &self.schema.tables {
4249            for index in &table.fts_indexes {
4250                self.create_fts_projection(table, index)?;
4251            }
4252        }
4253        Ok(())
4254    }
4255
4256    fn fts_projection_exists(&self, index: &FtsIndexSchema) -> Result<bool, String> {
4257        let count: i64 = self
4258            .conn
4259            .query_row(
4260                "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?1",
4261                rusqlite::params![index.name],
4262                |row| row.get(0),
4263            )
4264            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4265        Ok(count > 0)
4266    }
4267
4268    fn drop_fts_triggers(&self, index: &FtsIndexSchema) -> Result<(), String> {
4269        for suffix in ["ai", "ad", "au"] {
4270            self.conn
4271                .execute(
4272                    &format!(
4273                        "DROP TRIGGER IF EXISTS {}",
4274                        quote_ident(&format!("{}_{suffix}", index.name))
4275                    ),
4276                    [],
4277                )
4278                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4279        }
4280        Ok(())
4281    }
4282
4283    fn create_fts_triggers(
4284        &self,
4285        table: &TableSchema,
4286        index: &FtsIndexSchema,
4287    ) -> Result<(), String> {
4288        let fts = quote_ident(&index.name);
4289        let source = visible_table(&table.name);
4290        let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4291        let pk = quote_ident(&table.primary_key);
4292        let projection_columns = std::iter::once(source_id.clone())
4293            .chain(index.columns.iter().map(|column| quote_ident(column)))
4294            .collect::<Vec<_>>()
4295            .join(", ");
4296        let new_values = std::iter::once(format!("CAST(new.{pk} AS TEXT)"))
4297            .chain(
4298                index
4299                    .columns
4300                    .iter()
4301                    .map(|column| format!("new.{}", quote_ident(column))),
4302            )
4303            .collect::<Vec<_>>()
4304            .join(", ");
4305        let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4306        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)");
4307        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)");
4308        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})");
4309        let bi = quote_ident(&format!("{}_bi", index.name));
4310        let ai = quote_ident(&format!("{}_ai", index.name));
4311        let ad = quote_ident(&format!("{}_ad", index.name));
4312        let au = quote_ident(&format!("{}_au", index.name));
4313        let replacement_exists = format!("EXISTS (SELECT 1 FROM {source} WHERE {pk} = new.{pk})");
4314        let sql = format!(
4315            "DROP TRIGGER IF EXISTS {bi};
4316             DROP TRIGGER IF EXISTS {ai};
4317             DROP TRIGGER IF EXISTS {ad};
4318             DROP TRIGGER IF EXISTS {au};
4319             CREATE TRIGGER {bi} BEFORE INSERT ON {source} WHEN {replacement_exists} BEGIN {delete_new}; END;
4320             CREATE TRIGGER {ai} AFTER INSERT ON {source} BEGIN {insert_new}; END;
4321             CREATE TRIGGER {ad} AFTER DELETE ON {source} BEGIN {delete_old}; END;
4322             CREATE TRIGGER {au} AFTER UPDATE ON {source} BEGIN {delete_old}; {delete_new}; {insert_new}; END;",
4323        );
4324        self.conn
4325            .execute_batch(&sql)
4326            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4327    }
4328
4329    fn rebuild_fts_projection(
4330        &self,
4331        table: &TableSchema,
4332        index: &FtsIndexSchema,
4333    ) -> Result<(), String> {
4334        let fts = quote_ident(&index.name);
4335        let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4336        let pk = quote_ident(&table.primary_key);
4337        let indexed_columns = index
4338            .columns
4339            .iter()
4340            .map(|column| quote_ident(column))
4341            .collect::<Vec<_>>();
4342        let projection_columns = std::iter::once(source_id.clone())
4343            .chain(indexed_columns.iter().cloned())
4344            .collect::<Vec<_>>()
4345            .join(", ");
4346        let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4347        let sql = format!(
4348            "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};",
4349            columns = indexed_columns.join(", "),
4350            source = visible_table(&table.name),
4351        );
4352        self.conn
4353            .execute_batch(&sql)
4354            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4355    }
4356
4357    fn create_fts_projection(
4358        &self,
4359        table: &TableSchema,
4360        index: &FtsIndexSchema,
4361    ) -> Result<(), String> {
4362        self.begin_observation("syncular_fts_schema")?;
4363        let result = (|| {
4364            let existed = self.fts_projection_exists(index)?;
4365            let tokenizer = index.tokenize.replace('\'', "''");
4366            let columns = index
4367                .columns
4368                .iter()
4369                .map(|column| quote_ident(column))
4370                .collect::<Vec<_>>()
4371                .join(", ");
4372            let sql = format!(
4373            "CREATE VIRTUAL TABLE IF NOT EXISTS {fts} USING fts5({source_id} UNINDEXED, {columns}, tokenize='{tokenizer}')",
4374            fts = quote_ident(&index.name),
4375            source_id = quote_ident(FTS_SOURCE_ID_COLUMN),
4376        );
4377            self.conn.execute(&sql, []).map_err(|error| {
4378                format!(
4379                    "cannot create local FTS5 projection {:?}: {error}",
4380                    index.name
4381                )
4382            })?;
4383            let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4384            let mapped: bool = self
4385                .conn
4386                .query_row(
4387                    "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1)",
4388                    [format!("_syncular_fts_{}", index.name)],
4389                    |row| row.get(0),
4390                )
4391                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4392            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))?;
4393            if !mapped && existed {
4394                self.conn
4395                    .execute_batch(&format!(
4396                        "INSERT INTO {mapping}(id, source_id) SELECT rowid, {} FROM {}",
4397                        quote_ident(FTS_SOURCE_ID_COLUMN),
4398                        quote_ident(&index.name)
4399                    ))
4400                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4401            }
4402            self.create_fts_triggers(table, index)?;
4403            if !existed {
4404                self.rebuild_fts_projection(table, index)?;
4405            }
4406            Ok(())
4407        })();
4408        if let Err(error) = result {
4409            self.rollback_observation("syncular_fts_schema");
4410            return Err(error);
4411        }
4412        if let Err(error) = self.conn.execute_batch("RELEASE syncular_fts_schema") {
4413            self.rollback_observation("syncular_fts_schema");
4414            return Err(error.to_string());
4415        }
4416        Ok(())
4417    }
4418
4419    // -- persistence write-through --------------------------------------------
4420
4421    fn persist_outbox_insert(&self, commit: &OutboxCommit) -> Result<(), String> {
4422        let ops: Vec<Value> = commit
4423            .ops
4424            .iter()
4425            .map(|op| {
4426                let mut entry = serde_json::json!({
4427                    "op": if op.upsert { "upsert" } else { "delete" },
4428                    "table": op.table,
4429                    "rowId": op.row_id,
4430                    "baseVersion": op.base_version,
4431                    "values": op.values.clone().map(Value::Object),
4432                });
4433                if op.insert {
4434                    entry["insert"] = Value::Bool(true);
4435                }
4436                entry
4437            })
4438            .collect();
4439        self.conn
4440            .execute(
4441                "INSERT OR REPLACE INTO _syncular_outbox (commit_id, ops_json) VALUES (?1, ?2)",
4442                rusqlite::params![commit.client_commit_id, Value::Array(ops).to_string()],
4443            )
4444            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4445        for operation in &commit.ops {
4446            let Some(values) = &operation.values else {
4447                continue;
4448            };
4449            let Some(table) = self.schema.table(&operation.table) else {
4450                continue;
4451            };
4452            for column in table
4453                .columns
4454                .iter()
4455                .filter(|column| column.ty == ColumnType::BlobRef)
4456            {
4457                let Some(Value::String(raw)) = values.get(&column.name) else {
4458                    continue;
4459                };
4460                let Ok(blob_ref) = serde_json::from_str::<Value>(raw) else {
4461                    continue;
4462                };
4463                let Some(blob_id) = blob_ref.get("blobId").and_then(Value::as_str) else {
4464                    continue;
4465                };
4466                self.conn
4467                    .execute(
4468                        "INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id, blob_id)
4469                         SELECT ?1, ?2 WHERE EXISTS (SELECT 1 FROM _syncular_blobs WHERE blob_id = ?2)",
4470                        rusqlite::params![commit.client_commit_id, blob_id],
4471                    )
4472                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4473            }
4474        }
4475        Ok(())
4476    }
4477
4478    fn delete_outbox_persisted(&self, client_commit_id: &str) -> Result<(), String> {
4479        self.conn
4480            .execute(
4481                "DELETE FROM _syncular_blob_commit_refs WHERE commit_id = ?1",
4482                rusqlite::params![client_commit_id],
4483            )
4484            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4485        self.conn
4486            .execute(
4487                "DELETE FROM _syncular_outbox WHERE commit_id = ?1",
4488                rusqlite::params![client_commit_id],
4489            )
4490            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4491        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)", [])
4492            .map(|_| ())
4493            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4494    }
4495
4496    fn outcome_status_name(status: CommitOutcomeStatus) -> &'static str {
4497        match status {
4498            CommitOutcomeStatus::Applied => "applied",
4499            CommitOutcomeStatus::Cached => "cached",
4500            CommitOutcomeStatus::Conflict => "conflict",
4501            CommitOutcomeStatus::Rejected => "rejected",
4502        }
4503    }
4504
4505    fn outcome_resolution_name(resolution: CommitOutcomeResolution) -> &'static str {
4506        match resolution {
4507            CommitOutcomeResolution::Active => "active",
4508            CommitOutcomeResolution::ResolvedKeepServer => "resolved_keep_server",
4509            CommitOutcomeResolution::Superseded => "superseded",
4510            CommitOutcomeResolution::Dismissed => "dismissed",
4511        }
4512    }
4513
4514    fn parse_outcome_status(value: &str) -> Result<CommitOutcomeStatus, String> {
4515        match value {
4516            "applied" => Ok(CommitOutcomeStatus::Applied),
4517            "cached" => Ok(CommitOutcomeStatus::Cached),
4518            "conflict" => Ok(CommitOutcomeStatus::Conflict),
4519            "rejected" => Ok(CommitOutcomeStatus::Rejected),
4520            _ => Err(format!("invalid persisted commit outcome status {value:?}")),
4521        }
4522    }
4523
4524    fn parse_outcome_resolution(value: &str) -> Result<CommitOutcomeResolution, String> {
4525        match value {
4526            "active" => Ok(CommitOutcomeResolution::Active),
4527            "resolved_keep_server" => Ok(CommitOutcomeResolution::ResolvedKeepServer),
4528            "superseded" => Ok(CommitOutcomeResolution::Superseded),
4529            "dismissed" => Ok(CommitOutcomeResolution::Dismissed),
4530            _ => Err(format!(
4531                "invalid persisted commit outcome resolution {value:?}"
4532            )),
4533        }
4534    }
4535
4536    fn persist_commit_outcome(
4537        &self,
4538        client_commit_id: &str,
4539        status: CommitOutcomeStatus,
4540        results: &[CommitOperationOutcome],
4541        operations: Option<&[OutboxOp]>,
4542    ) -> Result<(), String> {
4543        let results_json = serde_json::to_string(results).map_err(|error| error.to_string())?;
4544        let operations_json = operations
4545            .map(|items| {
4546                serde_json::to_string(&items.iter().map(CommitOperation::from).collect::<Vec<_>>())
4547            })
4548            .transpose()
4549            .map_err(|error| error.to_string())?;
4550        self.conn
4551            .execute(
4552                "INSERT INTO _syncular_commit_outcomes (
4553                   client_commit_id, status, recorded_at_ms, results_json,
4554                   operations_json, resolution
4555                 ) VALUES (?1, ?2, ?3, ?4, ?5, 'active')",
4556                rusqlite::params![
4557                    client_commit_id,
4558                    Self::outcome_status_name(status),
4559                    self.clock_now_ms(),
4560                    results_json,
4561                    operations_json
4562                ],
4563            )
4564            .map(|_| ())
4565            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4566    }
4567
4568    /// §7.2: the journal holds a stored cell only in its canonical shape. A cell
4569    /// the byte-envelope rule refuses cannot be journaled verbatim.
4570    fn stored_cell_is_representable(cell: &Value) -> bool {
4571        cell.is_null()
4572            || cell.is_string()
4573            || cell.is_boolean()
4574            || cell.is_number()
4575            || is_canonical_bytes_envelope(cell)
4576    }
4577
4578    fn stored_row_is_representable(value: &Value) -> bool {
4579        value
4580            .as_object()
4581            .is_some_and(|row| row.values().all(Self::stored_cell_is_representable))
4582    }
4583
4584    fn stored_operation_is_representable(value: &Value) -> bool {
4585        value.get("table").is_some_and(Value::is_string)
4586            && value.get("rowId").is_some_and(Value::is_string)
4587            && value.get("baseVersion").is_none_or(|v| {
4588                v.as_i64()
4589                    .is_some_and(|n| n.unsigned_abs() <= MAX_JS_SAFE_INTEGER)
4590            })
4591            && match value.get("op").and_then(Value::as_str) {
4592                Some("upsert") => {
4593                    value
4594                        .get("values")
4595                        .is_some_and(Self::stored_row_is_representable)
4596                        && value
4597                            .get("insert")
4598                            .is_none_or(|insert| *insert == Value::Bool(true))
4599                }
4600                Some("delete") => value.get("values").is_none() && value.get("insert").is_none(),
4601                _ => false,
4602            }
4603    }
4604
4605    /// §7.2/§7.4.4: a dropped commit keeps its operation envelope in the journal
4606    /// only when the journal reader accepts the serialized operation, which is the
4607    /// rule `outcome_from_row` applies to this same row later.
4608    fn outbox_op_is_journalable(operation: &OutboxOp) -> bool {
4609        serde_json::to_value(CommitOperation::from(operation))
4610            .is_ok_and(|value| Self::stored_operation_is_representable(&value))
4611    }
4612
4613    fn outcome_from_row(row: StoredCommitOutcomeRow) -> Result<CommitOutcome, String> {
4614        let StoredCommitOutcomeRow {
4615            sequence,
4616            client_commit_id,
4617            status,
4618            recorded_at_ms,
4619            results_json,
4620            operations_json,
4621            resolution,
4622            resolved_at_ms,
4623            replacement_client_commit_id,
4624        } = row;
4625        if sequence.unsigned_abs() > MAX_JS_SAFE_INTEGER
4626            || recorded_at_ms.unsigned_abs() > MAX_JS_SAFE_INTEGER
4627            || resolved_at_ms.is_some_and(|value| value.unsigned_abs() > MAX_JS_SAFE_INTEGER)
4628        {
4629            return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned());
4630        }
4631        let invalid = || "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
4632        let stored: Vec<Value> = serde_json::from_str(&results_json).map_err(|_| invalid())?;
4633        for result in &stored {
4634            let nested = match result.get("status").and_then(Value::as_str) {
4635                Some("conflict") => result.get("conflict"),
4636                Some("error") => result.get("rejection"),
4637                _ => None,
4638            };
4639            if nested
4640                .and_then(|record| record.get("operation"))
4641                .is_some_and(|op| !Self::stored_operation_is_representable(op))
4642                || (result.get("status").and_then(Value::as_str) == Some("conflict")
4643                    && nested
4644                        .and_then(|record| record.get("serverRow"))
4645                        .is_some_and(|row| !Self::stored_row_is_representable(row)))
4646            {
4647                return Err(invalid());
4648            }
4649        }
4650        let results: Vec<CommitOperationOutcome> =
4651            serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())?;
4652        let has_conflict = results
4653            .iter()
4654            .any(|result| matches!(result, CommitOperationOutcome::Conflict { .. }));
4655        let has_error = results
4656            .iter()
4657            .any(|result| matches!(result, CommitOperationOutcome::Error { .. }));
4658        let status = Self::parse_outcome_status(&status).map_err(|_| invalid())?;
4659        let redacted = results.is_empty() && operations_json.is_none();
4660        if match status {
4661            CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => has_conflict || has_error,
4662            CommitOutcomeStatus::Conflict => !(has_conflict || redacted),
4663            CommitOutcomeStatus::Rejected => has_conflict || !(has_error || redacted),
4664        } {
4665            return Err(invalid());
4666        }
4667        let operations: Option<Vec<CommitOperation>> = operations_json
4668            .map(|raw| {
4669                let stored: Vec<Value> = serde_json::from_str(&raw).map_err(|_| invalid())?;
4670                if !stored.iter().all(Self::stored_operation_is_representable) {
4671                    return Err(invalid());
4672                }
4673                serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())
4674            })
4675            .transpose()?;
4676        for result in &results {
4677            match result {
4678                CommitOperationOutcome::Conflict { conflict }
4679                    if conflict.server_version.unsigned_abs() > MAX_JS_SAFE_INTEGER =>
4680                {
4681                    return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned())
4682                }
4683                CommitOperationOutcome::Error { rejection } => {
4684                    if let Some(details) = &rejection.details {
4685                        let encoded = serde_json::to_string(details).map_err(|_| {
4686                            "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4687                        })?;
4688                        RejectionDetails::parse(&encoded).map_err(|_| {
4689                            "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4690                        })?;
4691                    }
4692                }
4693                _ => {}
4694            }
4695        }
4696        Ok(CommitOutcome {
4697            sequence,
4698            client_commit_id,
4699            status,
4700            recorded_at_ms,
4701            results,
4702            operations,
4703            retained_rows: None,
4704            resolution: Self::parse_outcome_resolution(&resolution)?,
4705            resolved_at_ms,
4706            replacement_client_commit_id,
4707        })
4708    }
4709
4710    /// Resolve declared unique keys through SQLite, including affinity and NULL semantics.
4711    fn unique_conflicts(
4712        &self,
4713        table: &TableSchema,
4714        values: &Map<String, Value>,
4715        base: bool,
4716    ) -> Result<Vec<RetainedUniqueConflict>, String> {
4717        let source = if base {
4718            base_table(&table.name)
4719        } else {
4720            visible_table(&table.name)
4721        };
4722        let mut conflicts = Vec::new();
4723        for index in table.indexes.iter().filter(|index| index.unique) {
4724            let mut params = vec![json_param_to_sql(
4725                values.get(&table.primary_key).ok_or("sync.local_corrupt")?,
4726            )?];
4727            for name in &index.columns {
4728                let column = table
4729                    .columns
4730                    .iter()
4731                    .find(|column| column.name == *name)
4732                    .ok_or("sync.local_corrupt")?;
4733                let cell = json_to_column_value(column, values.get(name))?;
4734                params.push(owned_sql_value(RowParam::Cell(&cell))?);
4735            }
4736            let sql = format!(
4737                "SELECT * FROM {source} WHERE {} != ? AND {}",
4738                quote_ident(&table.primary_key),
4739                index
4740                    .columns
4741                    .iter()
4742                    .map(|column| format!("{} = ?", quote_ident(column)))
4743                    .collect::<Vec<_>>()
4744                    .join(" AND ")
4745            );
4746            let mut statement = self
4747                .conn
4748                .prepare_cached(&sql)
4749                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4750            let records = statement
4751                .query_map(rusqlite::params_from_iter(params), |record| {
4752                    let values = table
4753                        .columns
4754                        .iter()
4755                        .enumerate()
4756                        .map(|(index, column)| {
4757                            let value = sql_ref_to_json(column, record.get_ref(index)?);
4758                            json_to_column_value(column, Some(&value)).map_err(|message| {
4759                                rusqlite::Error::ToSqlConversionFailure(message.into())
4760                            })
4761                        })
4762                        .collect::<Result<Row, _>>()?;
4763                    Ok((values, record.get::<_, i64>(table.columns.len())?))
4764                })
4765                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4766            for record in records {
4767                let (row, version) =
4768                    record.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4769                let row_id = render_row_id_json(Some(&column_value_to_json(&row[table.pk_index])))?;
4770                conflicts.push(RetainedUniqueConflict {
4771                    index: index.name.clone(),
4772                    columns: index.columns.clone(),
4773                    row_id,
4774                    server_row: table
4775                        .columns
4776                        .iter()
4777                        .zip(&row)
4778                        .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
4779                        .collect(),
4780                    server_version: version,
4781                });
4782            }
4783        }
4784        Ok(conflicts)
4785    }
4786
4787    fn attach_retained_rows(&self, mut outcome: CommitOutcome) -> Result<CommitOutcome, String> {
4788        if let Some((commit, initial)) = self
4789            .failed_commits
4790            .iter()
4791            .find(|(commit, _)| commit.client_commit_id == outcome.client_commit_id)
4792        {
4793            let mut rows = Vec::new();
4794            for operation in &commit.ops {
4795                // A table the current schema removed has no rows to retain.
4796                let Some(table) = self.schema.table(&operation.table) else {
4797                    continue;
4798                };
4799                let key =
4800                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
4801                        .map_err(|_| "sync.local_corrupt".to_owned())?;
4802                let base = self.stored_row(table, &operation.row_id, true)?;
4803                rows.push(RetainedCommitRow {
4804                    table: operation.table.clone(),
4805                    row_id: operation.row_id.clone(),
4806                    unique_conflicts: if operation.upsert {
4807                        self.unique_conflicts(
4808                            table,
4809                            initial
4810                                .get(&key)
4811                                .and_then(Value::as_object)
4812                                .or(operation.values.as_ref())
4813                                .ok_or("sync.local_corrupt")?,
4814                            true,
4815                        )?
4816                    } else {
4817                        Vec::new()
4818                    },
4819                    local_row: if operation.upsert {
4820                        initial
4821                            .get(&key)
4822                            .and_then(Value::as_object)
4823                            .cloned()
4824                            .or_else(|| operation.values.clone())
4825                    } else {
4826                        None
4827                    },
4828                    server_row: base.as_ref().map(|(values, _)| {
4829                        table
4830                            .columns
4831                            .iter()
4832                            .zip(values)
4833                            .map(|(column, value)| {
4834                                (column.name.clone(), column_value_to_json(value))
4835                            })
4836                            .collect()
4837                    }),
4838                    server_version: base.map(|(_, version)| version),
4839                });
4840            }
4841            outcome.retained_rows = Some(rows);
4842        }
4843        Ok(outcome)
4844    }
4845
4846    pub fn commit_outcome(&self, client_commit_id: &str) -> Result<Option<CommitOutcome>, String> {
4847        let row = self
4848            .conn
4849            .query_row(
4850                "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
4851                        resolution, resolved_at_ms, replacement_client_commit_id
4852                   FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
4853                rusqlite::params![client_commit_id],
4854                |row| {
4855                    Ok(StoredCommitOutcomeRow {
4856                        sequence: row.get(0)?,
4857                        client_commit_id: row.get(1)?,
4858                        status: row.get(2)?,
4859                        recorded_at_ms: row.get(3)?,
4860                        results_json: row.get(4)?,
4861                        operations_json: row.get(5)?,
4862                        resolution: row.get(6)?,
4863                        resolved_at_ms: row.get(7)?,
4864                        replacement_client_commit_id: row.get(8)?,
4865                    })
4866                },
4867            )
4868            .optional()
4869            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4870        row.map(|row| self.attach_retained_rows(Self::outcome_from_row(row)?))
4871            .transpose()
4872    }
4873
4874    /// Internal host step. The host must run its idle drive before finishing.
4875    #[doc(hidden)]
4876    pub fn prepare_current_base(
4877        &self,
4878        client_commit_id: &str,
4879        sequence: i64,
4880    ) -> Result<CurrentBasePreparation, CurrentBaseProof> {
4881        let outcome = self
4882            .commit_outcome(client_commit_id)
4883            .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?;
4884        let valid = outcome.as_ref().is_some_and(|outcome| {
4885            outcome.sequence == sequence
4886                && outcome.resolution == CommitOutcomeResolution::Active
4887                && matches!(
4888                    outcome.status,
4889                    CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
4890                )
4891                && outcome
4892                    .operations
4893                    .as_ref()
4894                    .zip(outcome.retained_rows.as_ref())
4895                    .is_some_and(|(operations, rows)| {
4896                        !rows.is_empty() && operations.len() == rows.len()
4897                    })
4898        });
4899        if !valid {
4900            return Err(CurrentBaseProof::failure(
4901                CurrentBaseProofReason::OutcomeUnavailable,
4902            ));
4903        }
4904        if !self.transport_enabled {
4905            return Err(CurrentBaseProof::failure(CurrentBaseProofReason::Offline));
4906        }
4907        Ok(CurrentBasePreparation {
4908            client_commit_id: client_commit_id.to_owned(),
4909            sequence,
4910            units: load_units(&self.conn)
4911                .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?,
4912            transport_epoch: self.transport_epoch,
4913            registration_epoch: self.registration_epoch,
4914            security_epoch: self.security_epoch,
4915        })
4916    }
4917
4918    /// Internal host step after the completed post-rejection idle drive.
4919    #[doc(hidden)]
4920    pub fn finish_current_base(
4921        &mut self,
4922        prepared: CurrentBasePreparation,
4923        drive: SyncOutcome,
4924    ) -> CurrentBaseProof {
4925        if !self.transport_enabled || self.transport_epoch != prepared.transport_epoch {
4926            return CurrentBaseProof::failure(CurrentBaseProofReason::Offline);
4927        }
4928        if self.registration_epoch != prepared.registration_epoch {
4929            return CurrentBaseProof::failure(CurrentBaseProofReason::MissingCoverage);
4930        }
4931        if self.security_preflight || self.security_epoch != prepared.security_epoch {
4932            return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed);
4933        }
4934        let report = match drive {
4935            SyncOutcome::Ok(report) => report,
4936            SyncOutcome::BudgetExhausted(_) => {
4937                return CurrentBaseProof::failure(CurrentBaseProofReason::BudgetExhausted)
4938            }
4939            _ => return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed),
4940        };
4941        if report.schema_floor.is_some() {
4942            return CurrentBaseProof::failure(CurrentBaseProofReason::SchemaFloor);
4943        }
4944        if self
4945            .conn
4946            .execute_batch("SAVEPOINT syncular_base_proof")
4947            .is_err()
4948        {
4949            return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
4950        }
4951        let proof = (|| {
4952            let snapshot = snapshot_read_connection(
4953                &self.conn,
4954                &SnapshotReadRequest {
4955                    units: prepared.units.iter().map(|unit| unit.id.clone()).collect(),
4956                    commit_ids: vec![prepared.client_commit_id.clone()],
4957                    ..Default::default()
4958                },
4959            )
4960            .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4961            let current = self
4962                .commit_outcome(&prepared.client_commit_id)
4963                .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4964            let unavailable = if report.revoked.is_empty() {
4965                CurrentBaseProofReason::OutcomeUnavailable
4966            } else {
4967                CurrentBaseProofReason::Revoked
4968            };
4969            let Some(outcome) = current else {
4970                return Err(unavailable);
4971            };
4972            if !matches!(
4973                snapshot.deliveries.first(),
4974                Some(CommitDelivery::Known { .. })
4975            ) || outcome.sequence != prepared.sequence
4976                || outcome.resolution != CommitOutcomeResolution::Active
4977                || !matches!(
4978                    outcome.status,
4979                    CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
4980                )
4981            {
4982                return Err(unavailable);
4983            }
4984            let (Some(operations), Some(rows)) = (outcome.operations, outcome.retained_rows) else {
4985                return Err(unavailable);
4986            };
4987            if rows.is_empty() || operations.len() != rows.len() {
4988                return Err(unavailable);
4989            }
4990            let after =
4991                load_units(&self.conn).map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4992            let complete: HashSet<&str> = snapshot
4993                .units
4994                .iter()
4995                .filter_map(|unit| match unit {
4996                    UnitCatchup::Known {
4997                        id,
4998                        bootstrap_complete: true,
4999                        ..
5000                    } => Some(id.as_str()),
5001                    _ => None,
5002                })
5003                .collect();
5004            // A unit id names one scope map (§4.1), so the same id before and
5005            // after the drive is the same registration.
5006            let candidates: Vec<&UnitRecord> = after
5007                .iter()
5008                .filter(|unit| {
5009                    complete.contains(unit.id.as_str())
5010                        && prepared.units.iter().any(|before| before.id == unit.id)
5011                })
5012                .collect();
5013            let covered = |table_name: &str, row: &Map<String, Value>| {
5014                let Some(table) = self.schema.table(table_name) else {
5015                    return false;
5016                };
5017                candidates.iter().any(|unit| {
5018                    covers(table, &unit.scopes)
5019                        && pair_scopes(&unit.scopes, table_name, unit.echo.as_deref()).is_some_and(
5020                            |scopes| {
5021                                scopes.iter().all(|(variable, allowed)| {
5022                                    table
5023                                        .scope_column(variable)
5024                                        .and_then(|column| match row.get(column) {
5025                                            Some(Value::String(value)) => Some(value.clone()),
5026                                            Some(Value::Bool(value)) => Some(value.to_string()),
5027                                            Some(Value::Number(value)) => {
5028                                                value.as_f64().map(|number| {
5029                                                    ryu_js::Buffer::new()
5030                                                        .format_finite(number)
5031                                                        .to_owned()
5032                                                })
5033                                            }
5034                                            _ => None,
5035                                        })
5036                                        .is_some_and(|value| {
5037                                            !value.is_empty() && allowed.contains(&value)
5038                                        })
5039                                })
5040                            },
5041                        )
5042                })
5043            };
5044            for row in &rows {
5045                let Some(base) = row.server_row.as_ref().or(row.local_row.as_ref()) else {
5046                    return Err(if report.revoked.is_empty() {
5047                        CurrentBaseProofReason::MissingCoverage
5048                    } else {
5049                        CurrentBaseProofReason::Revoked
5050                    });
5051                };
5052                if !covered(&row.table, base)
5053                    || row
5054                        .unique_conflicts
5055                        .iter()
5056                        .any(|conflict| !covered(&row.table, &conflict.server_row))
5057                {
5058                    return Err(if report.revoked.is_empty() {
5059                        CurrentBaseProofReason::MissingCoverage
5060                    } else {
5061                        CurrentBaseProofReason::Revoked
5062                    });
5063                }
5064            }
5065            Ok(rows)
5066        })();
5067        if self
5068            .conn
5069            .execute_batch("RELEASE syncular_base_proof")
5070            .is_err()
5071        {
5072            return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
5073        }
5074        match proof {
5075            Ok(rows) => CurrentBaseProof {
5076                proven: true,
5077                rows: Some(rows),
5078                reason: None,
5079            },
5080            Err(reason) => CurrentBaseProof::failure(reason),
5081        }
5082    }
5083
5084    pub fn prove_current_base(
5085        &mut self,
5086        transport: &mut dyn Transport,
5087        client_commit_id: &str,
5088        sequence: i64,
5089        max_rounds: Option<u32>,
5090    ) -> CurrentBaseProof {
5091        let prepared = match self.prepare_current_base(client_commit_id, sequence) {
5092            Ok(prepared) => prepared,
5093            Err(proof) => return proof,
5094        };
5095        let drive = self.sync_until_idle(transport, max_rounds);
5096        self.finish_current_base(prepared, drive)
5097    }
5098
5099    pub fn commit_outcomes(&self, query: CommitOutcomeQuery) -> Result<Vec<CommitOutcome>, String> {
5100        if query.limit == Some(0) {
5101            return Err("sync.invalid_request: commit outcome limit must be positive".to_owned());
5102        }
5103        let mut sql = String::from(
5104            "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
5105                    resolution, resolved_at_ms, replacement_client_commit_id
5106               FROM _syncular_commit_outcomes",
5107        );
5108        if query.active_only {
5109            sql.push_str(" WHERE resolution = 'active' AND status IN ('conflict', 'rejected')");
5110        }
5111        sql.push_str(" ORDER BY seq DESC");
5112        if let Some(limit) = query.limit {
5113            sql.push_str(&format!(" LIMIT {limit}"));
5114        }
5115        let mut stmt = self
5116            .conn
5117            .prepare(&sql)
5118            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5119        let rows = stmt
5120            .query_map([], |row| {
5121                Ok(StoredCommitOutcomeRow {
5122                    sequence: row.get(0)?,
5123                    client_commit_id: row.get(1)?,
5124                    status: row.get(2)?,
5125                    recorded_at_ms: row.get(3)?,
5126                    results_json: row.get(4)?,
5127                    operations_json: row.get(5)?,
5128                    resolution: row.get(6)?,
5129                    resolved_at_ms: row.get(7)?,
5130                    replacement_client_commit_id: row.get(8)?,
5131                })
5132            })
5133            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5134        let mut outcomes = Vec::new();
5135        for row in rows {
5136            outcomes.push(self.attach_retained_rows(Self::outcome_from_row(
5137                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
5138            )?)?);
5139        }
5140        Ok(outcomes)
5141    }
5142
5143    fn prune_commit_outcomes(&self) -> Result<(), String> {
5144        #[cfg(test)]
5145        self.outcome_prune_count
5146            .set(self.outcome_prune_count.get() + 1);
5147        let max_entries = self.limits.outcome_retention_max_entries.unwrap_or(1_000);
5148        let count = self
5149            .conn
5150            .query_row(
5151                "SELECT COUNT(*) FROM _syncular_commit_outcomes",
5152                [],
5153                |row| row.get::<_, i64>(0),
5154            )
5155            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5156            as usize;
5157        let excess = count.saturating_sub(max_entries);
5158        if excess == 0 {
5159            return Ok(());
5160        }
5161        let mut stmt = self
5162            .conn
5163            .prepare(
5164                "SELECT seq FROM _syncular_commit_outcomes
5165                  WHERE status IN ('applied', 'cached') OR resolution != 'active'
5166                  ORDER BY seq ASC LIMIT ?1",
5167            )
5168            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5169        let rows = stmt
5170            .query_map(rusqlite::params![excess as i64], |row| row.get::<_, i64>(0))
5171            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5172        let sequences = rows
5173            .collect::<Result<Vec<_>, _>>()
5174            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5175        drop(stmt);
5176        for sequence in sequences {
5177            self.conn
5178                .execute(
5179                    "DELETE FROM _syncular_commit_outcomes WHERE seq = ?1",
5180                    rusqlite::params![sequence],
5181                )
5182                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5183        }
5184        Ok(())
5185    }
5186
5187    // -- units (§4.1) ------------------------------------------------------------
5188
5189    /// Every registered unit in registration order (§4.1).
5190    pub fn units(&self) -> Result<Vec<UnitRecord>, String> {
5191        self.stored(load_units(&self.conn))
5192    }
5193
5194    pub fn unit(&self, id: &str) -> Result<Option<UnitRecord>, String> {
5195        self.stored(get_unit(&self.conn, id))
5196    }
5197
5198    /// Register one unit (§4.1) and return its id.
5199    pub fn subscribe(&mut self, scopes: UnitScopes) -> Result<String, String> {
5200        Ok(self.subscribe_many(vec![scopes])?.remove(0))
5201    }
5202
5203    /// Register several units in one local transaction and return their ids:
5204    /// one commit for all of them (on OPFS a commit costs milliseconds, so a
5205    /// cold start with hundreds of units pays it once). An error rolls back
5206    /// every registration of the call. Registering an active unit again
5207    /// changes nothing; a revoked unit re-arms (§3.3). A call that registers or
5208    /// re-arms a unit raises sync-needed with an interactive intent.
5209    pub fn subscribe_many(&mut self, units: Vec<UnitScopes>) -> Result<Vec<String>, String> {
5210        self.begin_observation("syncular_subscribe")?;
5211        let mut changed = false;
5212        let registered = (|| {
5213            let mut ids = Vec::with_capacity(units.len());
5214            for scopes in units {
5215                let (id, held) = self.hold_unit(scopes, true)?;
5216                changed |= held;
5217                ids.push(id);
5218            }
5219            self.conn
5220                .execute_batch("RELEASE syncular_subscribe")
5221                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5222            Ok(ids)
5223        })();
5224        let ids = match registered {
5225            Ok(ids) => ids,
5226            Err(error) => {
5227                self.rollback_observation("syncular_subscribe");
5228                return Err(error);
5229            }
5230        };
5231        if changed {
5232            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5233            self.set_sync_needed(true, true);
5234        }
5235        Ok(ids)
5236    }
5237
5238    /// Release the explicit reference to a unit. The unit leaves the
5239    /// registration list when no window base holds it (§4.1); its rows stay.
5240    pub fn unsubscribe(&mut self, id: &str) -> Result<(), String> {
5241        let Some(unit) = self.stored(get_unit(&self.conn, id))? else {
5242            return Ok(());
5243        };
5244        if !unit.explicit {
5245            return Ok(());
5246        }
5247        if !self.stored(window_refs(&self.conn, id))?.is_empty() {
5248            return self.stored(save_unit(
5249                &self.conn,
5250                &UnitRecord {
5251                    explicit: false,
5252                    ..unit
5253                },
5254            ));
5255        }
5256        self.conn
5257            .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5258            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5259        self.registration_epoch = self.registration_epoch.wrapping_add(1);
5260        if unit.status == UnitStatus::Active {
5261            self.set_sync_needed(true, true);
5262        }
5263        Ok(())
5264    }
5265
5266    /// Take one reference on a unit (§4.1): validate the scope map, register a
5267    /// new unit catching up with cursor `-1`, re-arm a revoked one (§3.3).
5268    /// Returns the id and whether the registration list changed.
5269    fn hold_unit(&mut self, scopes: UnitScopes, explicit: bool) -> Result<(String, bool), String> {
5270        if scopes.is_empty()
5271            || scopes.values().any(|value| value == "*")
5272            || !self
5273                .schema
5274                .tables
5275                .iter()
5276                .any(|table| covers(table, &scopes))
5277        {
5278            return Err("sync.invalid_subscription: a unit names one non-wildcard value per variable and covers a table".to_owned());
5279        }
5280        let id = ssp2::registration::unit_id(&scope_pairs(&scopes));
5281        let existing = self.stored(get_unit(&self.conn, &id))?;
5282        if let Some(existing) = existing
5283            .as_ref()
5284            .filter(|unit| unit.status != UnitStatus::Revoked)
5285        {
5286            if explicit && !existing.explicit {
5287                self.stored(save_unit(
5288                    &self.conn,
5289                    &UnitRecord {
5290                        explicit,
5291                        ..existing.clone()
5292                    },
5293                ))?;
5294            }
5295            return Ok((id, false));
5296        }
5297        self.delete_pending_evict(&id)?;
5298        self.stored(save_unit(
5299            &self.conn,
5300            &UnitRecord {
5301                id: id.clone(),
5302                scopes,
5303                explicit: explicit || existing.is_some_and(|unit| unit.explicit),
5304                status: UnitStatus::Active,
5305                reason_code: None,
5306                cursor: Some(-1),
5307                bootstrap_state: None,
5308                seeded: Vec::new(),
5309                echo: None,
5310            },
5311        ))?;
5312        Ok((id, true))
5313    }
5314
5315    // -- windows (§4.8) -----------------------------------------------------------
5316
5317    /// §4.8: set the windowed-in values of a base, one unit per value. Added
5318    /// values take a reference on their unit (a new unit bootstraps on the
5319    /// next sync); removed values release theirs, and a unit no reference
5320    /// holds leaves the registration list fused with its first eviction chunk
5321    /// (E1–E4). Idempotent; re-entry cancels a deferred eviction.
5322    pub fn set_window(
5323        &mut self,
5324        base: &WindowBase,
5325        units: &[String],
5326    ) -> Result<CommandEffects, String> {
5327        let base_key = window_base_key(base);
5328        let live = self.load_window_units(&base_key)?;
5329        let mut changed = false;
5330        for value in units {
5331            if live.iter().any(|(held, _)| held == value) {
5332                continue;
5333            }
5334            let rollback = self.capture();
5335            self.begin_observation("syncular_window")?;
5336            let widened = (|| {
5337                let (id, registered) = self.hold_unit(window_unit_scopes(base, value), false)?;
5338                self.sync_needed |= registered;
5339                self.conn
5340                    .execute(
5341                        "INSERT OR REPLACE INTO _syncular_windows(base, unit, sub_id) VALUES (?1, ?2, ?3)",
5342                        rusqlite::params![base_key, value, id],
5343                    )
5344                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5345                let mut batch = ChangeAccumulator::default();
5346                batch.window(&base_key, value);
5347                batch.status = true;
5348                self.finish_observation("syncular_window", batch)
5349            })();
5350            if let Err(error) = widened {
5351                self.rollback_observation("syncular_window");
5352                self.restore(rollback);
5353                return Err(error);
5354            }
5355            changed = true;
5356            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5357        }
5358        for (value, id) in live {
5359            if units.contains(&value) {
5360                continue;
5361            }
5362            self.rebuild_overlay_if_dirty()?;
5363            let rollback = self.capture();
5364            self.begin_observation("syncular_window")?;
5365            let remaining = self.release_window_unit(&base_key, &value, &id);
5366            let remaining = match remaining {
5367                Ok(remaining) => remaining,
5368                Err(error) => {
5369                    self.rollback_observation("syncular_window");
5370                    self.restore(rollback);
5371                    return Err(error);
5372                }
5373            };
5374            changed = true;
5375            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5376            if remaining {
5377                self.drain_pending_evictions()?;
5378            }
5379        }
5380        Ok(if changed && self.transport_enabled {
5381            CommandEffects::interactive()
5382        } else {
5383            CommandEffects::none()
5384        })
5385    }
5386
5387    /// §4.8 completeness oracle: the windowed-in values of a base and those
5388    /// whose unit is not complete. A value is complete once its unit is active
5389    /// and no longer bootstrapping; registration alone is not completeness.
5390    pub fn window_state(&self, base: &WindowBase) -> Result<WindowState, String> {
5391        persisted_window_state(&self.conn, base).map_err(|failure| failure.message)
5392    }
5393
5394    /// Registry rows for a base, ordered by value: (value, unit id).
5395    fn load_window_units(&self, base_key: &str) -> Result<Vec<(String, String)>, String> {
5396        let mut statement = self
5397            .conn
5398            .prepare_cached(
5399                "SELECT unit, sub_id FROM _syncular_windows WHERE base = ?1 ORDER BY unit ASC",
5400            )
5401            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5402        let rows = statement
5403            .query_map([base_key], |row| Ok((row.get(0)?, row.get(1)?)))
5404            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5405        rows.collect::<Result<_, _>>()
5406            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5407    }
5408
5409    /// Every window registry row: (base key, value).
5410    fn load_window_registry(&self) -> Result<Vec<(String, String)>, String> {
5411        let mut statement = self
5412            .conn
5413            .prepare_cached("SELECT base, unit FROM _syncular_windows ORDER BY base, unit")
5414            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5415        let rows = statement
5416            .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
5417            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5418        rows.collect::<Result<_, _>>()
5419            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5420    }
5421
5422    /// §4.8: release a window value's reference inside the caller's
5423    /// observation. When no reference holds the unit, unregister it fused with
5424    /// its first eviction chunk (E3): delete the rows of every covered table
5425    /// matching the persisted echo, except rows pinned by the outbox (E1) or
5426    /// owned by another unit (§3.3), and park the per-table scopes of what
5427    /// remains in the pending-eviction registry. Fails closed without a local
5428    /// scope-column mapping. Returns whether unpinned rows remain.
5429    fn release_window_unit(
5430        &mut self,
5431        base_key: &str,
5432        value: &str,
5433        id: &str,
5434    ) -> Result<bool, String> {
5435        self.conn
5436            .execute(
5437                "DELETE FROM _syncular_windows WHERE base = ?1 AND unit = ?2",
5438                rusqlite::params![base_key, value],
5439            )
5440            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5441        let mut batch = ChangeAccumulator::default();
5442        batch.window(base_key, value);
5443        batch.status = true;
5444        let unit = self.stored(get_unit(&self.conn, id))?;
5445        let mut remaining = false;
5446        if let Some(unit) = unit.filter(|unit| !unit.explicit) {
5447            if self.stored(window_refs(&self.conn, id))?.is_empty() {
5448                let units = self.stored(load_units(&self.conn))?;
5449                self.conn
5450                    .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5451                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5452                self.sync_needed = true;
5453                for table in self.schema.tables.clone() {
5454                    let Some(effective) = unit
5455                        .echo
5456                        .as_deref()
5457                        .filter(|_| covers(&table, &unit.scopes))
5458                        .and_then(|echo| pair_scopes(&unit.scopes, &table.name, Some(echo)))
5459                    else {
5460                        continue;
5461                    };
5462                    let pinned = self.pinned_row_ids(&table.name);
5463                    let owners = unit_owners(&units, &table, id);
5464                    let (more, deferred) =
5465                        self.evict_scope_rows(&table.name, &effective, &owners, &pinned)?;
5466                    remaining |= more;
5467                    if deferred {
5468                        self.save_pending_evict(id, &table.name, &effective)?;
5469                    }
5470                    self.record_scope_map(&mut batch, &table.name, &effective);
5471                }
5472            }
5473        }
5474        self.finish_observation("syncular_window", batch)?;
5475        Ok(remaining)
5476    }
5477
5478    /// §4.8 E1: delete base rows owned by the effective scopes
5479    /// ([`local_scope_predicate`]) EXCEPT pinned primary keys. Returns (more
5480    /// unpinned work, any scoped rows remain). A missing scope-column mapping
5481    /// fails without deleting rows.
5482    fn evict_scope_rows(
5483        &self,
5484        table_name: &str,
5485        effective: &[(String, Vec<String>)],
5486        owners: &[Vec<(String, Vec<String>)>],
5487        pinned: &std::collections::HashSet<String>,
5488    ) -> Result<(bool, bool), String> {
5489        let table = self.schema.table(table_name).ok_or("sync.unknown_table")?;
5490        let Some((scope, mut params)) = local_scope_predicate(table, effective, owners)
5491            .map_err(|()| "sync.scope_revoked".to_owned())?
5492        else {
5493            return Ok((false, false));
5494        };
5495        let scope_params = params.len();
5496        let pk = quote_ident(&table.primary_key);
5497        // Pinned ids are rowId text; the text form matches every key type.
5498        let predicate = if pinned.is_empty() {
5499            scope.clone()
5500        } else {
5501            params.extend(pinned.iter().cloned().map(SqlValue::Text));
5502            let holes = vec!["?"; pinned.len()].join(", ");
5503            format!("{scope} AND CAST({pk} AS TEXT) NOT IN ({holes})")
5504        };
5505        let base = base_table(table_name);
5506        let visible = visible_table(table_name);
5507        let mut ids: Vec<SqlValue> = Vec::new();
5508        for source in [&base, &visible] {
5509            let mut stmt = self
5510                .conn
5511                .prepare_cached(&format!(
5512                    "SELECT {pk} FROM {source} WHERE {predicate} LIMIT 1024"
5513                ))
5514                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5515            ids = stmt
5516                .query_map(rusqlite::params_from_iter(&params), |row| row.get(0))
5517                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5518                .collect::<Result<_, _>>()
5519                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5520            if !ids.is_empty() {
5521                break;
5522            }
5523        }
5524        if !ids.is_empty() {
5525            for id in &ids {
5526                self.conn
5527                    .execute(
5528                        "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2",
5529                        rusqlite::params![table_name, id],
5530                    )
5531                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5532            }
5533            let holes = vec!["?"; ids.len()].join(", ");
5534            for source in [&base, &visible] {
5535                self.conn
5536                    .execute(
5537                        &format!("DELETE FROM {source} WHERE {pk} IN ({holes})"),
5538                        rusqlite::params_from_iter(&ids),
5539                    )
5540                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5541            }
5542        }
5543        let mut remaining = false;
5544        let mut deferred = false;
5545        for source in [&base, &visible] {
5546            remaining |= self
5547                .conn
5548                .query_row(
5549                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
5550                    rusqlite::params_from_iter(&params),
5551                    |row| row.get::<_, bool>(0),
5552                )
5553                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5554            deferred |= self
5555                .conn
5556                .query_row(
5557                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {scope})"),
5558                    rusqlite::params_from_iter(&params[..scope_params]),
5559                    |row| row.get::<_, bool>(0),
5560                )
5561                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5562        }
5563        Ok((remaining, deferred))
5564    }
5565
5566    /// §4.8 E1: continue deferred evictions after the outbox drains or between
5567    /// chunks, retaining outbox pins and their durable marker. A unit that
5568    /// re-entered the window has no pending entry left.
5569    fn drain_pending_evictions(&mut self) -> Result<(), String> {
5570        let pending = self.load_pending_evictions()?;
5571        if pending.is_empty() {
5572            return Ok(());
5573        }
5574        self.rebuild_overlay_if_dirty()?;
5575        for (unit_id, table_name, effective) in pending {
5576            let Some(table) = self.schema.table(&table_name).cloned() else {
5577                self.delete_pending_evict_table(&unit_id, &table_name)?;
5578                continue;
5579            };
5580            loop {
5581                std::thread::yield_now();
5582                self.begin_observation("syncular_evict")?;
5583                let chunk = (|| {
5584                    let pinned = self.pinned_row_ids(&table_name);
5585                    let owners =
5586                        unit_owners(&self.stored(load_units(&self.conn))?, &table, &unit_id);
5587                    let (remaining, deferred) =
5588                        self.evict_scope_rows(&table_name, &effective, &owners, &pinned)?;
5589                    if !deferred {
5590                        self.delete_pending_evict_table(&unit_id, &table_name)?;
5591                    }
5592                    let mut batch = ChangeAccumulator::default();
5593                    self.record_scope_map(&mut batch, &table_name, &effective);
5594                    self.finish_observation("syncular_evict", batch)?;
5595                    Ok(remaining)
5596                })();
5597                match chunk {
5598                    Ok(true) => {}
5599                    Ok(false) => break,
5600                    Err(error) => {
5601                        self.rollback_observation("syncular_evict");
5602                        return Err(error);
5603                    }
5604                }
5605            }
5606        }
5607        Ok(())
5608    }
5609
5610    /// §4.8 E1: primary keys of `table` referenced by a pending outbox
5611    /// commit — rows that MUST NOT be evicted until the commit drains.
5612    fn pinned_row_ids(&self, table: &str) -> std::collections::HashSet<String> {
5613        let mut pinned = std::collections::HashSet::new();
5614        for commit in self
5615            .outbox
5616            .iter()
5617            .map(|commit| &**commit)
5618            .chain(self.failed_commits.iter().map(|(commit, _)| commit))
5619        {
5620            for op in &commit.ops {
5621                if op.table == table {
5622                    pinned.insert(op.row_id.clone());
5623                }
5624            }
5625        }
5626        pinned
5627    }
5628
5629    fn save_pending_evict(
5630        &self,
5631        unit_id: &str,
5632        table: &str,
5633        effective: &[(String, Vec<String>)],
5634    ) -> Result<(), String> {
5635        self.conn.execute(
5636            "INSERT OR REPLACE INTO _syncular_pending_evictions(unit_id, tbl, effective_scopes) VALUES (?1, ?2, ?3)",
5637            rusqlite::params![unit_id, table, scope_map_to_json(effective).to_string()],
5638        ).map(|_| ()).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5639    }
5640
5641    /// Re-entry cancels every pending eviction of the unit.
5642    fn delete_pending_evict(&self, unit_id: &str) -> Result<(), String> {
5643        self.conn
5644            .execute(
5645                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
5646                [unit_id],
5647            )
5648            .map(|_| ())
5649            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5650    }
5651
5652    fn delete_pending_evict_table(&self, unit_id: &str, table: &str) -> Result<(), String> {
5653        self.conn
5654            .execute(
5655                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1 AND tbl = ?2",
5656                [unit_id, table],
5657            )
5658            .map(|_| ())
5659            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5660    }
5661
5662    fn load_pending_evictions(&self) -> Result<Vec<PendingEvict>, String> {
5663        let mut stmt = self
5664            .conn
5665            .prepare("SELECT unit_id, tbl, effective_scopes FROM _syncular_pending_evictions")
5666            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5667        let rows = stmt
5668            .query_map([], |row| {
5669                Ok((
5670                    row.get::<_, String>(0)?,
5671                    row.get::<_, String>(1)?,
5672                    row.get::<_, String>(2)?,
5673                ))
5674            })
5675            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5676        rows.map(|row| {
5677            let (unit_id, table, json) =
5678                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5679            let value: Value = serde_json::from_str(&json)
5680                .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5681            let effective = json_to_scope_map(&value)
5682                .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5683            Ok((unit_id, table, effective))
5684        })
5685        .collect()
5686    }
5687
5688    /// Select failed-intent retention; reload durable retained aggregates.
5689    pub fn set_retain_failed_commits(&mut self, enabled: bool) -> Result<(), String> {
5690        self.retain_failed_commits = enabled;
5691        for (commit, _) in self.failed_commits.iter() {
5692            for operation in &commit.ops {
5693                self.overlay_dirty.table(&operation.table);
5694            }
5695        }
5696        self.failed_commits = self.load_failed_commits()?.into();
5697        for (commit, _) in self.failed_commits.iter() {
5698            for operation in &commit.ops {
5699                self.overlay_dirty.table(&operation.table);
5700            }
5701        }
5702        Ok(())
5703    }
5704
5705    fn load_failed_commits(&self) -> Result<Vec<FailedCommit>, String> {
5706        let mut statement = self.conn.prepare("SELECT client_commit_id, operations_json, initial_json FROM _syncular_failed_commits ORDER BY seq")
5707            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5708        let rows = statement
5709            .query_map([], |row| {
5710                Ok((
5711                    row.get::<_, String>(0)?,
5712                    row.get::<_, String>(1)?,
5713                    row.get::<_, String>(2)?,
5714                ))
5715            })
5716            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5717        rows.map(|row| {
5718            let (id, operations, initial) =
5719                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5720            let operations: Vec<CommitOperation> =
5721                serde_json::from_str(&operations).map_err(|_| "sync.local_corrupt".to_owned())?;
5722            let initial =
5723                serde_json::from_str(&initial).map_err(|_| "sync.local_corrupt".to_owned())?;
5724            Ok((
5725                OutboxCommit {
5726                    client_commit_id: id,
5727                    ops: operations
5728                        .into_iter()
5729                        .map(|op| OutboxOp {
5730                            upsert: op.op == "upsert",
5731                            table: op.table,
5732                            row_id: op.row_id,
5733                            base_version: op.base_version,
5734                            values: op.values,
5735                            insert: op.insert,
5736                        })
5737                        .collect(),
5738                },
5739                initial,
5740            ))
5741        })
5742        .collect()
5743    }
5744
5745    fn retain_failed_commit(&mut self, id: &str, operations: &[OutboxOp]) -> Result<(), String> {
5746        let mut initial = Map::new();
5747        for operation in operations {
5748            // A table the current schema removed has no rows to retain.
5749            let Some(table) = self.schema.table(&operation.table) else {
5750                continue;
5751            };
5752            let initial_row = match self.stored_row(table, &operation.row_id, true)? {
5753                Some(row) => Some(row),
5754                None => self.visible_row(table, &operation.row_id)?,
5755            };
5756            if let Some((values, _)) = initial_row {
5757                let mut intended: Map<String, Value> = table
5758                    .columns
5759                    .iter()
5760                    .zip(values.iter())
5761                    .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
5762                    .collect();
5763                if let Some(patch) = &operation.values {
5764                    intended.extend(patch.clone());
5765                }
5766                initial.insert(
5767                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5768                        .map_err(|_| "sync.local_corrupt".to_owned())?,
5769                    Value::Object(intended),
5770                );
5771            }
5772        }
5773        self.conn.execute("INSERT INTO _syncular_failed_commits(client_commit_id, operations_json, initial_json) VALUES (?1, ?2, ?3)", rusqlite::params![id,
5774            serde_json::to_string(&operations.iter().map(CommitOperation::from).collect::<Vec<_>>()).map_err(|_| "sync.local_corrupt".to_owned())?,
5775            serde_json::to_string(&initial).map_err(|_| "sync.local_corrupt".to_owned())?])
5776            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5777        self.failed_commits.push((
5778            OutboxCommit {
5779                client_commit_id: id.to_owned(),
5780                ops: operations.to_vec(),
5781            },
5782            initial,
5783        ));
5784        Ok(())
5785    }
5786
5787    fn drop_failed_commits(
5788        &mut self,
5789        matches: impl Fn(&str, &Map<String, Value>) -> bool,
5790    ) -> Result<Vec<OutboxCommit>, String> {
5791        let mut doomed = self.drop_acknowledged_rows(&matches)?;
5792        for (commit, initial) in self.failed_commits.iter() {
5793            for operation in &commit.ops {
5794                let key =
5795                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5796                        .map_err(|_| "sync.local_corrupt".to_owned())?;
5797                if initial
5798                    .get(&key)
5799                    .and_then(Value::as_object)
5800                    .is_some_and(|values| matches(&operation.table, values))
5801                {
5802                    doomed.push(commit.clone());
5803                    break;
5804                }
5805            }
5806        }
5807        for commit in &doomed {
5808            self.conn
5809                .execute(
5810                    "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
5811                    rusqlite::params![commit.client_commit_id],
5812                )
5813                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5814        }
5815        for commit in &doomed {
5816            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))?;
5817        }
5818        self.conflicts.retain(|record| {
5819            !doomed
5820                .iter()
5821                .any(|commit| commit.client_commit_id == record.client_commit_id)
5822        });
5823        self.rejections.retain(|record| {
5824            !doomed
5825                .iter()
5826                .any(|commit| commit.client_commit_id == record.client_commit_id)
5827        });
5828        self.failed_commits.retain(|(commit, _)| {
5829            !doomed
5830                .iter()
5831                .any(|dropped| dropped.client_commit_id == commit.client_commit_id)
5832        });
5833        for commit in &doomed {
5834            for operation in &commit.ops {
5835                self.overlay_dirty.table(&operation.table);
5836            }
5837        }
5838        Ok(doomed)
5839    }
5840
5841    /// Record one commit of local mutations. The returned commit ID is the
5842    /// §2.3 idempotency key. Failures are structured so callers read
5843    /// `code`/`message`/`details` instead of parsing a string prefix.
5844    pub fn mutate(&mut self, mutations: Vec<Mutation>) -> Result<String, ClientError> {
5845        self.mutate_with_commit_id(mutations, None)
5846    }
5847
5848    /// [`Self::mutate`] under a caller-supplied `clientCommitId` (§7.1), so an
5849    /// app that loses the reply knows its commit. The ID is non-empty (§6.1);
5850    /// one this replica still holds fails with `client.commit_id_reused`.
5851    pub fn mutate_with_commit_id(
5852        &mut self,
5853        mutations: Vec<Mutation>,
5854        client_commit_id: Option<String>,
5855    ) -> Result<String, ClientError> {
5856        let prior = self.storage_failure.borrow_mut().take();
5857        if let Some(id) = &client_commit_id {
5858            let held = if id.is_empty() {
5859                Err("sync.invalid_request: clientCommitId is empty".to_owned())
5860            } else {
5861                self.conn
5862                    .query_row(
5863                        "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id=?1 UNION ALL SELECT 1 FROM _syncular_commit_outcomes WHERE client_commit_id=?1)",
5864                        [id],
5865                        |row| row.get(0),
5866                    )
5867                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5868            };
5869            match held {
5870                Ok(false) => {}
5871                Ok(true) => {
5872                    return self.finish_authoring(
5873                        prior,
5874                        Err(ClientError {
5875                            code: "client.commit_id_reused".to_owned(),
5876                            message: "clientCommitId is held".to_owned(),
5877                            details: Some(json!({ "clientCommitId": id })),
5878                            retryable: false,
5879                        }),
5880                    )
5881                }
5882                Err(message) => return self.finish_authoring(prior, Err(message.into())),
5883            }
5884        }
5885        let outcome = (|| -> Result<String, ClientError> {
5886            if mutations.is_empty() {
5887                return Err(
5888                    "sync.invalid_request: a commit must contain at least one operation (§6.1)"
5889                        .to_owned()
5890                        .into(),
5891                );
5892            }
5893            let mut ops = Vec::with_capacity(mutations.len());
5894            for mutation in mutations {
5895                match mutation {
5896                    Mutation::Patch {
5897                        table,
5898                        values,
5899                        base_version,
5900                    } => {
5901                        let schema_table = self
5902                            .schema
5903                            .table(&table)
5904                            .ok_or_else(|| "sync.unknown_table".to_owned())?;
5905                        let values = normalize_values_casing(schema_table, values)?;
5906                        let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
5907                        ops.push(self.prepare_patch(&table, &row_id, values, base_version)?);
5908                    }
5909                    Mutation::Upsert {
5910                        table,
5911                        values,
5912                        base_version,
5913                    } => {
5914                        let schema_table = self.schema.table(&table).ok_or_else(|| {
5915                            format!("sync.unknown_table: unknown table {table:?}")
5916                        })?;
5917                        // §5: value keys are accepted in snake_case AND the
5918                        // generated row types' camelCase; normalize to SQL truth
5919                        // before the pk lookup / codec see them.
5920                        let values = normalize_values_casing(schema_table, values)?;
5921                        let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
5922                        // §6.7 `mutate` marks every column present: fill missing
5923                        // nullable columns with NULL before the payload is built.
5924                        let values = full_row_values(schema_table, values)?;
5925                        self.refuse_sealed_row(schema_table, &row_id)?;
5926                        // §5.11: validate the payload encodes with the current
5927                        // codec. A key-selection or unknown-key failure is a
5928                        // durable rejection at the push seam (§10.3), never an
5929                        // author-time error. Full-row `mutate` presents every
5930                        // column, so no stored fallback is needed.
5931                        self.validate_author_encode(schema_table, &row_id, &values)?;
5932                        // §7.1 insert intent: the row is absent from the
5933                        // visible replica at call time, before this batch
5934                        // applies anything.
5935                        let insert = !self.visible_row_exists(schema_table, &row_id)?;
5936                        ops.push(OutboxOp {
5937                            upsert: true,
5938                            table,
5939                            row_id,
5940                            base_version,
5941                            values: Some(values),
5942                            insert,
5943                        });
5944                    }
5945                    Mutation::Delete {
5946                        table,
5947                        row_id,
5948                        base_version,
5949                    } => {
5950                        let schema_table = self.schema.table(&table).ok_or_else(|| {
5951                            format!("sync.unknown_table: unknown table {table:?}")
5952                        })?;
5953                        self.refuse_sealed_row(schema_table, &row_id)?;
5954                        // §2.4: the server rejects a rowId holding U+0000.
5955                        if row_id.contains('\0') {
5956                            return Err("sync.invalid_request: rowId holds U+0000 (§2.4)"
5957                                .to_owned()
5958                                .into());
5959                        }
5960                        ops.push(OutboxOp {
5961                            upsert: false,
5962                            table,
5963                            row_id,
5964                            base_version,
5965                            values: None,
5966                            insert: false,
5967                        });
5968                    }
5969                }
5970            }
5971            Ok(self.record_outbox_commit(ops, client_commit_id)?)
5972        })();
5973        self.finish_authoring(prior, outcome)
5974    }
5975
5976    /// Scope the retained `storage_failure` diagnostic to this call so an
5977    /// earlier operation's failure cannot classify a new one, and surface the
5978    /// call's own classified failure with its details. A fresh classified
5979    /// failure replaces the retained diagnostic; otherwise the earlier one is
5980    /// kept for the next sync.
5981    fn finish_authoring(
5982        &self,
5983        prior: Option<QueryReadFailure>,
5984        outcome: Result<String, ClientError>,
5985    ) -> Result<String, ClientError> {
5986        let fresh = self.storage_failure.borrow_mut().take();
5987        *self.storage_failure.borrow_mut() = fresh.clone().or(prior);
5988        outcome.map_err(|error| fresh.map(ClientError::from).unwrap_or(error))
5989    }
5990
5991    fn record_outbox_commit(
5992        &mut self,
5993        ops: Vec<OutboxOp>,
5994        client_commit_id: Option<String>,
5995    ) -> Result<String, String> {
5996        let commit = OutboxCommit {
5997            client_commit_id: client_commit_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
5998            ops,
5999        };
6000        self.begin_observation("syncular_mutation")?;
6001        let mut batch = ChangeAccumulator::default();
6002        for op in &commit.ops {
6003            let mut precise = self.record_row_scopes(&mut batch, &op.table, &op.row_id, false);
6004            if let Some(values) = &op.values {
6005                if let Some(table) = self.schema.table(&op.table) {
6006                    for scope in &table.scope_variables {
6007                        if let Some(Value::String(value)) = values.get(&scope.column) {
6008                            batch.scope(&op.table, format!("{}:{value}", scope.prefix));
6009                            precise = true;
6010                        }
6011                    }
6012                }
6013            }
6014            if !precise {
6015                batch.table(&op.table);
6016            }
6017        }
6018        if let Err(error) = self.persist_outbox_insert(&commit) {
6019            self.rollback_observation("syncular_mutation");
6020            return Err(error);
6021        }
6022        // A clean overlay contains the FIFO fold of every previous commit, so
6023        // the new commit applies over it. §7.1: an operation that does not
6024        // apply (a secondary unique collision) fails the whole commit; the
6025        // savepoint rollback removes the outbox entry and every visible write.
6026        // The append undoes itself: a rollback capture would copy the outbox.
6027        let was_dirty = self.overlay_dirty.snapshot();
6028        let id = commit.client_commit_id.clone();
6029        let appended = self.rebuild_overlay_if_dirty().and_then(|()| {
6030            commit
6031                .ops
6032                .iter()
6033                .try_for_each(|op| self.apply_outbox_op(op))?;
6034            self.outbox.push(Arc::new(commit));
6035            batch.status = true;
6036            self.finish_observation("syncular_mutation", batch)
6037                .inspect_err(|_| drop(self.outbox.pop()))
6038        });
6039        if let Err(error) = appended {
6040            self.rollback_observation("syncular_mutation");
6041            self.overlay_dirty.restore(was_dirty);
6042            return Err(error);
6043        }
6044        Ok(id)
6045    }
6046
6047    /// Record one §6.1 sparse upsert: the primary key plus the supplied
6048    /// non-scope columns are present; every other column is absent and stays
6049    /// untouched on the server and in the local overlay. An absent local base
6050    /// refuses the whole batch with sync.row_missing before enqueueing (§7.1).
6051    /// Failures are structured so callers read `code`/`message`/`details`.
6052    pub fn patch(
6053        &mut self,
6054        table: &str,
6055        row_id: &str,
6056        partial: Map<String, Value>,
6057        base_version: Option<i64>,
6058    ) -> Result<String, ClientError> {
6059        let prior = self.storage_failure.borrow_mut().take();
6060        let outcome = self.perform_patch(table, row_id, partial, base_version);
6061        self.finish_authoring(prior, outcome)
6062    }
6063
6064    /// The unscoped patch body. Public authoring entry points scope
6065    /// `storage_failure` around the whole operation, including any pre-read.
6066    fn perform_patch(
6067        &mut self,
6068        table: &str,
6069        row_id: &str,
6070        partial: Map<String, Value>,
6071        base_version: Option<i64>,
6072    ) -> Result<String, ClientError> {
6073        let operation = self.prepare_patch(table, row_id, partial, base_version)?;
6074        Ok(self.record_outbox_commit(vec![operation], None)?)
6075    }
6076
6077    fn prepare_patch(
6078        &self,
6079        table: &str,
6080        row_id: &str,
6081        partial: Map<String, Value>,
6082        base_version: Option<i64>,
6083    ) -> Result<OutboxOp, ClientError> {
6084        let schema_table = self
6085            .schema
6086            .table(table)
6087            .ok_or_else(|| format!("sync.unknown_table: unknown table {table:?}"))?;
6088        let partial = normalize_values_casing(schema_table, partial)?;
6089        if let Some(pk) = partial.get(&schema_table.primary_key) {
6090            if render_row_id_json(Some(pk)).ok().as_deref() != Some(row_id) {
6091                return Err(invalid_authoring(
6092                    "patch cannot change the primary key",
6093                    json!({ "table": table }),
6094                ));
6095            }
6096        }
6097        if !self.visible_row_exists(schema_table, row_id)? {
6098            return Err("sync.row_missing: a sparse patch requires a local row"
6099                .to_owned()
6100                .into());
6101        }
6102        self.refuse_sealed_row(schema_table, row_id)?;
6103        // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
6104        // server accepts a present scope column whose value equals the
6105        // stored row and applies it as a no-op, so a decoded envelope
6106        // round-trips. The local row is the only value the client can prove
6107        // equality against; when the row is absent locally the client cannot
6108        // prove equality against the server's stored row and fails closed.
6109        // A primary key that is also a scope column needs no stored-row
6110        // read: the primary key in a sparse payload is by construction the
6111        // row id being patched (§6.1), so its value is proven equal already.
6112        for scope in &schema_table.scope_variables {
6113            if !partial.contains_key(&scope.column) || scope.column == schema_table.primary_key {
6114                continue;
6115            }
6116            let Some(column) = schema_table
6117                .columns
6118                .iter()
6119                .find(|column| column.name == scope.column)
6120            else {
6121                continue;
6122            };
6123            let stored = self
6124                .conn
6125                .query_row(
6126                    &format!(
6127                        "SELECT {} FROM {} WHERE {}",
6128                        quote_ident(&scope.column),
6129                        visible_table(&schema_table.name),
6130                        row_id_predicate(schema_table)
6131                    ),
6132                    rusqlite::params![row_id],
6133                    |row| Ok(sql_ref_to_json(column, row.get_ref(0)?)),
6134                )
6135                .optional()
6136                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6137            // Decode the supplied value through the same column-type path the
6138            // rest of the patch encoding uses, so a value that only equals
6139            // the stored one in another number representation still compares
6140            // equal.
6141            let incoming = json_to_column_value(column, partial.get(&scope.column))
6142                .ok()
6143                .map(|value| column_value_to_json(&value));
6144            // A stored blob never equals a patch value, matching the server's
6145            // scope-column comparison (§3.4): bytes are unstorable as scope
6146            // values.
6147            let equal = stored.as_ref().is_some_and(|stored| {
6148                stored.get("$bytes").is_none() && incoming.as_ref() == Some(stored)
6149            });
6150            if !equal {
6151                return Err(invalid_authoring(
6152                    "patch cannot write a scope column (§3.4)",
6153                    json!({ "table": table, "column": scope.column }),
6154                ));
6155            }
6156        }
6157        let mut values = partial;
6158        // Presence-set semantics: a proven-equal scope column is dropped, so
6159        // the patch leaves the stored value untouched (§6.2).
6160        for scope in &schema_table.scope_variables {
6161            values.remove(&scope.column);
6162        }
6163        let pk_value = match schema_table.columns[schema_table.pk_index].ty {
6164            // §2.4: the rowId of an integer key is its canonical decimal form.
6165            ColumnType::Integer => match row_id.parse::<i64>() {
6166                Ok(v)
6167                    if v.to_string() == row_id
6168                        && (-ssp2::primitives::I64_SAFE_MAX..=ssp2::primitives::I64_SAFE_MAX)
6169                            .contains(&v) =>
6170                {
6171                    Value::from(v)
6172                }
6173                _ => {
6174                    return Err(format!(
6175                    "sync.invalid_request: table {table:?}: invalid integer primary key {row_id:?}"
6176                )
6177                    .into())
6178                }
6179            },
6180            ColumnType::Boolean => match row_id {
6181                "true" => Value::Bool(true),
6182                "false" => Value::Bool(false),
6183                _ => {
6184                    return Err(format!(
6185                    "sync.invalid_request: table {table:?}: invalid boolean primary key {row_id:?}"
6186                )
6187                    .into())
6188                }
6189            },
6190            _ => Value::from(row_id.to_owned()),
6191        };
6192        values.insert(schema_table.primary_key.clone(), pk_value);
6193        // §6.1: a patch cannot null a non-nullable column.
6194        if let Some(column) = schema_table
6195            .columns
6196            .iter()
6197            .find(|column| !column.nullable && values.get(&column.name) == Some(&Value::Null))
6198        {
6199            return Err(invalid_authoring(
6200                "a non-nullable column is null (§6.1)",
6201                json!({ "table": table, "column": column.name }),
6202            ));
6203        }
6204        // §5.11: structural validation only; an absent key-id selector is
6205        // resolved at the push seam from the stored local row, and a
6206        // key-selection or unknown-key failure becomes a durable
6207        // `client.encrypt_failed` rejection there (§10.3), never an
6208        // author-time error.
6209        self.validate_author_encode(schema_table, row_id, &values)?;
6210        Ok(OutboxOp {
6211            upsert: true,
6212            table: table.to_owned(),
6213            row_id: row_id.to_owned(),
6214            base_version,
6215            values: Some(values),
6216            insert: false,
6217        })
6218    }
6219
6220    /// §5.11 key-id fallback: the stored local row's selector value as a
6221    /// positional row (only the selector slot filled). Returns None when no
6222    /// selector is configured, the row is locally absent, or the stored
6223    /// value is not a usable key id. A failed storage read is an error.
6224    fn stored_key_fallback(
6225        &self,
6226        table: &TableSchema,
6227        row_id: &str,
6228    ) -> Result<Option<Row>, String> {
6229        let Some(selector) = self.encryption.key_id_columns.get(&table.name) else {
6230            return Ok(None);
6231        };
6232        let Some(index) = table
6233            .columns
6234            .iter()
6235            .position(|column| &column.name == selector)
6236        else {
6237            return Ok(None);
6238        };
6239        let sql = format!(
6240            "SELECT {} FROM {} WHERE {}",
6241            quote_ident(selector),
6242            visible_table(&table.name),
6243            row_id_predicate(table)
6244        );
6245        let key = self
6246            .conn
6247            .query_row(&sql, rusqlite::params![row_id], |row| {
6248                row.get::<_, Option<String>>(0)
6249            })
6250            .optional()
6251            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6252            .flatten()
6253            .filter(|key| !key.is_empty());
6254        let Some(key) = key else {
6255            return Ok(None);
6256        };
6257        let mut fallback: Row = vec![None; table.columns.len()];
6258        fallback[index] = Some(ColumnValue::String(key));
6259        Ok(Some(fallback))
6260    }
6261
6262    /// §5.11/§10.3 author-time encode check: a structural failure (a
6263    /// non-nullable NULL, a value the codec rejects) is an author-time
6264    /// error; a key-selection or unknown-key failure is deferred to the push
6265    /// seam, where it becomes a durable `client.encrypt_failed` rejection.
6266    fn validate_author_encode(
6267        &self,
6268        table: &TableSchema,
6269        row_id: &str,
6270        values: &Map<String, Value>,
6271    ) -> Result<(), String> {
6272        match encode_sparse_row_json(table, row_id, values, &self.encryption, None) {
6273            Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => Ok(()),
6274            result => result.map(|_| ()),
6275        }
6276    }
6277
6278    /// §5.11/§10.3: drop every pending commit whose push encode fails with
6279    /// `client.encrypt_failed` (an unresolvable key id or an unknown key) and
6280    /// raise one durable rejection per commit. `sync()` never aborts for an
6281    /// encode failure. Mirrors §7.4.4's `drop_incompatible_outbox`, including
6282    /// undoing the dropped commit's purely-optimistic rows.
6283    /// §7.1/§7.4.4: drop pending commits whose values the current codec refuses
6284    /// (an envelope or a type an earlier version accepted). `with_encryption`
6285    /// additionally drops commits whose §5.11 encryption cannot resolve a key;
6286    /// the startup boundary leaves those to the send seam, where hosts configure
6287    /// keys after open.
6288    /// Recovery runs as one observation. An enclosing observation (the guarded
6289    /// schema reset) passes its `batch`, so the rejection, outcome, and table
6290    /// domains join that change event instead of publishing a second one.
6291    fn drop_unencodable_outbox(
6292        &mut self,
6293        with_encryption: bool,
6294        batch: Option<&mut ChangeAccumulator>,
6295    ) -> Result<bool, String> {
6296        let mut failures = Vec::new();
6297        for commit in self.outbox.iter() {
6298            for op in &commit.ops {
6299                let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6300                    continue;
6301                };
6302                // An insert lacking a non-nullable column is left to
6303                // `drop_incompatible_outbox` (§7.4.4).
6304                let Some(values) = op.presented_values(table) else {
6305                    continue;
6306                };
6307                let fallback = self.stored_key_fallback(table, &op.row_id)?;
6308                let failure = match encode_sparse_row_json(
6309                    table,
6310                    &op.row_id,
6311                    &values,
6312                    &self.encryption,
6313                    fallback.as_ref(),
6314                ) {
6315                    Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => {
6316                        with_encryption.then_some((error, ENCRYPT_FAILED_CODE))
6317                    }
6318                    // §7.1/§7.4.4: a value the current codec refuses was
6319                    // persisted by a version that accepted it; it leaves
6320                    // through the incompatible-outbox path, so the FIFO
6321                    // queue never wedges.
6322                    Err(error) if error.starts_with(INVALID_REQUEST_CODE) => Some((
6323                        LEGACY_VALUE_REFUSAL_MESSAGE.to_owned(),
6324                        OUTBOX_INCOMPATIBLE_CODE,
6325                    )),
6326                    _ => None,
6327                };
6328                if let Some((error, code)) = failure {
6329                    failures.push((commit.clone(), error, code));
6330                    break;
6331                }
6332            }
6333        }
6334        if failures.is_empty() {
6335            return Ok(false);
6336        }
6337        // §7.4.4: one observation covers the durable outcome writes, the outbox
6338        // removal, the in-memory drop, and the overlay rebuild, so a storage fault
6339        // leaves the replica and the client unchanged, a successful recovery
6340        // publishes one batch with the rejection, outcome, and table domains, and
6341        // an ordinary open with nothing to recover publishes nothing.
6342        let rollback = self.capture();
6343        let owns_observation = batch.is_none();
6344        let owns_transaction = self.conn.is_autocommit();
6345        let mut domains = ChangeAccumulator::default();
6346        if owns_observation {
6347            self.begin_observation("syncular_value_recovery")?;
6348        }
6349        let dropped = (|| -> Result<(), String> {
6350            for (commit, message, code) in failures {
6351                if self.retain_failed_commits && code == ENCRYPT_FAILED_CODE {
6352                    self.retain_failed_commit(&commit.client_commit_id, &commit.ops)?;
6353                }
6354                let representable = commit.ops.iter().all(Self::outbox_op_is_journalable);
6355                let rejection = RejectionRecord {
6356                    client_commit_id: commit.client_commit_id.clone(),
6357                    op_index: 0,
6358                    code: code.to_owned(),
6359                    message,
6360                    retryable: false,
6361                    details: (code == OUTBOX_INCOMPATIBLE_CODE).then(|| RejectionDetails {
6362                        field_paths: None,
6363                        reason: Some(INVALID_STORED_VALUES_REASON.to_owned()),
6364                        required_action: None,
6365                        references: None,
6366                    }),
6367                    operation: representable
6368                        .then(|| commit.ops.first())
6369                        .flatten()
6370                        .map(CommitOperation::from),
6371                };
6372                self.persist_commit_outcome(
6373                    &commit.client_commit_id,
6374                    CommitOutcomeStatus::Rejected,
6375                    &[CommitOperationOutcome::Error {
6376                        rejection: rejection.clone(),
6377                    }],
6378                    representable.then_some(commit.ops.as_slice()),
6379                )?;
6380                self.delete_outbox_persisted(&commit.client_commit_id)?;
6381                self.outbox
6382                    .retain(|candidate| candidate.client_commit_id != commit.client_commit_id);
6383                self.rejections.push(rejection);
6384                for operation in &commit.ops {
6385                    domains.table(operation.table.as_str());
6386                }
6387            }
6388            domains.status = true;
6389            domains.rejections = true;
6390            domains.outcomes = true;
6391            self.prune_commit_outcomes()?;
6392            // The visible projection is re-derived from the surviving base + outbox.
6393            self.overlay_dirty.set(true);
6394            self.rebuild_overlay()?;
6395            Ok(())
6396        })();
6397        let result = match batch {
6398            Some(batch) => {
6399                if dropped.is_ok() {
6400                    for table in domains.tables.keys() {
6401                        batch.table(table.as_str());
6402                    }
6403                    batch.status |= domains.status;
6404                    batch.rejections |= domains.rejections;
6405                    batch.outcomes |= domains.outcomes;
6406                }
6407                dropped
6408            }
6409            None => {
6410                dropped.and_then(|()| self.finish_observation("syncular_value_recovery", domains))
6411            }
6412        };
6413        if let Err(error) = result {
6414            if owns_observation {
6415                if owns_transaction {
6416                    if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
6417                        let mut failure = self.storage_failure.borrow_mut();
6418                        let failure =
6419                            failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
6420                        failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
6421                    }
6422                } else {
6423                    self.rollback_observation("syncular_value_recovery");
6424                }
6425            }
6426            self.restore(rollback);
6427            return Err(error);
6428        }
6429        Ok(true)
6430    }
6431
6432    pub fn pending_commit_ids(&self) -> Vec<String> {
6433        self.outbox
6434            .iter()
6435            .map(|c| c.client_commit_id.clone())
6436            .collect()
6437    }
6438
6439    /// §6.1: the sparse push payload bytes of every pending upsert operation,
6440    /// FIFO — exactly what the next push round would put on the wire. Used by
6441    /// conformance B.21(h) to pin cross-core byte identity.
6442    pub fn pending_payloads(&self) -> Result<Vec<Vec<u8>>, String> {
6443        let mut payloads = Vec::new();
6444        for commit in self.outbox.iter() {
6445            for op in &commit.ops {
6446                let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6447                    continue;
6448                };
6449                let Some(values) = op.presented_values(table) else {
6450                    continue;
6451                };
6452                let fallback = self.stored_key_fallback(table, &op.row_id)?;
6453                if let Ok(payload) = encode_sparse_row_json(
6454                    table,
6455                    &op.row_id,
6456                    &values,
6457                    &self.encryption,
6458                    fallback.as_ref(),
6459                ) {
6460                    payloads.push(payload);
6461                }
6462            }
6463        }
6464        Ok(payloads)
6465    }
6466
6467    pub fn conflicts(&self) -> &[ConflictRecord] {
6468        &self.conflicts
6469    }
6470
6471    pub fn rejections(&self) -> &[RejectionRecord] {
6472        &self.rejections
6473    }
6474
6475    pub fn resolve_commit_outcome(
6476        &mut self,
6477        input: ResolveCommitOutcomeInput,
6478    ) -> Result<CommitOutcome, String> {
6479        let current = self
6480            .commit_outcome(&input.client_commit_id)?
6481            .ok_or_else(|| {
6482                format!(
6483                    "sync.outcome_not_found: no durable outcome exists for {:?}",
6484                    input.client_commit_id
6485                )
6486            })?;
6487        if current.resolution != CommitOutcomeResolution::Active {
6488            return Ok(current);
6489        }
6490        if input.resolution == CommitOutcomeResolution::Active {
6491            return Err("sync.invalid_request: resolution must leave active state".to_owned());
6492        }
6493        match input.resolution {
6494            CommitOutcomeResolution::Superseded => {
6495                let replacement = input
6496                    .replacement_client_commit_id
6497                    .as_deref()
6498                    .filter(|value| !value.is_empty() && *value != input.client_commit_id)
6499                    .ok_or_else(|| {
6500                        "sync.invalid_request: superseded outcomes require a distinct replacementClientCommitId"
6501                            .to_owned()
6502                    })?;
6503                let _ = replacement;
6504            }
6505            _ if input.replacement_client_commit_id.is_some() => {
6506                return Err(
6507                    "sync.invalid_request: replacementClientCommitId is valid only for superseded outcomes"
6508                        .to_owned(),
6509                );
6510            }
6511            _ => {}
6512        }
6513        let allowed = match current.status {
6514            CommitOutcomeStatus::Conflict => matches!(
6515                input.resolution,
6516                CommitOutcomeResolution::ResolvedKeepServer | CommitOutcomeResolution::Superseded
6517            ),
6518            CommitOutcomeStatus::Rejected => {
6519                matches!(
6520                    input.resolution,
6521                    CommitOutcomeResolution::Superseded
6522                        | CommitOutcomeResolution::ResolvedKeepServer
6523                )
6524            }
6525            CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => {
6526                input.resolution == CommitOutcomeResolution::Dismissed
6527            }
6528        };
6529        if !allowed {
6530            return Err(format!(
6531                "sync.invalid_request: resolution {:?} is invalid for {:?} outcome",
6532                input.resolution, current.status
6533            ));
6534        }
6535
6536        let rollback = self.capture();
6537        self.begin_observation("syncular_outcome_resolution")?;
6538        let result = (|| {
6539            self.conn
6540                .execute(
6541                    "UPDATE _syncular_commit_outcomes
6542                        SET resolution = ?1, resolved_at_ms = ?2,
6543                            replacement_client_commit_id = ?3
6544                      WHERE client_commit_id = ?4 AND resolution = 'active'",
6545                    rusqlite::params![
6546                        Self::outcome_resolution_name(input.resolution),
6547                        self.clock_now_ms(),
6548                        input.replacement_client_commit_id,
6549                        input.client_commit_id
6550                    ],
6551                )
6552                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6553            let resolved = self
6554                .commit_outcome(&current.client_commit_id)?
6555                .ok_or_else(|| "sync.outcome_not_found: outcome disappeared".to_owned())?;
6556            self.conn
6557                .execute(
6558                    "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
6559                    rusqlite::params![input.client_commit_id],
6560                )
6561                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6562            for (commit, _) in self.failed_commits.iter() {
6563                if commit.client_commit_id == input.client_commit_id {
6564                    for operation in &commit.ops {
6565                        self.overlay_dirty.table(&operation.table);
6566                    }
6567                }
6568            }
6569            self.failed_commits
6570                .retain(|(commit, _)| commit.client_commit_id != input.client_commit_id);
6571            self.prune_commit_outcomes()?;
6572            Ok(resolved)
6573        })();
6574        let resolved = match result {
6575            Ok(outcome) => outcome,
6576            Err(error) => {
6577                self.rollback_observation("syncular_outcome_resolution");
6578                self.restore(rollback);
6579                return Err(error);
6580            }
6581        };
6582        self.conflicts
6583            .retain(|record| record.client_commit_id != current.client_commit_id);
6584        self.rejections
6585            .retain(|record| record.client_commit_id != current.client_commit_id);
6586        let mut batch = ChangeAccumulator {
6587            conflicts: current.status == CommitOutcomeStatus::Conflict,
6588            rejections: current.status == CommitOutcomeStatus::Rejected,
6589            outcomes: true,
6590            ..ChangeAccumulator::default()
6591        };
6592        if let Some(operations) = &current.operations {
6593            for operation in operations {
6594                batch.table(&operation.table);
6595            }
6596        }
6597        if let Err(error) = self
6598            .rebuild_overlay_if_dirty()
6599            .and_then(|()| self.finish_observation("syncular_outcome_resolution", batch))
6600        {
6601            self.rollback_observation("syncular_outcome_resolution");
6602            self.restore(rollback);
6603            return Err(error);
6604        }
6605        Ok(resolved)
6606    }
6607
6608    pub fn schema_floor(&self) -> Option<&SchemaFloor> {
6609        self.schema_floor.as_ref()
6610    }
6611
6612    /// §7.3.5: the client's opaque auth-lease state, if any.
6613    pub fn lease_state(&self) -> Option<&LeaseState> {
6614        self.lease_state.as_ref()
6615    }
6616
6617    /// §7.3.5: record a request-level lease error (stop-and-surface). Only
6618    /// the two lease codes set it; other errors leave leaseState untouched.
6619    fn record_lease_error(&mut self, code: &str) -> Result<(), String> {
6620        if code != "sync.auth_lease_required" && code != "sync.auth_lease_revoked" {
6621            return Ok(());
6622        }
6623        let mut next = self.lease_state.clone().unwrap_or_default();
6624        next.error_code = Some(code.to_owned());
6625        self.set_lease_state(Some(next))
6626    }
6627
6628    fn set_lease_state(&mut self, next: Option<LeaseState>) -> Result<(), String> {
6629        if self.lease_state == next {
6630            return Ok(());
6631        }
6632        self.begin_observation("syncular_lease")?;
6633        let rollback = self.capture();
6634        self.lease_state = next;
6635        let persisted = match &self.lease_state {
6636            Some(lease) => serde_json::to_string(lease)
6637                .map_err(|error| error.to_string())
6638                .and_then(|json| self.set_meta(LEASE_STATE_KEY, &json)),
6639            None => self.delete_meta(LEASE_STATE_KEY),
6640        };
6641        let batch = ChangeAccumulator {
6642            status: true,
6643            ..ChangeAccumulator::default()
6644        };
6645        if let Err(error) =
6646            persisted.and_then(|()| self.finish_observation("syncular_lease", batch))
6647        {
6648            self.rollback_observation("syncular_lease");
6649            self.restore(rollback);
6650            return Err(error);
6651        }
6652        Ok(())
6653    }
6654
6655    fn set_schema_floor(&mut self, next: Option<SchemaFloor>) -> Result<(), String> {
6656        if self.schema_floor == next {
6657            return Ok(());
6658        }
6659        self.begin_observation("syncular_schema_floor")?;
6660        let rollback = self.capture();
6661        self.stopped = next.is_some();
6662        self.schema_floor = next;
6663        let persisted = match &self.schema_floor {
6664            Some(floor) => serde_json::to_string(floor)
6665                .map_err(|error| error.to_string())
6666                .and_then(|json| self.set_meta(SCHEMA_FLOOR_KEY, &json)),
6667            None => self.delete_meta(SCHEMA_FLOOR_KEY),
6668        };
6669        let batch = ChangeAccumulator {
6670            status: true,
6671            ..ChangeAccumulator::default()
6672        };
6673        if let Err(error) =
6674            persisted.and_then(|()| self.finish_observation("syncular_schema_floor", batch))
6675        {
6676            self.rollback_observation("syncular_schema_floor");
6677            self.restore(rollback);
6678            return Err(error);
6679        }
6680        Ok(())
6681    }
6682
6683    fn set_upgrading(&mut self, value: bool) {
6684        if self.upgrading == value {
6685            return;
6686        }
6687        if self.begin_observation("syncular_upgrading").is_err() {
6688            return;
6689        }
6690        self.upgrading = value;
6691        let batch = ChangeAccumulator {
6692            status: true,
6693            ..ChangeAccumulator::default()
6694        };
6695        if self
6696            .finish_observation("syncular_upgrading", batch)
6697            .is_err()
6698        {
6699            self.rollback_observation("syncular_upgrading");
6700        }
6701    }
6702
6703    pub fn sync_needed(&self) -> bool {
6704        self.sync_needed
6705    }
6706
6707    pub fn read_rows(&self, table: &str) -> Result<Vec<RowState>, String> {
6708        let schema_table = self
6709            .schema
6710            .table(table)
6711            .ok_or_else(|| format!("unknown table {table:?}"))?;
6712        let sql = format!(
6713            "SELECT * FROM {} ORDER BY {} ASC",
6714            visible_table(table),
6715            quote_ident(&schema_table.primary_key)
6716        );
6717        let mut stmt = self
6718            .conn
6719            .prepare(&sql)
6720            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6721        let mut rows = stmt
6722            .query([])
6723            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6724        let mut out = Vec::new();
6725        while let Some(row) = rows
6726            .next()
6727            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6728        {
6729            let mut values = Map::new();
6730            for (i, column) in schema_table.columns.iter().enumerate() {
6731                let value = row
6732                    .get_ref(i)
6733                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6734                values.insert(column.name.clone(), sql_ref_to_json(column, value));
6735            }
6736            let version: i64 = row
6737                .get(schema_table.columns.len())
6738                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6739            let row_id = match values.get(&schema_table.primary_key) {
6740                Some(Value::String(s)) => s.clone(),
6741                Some(Value::Number(n)) => n.to_string(),
6742                Some(Value::Bool(b)) => b.to_string(),
6743                other => format!("{}", other.cloned().unwrap_or(Value::Null)),
6744            };
6745            let sealed_key = if schema_table.has_encrypted_columns() {
6746                row.get(schema_table.columns.len() + 1)
6747                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6748            } else {
6749                None
6750            };
6751            out.push(RowState {
6752                row_id,
6753                version,
6754                values,
6755                sealed_key,
6756            });
6757        }
6758        Ok(out)
6759    }
6760
6761    // -- §5.10.5 native CRDT (the `crdt-yjs` feature) --------------------------
6762    //
6763    // The Rust face of the §5.10.4 client model: a local crdt edit loads the
6764    // current stored (server-merged ⊕ pending-overlay) column bytes, applies
6765    // the op with `yrs`, re-encodes the whole doc state, and records a
6766    // baseVersion-less sparse upsert carrying only the primary key and the
6767    // crdt column (§5.10.3, §6.6). No local merge — merging is server-side;
6768    // the overlay re-materializes the edit immediately (optimistic apply,
6769    // §7.1) and the server-merged bytes arrive on the next pull, idempotently.
6770    // Byte-compatible with `@syncular/crdt-yjs`.
6771
6772    /// The current stored value of a `crdt` column for one row — the visible
6773    /// (optimistic) bytes, or `None` when the row is absent or the column is
6774    /// NULL (the empty document, §5.10.1). Errors if the column is not a
6775    /// `crdt` column (guards the app against a typo'd column name).
6776    #[cfg(feature = "crdt-yjs")]
6777    fn crdt_column_bytes(
6778        &self,
6779        table: &str,
6780        row_id: &str,
6781        column: &str,
6782    ) -> Result<Option<Vec<u8>>, String> {
6783        let schema_table = self
6784            .schema
6785            .table(table)
6786            .ok_or_else(|| format!("unknown table {table:?}"))?;
6787        let col = schema_table
6788            .columns
6789            .iter()
6790            .find(|c| c.name == column)
6791            .ok_or_else(|| format!("table {table:?} has no column {column:?}"))?;
6792        if col.ty != ColumnType::Crdt {
6793            return Err(format!("column {column:?} is not a crdt column (§5.10.1)"));
6794        }
6795        let sql = format!(
6796            "SELECT {} FROM {} WHERE {}",
6797            quote_ident(column),
6798            visible_table(table),
6799            row_id_predicate(schema_table)
6800        );
6801        let bytes: Option<Vec<u8>> = self
6802            .conn
6803            .prepare_cached(&sql)
6804            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6805            .query_row(rusqlite::params![row_id], |row| {
6806                row.get::<_, Option<Vec<u8>>>(0)
6807            })
6808            .map_err(|e| match e {
6809                rusqlite::Error::QueryReturnedNoRows => "no such row".to_owned(),
6810                other => Self::sqlite_failure(&self.storage_failure, other),
6811            })?;
6812        Ok(bytes)
6813    }
6814
6815    /// §5.10.4 materialize: the collaborative text of a `crdt` column, decoded
6816    /// from the stored bytes with `yrs` — `YjsColumn.text(name).toString()`.
6817    /// An absent row / NULL column is the empty document (empty string).
6818    #[cfg(feature = "crdt-yjs")]
6819    pub fn crdt_text(
6820        &self,
6821        table: &str,
6822        row_id: &str,
6823        column: &str,
6824        name: &str,
6825    ) -> Result<String, String> {
6826        let bytes = self
6827            .crdt_column_bytes(table, row_id, column)?
6828            .unwrap_or_default();
6829        crate::crdt::text(&bytes, name)
6830    }
6831
6832    /// §5.10.4 push-an-update: apply a text insert to a `crdt` column and
6833    /// record the resulting crdt-only sparse operation. Returns the enqueued
6834    /// `clientCommitId`.
6835    #[cfg(feature = "crdt-yjs")]
6836    pub fn crdt_insert_text(
6837        &mut self,
6838        table: &str,
6839        row_id: &str,
6840        column: &str,
6841        name: &str,
6842        index: u32,
6843        value: &str,
6844    ) -> Result<String, ClientError> {
6845        let prior = self.storage_failure.borrow_mut().take();
6846        let outcome = (|| -> Result<String, ClientError> {
6847            let current = self
6848                .crdt_column_bytes(table, row_id, column)?
6849                .unwrap_or_default();
6850            let update = crate::crdt::insert_text(&current, name, index, value)?;
6851            self.perform_crdt_push_update(table, row_id, column, &update)
6852        })();
6853        self.finish_authoring(prior, outcome)
6854    }
6855
6856    /// §5.10.4 push-an-update: apply a text delete to a `crdt` column and
6857    /// record the resulting crdt-only sparse operation. Returns the enqueued
6858    /// `clientCommitId`.
6859    #[cfg(feature = "crdt-yjs")]
6860    pub fn crdt_delete_text(
6861        &mut self,
6862        table: &str,
6863        row_id: &str,
6864        column: &str,
6865        name: &str,
6866        index: u32,
6867        len: u32,
6868    ) -> Result<String, ClientError> {
6869        let prior = self.storage_failure.borrow_mut().take();
6870        let outcome = (|| -> Result<String, ClientError> {
6871            let current = self
6872                .crdt_column_bytes(table, row_id, column)?
6873                .unwrap_or_default();
6874            let update = crate::crdt::delete_text(&current, name, index, len)?;
6875            self.perform_crdt_push_update(table, row_id, column, &update)
6876        })();
6877        self.finish_authoring(prior, outcome)
6878    }
6879
6880    /// §5.10.4 generic escape hatch: apply an arbitrary Yjs update onto a
6881    /// `crdt` column's current state and record the resulting crdt-only sparse
6882    /// operation. The app authored the update with its own `yrs` model.
6883    /// Returns the enqueued `clientCommitId`.
6884    #[cfg(feature = "crdt-yjs")]
6885    pub fn crdt_apply_update(
6886        &mut self,
6887        table: &str,
6888        row_id: &str,
6889        column: &str,
6890        update: &[u8],
6891    ) -> Result<String, ClientError> {
6892        let prior = self.storage_failure.borrow_mut().take();
6893        let outcome = (|| -> Result<String, ClientError> {
6894            let current = self
6895                .crdt_column_bytes(table, row_id, column)?
6896                .unwrap_or_default();
6897            let next = crate::crdt::apply_update(&current, update)?;
6898            self.perform_crdt_push_update(table, row_id, column, &next)
6899        })();
6900        self.finish_authoring(prior, outcome)
6901    }
6902
6903    /// Shared tail of the crdt edit methods: record a §6.1 sparse crdt-only
6904    /// upsert — the primary key plus the crdt column, no `baseVersion` — and
6905    /// enqueue it. The server merges the crdt column and leaves every other
6906    /// column untouched (§5.10.3), so a baseVersion-less crdt edit cannot
6907    /// clobber a concurrent edit to another column. A locally absent row
6908    /// records the same partial operation; the server answers per §6.2.
6909    #[cfg(feature = "crdt-yjs")]
6910    fn perform_crdt_push_update(
6911        &mut self,
6912        table: &str,
6913        row_id: &str,
6914        column: &str,
6915        crdt_bytes: &[u8],
6916    ) -> Result<String, ClientError> {
6917        let mut bytes_obj = Map::new();
6918        bytes_obj.insert("$bytes".to_owned(), Value::from(bytes_to_hex(crdt_bytes)));
6919        let mut partial = Map::new();
6920        partial.insert(column.to_owned(), Value::Object(bytes_obj));
6921        self.perform_patch(table, row_id, partial, None)
6922    }
6923
6924    /// Run an arbitrary read-only SQL query against the local database and
6925    /// return each row as a `column-name → JSON value` map. This is the seam
6926    /// the React `useSyncQuery` live-query API needs (it takes app-authored
6927    /// SQL over the visible tables/views, not a fixed table read like
6928    /// [`read_rows`]).
6929    ///
6930    /// Bound `params` are the driver value forms: JSON strings/numbers/bools/
6931    /// null bind directly; a `{"$bytes": hex}` object binds as a BLOB — the
6932    /// same envelope the command surface uses everywhere else. Output BLOB
6933    /// columns come back as `{"$bytes": hex}` to round-trip cleanly.
6934    ///
6935    /// The result column typing is dynamic (SQLite's stored affinity), because
6936    /// arbitrary SQL can alias, join, and compute — there is no schema column
6937    /// to consult per output cell, unlike [`read_rows`].
6938    pub fn query(&self, sql: &str, params: &[QueryValue]) -> Result<Vec<QueryRow>, String> {
6939        query_connection(&self.conn, sql, params).map_err(|failure| failure.to_string())
6940    }
6941
6942    /// Repository benchmark and conformance access, present only with `bench-internals`.
6943    #[cfg(feature = "bench-internals")]
6944    #[doc(hidden)]
6945    pub fn benchmark_connection(&mut self) -> &mut Connection {
6946        &mut self.conn
6947    }
6948
6949    /// Private benchmark intervals; absent from ordinary builds and diagnostics.
6950    #[cfg(feature = "bench-internals")]
6951    #[doc(hidden)]
6952    pub fn benchmark_phases(
6953        &self,
6954        enabled: Option<bool>,
6955        reset: bool,
6956    ) -> Result<Option<Value>, String> {
6957        self.benchmark_phases.configure(enabled, reset)?;
6958        Ok(self.benchmark_phases.snapshot())
6959    }
6960
6961    /// One serialized, read-only authority observation, including durable coverage.
6962    pub fn authority_snapshot(&self) -> Result<Value, String> {
6963        validate_authority_reads(&self.schema, &self.limits.authority_reads)?;
6964        if self.limits.authority_reads.is_empty() {
6965            return Err("client.authority_read_forbidden: no authority reads were declared at client creation".into());
6966        }
6967        self.conn
6968            .execute_batch("SAVEPOINT authority_snapshot")
6969            .map_err(|e| e.to_string())?;
6970        let result = (|| {
6971            let revision = self
6972                .get_meta(LOCAL_REVISION_KEY)?
6973                .ok_or("sync.local_corrupt: authority revision is missing")?;
6974            let parsed_revision = revision
6975                .parse::<u64>()
6976                .map_err(|_| "sync.local_corrupt: authority revision is invalid")?;
6977            if parsed_revision.to_string() != revision {
6978                return Err("sync.local_corrupt: authority revision is invalid".into());
6979            }
6980            let mut tables = Vec::new();
6981            for read in &self.limits.authority_reads {
6982                let table = self
6983                    .schema
6984                    .table(&read.table)
6985                    .ok_or("client.authority_read_forbidden: authority table is not declared")?;
6986                let scalar = |column: &str, value: &Value| -> Result<String, String> {
6987                    let ty = table
6988                        .columns
6989                        .iter()
6990                        .find(|c| c.name == column)
6991                        .expect("validated authority column")
6992                        .ty;
6993                    if ty == ColumnType::Boolean {
6994                        if let Some(value) = value.as_bool() {
6995                            return Ok(value.to_string());
6996                        }
6997                        return match value.as_i64() {
6998                            Some(0) => Ok("false".into()),
6999                            Some(1) => Ok("true".into()),
7000                            _ => Err("sync.local_corrupt: authority boolean is invalid".into()),
7001                        };
7002                    }
7003                    match value {
7004                        Value::String(s) => Ok(s.clone()),
7005                        Value::Number(n) => Ok(n.to_string()),
7006                        Value::Object(o) if ty == ColumnType::Integer && o.len() == 1 => o
7007                            .get("$bigint")
7008                            .and_then(Value::as_str)
7009                            .map(str::to_owned)
7010                            .ok_or("sync.local_corrupt: authority integer is invalid".into()),
7011                        _ => {
7012                            Err("sync.local_corrupt: authority scalar is missing or invalid".into())
7013                        }
7014                    }
7015                };
7016                let matches = |row: &QueryRow| -> Result<bool, String> {
7017                    for (variable, values) in &read.scopes {
7018                        let column = table
7019                            .scope_column(variable)
7020                            .expect("validated authority scope");
7021                        let value = row
7022                            .get(column)
7023                            .ok_or("sync.local_corrupt: authority scope column is missing")?;
7024                        if value.is_null() || !values.contains(&scalar(column, value)?) {
7025                            return Ok(false);
7026                        }
7027                    }
7028                    Ok(true)
7029                };
7030                let selected = read
7031                    .columns
7032                    .iter()
7033                    .map(|c| quote_ident(c))
7034                    .collect::<Vec<_>>()
7035                    .join(",");
7036                let mut intent = BTreeSet::new();
7037                let mut relevant = BTreeSet::new();
7038                for row in query_connection(&self.conn,
7039                    "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=?",
7040                    &[Value::String(read.table.clone())]).map_err(|e| e.to_string())? {
7041                    let id = row.get("id").and_then(Value::as_str).ok_or("sync.local_corrupt: authority intent id is invalid")?.to_owned();
7042                    intent.insert(id.clone());
7043                    if let Some(raw) = row.get("values_json").and_then(Value::as_str) {
7044                        let values: QueryRow = serde_json::from_str(raw).map_err(|_| "sync.local_corrupt: authority intent values are invalid")?;
7045                        if read.scopes.keys().all(|v| values.contains_key(table.scope_column(v).expect("validated scope"))) && matches(&values)? {relevant.insert(id);}
7046                    }
7047                }
7048                let mut rows = BTreeMap::new();
7049                for full in [base_table(&read.table), visible_table(&read.table)] {
7050                    for mut values in query_connection(
7051                        &self.conn,
7052                        &format!(
7053                            "SELECT {selected},_syncular_version AS authority_version FROM {full}"
7054                        ),
7055                        &[],
7056                    )
7057                    .map_err(|e| e.to_string())?
7058                    {
7059                        if !matches(&values)? {
7060                            continue;
7061                        }
7062                        let id = scalar(
7063                            &table.primary_key,
7064                            values
7065                                .get(&table.primary_key)
7066                                .expect("selected primary key"),
7067                        )?;
7068                        relevant.insert(id.clone());
7069                        if full == base_table(&read.table) {
7070                            let version = values
7071                                .remove("authority_version")
7072                                .expect("selected version");
7073                            let version = version
7074                                .as_i64()
7075                                .ok_or("sync.local_corrupt: authority server version is invalid")?;
7076                            if version >= 0 {
7077                                rows.insert(id.clone(), json!({"values": values, "version": version, "hasLocalIntent": intent.contains(&id)}));
7078                            }
7079                        }
7080                    }
7081                }
7082                intent.retain(|id| relevant.contains(id));
7083                let rows = rows.into_values().collect::<Vec<_>>();
7084                // Every unit covering the table, as its (unit, table) pair (§4.4).
7085                let replica = self.stored(replica_cursor(&self.conn))?;
7086                let persisted = self
7087                    .stored(load_units(&self.conn))?
7088                    .into_iter()
7089                    .filter(|unit| covers(table, &unit.scopes))
7090                    .map(|unit| {
7091                        let effective = unit.echo.as_deref().and_then(|echo| {
7092                            pair_scopes(&unit.scopes, &read.table, Some(echo))
7093                        });
7094                        let requested = read
7095                            .scopes
7096                            .keys()
7097                            .map(|v| (v.clone(), json!(unit.scopes.get(v).into_iter().collect::<Vec<_>>())))
7098                            .collect::<Map<_, _>>();
7099                        let complete = effective
7100                            .as_ref()
7101                            .is_some_and(|scopes| scopes.len() == read.scopes.len())
7102                            && unit.status == UnitStatus::Active
7103                            && !unit.bootstrapping();
7104                        let exposed = effective.map(|scopes| {
7105                            read.scopes
7106                                .keys()
7107                                .map(|v| {
7108                                    let held = scopes.iter().find(|(variable, _)| variable == v);
7109                                    (v.clone(), json!(held.map_or(&Vec::new(), |(_, values)| values)))
7110                                })
7111                                .collect::<Map<_, _>>()
7112                        });
7113                        json!({"requestedScopes": requested, "status": unit.status, "cursor": unit.cursor.unwrap_or(replica), "effectiveScopes": exposed, "complete": complete})
7114                    })
7115                    .collect::<Vec<_>>();
7116                fn covered(selectors: &[(&String, &Vec<String>)], candidates: &[&Value]) -> bool {
7117                    match selectors.split_first() {
7118                        None => !candidates.is_empty(),
7119                        Some(((variable, values), rest)) => values.iter().all(|value| {
7120                            covered(
7121                                rest,
7122                                &candidates
7123                                    .iter()
7124                                    .copied()
7125                                    .filter(|p| {
7126                                        p["effectiveScopes"][variable.as_str()]
7127                                            .as_array()
7128                                            .is_some_and(|held| {
7129                                                held.contains(&Value::String(value.clone()))
7130                                                    || held.contains(&Value::String("*".into()))
7131                                            })
7132                                    })
7133                                    .collect::<Vec<_>>(),
7134                            )
7135                        }),
7136                    }
7137                }
7138                let coverage = if covered(
7139                    &read.scopes.iter().collect::<Vec<_>>(),
7140                    &persisted
7141                        .iter()
7142                        .filter(|p| p["complete"] == true)
7143                        .collect::<Vec<_>>(),
7144                ) {
7145                    "complete"
7146                } else if persisted.iter().any(|p| {
7147                    p["status"] == "active"
7148                        && read.scopes.iter().all(|(v, values)| {
7149                            values.iter().any(|value| {
7150                                p["requestedScopes"][v].as_array().is_some_and(|held| {
7151                                    held.contains(&Value::String(value.clone()))
7152                                })
7153                            })
7154                        })
7155                }) {
7156                    "pending"
7157                } else {
7158                    "missing"
7159                };
7160                tables.push(json!({"table": read.table, "rows": rows, "localIntentRowIds": intent, "scopes": read.scopes, "coverage": coverage, "persisted": persisted}));
7161            }
7162            Ok(
7163                json!({"revision": revision, "complete": tables.iter().all(|t| t["coverage"] == "complete"), "tables": tables}),
7164            )
7165        })();
7166        match result {
7167            Ok(snapshot) => {
7168                self.conn
7169                    .execute_batch("RELEASE authority_snapshot")
7170                    .map_err(|e| e.to_string())?;
7171                Ok(snapshot)
7172            }
7173            Err(error) => {
7174                self.conn
7175                    .execute_batch("ROLLBACK TO authority_snapshot; RELEASE authority_snapshot")
7176                    .map_err(|e| format!("{error}; rollback failed: {e}"))?;
7177                Err(error)
7178            }
7179        }
7180    }
7181
7182    /// Rows, coverage, and local revision from one SQLite read snapshot.
7183    /// §7.5 atomic snapshot read. An `owner` records a failure in
7184    /// `diagnostics_snapshot().query_failures` until its next successful read.
7185    pub fn query_snapshot(
7186        &mut self,
7187        sql: &str,
7188        params: &[QueryValue],
7189        coverage: &[WindowCoverage],
7190        owner: Option<QueryOwner<'_>>,
7191    ) -> Result<QuerySnapshot, String> {
7192        let result = snapshot_connection(&self.conn, sql, params, coverage);
7193        if let Some(owner) = owner {
7194            self.record_query_read(owner, result.as_ref().err());
7195        }
7196        result.map_err(|failure| failure.to_string())
7197    }
7198
7199    /// §7.6: record the outcome of one owned snapshot read, including reads a
7200    /// host ran on a separate connection. A success removes the owner's entry;
7201    /// an identical failure leaves it unchanged; a changed failure moves last.
7202    pub fn record_query_read(&mut self, owner: QueryOwner<'_>, failure: Option<&QueryReadFailure>) {
7203        let position = self
7204            .query_failures
7205            .iter()
7206            .position(|entry| entry.id == owner.id);
7207        let Some(failure) = failure else {
7208            if let Some(index) = position {
7209                self.query_failures.remove(index);
7210            }
7211            return;
7212        };
7213        let tables: Vec<String> = BTreeSet::from_iter(owner.tables.iter().copied())
7214            .into_iter()
7215            .map(str::to_owned)
7216            .collect();
7217        let code = failure.code.unwrap_or("client.query_failed").to_owned();
7218        if position.is_some_and(|index| {
7219            let entry = &self.query_failures[index];
7220            entry.tables == tables && entry.code == code && entry.sqlite_code == failure.sqlite_code
7221        }) {
7222            return;
7223        }
7224        if let Some(index) = position {
7225            self.query_failures.remove(index);
7226        }
7227        self.query_failures.push(DiagnosticQueryFailure {
7228            id: owner.id.to_owned(),
7229            tables,
7230            code,
7231            sqlite_code: failure.sqlite_code,
7232            at_ms: self.clock_now_ms(),
7233        });
7234        if self.query_failures.len() > MAX_DIAGNOSTIC_QUERY_FAILURES {
7235            self.query_failures.remove(0);
7236        }
7237    }
7238
7239    // -- request building ---------------------------------------------------------
7240
7241    fn build_request(&self, url_capable: bool) -> Result<(Message, RequestMeta), Box<SyncOutcome>> {
7242        #[cfg(feature = "bench-internals")]
7243        let _phase = self.benchmark_phases.start(Phase::RequestPrepare);
7244        let log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7245            Box::new(SyncOutcome::Failed {
7246                error_code: "storage.failed".into(),
7247                message,
7248                details: None,
7249                recommended_action: None,
7250            })
7251        })?;
7252        let max_commits = self.limits.max_push_commits_per_request;
7253        let max_ops = self
7254            .limits
7255            .max_push_operations_per_request
7256            .unwrap_or(PUSH_OPS_PER_REQUEST);
7257        let byte_cap = self.limits.max_push_request_bytes;
7258        // §4.2/§5.4: bit 3 is advertised iff the transport can fetch a
7259        // bare URL — capability negotiation, decided per transport.
7260        let accept = self.limits.accept.unwrap_or(if url_capable {
7261            DEFAULT_ACCEPT | ACCEPT_SIGNED_URLS
7262        } else {
7263            DEFAULT_ACCEPT
7264        });
7265        let storage_failed = |message: String| {
7266            Box::new(SyncOutcome::Failed {
7267                error_code: "storage.failed".into(),
7268                message,
7269                details: None,
7270                recommended_action: None,
7271            })
7272        };
7273        let header = Frame::ReqHeader {
7274            client_id: self.client_id.clone(),
7275            schema_version: self.schema.version,
7276            log_epoch: log_epoch.clone(),
7277            outbox_id: self.get_meta(OUTBOX_ID_KEY).map_err(storage_failed)?,
7278        };
7279        // §1.5: the lead frames are REQ_HEADER plus the optional ROUND_FAILURE,
7280        // which stays ahead of every push, pull, unit and progress frame; the
7281        // byte-capacity probes below measure this exact sequence.
7282        let mut lead = vec![header];
7283        lead.extend(
7284            self.round_failure
7285                .iter()
7286                .map(|code| Frame::RoundFailure { code: code.clone() }),
7287        );
7288        let registered: Vec<UnitRecord> = self
7289            .stored(load_units(&self.conn))
7290            .map_err(storage_failed)?
7291            .into_iter()
7292            .filter(|unit| unit.status == UnitStatus::Active)
7293            .collect();
7294        let registration_digest = ssp2::registration::registration_digest(
7295            registered
7296                .iter()
7297                .map(|unit| scope_pairs(&unit.scopes))
7298                .collect::<Vec<_>>()
7299                .iter()
7300                .map(Vec::as_slice),
7301        );
7302        let echo_digest = self
7303            .get_meta(ECHO_DIGEST_KEY)
7304            .map_err(storage_failed)?
7305            .filter(|hex| !hex.is_empty())
7306            .map(|hex| {
7307                crate::values::hex_to_bytes(&hex)
7308                    .ok()
7309                    .and_then(|bytes| <[u8; 32]>::try_from(bytes).ok())
7310                    .ok_or_else(|| {
7311                        "sync.local_corrupt: persisted echo digest is invalid".to_owned()
7312                    })
7313            })
7314            .transpose()
7315            .map_err(storage_failed)?;
7316        let pull = Frame::PullHeader {
7317            limit_commits: self.limits.limit_commits.unwrap_or(0),
7318            limit_snapshot_rows: self.limits.limit_snapshot_rows.unwrap_or(0),
7319            max_snapshot_pages: self.limits.max_snapshot_pages.unwrap_or(0),
7320            accept,
7321            cursor: self
7322                .stored(replica_cursor(&self.conn))
7323                .map_err(storage_failed)?,
7324            registration_digest,
7325            echo_digest,
7326        };
7327        let registration_digest = bytes_to_hex(&registration_digest);
7328        // §4.1: the list travels when it changed since the server stored it,
7329        // after `unregistered` and after a reset (both clear the stored digest).
7330        let travels = self
7331            .get_meta(REGISTERED_DIGEST_KEY)
7332            .map_err(storage_failed)?
7333            .as_deref()
7334            != Some(registration_digest.as_str());
7335        let mut sub_frames: Vec<Frame> = Vec::new();
7336        if travels {
7337            sub_frames.extend(registered.iter().map(|unit| Frame::Unit {
7338                scopes: scope_pairs(&unit.scopes),
7339            }));
7340        }
7341        // §4.3: one PROGRESS per catching-up unit, in registration order.
7342        sub_frames.extend(registered.iter().filter_map(|unit| {
7343            Some(Frame::Progress {
7344                id: unit.id.clone(),
7345                cursor: unit.cursor?,
7346                bootstrap_state: unit.bootstrap_state.clone().map(RawJson),
7347            })
7348        }));
7349        // The fixed frames (order-independent size) and the header+pull probe
7350        // both encode canonically, so the byte budget is the exact wire size.
7351        let fixed_bytes = match byte_cap {
7352            Some(_) => {
7353                let mut frames = lead.clone();
7354                frames.push(pull.clone());
7355                frames.extend(sub_frames.iter().cloned());
7356                encode_message(&Message {
7357                    wire_version: WIRE_VERSION,
7358                    msg_kind: MsgKind::Request,
7359                    frames,
7360                })
7361                .len()
7362            }
7363            None => 0,
7364        };
7365        if let Some(cap) = byte_cap {
7366            if fixed_bytes > cap {
7367                return Err(Self::push_capacity_outcome("bytes", cap, fixed_bytes, None));
7368            }
7369        }
7370        let base_bytes = match byte_cap {
7371            Some(_) => {
7372                let mut frames = lead.clone();
7373                frames.push(pull.clone());
7374                encode_message(&Message {
7375                    wire_version: WIRE_VERSION,
7376                    msg_kind: MsgKind::Request,
7377                    frames,
7378                })
7379                .len()
7380            }
7381            None => 0,
7382        };
7383        let total_outbox = if log_epoch.is_some() {
7384            self.outbox.len()
7385        } else {
7386            0
7387        };
7388        let mut push_frames: Vec<Frame> = Vec::new();
7389        let mut pushed_ids = Vec::new();
7390        let mut ops_in_request = 0usize;
7391        let mut bytes_in_request = 0usize;
7392        let mut deferred_commits = 0usize;
7393        #[cfg(feature = "bench-internals")]
7394        let outbox_phase = self.benchmark_phases.start(Phase::OutboxEncode);
7395        for (index, commit) in self.outbox.iter().take(total_outbox).enumerate() {
7396            // §6.1/§7.1: the commit-count and operation caps are hard. A
7397            // first commit over the operation cap is a typed capacity error
7398            // and stays queued; a later one defers with the complete suffix.
7399            if max_commits.is_some_and(|cap| push_frames.len() >= cap) {
7400                deferred_commits = total_outbox - index;
7401                break;
7402            }
7403            if ops_in_request + commit.ops.len() > max_ops {
7404                if push_frames.is_empty() {
7405                    return Err(Self::push_capacity_outcome(
7406                        "operations",
7407                        max_ops,
7408                        commit.ops.len(),
7409                        Some(commit.client_commit_id.as_str()),
7410                    ));
7411                }
7412                deferred_commits = total_outbox - index;
7413                break;
7414            }
7415            // §7.1 chained base: the commit waits for the change of the commit
7416            // it chains on, which supplies its rebased version.
7417            if self.outbox[..index]
7418                .iter()
7419                .flat_map(|earlier| &earlier.ops)
7420                .any(|earlier| commit.ops.iter().any(|op| chains_on(earlier, op)))
7421            {
7422                deferred_commits = total_outbox - index;
7423                break;
7424            }
7425            let operations = commit
7426                .ops
7427                .iter()
7428                .map(|op| {
7429                    let payload = match self
7430                        .schema
7431                        .table(&op.table)
7432                        .and_then(|table| Some((table, op.presented_values(table)?)))
7433                    {
7434                        Some((table, values)) => {
7435                            // §0: outbox entries encode at send time with the
7436                            // current codec (validated at mutate()). §6.1: the
7437                            // values map's keys are the sparse presence set; an
7438                            // insert-intent operation presents every column (§7.1).
7439                            // §5.11: encrypted columns are encrypted here, with
7440                            // an absent key-id selector read from the stored row.
7441                            // `sync_inner` runs `drop_unencodable_outbox` first,
7442                            // so an encrypt failure cannot reach this encode; the
7443                            // author seam validated every other failure.
7444                            let fallback =
7445                                self.stored_key_fallback(table, &op.row_id)
7446                                    .map_err(|message| {
7447                                        Box::new(SyncOutcome::Failed {
7448                                            error_code: "storage.failed".into(),
7449                                            message,
7450                                            details: None,
7451                                            recommended_action: None,
7452                                        })
7453                                    })?;
7454                            encode_sparse_row_json(
7455                                table,
7456                                &op.row_id,
7457                                &values,
7458                                &self.encryption,
7459                                fallback.as_ref(),
7460                            )
7461                            .ok()
7462                        }
7463                        None => None,
7464                    };
7465                    Ok(ssp2::model::Operation {
7466                        table: op.table.clone(),
7467                        row_id: op.row_id.clone(),
7468                        op: if op.upsert { Op::Upsert } else { Op::Delete },
7469                        base_version: op.base_version,
7470                        payload,
7471                    })
7472                })
7473                .collect::<Result<Vec<_>, Box<SyncOutcome>>>()?;
7474            // §6.3.2, §7.1: the commit's outbox sequence.
7475            let client_seq = self
7476                .conn
7477                .prepare_cached("SELECT seq FROM _syncular_outbox WHERE commit_id = ?1")
7478                .and_then(|mut statement| {
7479                    statement.query_row([&commit.client_commit_id], |row| row.get(0))
7480                })
7481                .map_err(|error| {
7482                    storage_failed(Self::sqlite_failure(&self.storage_failure, error))
7483                })?;
7484            let frame = Frame::PushCommit {
7485                client_commit_id: commit.client_commit_id.clone(),
7486                client_seq,
7487                operations,
7488            };
7489            let frame_bytes = match byte_cap {
7490                Some(_) => {
7491                    let mut frames = lead.clone();
7492                    frames.push(frame.clone());
7493                    frames.push(pull.clone());
7494                    encode_message(&Message {
7495                        wire_version: WIRE_VERSION,
7496                        msg_kind: MsgKind::Request,
7497                        frames,
7498                    })
7499                    .len()
7500                        - base_bytes
7501                }
7502                None => 0,
7503            };
7504            // The head is always encoded so the caller can report the full
7505            // projected request size; a later commit defers once it no longer
7506            // fits.
7507            if let Some(cap) = byte_cap {
7508                if !push_frames.is_empty() && fixed_bytes + bytes_in_request + frame_bytes > cap {
7509                    deferred_commits = total_outbox - index;
7510                    break;
7511                }
7512            }
7513            push_frames.push(frame);
7514            pushed_ids.push(commit.client_commit_id.clone());
7515            ops_in_request += commit.ops.len();
7516            bytes_in_request += frame_bytes;
7517        }
7518        #[cfg(feature = "bench-internals")]
7519        drop(outbox_phase);
7520        if let Some(cap) = byte_cap {
7521            if fixed_bytes + bytes_in_request > cap {
7522                // The head alone does not fit this budget; the commit stays
7523                // queued and no transport round is attempted.
7524                let blocked = if push_frames.is_empty() {
7525                    None
7526                } else {
7527                    self.outbox.first().map(|c| c.client_commit_id.as_str())
7528                };
7529                return Err(Self::push_capacity_outcome(
7530                    "bytes",
7531                    cap,
7532                    fixed_bytes + bytes_in_request,
7533                    blocked,
7534                ));
7535            }
7536        }
7537        let mut frames = lead;
7538        frames.extend(push_frames);
7539        frames.push(pull);
7540        frames.extend(sub_frames);
7541        let message = Message {
7542            wire_version: WIRE_VERSION,
7543            msg_kind: MsgKind::Request,
7544            frames,
7545        };
7546        Ok((
7547            message,
7548            RequestMeta {
7549                pushed_ids,
7550                registration_digest,
7551                accept,
7552                deferred_commits,
7553                applied: BTreeMap::new(),
7554                deferred: BTreeSet::new(),
7555            },
7556        ))
7557    }
7558
7559    /// §7.1: a configured push capacity limit cannot carry this request.
7560    fn push_capacity_outcome(
7561        kind: &str,
7562        limit: usize,
7563        size: usize,
7564        client_commit_id: Option<&str>,
7565    ) -> Box<SyncOutcome> {
7566        let mut details = Map::new();
7567        details.insert("kind".to_owned(), Value::from(kind));
7568        details.insert("limit".to_owned(), Value::from(limit as u64));
7569        details.insert("size".to_owned(), Value::from(size as u64));
7570        if let Some(id) = client_commit_id {
7571            details.insert("clientCommitId".to_owned(), Value::from(id));
7572        }
7573        Box::new(SyncOutcome::Failed {
7574            error_code: "client.push_request_too_large".into(),
7575            message: "the push request exceeds a configured capacity limit".into(),
7576            details: Some(Value::Object(details)),
7577            recommended_action: None,
7578        })
7579    }
7580
7581    // -- sync -------------------------------------------------------------------
7582
7583    /// Cloneable observation handle; no client lock is needed to read it.
7584    pub fn progress(&self) -> ProgressObserver {
7585        self.progress.clone()
7586    }
7587
7588    pub fn sync(&mut self, transport: &mut dyn Transport) -> SyncOutcome {
7589        let prepared = match self.prepare_sync_round(transport.supports_url_fetch()) {
7590            Ok(prepared) => prepared,
7591            Err(outcome) => return *outcome,
7592        };
7593        // The round's network deadline rides `PreparedSyncRound` and is scoped
7594        // to each exchange, so uploads, continuations, the main request, and
7595        // every segment fetch share one monotonic anchor without leaving
7596        // deadline state on a reused transport.
7597        let mut next = prepared;
7598        loop {
7599            match self.apply_sync_round(next.exchange(transport)) {
7600                crate::AppliedSyncRound::Continue(prepared) => next = prepared,
7601                crate::AppliedSyncRound::Complete {
7602                    outcome, controls, ..
7603                } => {
7604                    if self.transport_enabled {
7605                        for text in controls {
7606                            let _ = transport.realtime_send(&text);
7607                        }
7608                    } else {
7609                        self.disconnect_realtime(transport);
7610                    }
7611                    return outcome;
7612                }
7613            }
7614        }
7615    }
7616
7617    fn finish_sync_round(&mut self, started_at_ms: i64, mut outcome: SyncOutcome) -> SyncOutcome {
7618        if let SyncOutcome::Failed {
7619            error_code,
7620            message,
7621            details,
7622            ..
7623        } = &mut outcome
7624        {
7625            if let Some((failure, code)) = self
7626                .storage_failure
7627                .borrow()
7628                .as_ref()
7629                .and_then(|failure| failure.code.map(|code| (failure, code)))
7630            {
7631                *error_code = code.to_owned();
7632                *message = match code {
7633                    "client.storage_busy" => "local SQLite storage is busy",
7634                    "client.storage_full" => "local SQLite storage is full",
7635                    "client.storage_io" => "local SQLite storage I/O failed",
7636                    "client.storage_corrupt" => "local SQLite storage is corrupt",
7637                    _ => unreachable!("unrecognized classified storage failure"),
7638                }
7639                .to_owned();
7640                *details = failure.details();
7641            }
7642        }
7643        let details = match &outcome {
7644            SyncOutcome::Failed { details, .. } => details.as_ref(),
7645            _ => None,
7646        };
7647        let cause_kind = details
7648            .and_then(|details| details.get("causeKind"))
7649            .and_then(Value::as_str)
7650            .and_then(|cause| match cause {
7651                "network" => Some(crate::TransportCauseKind::Network),
7652                "connect" => Some(crate::TransportCauseKind::Connect),
7653                "tls" => Some(crate::TransportCauseKind::Tls),
7654                "io" => Some(crate::TransportCauseKind::Io),
7655                "request" => Some(crate::TransportCauseKind::Request),
7656                "protocol" => Some(crate::TransportCauseKind::Protocol),
7657                "timeout" => Some(crate::TransportCauseKind::Timeout),
7658                "round_deadline" => Some(crate::TransportCauseKind::RoundDeadline),
7659                "aborted" => Some(crate::TransportCauseKind::Aborted),
7660                "body" => Some(crate::TransportCauseKind::Body),
7661                "status" => Some(crate::TransportCauseKind::Status),
7662                "redirect" => Some(crate::TransportCauseKind::Redirect),
7663                "unknown" => Some(crate::TransportCauseKind::Unknown),
7664                _ => None,
7665            });
7666        let http_status = if matches!(
7667            cause_kind,
7668            Some(
7669                crate::TransportCauseKind::Status
7670                    | crate::TransportCauseKind::Body
7671                    | crate::TransportCauseKind::Redirect
7672            )
7673        ) {
7674            details
7675                .and_then(|details| details.get("httpStatus"))
7676                .and_then(Value::as_f64)
7677                .filter(|status| status.fract() == 0.0 && (100.0..=599.0).contains(status))
7678                .map(|status| status as u16)
7679        } else {
7680            None
7681        };
7682        let retry_delay_ms = self.round_retry_delay_ms;
7683        self.progress.update(|p| match &outcome {
7684            SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report)
7685                if report.failed.is_empty() =>
7686            {
7687                p.state = ProgressState::Complete
7688            }
7689            SyncOutcome::Ok(_) | SyncOutcome::BudgetExhausted(_) => {
7690                p.state = ProgressState::Failed;
7691                p.error_code = Some("sync.scope_revoked".into());
7692            }
7693            SyncOutcome::Failed { error_code, .. } => {
7694                p.state = ProgressState::Failed;
7695                p.error_code = Some(Self::diagnostic_code(error_code));
7696                p.cause_kind = cause_kind;
7697                p.http_status = http_status;
7698                p.retry_delay_ms = retry_delay_ms;
7699            }
7700            SyncOutcome::RealtimeUnavailable { .. } => {
7701                p.state = ProgressState::Failed;
7702                p.error_code = Some(REALTIME_UNAVAILABLE_CODE.to_owned());
7703                p.retry_delay_ms = retry_delay_ms;
7704            }
7705        });
7706        let completed_at_ms = self.clock_now_ms();
7707        self.last_round = Some(match &outcome {
7708            SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report) => DiagnosticLastRound {
7709                status: "succeeded".to_owned(),
7710                started_at_ms,
7711                completed_at_ms,
7712                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7713                counters: Some(DiagnosticRoundCounters {
7714                    pushed: report.pushed,
7715                    applied: report.applied.len(),
7716                    rejected: report.rejected.len(),
7717                    retryable: report.retryable.len(),
7718                    conflicts: report.conflicts,
7719                    commits_applied: report.commits_applied,
7720                    segment_rows_applied: report.segment_rows_applied,
7721                    bootstrapping: report.bootstrapping.len(),
7722                    resets: report.resets.len(),
7723                    revoked: report.revoked.len(),
7724                    failed: report.failed.len(),
7725                    deferred_commits: report.deferred_commits,
7726                }),
7727                error_code: None,
7728                cause_kind: None,
7729                http_status: None,
7730            },
7731            SyncOutcome::Failed { error_code, .. } => DiagnosticLastRound {
7732                status: "failed".to_owned(),
7733                started_at_ms,
7734                completed_at_ms,
7735                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7736                counters: None,
7737                error_code: Some(Self::diagnostic_code(error_code)),
7738                cause_kind,
7739                http_status,
7740            },
7741            SyncOutcome::RealtimeUnavailable { .. } => DiagnosticLastRound {
7742                status: "failed".to_owned(),
7743                started_at_ms,
7744                completed_at_ms,
7745                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7746                counters: None,
7747                error_code: Some(REALTIME_UNAVAILABLE_CODE.to_owned()),
7748                cause_kind: None,
7749                http_status: None,
7750            },
7751        });
7752        outcome
7753    }
7754
7755    /// Capture one request on the client owner. Mutations made after this
7756    /// call remain in the outbox for a later round; no network I/O occurs here.
7757    pub fn prepare_sync_round(
7758        &mut self,
7759        url_capable: bool,
7760    ) -> Result<crate::PreparedSyncRound, Box<SyncOutcome>> {
7761        if !self.transport_enabled {
7762            return Err(Box::new(SyncOutcome::Failed {
7763                error_code: "sync.offline".into(),
7764                message: "transport gate is closed".into(),
7765                details: None,
7766                recommended_action: None,
7767            }));
7768        }
7769        if self.active_round.is_some() {
7770            return Err(Box::new(SyncOutcome::Failed {
7771                error_code: "client.round_in_progress".into(),
7772                message: "a sync round is already in flight".into(),
7773                details: None,
7774                recommended_action: None,
7775            }));
7776        }
7777        self.storage_failure.borrow_mut().take();
7778        self.progress.start();
7779        self.round_retry_delay_ms = None;
7780        let started_at_ms = self.clock_now_ms();
7781        let prepared = (|| {
7782            if self.stopped {
7783                return Err(Box::new(SyncOutcome::Ok(SyncReport {
7784                    schema_floor: self.schema_floor.clone(),
7785                    ..SyncReport::default()
7786                })));
7787            }
7788            if self.security_preflight {
7789                return Err(Box::new(SyncOutcome::Failed {
7790                    error_code: SECURITY_PREFLIGHT_REQUIRED_CODE.into(),
7791                    message: "security preflight must complete before syncing".into(),
7792                    details: None,
7793                    recommended_action: None,
7794                }));
7795            }
7796            self.set_sync_needed(false, false);
7797            self.drain_pending_evictions()
7798                .and_then(|_| self.drop_incompatible_outbox())
7799                .and_then(|_| self.drop_unencodable_outbox(true, None))
7800                .map_err(|message| {
7801                    Box::new(SyncOutcome::Failed {
7802                        error_code: "storage.failed".into(),
7803                        message,
7804                        details: None,
7805                        recommended_action: None,
7806                    })
7807                })?;
7808            // §5.11: reveal rows sealed under a key the keyring gained since.
7809            self.reveal_sealed_rows().map_err(|error| {
7810                Box::new(SyncOutcome::Failed {
7811                    error_code: error.code,
7812                    message: error.message,
7813                    details: error.details,
7814                    recommended_action: None,
7815                })
7816            })?;
7817            let has_log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7818                Box::new(SyncOutcome::Failed {
7819                    error_code: "storage.failed".into(),
7820                    message,
7821                    details: None,
7822                    recommended_action: None,
7823                })
7824            })?;
7825            let uploads = if has_log_epoch.is_some() && self.schema_has_blobs() {
7826                self.pending_blob_uploads().map_err(|e| {
7827                    Box::new(SyncOutcome::Failed {
7828                        error_code: e.code,
7829                        message: e.message,
7830                        details: e.details,
7831                        recommended_action: None,
7832                    })
7833                })?
7834            } else {
7835                Vec::new()
7836            };
7837            if self.realtime_state != RealtimeState::Connected
7838                && self.realtime_policy == RealtimePolicy::Required
7839            {
7840                let retry_delay_ms = self.schedule_background_retry();
7841                self.realtime_retry_delay_ms = Some(retry_delay_ms);
7842                return Err(Box::new(SyncOutcome::RealtimeUnavailable {
7843                    state: self.realtime_state,
7844                    reason_code: self.realtime_reason_code.clone(),
7845                    retry_delay_ms,
7846                }));
7847            }
7848            let (message, mut meta) = self.build_request(url_capable)?;
7849            let units = self.stored(load_units(&self.conn)).map_err(|message| {
7850                Box::new(SyncOutcome::Failed {
7851                    error_code: "storage.failed".into(),
7852                    message,
7853                    details: None,
7854                    recommended_action: None,
7855                })
7856            })?;
7857            meta.applied = units
7858                .iter()
7859                .filter_map(|unit| {
7860                    let (cursor, token, ids) = self.applied_segments.get(&unit.id)?;
7861                    (*cursor == unit.cursor && *token == unit.bootstrap_state)
7862                        .then(|| (unit.id.clone(), ids.clone()))
7863                })
7864                .collect();
7865            let id = uuid::Uuid::new_v4();
7866            self.active_round = Some(id);
7867            let phase = if uploads.is_empty() {
7868                crate::round::RoundPhase::Sync
7869            } else {
7870                crate::round::RoundPhase::UploadGrant
7871            };
7872            Ok(crate::PreparedSyncRound {
7873                id,
7874                started_at_ms,
7875                message,
7876                meta,
7877                uploads: uploads.into(),
7878                phase,
7879                encoded: None,
7880                continuation: None,
7881                completed: None,
7882                realtime: self.realtime_state == RealtimeState::Connected,
7883                // §5.5: the owning unit's scope map, each value a one-element list.
7884                scopes: units
7885                    .into_iter()
7886                    .map(|unit| {
7887                        (
7888                            unit.id,
7889                            canonical_scope_json(&unit_scope_lists(&unit.scopes)),
7890                        )
7891                    })
7892                    .collect(),
7893                #[cfg(feature = "bench-internals")]
7894                benchmark_phases: self.benchmark_phases.clone(),
7895                progress: self.progress.clone(),
7896                fixed_now: self.now_ms,
7897                round_deadline_at: None,
7898            })
7899        })();
7900        prepared.map_err(|outcome| Box::new(self.finish_sync_round(started_at_ms, *outcome)))
7901    }
7902
7903    /// Discard the reply of an old authorization or registration context. Its
7904    /// submitted commits stay durable and can be retried with the same ids.
7905    pub fn cancel_sync_round(&mut self) {
7906        self.active_round = None;
7907    }
7908
7909    /// Apply captured network results on the owner, preserving all normal
7910    /// version, schema, content-address and cursor checks. No network I/O.
7911    pub fn apply_sync_round(
7912        &mut self,
7913        completed: crate::CompletedSyncRound,
7914    ) -> crate::AppliedSyncRound {
7915        let mut prepared = completed.prepared;
7916        if self.active_round != Some(prepared.id) || self.security_preflight {
7917            return crate::AppliedSyncRound::Complete {
7918                outcome: SyncOutcome::Failed {
7919                    error_code: "client.round_cancelled".into(),
7920                    message: "sync round belongs to a released client context".into(),
7921                    details: None,
7922                    recommended_action: None,
7923                },
7924                controls: Vec::new(),
7925                more: false,
7926                bootstrap_advanced: false,
7927            };
7928        }
7929        self.storage_failure.borrow_mut().take();
7930        let (response, mut downloads, transport_failed) = match completed.exchange {
7931            crate::round::ExchangeResult::Upload { id, result } => {
7932                let result = match result {
7933                    // §5.9.7: a non-retryable server refusal (`blob.too_large`)
7934                    // is the body's final outcome. The commits naming it take
7935                    // the incompatible-commit path with the server's code and
7936                    // leave this round's request; the round continues.
7937                    Err(error)
7938                        if error
7939                            .details
7940                            .as_ref()
7941                            .and_then(|details| details.get("retryable"))
7942                            == Some(&Value::Bool(false)) =>
7943                    {
7944                        self.conn
7945                            .prepare(
7946                                "SELECT commit_id FROM _syncular_blob_commit_refs WHERE blob_id = ?",
7947                            )
7948                            .and_then(|mut statement| {
7949                                statement
7950                                    .query_map(rusqlite::params![id], |row| row.get::<_, String>(0))?
7951                                    .collect::<Result<HashSet<_>, _>>()
7952                            })
7953                            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
7954                            .and_then(|refused| {
7955                                let commits = self
7956                                    .outbox
7957                                    .iter()
7958                                    .filter(|commit| refused.contains(&commit.client_commit_id))
7959                                    .cloned()
7960                                    .collect::<Vec<_>>();
7961                                if !commits.is_empty() {
7962                                    self.drop_outbox_commits(&commits, &error.code, &error.message)?;
7963                                }
7964                                prepared.message.frames.retain(|frame| {
7965                                    !matches!(frame, Frame::PushCommit { client_commit_id, .. }
7966                                        if refused.contains(client_commit_id))
7967                                });
7968                                prepared.meta.pushed_ids.retain(|id| !refused.contains(id));
7969                                prepared.continuation = Some(crate::round::RoundPhase::UploadGrant);
7970                                Ok(())
7971                            })
7972                            .map_err(|message| TransportError::new("client.failed", message))
7973                    }
7974                    result => result,
7975                };
7976                let result = result.and_then(|()| {
7977                    self.conn
7978                        .execute(
7979                            "DELETE FROM _syncular_blob_uploads WHERE blob_id = ?",
7980                            rusqlite::params![id],
7981                        )
7982                        .map(|_| ())
7983                        .map_err(|error| {
7984                            TransportError::new(
7985                                "client.failed",
7986                                Self::sqlite_failure(&self.storage_failure, error),
7987                            )
7988                        })
7989                });
7990                match result {
7991                    Ok(()) => return crate::AppliedSyncRound::Continue(prepared),
7992                    Err(TransportError {
7993                        code,
7994                        message,
7995                        details,
7996                    }) => {
7997                        self.active_round = None;
7998                        if Self::unreachable_transport(&details) {
7999                            // The round's work is still owed; the host's
8000                            // connectivity resume runs it.
8001                            self.set_sync_needed(true, false);
8002                        } else if Self::retryable_failure_code(&code) {
8003                            self.schedule_background_retry();
8004                        }
8005                        let recommended_action = recommended_action_of(&details);
8006                        let outcome = self.finish_sync_round(
8007                            prepared.started_at_ms,
8008                            SyncOutcome::Failed {
8009                                error_code: code,
8010                                message,
8011                                details,
8012                                recommended_action,
8013                            },
8014                        );
8015                        return crate::AppliedSyncRound::Complete {
8016                            outcome,
8017                            controls: Vec::new(),
8018                            more: false,
8019                            bootstrap_advanced: false,
8020                        };
8021                    }
8022                }
8023            }
8024            crate::round::ExchangeResult::Reply {
8025                response,
8026                downloads,
8027                transport_failed,
8028            } => (response, downloads, transport_failed),
8029        };
8030        self.active_round = None;
8031        let before = self.resume_tokens();
8032        let outcome = (|| {
8033            let response = match response {
8034                Ok(response) => {
8035                    // §1.5: a complete, decodable response ends the report, an
8036                    // in-band ERROR included (the server already recorded it).
8037                    self.round_failure = None;
8038                    response
8039                }
8040                Err(TransportError {
8041                    code,
8042                    message,
8043                    details,
8044                }) => {
8045                    // §1.5: the server cannot see a round whose transport
8046                    // failed or whose response never decoded, so its code rides
8047                    // the following requests. A code the frame grammar rejects
8048                    // is not reportable, and the previous code stays.
8049                    if ssp2::model::valid_round_failure_code(&code) {
8050                        self.round_failure = Some(code.clone());
8051                    }
8052                    if transport_failed {
8053                        if prepared.realtime {
8054                            self.set_realtime_state(RealtimeState::Lost, Some(&code));
8055                        }
8056                        if let Err(message) = self.record_lease_error(&code) {
8057                            return SyncOutcome::Failed {
8058                                error_code: "storage.failed".to_owned(),
8059                                message,
8060                                details: None,
8061                                recommended_action: None,
8062                            };
8063                        }
8064                    }
8065                    if Self::retryable_failure_code(&code) && !Self::unreachable_transport(&details)
8066                    {
8067                        let delay = self.schedule_background_retry();
8068                        if prepared.realtime && transport_failed {
8069                            self.realtime_retry_delay_ms = Some(delay);
8070                        }
8071                    }
8072                    let recommended_action = recommended_action_of(&details);
8073                    return SyncOutcome::Failed {
8074                        error_code: code,
8075                        message,
8076                        details,
8077                        recommended_action,
8078                    };
8079                }
8080            };
8081            let mut outcome = self.process_response(&mut downloads, response, &prepared.meta);
8082            if let SyncOutcome::Ok(report) = &mut outcome {
8083                report.deferred_commits = prepared.meta.deferred_commits;
8084            }
8085            match &outcome {
8086                SyncOutcome::Ok(_) => self.reset_background_retry(),
8087                SyncOutcome::Failed {
8088                    error_code,
8089                    details,
8090                    ..
8091                } if Self::retryable_failure_code(error_code)
8092                    && !Self::unreachable_transport(details) =>
8093                {
8094                    self.schedule_background_retry();
8095                }
8096                _ => {}
8097            }
8098            if prepared.meta.deferred_commits > 0 {
8099                self.set_sync_needed(true, true);
8100            }
8101            self.previous_version_lifetime_check();
8102            outcome
8103        })();
8104        match &outcome {
8105            // §7.1: a unit still catching up needs another round, also when the
8106            // drive that started it ends early.
8107            SyncOutcome::Ok(report) if !report.bootstrapping.is_empty() => {
8108                self.set_sync_needed(true, false)
8109            }
8110            // The round's work is still owed; the host's connectivity resume
8111            // runs it.
8112            SyncOutcome::Failed { details, .. } if Self::unreachable_transport(details) => {
8113                self.set_sync_needed(true, false)
8114            }
8115            _ => {}
8116        }
8117        let more = self.transport_enabled
8118            && matches!(&outcome, SyncOutcome::Ok(report)
8119                if report.schema_floor.is_none()
8120                    && (!report.bootstrapping.is_empty()
8121                        || report.commits_applied > 0
8122                        || report.segment_rows_applied > 0
8123                        || !report.resets.is_empty()
8124                        || report.deferred_commits > 0
8125                        || self.sync_needed));
8126        let bootstrap_advanced = matches!(&outcome, SyncOutcome::Ok(report) if report.segment_rows_applied > 0 && !report.bootstrapping.is_empty())
8127            && before != self.resume_tokens();
8128        crate::AppliedSyncRound::Complete {
8129            outcome: self.finish_sync_round(prepared.started_at_ms, outcome),
8130            controls: if self.transport_enabled {
8131                downloads.controls
8132            } else {
8133                Vec::new()
8134            },
8135            more,
8136            bootstrap_advanced,
8137        }
8138    }
8139
8140    /// Every unit's resume token and applied-segment count: a bootstrap that
8141    /// advanced changes one (§4.7), also when it applied images of a section
8142    /// it deferred (§5.3, §5.6).
8143    fn resume_tokens(&self) -> Option<Vec<(String, Option<String>, usize)>> {
8144        load_units(&self.conn).ok().map(|units| {
8145            units
8146                .into_iter()
8147                .map(|unit| {
8148                    let applied = self
8149                        .applied_segments
8150                        .get(&unit.id)
8151                        .map_or(0, |(_, _, ids)| ids.len());
8152                    (unit.id, unit.bootstrap_state, applied)
8153                })
8154                .collect()
8155        })
8156    }
8157
8158    /// §7.8: one idle drive's default total deadline, the TS client's value.
8159    pub const SYNC_IDLE_TIMEOUT_MS: u64 = 60_000;
8160
8161    pub fn sync_until_idle(
8162        &mut self,
8163        transport: &mut dyn Transport,
8164        max_rounds: Option<u32>,
8165    ) -> SyncOutcome {
8166        self.sync_until_idle_with_deadline(transport, max_rounds, Some(Self::SYNC_IDLE_TIMEOUT_MS))
8167    }
8168
8169    /// As [`SyncClient::sync_until_idle`], with an explicit total deadline in
8170    /// milliseconds (`None` disables it). The deadline is checked between
8171    /// rounds; one blocking transport call is bounded by the transport's own
8172    /// whole-round deadline (§1.8).
8173    pub fn sync_until_idle_with_deadline(
8174        &mut self,
8175        transport: &mut dyn Transport,
8176        max_rounds: Option<u32>,
8177        timeout_ms: Option<u64>,
8178    ) -> SyncOutcome {
8179        // §7.8: an explicit budget is a strict positive round count. Zero is a
8180        // caller error, not an exhaustion.
8181        if max_rounds == Some(0) {
8182            return SyncOutcome::Failed {
8183                details: None,
8184                error_code: "sync.invalid_request".into(),
8185                message: "maxRounds must be a positive integer".into(),
8186                recommended_action: None,
8187            };
8188        }
8189        if timeout_ms.is_some_and(|ms| ms == 0 || i64::try_from(ms).is_err()) {
8190            return SyncOutcome::Failed {
8191                details: None,
8192                error_code: "sync.invalid_request".into(),
8193                message: "timeoutMs must be a positive integer".into(),
8194                recommended_action: None,
8195            };
8196        }
8197        let started_at_ms = self.clock_now_ms();
8198        let deadline_ms = timeout_ms.map(|ms| started_at_ms.saturating_add(ms as i64));
8199        self.sync_until_idle_bounded(transport, max_rounds, started_at_ms, deadline_ms)
8200    }
8201
8202    fn sync_until_idle_bounded(
8203        &mut self,
8204        transport: &mut dyn Transport,
8205        max_rounds: Option<u32>,
8206        started_at_ms: i64,
8207        deadline_ms: Option<i64>,
8208    ) -> SyncOutcome {
8209        let rounds = max_rounds.unwrap_or(20);
8210        let mut aggregate = SyncReport::default();
8211        let mut spent = 0;
8212        while spent < rounds {
8213            if let Some(deadline_ms) = deadline_ms {
8214                if self.clock_now_ms() >= deadline_ms {
8215                    return SyncOutcome::Failed {
8216                        error_code: "sync.idle_timeout".into(),
8217                        message: "sync_until_idle exceeded its deadline".into(),
8218                        details: Some(serde_json::json!({
8219                            "timeoutMs": deadline_ms
8220                                .saturating_sub(started_at_ms) as u64,
8221                            "rounds": spent,
8222                        })),
8223                        recommended_action: Some("retryLater".into()),
8224                    };
8225                }
8226            }
8227            spent += 1;
8228            let before = self.resume_tokens();
8229            match self.sync(transport) {
8230                SyncOutcome::Failed {
8231                    error_code,
8232                    message,
8233                    details,
8234                    recommended_action,
8235                } => {
8236                    return SyncOutcome::Failed {
8237                        details,
8238                        error_code,
8239                        message,
8240                        recommended_action,
8241                    };
8242                }
8243                outcome @ SyncOutcome::RealtimeUnavailable { .. } => return outcome,
8244                SyncOutcome::BudgetExhausted(_) => {
8245                    unreachable!("sync() never exhausts a round budget")
8246                }
8247                SyncOutcome::Ok(report) => {
8248                    if max_rounds.is_none()
8249                        && report.segment_rows_applied > 0
8250                        && !report.bootstrapping.is_empty()
8251                        && before != self.resume_tokens()
8252                    {
8253                        spent = 0;
8254                    }
8255                    // TS parity: a disabled transport or a schema floor ends
8256                    // the loop. The latest round still merges first.
8257                    let stop = !self.transport_enabled() || report.schema_floor.is_some();
8258                    aggregate.merge(&report);
8259                    if stop {
8260                        return SyncOutcome::Ok(aggregate);
8261                    }
8262                    // §4.5: pull again whenever the response contained
8263                    // commits or segments; resets re-bootstrap; a pending
8264                    // resume token continues paging (§4.7); deferred outbox
8265                    // commits and a raised sync-needed signal push on the next
8266                    // round.
8267                    let more = !report.bootstrapping.is_empty()
8268                        || report.commits_applied > 0
8269                        || report.segment_rows_applied > 0
8270                        || !report.resets.is_empty()
8271                        || report.deferred_commits > 0
8272                        || self.sync_needed;
8273                    if !more {
8274                        return SyncOutcome::Ok(aggregate);
8275                    }
8276                }
8277            }
8278        }
8279        // §7.8: partial success. The aggregate report is retained and the run
8280        // is explicitly not idle.
8281        SyncOutcome::BudgetExhausted(aggregate)
8282    }
8283
8284    fn process_response(
8285        &mut self,
8286        transport: &mut dyn Transport,
8287        response: Message,
8288        meta: &RequestMeta,
8289    ) -> SyncOutcome {
8290        #[cfg(feature = "bench-internals")]
8291        let _phase = self.benchmark_phases.start(Phase::ResponseApply);
8292        let mut report = SyncReport {
8293            pushed: meta.pushed_ids.len() as u32,
8294            ..SyncReport::default()
8295        };
8296        let mut rejection_details_by_commit: HashMap<String, BTreeMap<i32, RejectionDetails>> =
8297            HashMap::new();
8298        let pushed_ids = meta
8299            .pushed_ids
8300            .iter()
8301            .map(String::as_str)
8302            .collect::<HashSet<_>>();
8303        let mut last_final_push_result_id: Option<String> = None;
8304        for frame in &response.frames {
8305            match frame {
8306                Frame::PushResultDetails {
8307                    client_commit_id,
8308                    entries,
8309                } => {
8310                    let details = rejection_details_by_commit
8311                        .entry(client_commit_id.clone())
8312                        .or_default();
8313                    for entry in entries {
8314                        let parsed = match RejectionDetails::parse(&entry.details.0) {
8315                            Ok(value) => value,
8316                            Err(message) => {
8317                                return SyncOutcome::Failed {
8318                                    details: None,
8319                                    error_code: "sync.invalid_request".to_owned(),
8320                                    message,
8321                                    recommended_action: None,
8322                                };
8323                            }
8324                        };
8325                        details.insert(entry.op_index, parsed);
8326                    }
8327                }
8328                Frame::PushResult {
8329                    client_commit_id,
8330                    status,
8331                    results,
8332                    ..
8333                } if pushed_ids.contains(client_commit_id.as_str())
8334                    && Self::push_result_is_final(*status, results) =>
8335                {
8336                    last_final_push_result_id = Some(client_commit_id.clone());
8337                }
8338                _ => {}
8339            }
8340        }
8341        let mut frames = response.frames.into_iter().peekable();
8342        match frames.next() {
8343            Some(Frame::RespHeader {
8344                required_schema_version,
8345                latest_schema_version,
8346                log_epoch,
8347                reset_required,
8348            }) => {
8349                if let Some(required) = required_schema_version {
8350                    // §1.6 schema-floor response: nothing else is processed;
8351                    // stop syncing and surface the upgrade requirement.
8352                    let floor = SchemaFloor {
8353                        required_schema_version: Some(required),
8354                        latest_schema_version,
8355                    };
8356                    if let Err(message) = self.set_schema_floor(Some(floor.clone())) {
8357                        return SyncOutcome::Failed {
8358                            details: None,
8359                            error_code: "storage.failed".to_owned(),
8360                            message,
8361                            recommended_action: None,
8362                        };
8363                    }
8364                    report.schema_floor = Some(floor);
8365                    return SyncOutcome::Ok(report);
8366                }
8367                if reset_required {
8368                    if frames.next().is_some() {
8369                        return SyncOutcome::Failed {
8370                            details: None,
8371                            error_code: "client.invalid_host_response".to_owned(),
8372                            message: "log-epoch reset response contains body frames".to_owned(),
8373                            recommended_action: None,
8374                        };
8375                    }
8376                    match self.run_log_epoch_reset(&log_epoch) {
8377                        Ok(resets) => {
8378                            report.resets = resets;
8379                            return SyncOutcome::Ok(report);
8380                        }
8381                        Err(message) => {
8382                            return SyncOutcome::Failed {
8383                                details: None,
8384                                error_code: "sync.local_corrupt".to_owned(),
8385                                message,
8386                                recommended_action: None,
8387                            };
8388                        }
8389                    }
8390                }
8391                let stored_epoch = match self.get_meta(LOG_EPOCH_KEY) {
8392                    Ok(stored) => stored,
8393                    Err(message) => {
8394                        return SyncOutcome::Failed {
8395                            details: None,
8396                            error_code: "storage.failed".to_owned(),
8397                            message,
8398                            recommended_action: None,
8399                        };
8400                    }
8401                };
8402                if stored_epoch.as_deref() != Some(log_epoch.as_str()) {
8403                    return SyncOutcome::Failed {
8404                        details: None,
8405                        error_code: "client.invalid_host_response".to_owned(),
8406                        message: "server changed logEpoch without requiring a reset".to_owned(),
8407                        recommended_action: None,
8408                    };
8409                }
8410            }
8411            _ => {
8412                return SyncOutcome::Failed {
8413                    details: None,
8414                    error_code: "sync.invalid_request".to_owned(),
8415                    message: "response does not start with RESP_HEADER".to_owned(),
8416                    recommended_action: None,
8417                };
8418            }
8419        }
8420
8421        if let Err(message) = self.begin_coalesced_apply() {
8422            return SyncOutcome::Failed {
8423                details: None,
8424                error_code: "storage.failed".into(),
8425                message,
8426                recommended_action: None,
8427            };
8428        }
8429        let mut failure: Option<(String, String, Option<String>, Option<Value>)> = None;
8430        // §4.5 client application: the units whose persisted echo a live
8431        // change must match, fixed at LIVE_START after every SUB_END persisted.
8432        let mut live: Option<(LiveStatus, String, Vec<UnitRecord>)> = None;
8433        let mut live_ended = false;
8434        while let Some(frame) = frames.next() {
8435            match frame {
8436                frame @ Frame::PushResult { .. } => {
8437                    let successful = matches!(
8438                        &frame,
8439                        Frame::PushResult {
8440                            status: PushStatus::Applied | PushStatus::Cached,
8441                            ..
8442                        }
8443                    );
8444                    let mut results = vec![frame];
8445                    if successful {
8446                        while matches!(
8447                            frames.peek(),
8448                            Some(Frame::PushResult {
8449                                status: PushStatus::Applied | PushStatus::Cached,
8450                                ..
8451                            })
8452                        ) {
8453                            if let Some(next) = frames.next() {
8454                                results.push(next);
8455                            }
8456                        }
8457                    }
8458                    if self
8459                        .handle_push_results(
8460                            &results,
8461                            &pushed_ids,
8462                            &rejection_details_by_commit,
8463                            &mut report,
8464                            last_final_push_result_id.as_deref(),
8465                        )
8466                        .is_err()
8467                    {
8468                        failure = Some((
8469                            "client.outcome_persistence_failed".to_owned(),
8470                            "local commit outcome could not be persisted".to_owned(),
8471                            None,
8472                            None,
8473                        ));
8474                        break;
8475                    }
8476                }
8477                Frame::PushResultDetails { .. } => {}
8478                Frame::SubStart {
8479                    id,
8480                    status,
8481                    reason_code,
8482                    bootstrap,
8483                    fenced,
8484                } => {
8485                    // §1.4 rule 5: an ERROR closes the section; its body still
8486                    // applied, its SUB_END values are never persisted.
8487                    let mut body = Vec::new();
8488                    let mut sub_end: Option<(i64, Option<String>)> = None;
8489                    let mut error: Option<Frame> = None;
8490                    for inner in frames.by_ref() {
8491                        match inner {
8492                            Frame::SubEnd {
8493                                next_cursor,
8494                                bootstrap_state,
8495                            } => {
8496                                sub_end = Some((next_cursor, bootstrap_state.map(|r| r.0)));
8497                                break;
8498                            }
8499                            inner @ Frame::Error { .. } => {
8500                                error = Some(inner);
8501                                break;
8502                            }
8503                            Frame::Unknown { .. } => {}
8504                            other => body.push(other),
8505                        }
8506                    }
8507                    let ended = sub_end.is_some();
8508                    let section = SectionStart {
8509                        id,
8510                        status,
8511                        reason_code,
8512                        bootstrap,
8513                        fenced,
8514                    };
8515                    match self.process_section(
8516                        transport,
8517                        &section,
8518                        body,
8519                        sub_end,
8520                        meta,
8521                        &mut report,
8522                    ) {
8523                        Err(SectionError::Abort(code, message)) => {
8524                            failure = Some((code, message, None, None));
8525                            break;
8526                        }
8527                        Err(SectionError::Transport(error)) => {
8528                            failure = Some((error.code, error.message, None, error.details));
8529                            break;
8530                        }
8531                        _ => {}
8532                    }
8533                    if ended {
8534                        // The counters stay: `complete` and `failed` report them.
8535                        self.progress.update(|p| {
8536                            p.unit_id = None;
8537                            p.table = None;
8538                            p.segment_id = None;
8539                        });
8540                    }
8541                    match error {
8542                        Some(Frame::Error {
8543                            code,
8544                            message,
8545                            recommended_action,
8546                            details,
8547                            ..
8548                        }) => {
8549                            failure = Some(Self::error_frame_failure(
8550                                code,
8551                                message,
8552                                recommended_action,
8553                                details,
8554                            ));
8555                            break;
8556                        }
8557                        Some(_) => unreachable!("only an ERROR closes a section early"),
8558                        None if !ended => {
8559                            failure = Some((
8560                                "sync.invalid_request".to_owned(),
8561                                "unit section without SUB_END".to_owned(),
8562                                None,
8563                                None,
8564                            ));
8565                            break;
8566                        }
8567                        None => {}
8568                    }
8569                }
8570                Frame::LiveStart {
8571                    status,
8572                    reason_code,
8573                } => {
8574                    let receivers = match self.stored(load_units(&self.conn)) {
8575                        Ok(units) => units
8576                            .into_iter()
8577                            .filter(|unit| {
8578                                unit.status == UnitStatus::Active
8579                                    && unit.echo.is_some()
8580                                    && !unit.bootstrapping()
8581                            })
8582                            .collect(),
8583                        Err(message) => {
8584                            failure = Some(("storage.failed".to_owned(), message, None, None));
8585                            break;
8586                        }
8587                    };
8588                    live = Some((status, reason_code, receivers));
8589                }
8590                Frame::Commit {
8591                    commit_seq,
8592                    tables,
8593                    changes,
8594                    ..
8595                } => {
8596                    let Some((LiveStatus::Active, _, receivers)) = &live else {
8597                        continue;
8598                    };
8599                    let receivers = receivers.clone();
8600                    match self.apply_live_commit(
8601                        &receivers,
8602                        &tables,
8603                        changes,
8604                        commit_seq,
8605                        AppliedServerCommitSource::Pull,
8606                    ) {
8607                        Ok(applied) => report.commits_applied += u32::from(applied),
8608                        Err(error) => {
8609                            failure = Some((error.code, error.message, None, error.details));
8610                            break;
8611                        }
8612                    }
8613                }
8614                Frame::LiveEnd {
8615                    through_seq,
8616                    echo_digest,
8617                } => {
8618                    let Some((status, reason_code, _)) = live.take() else {
8619                        continue;
8620                    };
8621                    live_ended = true;
8622                    live = Some((status, String::new(), Vec::new()));
8623                    if let Err(message) = self.finish_live_section(
8624                        status,
8625                        &reason_code,
8626                        through_seq,
8627                        echo_digest,
8628                        &meta.registration_digest,
8629                        &mut report,
8630                    ) {
8631                        failure = Some(("storage.failed".to_owned(), message, None, None));
8632                        break;
8633                    }
8634                }
8635                Frame::Lease {
8636                    lease_id,
8637                    expires_at_ms,
8638                } => {
8639                    // §7.3.5: persist the opaque lease; a fresh lease clears
8640                    // any prior lease error (the outage/revocation is over).
8641                    if let Err(message) = self.set_lease_state(Some(LeaseState {
8642                        lease_id: Some(lease_id),
8643                        expires_at_ms: Some(expires_at_ms),
8644                        error_code: None,
8645                    })) {
8646                        failure = Some(("storage.failed".to_owned(), message, None, None));
8647                        break;
8648                    }
8649                }
8650                Frame::Error {
8651                    code,
8652                    message,
8653                    recommended_action,
8654                    details,
8655                    ..
8656                } => {
8657                    // §1.6: the whole request failed; already-completed
8658                    // units keep their applied data and cursors.
8659                    failure = Some(Self::error_frame_failure(
8660                        code,
8661                        message,
8662                        recommended_action,
8663                        details,
8664                    ));
8665                    break;
8666                }
8667                Frame::Unknown { .. } => {}
8668                _ => {
8669                    failure = Some((
8670                        "sync.invalid_request".to_owned(),
8671                        "unexpected frame in response".to_owned(),
8672                        None,
8673                        None,
8674                    ));
8675                    break;
8676                }
8677            }
8678        }
8679
8680        let applied = match failure {
8681            Some(failure) => Err(failure),
8682            // Local apply boundaries already reconciled their affected overlay.
8683            // Refuse round success if any remaining dirty work fails to
8684            // reconcile. §4.8 E1: the push half may have drained commits that
8685            // pinned rows of a shrunk window unit, so retry deferred evictions.
8686            None => self
8687                .rebuild_overlay_if_dirty()
8688                .and_then(|()| self.drain_pending_evictions())
8689                .map_err(|message| ("storage.failed".to_owned(), message, None, None)),
8690        };
8691        // §1.4 rule 4: frames completed before a failure stay committed; a
8692        // failed COMMIT of the coalesced transaction fails the round.
8693        if let Err(message) = self.finish_coalesced_apply() {
8694            return SyncOutcome::Failed {
8695                details: None,
8696                error_code: "storage.failed".into(),
8697                message,
8698                recommended_action: None,
8699            };
8700        }
8701        if let Err((error_code, message, recommended_action, details)) = applied {
8702            return SyncOutcome::Failed {
8703                details,
8704                error_code,
8705                message,
8706                recommended_action,
8707            };
8708        }
8709        let catching_up = match self.stored(load_units(&self.conn)) {
8710            Ok(units) => units
8711                .into_iter()
8712                .filter(|unit| unit.status == UnitStatus::Active && unit.cursor.is_some())
8713                .map(|unit| unit.id)
8714                .collect::<Vec<_>>(),
8715            Err(message) => {
8716                return SyncOutcome::Failed {
8717                    details: None,
8718                    error_code: "storage.failed".into(),
8719                    message,
8720                    recommended_action: None,
8721                }
8722            }
8723        };
8724        // §7.1: a response without LIVE_END, one answered `unregistered` or
8725        // `reset`, or a unit still catching up leaves sync-needed raised;
8726        // after `unregistered` the next round starts at once.
8727        let status = live.map(|(status, _, _)| status);
8728        if !live_ended || status != Some(LiveStatus::Active) || !catching_up.is_empty() {
8729            self.set_sync_needed(true, status == Some(LiveStatus::Unregistered));
8730        }
8731        self.ack_after_pull(transport);
8732        // §7.4.5: the reset is over once the first post-reset pull round
8733        // leaves no unit catching up: the tables are rebuilt and current.
8734        if self.upgrading && catching_up.is_empty() {
8735            self.set_upgrading(false);
8736        }
8737        report.bootstrapping = catching_up;
8738        SyncOutcome::Ok(report)
8739    }
8740
8741    /// §1.6 / §10.1: the failure an in-band `ERROR` frame reports.
8742    fn error_frame_failure(
8743        code: String,
8744        message: String,
8745        recommended_action: String,
8746        details: Option<RawJson>,
8747    ) -> (String, String, Option<String>, Option<Value>) {
8748        let recommended_action = (!recommended_action.is_empty()).then_some(recommended_action);
8749        let details = details
8750            .and_then(|details| serde_json::from_str::<Value>(&details.0).ok())
8751            .filter(Value::is_object);
8752        (code, message, recommended_action, details)
8753    }
8754
8755    /// §4.5 at `LIVE_END` of a pull: join rule J for an `active` section, the
8756    /// §4.6 replica reset for `reset`, nothing for `unregistered`; then the
8757    /// replica cursor, the echo digest and the digest of the list the server
8758    /// now stores.
8759    fn finish_live_section(
8760        &mut self,
8761        status: LiveStatus,
8762        reason_code: &str,
8763        through_seq: i64,
8764        echo_digest: Option<[u8; 32]>,
8765        registration_digest: &str,
8766        report: &mut SyncReport,
8767    ) -> Result<(), String> {
8768        let rollback = self.capture();
8769        let resets = report.resets.len();
8770        self.begin_observation("syncular_live_end")?;
8771        let finished = (|| {
8772            let mut batch = ChangeAccumulator::default();
8773            let before = self.stored(replica_cursor(&self.conn))?;
8774            let mut cursor = if status == LiveStatus::Unregistered {
8775                before
8776            } else {
8777                -1
8778            };
8779            let joined = before.max(through_seq);
8780            for unit in self.stored(load_units(&self.conn))? {
8781                if unit.status != UnitStatus::Active || unit.bootstrapping() {
8782                    continue;
8783                }
8784                match status {
8785                    // §4.6 replica reset: every live unit bootstraps again;
8786                    // post-bootstrap units keep their cursors.
8787                    LiveStatus::Reset if unit.cursor.is_none() => {
8788                        for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
8789                            batch.window(&base_key, &value);
8790                        }
8791                        report.resets.push(unit.id.clone());
8792                        self.stored(save_unit(
8793                            &self.conn,
8794                            &UnitRecord {
8795                                reason_code: Some(reason_code.to_owned()),
8796                                cursor: Some(-1),
8797                                seeded: Vec::new(),
8798                                ..unit
8799                            },
8800                        ))?;
8801                    }
8802                    // §4.5 join rule J.
8803                    LiveStatus::Active => {
8804                        let next = unit.cursor.unwrap_or(joined).max(through_seq);
8805                        if next >= joined {
8806                            cursor = joined;
8807                        }
8808                        if unit.cursor.is_some() {
8809                            self.stored(save_unit(
8810                                &self.conn,
8811                                &UnitRecord {
8812                                    cursor: (next < joined).then_some(next),
8813                                    ..unit
8814                                },
8815                            ))?;
8816                        }
8817                    }
8818                    _ => {}
8819                }
8820            }
8821            self.set_meta(REPLICA_CURSOR_KEY, &cursor.to_string())?;
8822            self.set_meta(
8823                ECHO_DIGEST_KEY,
8824                &echo_digest
8825                    .map(|digest| bytes_to_hex(&digest))
8826                    .unwrap_or_default(),
8827            )?;
8828            if status == LiveStatus::Unregistered {
8829                self.delete_meta(REGISTERED_DIGEST_KEY)?;
8830            } else {
8831                self.set_meta(REGISTERED_DIGEST_KEY, registration_digest)?;
8832            }
8833            self.finish_observation("syncular_live_end", batch)
8834        })();
8835        if finished.is_err() {
8836            self.rollback_observation("syncular_live_end");
8837            self.restore(rollback);
8838            report.resets.truncate(resets);
8839        }
8840        finished
8841    }
8842
8843    // -- push results (§6.3, §7.2) ------------------------------------------------
8844
8845    fn handle_push_results(
8846        &mut self,
8847        frames: &[Frame],
8848        pushed_ids: &HashSet<&str>,
8849        rejection_details_by_commit: &HashMap<String, BTreeMap<i32, RejectionDetails>>,
8850        report: &mut SyncReport,
8851        last_final_push_result_id: Option<&str>,
8852    ) -> Result<(), String> {
8853        self.begin_observation("syncular_push_results")?;
8854        let rollback = self.capture();
8855        let conflict_count = self.conflicts.len();
8856        let applied_count = report.applied.len();
8857        let rejected_count = report.rejected.len();
8858        let retryable_count = report.retryable.len();
8859        let mut drained = Vec::new();
8860        let mut batch = ChangeAccumulator::default();
8861        let persisted = (|| {
8862            for frame in frames {
8863                let Frame::PushResult {
8864                    client_commit_id,
8865                    status,
8866                    results,
8867                    commit_seq,
8868                } = frame
8869                else {
8870                    return Err("unexpected acknowledgement frame".to_owned());
8871                };
8872                if !pushed_ids.contains(client_commit_id.as_str()) {
8873                    continue;
8874                }
8875                let Some(index) = self
8876                    .outbox
8877                    .iter()
8878                    .position(|commit| commit.client_commit_id == *client_commit_id)
8879                else {
8880                    continue;
8881                };
8882                let status = *status;
8883                let rejection_details = rejection_details_by_commit.get(client_commit_id);
8884                let operations = self.outbox[index].ops.clone();
8885                match status {
8886                    PushStatus::Applied | PushStatus::Cached => {
8887                        // §7.2: a lost ack replays as `cached` — proceed as if the
8888                        // ack had arrived.
8889                        let sequence =
8890                            commit_seq.ok_or_else(|| "ACK lacks a commit sequence".to_owned())?;
8891                        let affected: HashSet<_> = operations
8892                            .iter()
8893                            .map(|op| (op.table.as_str(), op.row_id.as_str()))
8894                            .collect();
8895                        let prior = self.acknowledged_operations(Some(&affected), None)?;
8896                        for (op_index, operation) in operations.iter().enumerate() {
8897                            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))
8898                                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
8899                            if delivered {
8900                                continue;
8901                            }
8902                            let table = self
8903                                .schema
8904                                .table(&operation.table)
8905                                .ok_or_else(|| "sync.unknown_table".to_owned())?;
8906                            let mut intended: Map<String, Value> = self
8907                                .stored_row(table, &operation.row_id, true)?
8908                                .map(|(row, _)| {
8909                                    table
8910                                        .columns
8911                                        .iter()
8912                                        .zip(&row)
8913                                        .map(|(column, value)| {
8914                                            (column.name.clone(), column_value_to_json(value))
8915                                        })
8916                                        .collect()
8917                                })
8918                                .unwrap_or_default();
8919                            let mut scope_image = intended.clone();
8920                            for op in prior
8921                                .iter()
8922                                .chain(
8923                                    self.failed_commits
8924                                        .iter()
8925                                        .flat_map(|(commit, _)| &commit.ops),
8926                                )
8927                                .chain(
8928                                    self.outbox
8929                                        .iter()
8930                                        .take(index)
8931                                        .flat_map(|commit| &commit.ops),
8932                                )
8933                                .chain(operations.iter().take(op_index + 1))
8934                            {
8935                                if op.table != operation.table || op.row_id != operation.row_id {
8936                                    continue;
8937                                }
8938                                if let Some(values) = &op.values {
8939                                    intended.extend(values.clone());
8940                                } else {
8941                                    scope_image = intended.clone();
8942                                    intended.clear();
8943                                }
8944                            }
8945                            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)",
8946                                rusqlite::params![client_commit_id, op_index as i64, operation.table, operation.row_id, sequence,
8947                                    serde_json::to_string(&CommitOperation::from(operation)).map_err(|_| "sync.local_corrupt".to_owned())?,
8948                                    serde_json::to_string(if operation.upsert { &intended } else { &scope_image }).map_err(|_| "sync.local_corrupt".to_owned())?])
8949                                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
8950                        }
8951                        let journal_results = results
8952                            .iter()
8953                            .map(|result| {
8954                                let op_index = match result {
8955                                    OpResult::Applied { op_index }
8956                                    | OpResult::Conflict { op_index, .. }
8957                                    | OpResult::Error { op_index, .. } => *op_index,
8958                                };
8959                                CommitOperationOutcome::Applied { op_index }
8960                            })
8961                            .collect::<Vec<_>>();
8962                        let outcome_status = if status == PushStatus::Applied {
8963                            CommitOutcomeStatus::Applied
8964                        } else {
8965                            CommitOutcomeStatus::Cached
8966                        };
8967                        let persisted = self
8968                            .persist_commit_outcome(
8969                                client_commit_id,
8970                                outcome_status,
8971                                &journal_results,
8972                                None,
8973                            )
8974                            .and_then(|()| self.delete_outbox_persisted(client_commit_id));
8975                        persisted?;
8976                        self.sync_needed = true;
8977                        batch.status = true;
8978                        batch.outcomes = true;
8979                    }
8980                    PushStatus::Rejected => {
8981                        if results.iter().any(|result| {
8982                            matches!(
8983                                result,
8984                                OpResult::Error {
8985                                    code,
8986                                    retryable: true,
8987                                    ..
8988                                } if code == "sync.idempotency_cache_miss"
8989                            )
8990                        }) {
8991                            // §6.3/§7.2: a serving failure, not an outcome — keep the
8992                            // exact commit queued for an identical retry.
8993                            report.retryable.push(client_commit_id.to_owned());
8994                            continue;
8995                        }
8996
8997                        let mut journal_results = Vec::with_capacity(results.len());
8998                        let mut conflicts = Vec::new();
8999                        let mut rejections = Vec::new();
9000                        for result in results {
9001                            match result {
9002                                OpResult::Applied { op_index } => {
9003                                    journal_results.push(CommitOperationOutcome::Applied {
9004                                        op_index: *op_index,
9005                                    });
9006                                }
9007                                OpResult::Conflict {
9008                                    op_index,
9009                                    code,
9010                                    message,
9011                                    server_version,
9012                                    server_row,
9013                                    conflict_columns: conflict_columns_bitmap,
9014                                } => {
9015                                    let operation = operations
9016                                        .get(*op_index as usize)
9017                                        .map(CommitOperation::from);
9018                                    let (table, row_id) = operation
9019                                        .as_ref()
9020                                        .map(|op| (op.table.clone(), op.row_id.clone()))
9021                                        .unwrap_or_default();
9022                                    let server_row_json = self
9023                                        .schema
9024                                        .table(&table)
9025                                        .and_then(|t| {
9026                                            decode_row_bytes(t, server_row, &self.encryption)
9027                                                .ok()
9028                                                .map(|(row, _)| (t, row))
9029                                        })
9030                                        .map(|(t, row)| {
9031                                            let mut map = Map::new();
9032                                            for (i, column) in t.columns.iter().enumerate() {
9033                                                map.insert(
9034                                                    column.name.clone(),
9035                                                    column_value_to_json(
9036                                                        row.get(i).unwrap_or(&None),
9037                                                    ),
9038                                                );
9039                                            }
9040                                            map
9041                                        })
9042                                        .unwrap_or_default();
9043                                    // §6.3: decode the presence-layout bitmap
9044                                    // into the marked column names.
9045                                    let conflict_columns = self
9046                                        .schema
9047                                        .table(&table)
9048                                        .map(|t| {
9049                                            t.columns
9050                                                .iter()
9051                                                .enumerate()
9052                                                .filter(|(index, _)| {
9053                                                    conflict_columns_bitmap
9054                                                        .get(index / 8)
9055                                                        .is_some_and(|byte| {
9056                                                            byte & (1 << (index % 8)) != 0
9057                                                        })
9058                                                })
9059                                                .map(|(_, column)| column.name.clone())
9060                                                .collect::<Vec<_>>()
9061                                        })
9062                                        .unwrap_or_default();
9063                                    let conflict = ConflictRecord {
9064                                        client_commit_id: client_commit_id.to_owned(),
9065                                        op_index: *op_index,
9066                                        table,
9067                                        row_id,
9068                                        code: code.clone(),
9069                                        message: message.clone(),
9070                                        server_version: *server_version,
9071                                        server_row: server_row_json,
9072                                        conflict_columns,
9073                                        operation,
9074                                    };
9075                                    journal_results.push(CommitOperationOutcome::Conflict {
9076                                        conflict: conflict.clone(),
9077                                    });
9078                                    conflicts.push(conflict);
9079                                }
9080                                OpResult::Error {
9081                                    op_index,
9082                                    code,
9083                                    message,
9084                                    retryable,
9085                                } => {
9086                                    let rejection = RejectionRecord {
9087                                        client_commit_id: client_commit_id.to_owned(),
9088                                        op_index: *op_index,
9089                                        code: code.clone(),
9090                                        message: message.clone(),
9091                                        retryable: *retryable,
9092                                        details: rejection_details
9093                                            .and_then(|details| details.get(op_index))
9094                                            .cloned(),
9095                                        operation: operations
9096                                            .get(*op_index as usize)
9097                                            .map(CommitOperation::from),
9098                                    };
9099                                    journal_results.push(CommitOperationOutcome::Error {
9100                                        rejection: rejection.clone(),
9101                                    });
9102                                    rejections.push(rejection);
9103                                }
9104                            }
9105                        }
9106                        if self.retain_failed_commits {
9107                            self.retain_failed_commit(client_commit_id, &operations)?;
9108                        }
9109                        let outcome_status = if conflicts.is_empty() {
9110                            CommitOutcomeStatus::Rejected
9111                        } else {
9112                            CommitOutcomeStatus::Conflict
9113                        };
9114                        let persisted = self
9115                            .persist_commit_outcome(
9116                                client_commit_id,
9117                                outcome_status,
9118                                &journal_results,
9119                                Some(&operations),
9120                            )
9121                            .and_then(|()| self.delete_outbox_persisted(client_commit_id));
9122                        persisted?;
9123                        batch.conflicts = !conflicts.is_empty();
9124                        batch.rejections = !rejections.is_empty();
9125                        batch.status = true;
9126                        batch.outcomes = true;
9127                        self.conflicts.extend(conflicts);
9128                        self.rejections.extend(rejections);
9129                    }
9130                }
9131                drained.push(self.outbox.remove(index));
9132                if batch.status {
9133                    for operation in &operations {
9134                        if !self.record_row_scopes(
9135                            &mut batch,
9136                            &operation.table,
9137                            &operation.row_id,
9138                            false,
9139                        ) {
9140                            batch.table(&operation.table);
9141                        }
9142                    }
9143                }
9144                match status {
9145                    PushStatus::Applied | PushStatus::Cached => {
9146                        report.applied.push(client_commit_id.to_owned())
9147                    }
9148                    PushStatus::Rejected => report.rejected.push(client_commit_id.to_owned()),
9149                }
9150            }
9151            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)) {
9152                self.prune_commit_outcomes()?;
9153            }
9154            self.reconcile_rows(&drained)?;
9155            self.rebuild_overlay_if_dirty()?;
9156            self.finish_observation("syncular_push_results", batch)
9157        })();
9158        if let Err(error) = persisted {
9159            self.rollback_observation("syncular_push_results");
9160            self.restore(rollback);
9161            report.applied.truncate(applied_count);
9162            report.rejected.truncate(rejected_count);
9163            report.retryable.truncate(retryable_count);
9164            return Err(error);
9165        }
9166        if !rollback.sync_needed && self.sync_needed {
9167            self.sync_intent_queue.push_back(SyncIntent::Interactive);
9168        }
9169        report.conflicts += (self.conflicts.len() - conflict_count) as u32;
9170        Ok(())
9171    }
9172
9173    fn push_result_is_final(status: PushStatus, results: &[OpResult]) -> bool {
9174        status != PushStatus::Rejected
9175            || !results.iter().any(|result| {
9176                matches!(
9177                    result,
9178                    OpResult::Error {
9179                        code,
9180                        retryable: true,
9181                        ..
9182                    } if code == "sync.idempotency_cache_miss"
9183                )
9184            })
9185    }
9186
9187    // -- unit sections and the live section ------------------------------------------
9188
9189    /// One unit section (§4.4): apply its segments, then persist its
9190    /// `SUB_END` (§4.6 reset, §3.3 revocation and purge, the echo, cursor and
9191    /// resume token). A section of a unit the app released while the round was
9192    /// in flight is skipped; a fail-closed first page fails the unit and skips
9193    /// the rest of its section (§5.6).
9194    fn process_section(
9195        &mut self,
9196        transport: &mut dyn Transport,
9197        start: &SectionStart,
9198        body: Vec<Frame>,
9199        sub_end: Option<(i64, Option<String>)>,
9200        meta: &RequestMeta,
9201        report: &mut SyncReport,
9202    ) -> Result<(), SectionError> {
9203        let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
9204        let unit = self
9205            .stored(get_unit(&self.conn, &start.id))
9206            .map_err(storage)?
9207            .filter(|unit| unit.status == UnitStatus::Active);
9208        // §7.7: a section boundary ends the previous payload.
9209        self.progress.update(|p| {
9210            p.phase = ProgressPhase::Import;
9211            p.unit_id = unit.as_ref().map(|unit| unit.id.clone());
9212            p.table = None;
9213            p.segment_id = None;
9214            p.bytes_received = 0;
9215            p.bytes_total = None;
9216            p.rows_processed = 0;
9217            p.rows_total = None;
9218            p.import_write_ms = None;
9219            p.import_commit_ms = None;
9220        });
9221        let Some(unit) = unit else {
9222            return Ok(());
9223        };
9224        let echo: Vec<EchoRecord> = start
9225            .fenced
9226            .iter()
9227            .map(|record| EchoRecord {
9228                table: record.table.clone(),
9229                status: record.status.name().to_owned(),
9230                scopes: record.scopes.iter().cloned().collect(),
9231            })
9232            .collect();
9233        // §5.6: the applied-segment record ends when the presented cursor or
9234        // token changes.
9235        if self
9236            .applied_segments
9237            .get(&unit.id)
9238            .is_some_and(|(cursor, token, _)| {
9239                (*cursor, token) != (unit.cursor, &unit.bootstrap_state)
9240            })
9241        {
9242            self.applied_segments.remove(&unit.id);
9243        }
9244        // §5.6: a resumed bootstrap keeps the tables it already seeded.
9245        let mut seeded: BTreeSet<String> = if unit.bootstrap_state.is_none() {
9246            BTreeSet::new()
9247        } else {
9248            unit.seeded.iter().cloned().collect()
9249        };
9250        let applied = (|| {
9251            for frame in body {
9252                match frame {
9253                    Frame::SegmentInline { payload } => {
9254                        let segment = decode_rows_segment(&payload).map_err(|e| {
9255                            SectionError::Abort(e.code.as_str().to_owned(), e.detail)
9256                        })?;
9257                        self.progress.update(|p| {
9258                            p.phase = ProgressPhase::Import;
9259                            p.unit_id = Some(unit.id.clone());
9260                            p.table = Some(segment.table.clone());
9261                            p.segment_id = None;
9262                            p.bytes_received = payload.len() as u64;
9263                            p.bytes_total = Some(payload.len() as u64);
9264                            p.rows_processed = 0;
9265                            p.rows_total =
9266                                Some(segment.blocks.iter().map(|block| block.len() as u64).sum());
9267                            p.import_write_ms = None;
9268                            p.import_commit_ms = None;
9269                        });
9270                        let (pair, clear, effective) =
9271                            self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
9272                        report.segment_rows_applied +=
9273                            self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
9274                        seeded.insert(segment.table);
9275                    }
9276                    Frame::SegmentRef {
9277                        segment_id,
9278                        byte_length,
9279                        media_type,
9280                        table,
9281                        row_count,
9282                        as_of_commit_seq,
9283                        scope_digest,
9284                        row_cursor,
9285                        next_row_cursor,
9286                        url,
9287                        url_expires_at_ms,
9288                        ..
9289                    } => {
9290                        // §4.2: reject a descriptor whose mediaType was not
9291                        // advertised — never skip or guess.
9292                        let advertised = match media_type {
9293                            MediaType::Rows => {
9294                                meta.accept & ACCEPT_EXTERNAL_ROWS != 0
9295                                    || meta.accept & ACCEPT_INLINE_ROWS != 0
9296                            }
9297                            MediaType::Sqlite => meta.accept & ACCEPT_SQLITE != 0,
9298                        };
9299                        if !advertised {
9300                            return Err(SectionError::Abort(
9301                                "sync.invalid_request".to_owned(),
9302                                format!(
9303                                    "SEGMENT_REF mediaType {} was not advertised in accept (§4.2)",
9304                                    media_type.name()
9305                                ),
9306                            ));
9307                        }
9308                        // §5.6 applied-segment rule.
9309                        if meta
9310                            .applied
9311                            .get(&unit.id)
9312                            .is_some_and(|ids| ids.contains(&segment_id))
9313                        {
9314                            seeded.insert(table);
9315                            continue;
9316                        }
9317                        if meta
9318                            .deferred
9319                            .contains(&(unit.id.clone(), segment_id.clone()))
9320                        {
9321                            return Err(SectionError::Deferred);
9322                        }
9323                        self.progress.update(|p| {
9324                            p.phase = ProgressPhase::Download;
9325                            p.unit_id = Some(unit.id.clone());
9326                            p.table = Some(table.clone());
9327                            p.segment_id = Some(segment_id.clone());
9328                            p.bytes_received = 0;
9329                            p.bytes_total = u64::try_from(byte_length).ok();
9330                            p.rows_processed = 0;
9331                            p.rows_total = u64::try_from(row_count).ok();
9332                            p.import_write_ms = None;
9333                            p.import_commit_ms = None;
9334                        });
9335                        let observer = self.progress.clone();
9336                        let mut on_progress = |bytes| observer.update(|p| p.bytes_received = bytes);
9337                        let bytes = if let Some(url) = url {
9338                            // §5.4: a url-carrying descriptor MUST be fetched
9339                            // from that URL; failure invalidates the whole
9340                            // descriptor (no fall-through to §5.5 — re-pull
9341                            // recovers, §1.4 rule 5).
9342                            if meta.accept & ACCEPT_SIGNED_URLS == 0 {
9343                                return Err(SectionError::Abort(
9344                                    "sync.invalid_request".to_owned(),
9345                                    "SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)"
9346                                        .to_owned(),
9347                                ));
9348                            }
9349                            // §5.4: MUST NOT start a fetch at/past expiry.
9350                            if url_expires_at_ms.is_some_and(|exp| {
9351                                exp <= transport
9352                                    .segment_fetch_started_at(&url)
9353                                    .unwrap_or_else(|| self.clock_now_ms())
9354                            }) {
9355                                return Err(SectionError::Abort(
9356                                    "sync.segment_expired".to_owned(),
9357                                    format!(
9358                                        "signed URL for segment {segment_id} expired before fetch — re-pull mints fresh descriptors (§5.4)"
9359                                    ),
9360                                ));
9361                            }
9362                            transport
9363                                .fetch_url(
9364                                    &url,
9365                                    u64::try_from(byte_length).unwrap_or(0),
9366                                    &mut on_progress,
9367                                )
9368                                .map_err(|e| self.segment_fetch_failed(e))?
9369                        } else {
9370                            // §5.5: the owning unit's scope map, each value a one-element list.
9371                            let requested_scopes_json =
9372                                canonical_scope_json(&unit_scope_lists(&unit.scopes));
9373                            transport
9374                                .download_segment(
9375                                    &SegmentRequest {
9376                                        segment_id: segment_id.clone(),
9377                                        table: table.clone(),
9378                                        requested_scopes_json,
9379                                        byte_length: u64::try_from(byte_length).unwrap_or(0),
9380                                    },
9381                                    &mut on_progress,
9382                                )
9383                                .map_err(|e| {
9384                                    // §5.5: access changed since the response;
9385                                    // the next round's SUB_START settles the unit.
9386                                    if e.code == "sync.forbidden" {
9387                                        SectionError::Refused
9388                                    } else {
9389                                        self.segment_fetch_failed(e)
9390                                    }
9391                                })?
9392                        };
9393                        // §5.4: the descriptor's byteLength caps the body before
9394                        // §5.1 verifies the content address; the client discards
9395                        // the segment and re-pulls on either failure.
9396                        if bytes.len() as i64 > byte_length {
9397                            self.schedule_background_retry();
9398                            return Err(SectionError::Abort(
9399                                "sync.invalid_request".to_owned(),
9400                                "segment exceeds its byteLength".to_owned(),
9401                            ));
9402                        }
9403                        on_progress(bytes.len() as u64);
9404                        let digest = Sha256::digest(&bytes);
9405                        let expected = segment_id
9406                            .strip_prefix("sha256:")
9407                            .unwrap_or(segment_id.as_str());
9408                        if bytes_to_hex(&digest) != expected {
9409                            // §5.1: the client discards the segment and re-pulls.
9410                            self.schedule_background_retry();
9411                            return Err(SectionError::Abort(
9412                                "sync.invalid_request".to_owned(),
9413                                "segment bytes do not match the content address (§5.1)".to_owned(),
9414                            ));
9415                        }
9416                        self.progress.update(|p| p.phase = ProgressPhase::Import);
9417                        if media_type == MediaType::Sqlite {
9418                            // §5.3: a range image keeps its position in the resume
9419                            // token; a descriptor row cursor is invalid.
9420                            if row_cursor.is_some() || next_row_cursor.is_some() {
9421                                return Err(SectionError::Abort(
9422                                    "sync.invalid_request".to_owned(),
9423                                    "sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)"
9424                                        .to_owned(),
9425                                ));
9426                            }
9427                            let (pair, clear, effective) =
9428                                self.segment_pair(&unit, &echo, &seeded, &table)?;
9429                            report.segment_rows_applied += self.apply_sqlite_segment(
9430                                &pair,
9431                                &bytes,
9432                                clear,
9433                                &effective,
9434                                &unit.id,
9435                                row_count,
9436                                as_of_commit_seq,
9437                                &scope_digest,
9438                            )?;
9439                            seeded.insert(table);
9440                        } else {
9441                            let segment = decode_rows_segment(&bytes).map_err(|e| {
9442                                SectionError::Abort(e.code.as_str().to_owned(), e.detail)
9443                            })?;
9444                            let (pair, clear, effective) =
9445                                self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
9446                            report.segment_rows_applied +=
9447                                self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
9448                            seeded.insert(segment.table);
9449                        }
9450                        self.applied_segments
9451                            .entry(unit.id.clone())
9452                            .or_insert_with(|| {
9453                                (unit.cursor, unit.bootstrap_state.clone(), BTreeSet::new())
9454                            })
9455                            .2
9456                            .insert(segment_id);
9457                    }
9458                    _ => {
9459                        return Err(SectionError::Abort(
9460                            "sync.invalid_request".to_owned(),
9461                            "unexpected frame inside a unit section".to_owned(),
9462                        ));
9463                    }
9464                }
9465            }
9466            Ok(())
9467        })();
9468        match applied {
9469            Ok(()) => {}
9470            // The unit keeps catching up with its cursor unpersisted.
9471            Err(SectionError::Refused | SectionError::Deferred) => return Ok(()),
9472            Err(SectionError::FailClosed) => {
9473                // §5.6: the failure is unit-local; the rest of the response
9474                // still applies and the failed unit leaves the list.
9475                self.begin_observation("syncular_section_failure")
9476                    .map_err(storage)?;
9477                let failed = (|| {
9478                    let mut batch = ChangeAccumulator::default();
9479                    for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9480                        batch.window(&base_key, &value);
9481                    }
9482                    batch.status = true;
9483                    self.stored(save_unit(
9484                        &self.conn,
9485                        &UnitRecord {
9486                            status: UnitStatus::Failed,
9487                            reason_code: Some("sync.scope_revoked".to_owned()),
9488                            ..unit.clone()
9489                        },
9490                    ))?;
9491                    self.finish_observation("syncular_section_failure", batch)
9492                })();
9493                if let Err(message) = failed {
9494                    self.rollback_observation("syncular_section_failure");
9495                    return Err(storage(message));
9496                }
9497                report.failed.push(unit.id);
9498                return Ok(());
9499            }
9500            Err(error) => return Err(error),
9501        }
9502        let Some((next_cursor, bootstrap_state)) = sub_end else {
9503            return Ok(());
9504        };
9505        let rollback = self.capture();
9506        let counts = (
9507            report.resets.len(),
9508            report.revoked.len(),
9509            report.failed.len(),
9510        );
9511        self.begin_observation("syncular_sub_end")
9512            .map_err(storage)?;
9513        let finished = self
9514            .finish_section(start, echo, next_cursor, bootstrap_state, seeded, report)
9515            .and_then(|batch| {
9516                self.rebuild_overlay_if_dirty()?;
9517                self.finish_observation("syncular_sub_end", batch)
9518            });
9519        if let Err(message) = finished {
9520            self.rollback_observation("syncular_sub_end");
9521            self.restore(rollback);
9522            report.resets.truncate(counts.0);
9523            report.revoked.truncate(counts.1);
9524            report.failed.truncate(counts.2);
9525            return Err(storage(message));
9526        }
9527        self.applied_segments.remove(&unit.id);
9528        Ok(())
9529    }
9530
9531    /// §5.6: the table, first-page flag and effective scopes of one segment
9532    /// of `unit`'s section.
9533    #[allow(clippy::type_complexity)]
9534    fn segment_pair(
9535        &self,
9536        unit: &UnitRecord,
9537        echo: &[EchoRecord],
9538        seeded: &BTreeSet<String>,
9539        name: &str,
9540    ) -> Result<(TableSchema, bool, Vec<(String, Vec<String>)>), SectionError> {
9541        let table = self.schema.table(name).cloned().ok_or_else(|| {
9542            SectionError::Abort(
9543                "sync.schema_mismatch".to_owned(),
9544                format!("segment table {name:?} is not in the client schema"),
9545            )
9546        })?;
9547        let effective = covers(&table, &unit.scopes)
9548            .then(|| pair_scopes(&unit.scopes, name, Some(echo)))
9549            .flatten()
9550            .ok_or_else(|| {
9551                SectionError::Abort(
9552                    "sync.invalid_request".to_owned(),
9553                    "a segment names no active pair of its unit".to_owned(),
9554                )
9555            })?;
9556        Ok((table, !seeded.contains(name), effective))
9557    }
9558
9559    /// §4.4 `SUB_END` of an active, revoked or reset section, inside the
9560    /// caller's observation: a reset discards cursor, resume token and
9561    /// first-page record and keeps the echo; a revoked pair purges by its last
9562    /// echo (§3.3); otherwise the echo replaces the persisted one, a revoked
9563    /// fenced record that turns active again re-bootstraps the unit, and a
9564    /// bootstrap section persists its pin, resume token and seeded tables.
9565    fn finish_section(
9566        &mut self,
9567        start: &SectionStart,
9568        echo: Vec<EchoRecord>,
9569        next_cursor: i64,
9570        bootstrap_state: Option<String>,
9571        seeded: BTreeSet<String>,
9572        report: &mut SyncReport,
9573    ) -> Result<ChangeAccumulator, String> {
9574        #[cfg(feature = "bench-internals")]
9575        let _phase = self.benchmark_phases.start(Phase::CursorPersist);
9576        let mut batch = ChangeAccumulator::default();
9577        // §4.4: SUB_END writes only into a unit that is still registered.
9578        let Some(unit) = self
9579            .stored(get_unit(&self.conn, &start.id))?
9580            .filter(|unit| unit.status == UnitStatus::Active)
9581        else {
9582            return Ok(batch);
9583        };
9584        for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9585            batch.window(&base_key, &value);
9586        }
9587        if start.status == SubStatus::Reset {
9588            // §4.6: staleness, never a purge; the rows stay until the
9589            // bootstrap replaces them.
9590            report.resets.push(unit.id.clone());
9591            self.stored(save_unit(
9592                &self.conn,
9593                &UnitRecord {
9594                    reason_code: Some(start.reason_code.clone()),
9595                    cursor: Some(-1),
9596                    bootstrap_state: None,
9597                    seeded: Vec::new(),
9598                    ..unit
9599                },
9600            ))?;
9601            return Ok(batch);
9602        }
9603        let revoked = start.status == SubStatus::Revoked;
9604        let mut units = None;
9605        let mut failed = false;
9606        let mut rearmed = false;
9607        for table in self.schema.tables.clone() {
9608            if !covers(&table, &unit.scopes) {
9609                continue;
9610            }
9611            let last = unit
9612                .echo
9613                .as_deref()
9614                .and_then(|last| pair_scopes(&unit.scopes, &table.name, Some(last)));
9615            let next = (!revoked)
9616                .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
9617                .flatten();
9618            // §3.3: a revoked fenced record that turns active again re-bootstraps.
9619            rearmed |= unit.echo.is_some() && last.is_none() && next.is_some();
9620            // §3.3: purge a pair the response revokes, keyed on the echo the
9621            // client persisted while the pair was active.
9622            if let (Some(last), None) = (&last, &next) {
9623                let units = match units {
9624                    Some(ref units) => units,
9625                    None => units.insert(self.stored(load_units(&self.conn))?),
9626                };
9627                let owners = unit_owners(units, &table, &unit.id);
9628                failed |= !self.purge_pair(&mut batch, &table, last, &owners)?;
9629            }
9630        }
9631        if revoked || failed {
9632            if revoked {
9633                report.revoked.push(unit.id.clone());
9634            }
9635            if failed {
9636                report.failed.push(unit.id.clone());
9637            }
9638            batch.status = true;
9639            self.stored(save_unit(
9640                &self.conn,
9641                &UnitRecord {
9642                    status: if failed {
9643                        UnitStatus::Failed
9644                    } else {
9645                        UnitStatus::Revoked
9646                    },
9647                    reason_code: Some(if failed {
9648                        "sync.scope_revoked".to_owned()
9649                    } else {
9650                        start.reason_code.clone()
9651                    }),
9652                    cursor: Some(-1),
9653                    bootstrap_state: None,
9654                    seeded: Vec::new(),
9655                    echo: None,
9656                    ..unit
9657                },
9658            ))?;
9659            return Ok(batch);
9660        }
9661        let completed = start.bootstrap && !rearmed && bootstrap_state.is_none();
9662        let (cursor, bootstrap_state, seeded) = if rearmed {
9663            (Some(-1), None, Vec::new())
9664        } else if start.bootstrap {
9665            let seeded = if bootstrap_state.is_none() {
9666                Vec::new()
9667            } else {
9668                seeded.into_iter().collect()
9669            };
9670            (Some(next_cursor), bootstrap_state, seeded)
9671        } else {
9672            (
9673                unit.cursor,
9674                unit.bootstrap_state.clone(),
9675                unit.seeded.clone(),
9676            )
9677        };
9678        self.stored(save_unit(
9679            &self.conn,
9680            &UnitRecord {
9681                reason_code: None,
9682                echo: Some(echo.clone()),
9683                cursor,
9684                bootstrap_state,
9685                seeded,
9686                ..unit.clone()
9687            },
9688        ))?;
9689        if !completed {
9690            return Ok(batch);
9691        }
9692        // §7.1: a completed bootstrap covers acknowledged intent of its pairs
9693        // at or below its pin.
9694        for table in self.schema.tables.clone() {
9695            let Some(effective) = covers(&table, &unit.scopes)
9696                .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
9697                .flatten()
9698            else {
9699                continue;
9700            };
9701            let mut statement = self
9702                .conn
9703                .prepare("SELECT id,intent_json FROM _syncular_acked_rows WHERE tbl=?1 AND commit_seq<=?2")
9704                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9705            let rows = statement
9706                .query_map(rusqlite::params![table.name, next_cursor], |row| {
9707                    Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
9708                })
9709                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9710            let mut covered = HashSet::new();
9711            for row in rows {
9712                let (id, intent) =
9713                    row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9714                let values: Map<String, Value> =
9715                    serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
9716                if owns_local_row(&table, &effective, &[], &values) {
9717                    covered.insert(id);
9718                }
9719            }
9720            drop(statement);
9721            for id in covered {
9722                self.conn
9723                    .execute(
9724                        "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3",
9725                        rusqlite::params![table.name, id, next_cursor],
9726                    )
9727                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9728                self.overlay_dirty.table(&table.name);
9729                batch.table(&table.name);
9730            }
9731        }
9732        Ok(batch)
9733    }
9734
9735    /// §3.3: purge one revoked pair inside the caller's observation: delete
9736    /// the rows matching its last effective scopes that no owner holds, drop
9737    /// the retained intent and every pending commit that provably writes into
9738    /// them, and delete now-unauthorized blob bodies. `Ok(false)` when the
9739    /// table has no local scope-column mapping (fail closed: nothing deleted).
9740    fn purge_pair(
9741        &mut self,
9742        batch: &mut ChangeAccumulator,
9743        table: &TableSchema,
9744        last: &[(String, Vec<String>)],
9745        owners: &[Vec<(String, Vec<String>)>],
9746    ) -> Result<bool, String> {
9747        if local_scope_predicate(table, last, owners).is_err() {
9748            return Ok(false);
9749        }
9750        for commit in self.drop_failed_commits(|name, values| {
9751            name == table.name && owns_local_row(table, last, owners, values)
9752        })? {
9753            batch.conflicts = true;
9754            batch.rejections = true;
9755            batch.outcomes = true;
9756            for operation in commit.ops {
9757                batch.table(&operation.table);
9758            }
9759        }
9760        if !self.purge_scope_rows(&table.name, last, owners)? {
9761            return Err("storage.failed: the revoked scope purge failed".to_owned());
9762        }
9763        self.record_scope_map(batch, &table.name, last);
9764        if self.drop_doomed_outbox(table, last, owners)? {
9765            batch.status = true;
9766            batch.rejections = true;
9767            batch.outcomes = true;
9768        }
9769        // §5.9.7 B2: revocation deletes now-unauthorized blob bodies.
9770        self.delete_unreferenced_cached_blobs()?;
9771        Ok(true)
9772    }
9773
9774    /// §4.5 client application: apply one live-section or delta `COMMIT`
9775    /// with only the changes that match the persisted echo of a receiving
9776    /// unit; every applied change then goes through the version guard.
9777    /// Returns whether any change of the frame applied.
9778    fn apply_live_commit(
9779        &mut self,
9780        receivers: &[UnitRecord],
9781        tables: &[String],
9782        changes: Vec<ssp2::model::Change>,
9783        commit_seq: i64,
9784        source: AppliedServerCommitSource,
9785    ) -> Result<bool, TransportError> {
9786        let changes: Vec<ssp2::model::Change> = changes
9787            .into_iter()
9788            .filter(|change| {
9789                // An unknown table fails loud in the apply below.
9790                let Some(table) = tables
9791                    .get(change.table_index as usize)
9792                    .and_then(|name| self.schema.table(name))
9793                else {
9794                    return true;
9795                };
9796                receivers.iter().any(|unit| {
9797                    covers(table, &unit.scopes)
9798                        && pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()).is_some_and(
9799                            |scopes| {
9800                                scopes.iter().all(|(variable, values)| {
9801                                    change
9802                                        .scopes
9803                                        .iter()
9804                                        .find(|(key, _)| key == variable)
9805                                        .is_some_and(|(_, value)| values.contains(value))
9806                                })
9807                            },
9808                        )
9809                })
9810            })
9811            .collect();
9812        if changes.is_empty() {
9813            return Ok(false);
9814        }
9815        let affected_tables = changes
9816            .iter()
9817            .filter_map(|change| tables.get(change.table_index as usize))
9818            .cloned()
9819            .collect::<BTreeSet<_>>();
9820        let previous_batches = self.change_queue.len();
9821        self.apply_commit_frame(tables, &changes, commit_seq)?;
9822        if self.change_queue.len() > previous_batches {
9823            if let Some(batch) = self.change_queue.back_mut() {
9824                batch
9825                    .applied_commits
9826                    .extend(
9827                        affected_tables
9828                            .into_iter()
9829                            .map(|table| AppliedServerCommit {
9830                                table,
9831                                commit_seq,
9832                                source,
9833                            }),
9834                    );
9835            }
9836        }
9837        Ok(true)
9838    }
9839
9840    // Both pull and realtime frames use the same durable observation boundary.
9841    fn apply_commit_frame(
9842        &mut self,
9843        tables: &[String],
9844        changes: &[ssp2::model::Change],
9845        sequence: i64,
9846    ) -> Result<(), TransportError> {
9847        #[cfg(feature = "bench-internals")]
9848        let _phase = self.benchmark_phases.start(Phase::CommitApply);
9849        let rollback = self.capture();
9850        self.coalesce_unit(changes.len())
9851            .and_then(|()| self.begin_observation("syncular_commit"))
9852            .map_err(|message| TransportError::new("storage.failed", message))?;
9853        let applied = (|| {
9854            let mut batch = ChangeAccumulator::default();
9855            self.record_commit_changes(&mut batch, tables, changes);
9856            // §7.1 chained base: a change names the version an acknowledged own
9857            // commit wrote; pending upserts chained on it move to that version.
9858            for change in changes {
9859                let Some(table) = tables.get(change.table_index as usize) else {
9860                    continue;
9861                };
9862                let acknowledged = self
9863                    .conn
9864                    .prepare_cached("SELECT op_json FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq=?3")
9865                    .and_then(|mut statement| {
9866                        statement
9867                            .query_map(rusqlite::params![table, change.row_id, sequence], |row| row.get::<_, String>(0))?
9868                            .collect::<Result<Vec<_>, _>>()
9869                    })
9870                    .map_err(|error| TransportError::new("storage.failed", Self::sqlite_failure(&self.storage_failure, error)))?
9871                    .iter()
9872                    .map(|op| serde_json::from_str::<CommitOperation>(op).map(OutboxOp::from))
9873                    .collect::<Result<Vec<_>, _>>()
9874                    .map_err(|_| TransportError::new("storage.failed", "sync.local_corrupt: invalid acknowledged operation".to_owned()))?;
9875                for index in 0..self.outbox.len() {
9876                    if !self.outbox[index]
9877                        .ops
9878                        .iter()
9879                        .any(|op| acknowledged.iter().any(|earlier| chains_on(earlier, op)))
9880                    {
9881                        continue;
9882                    }
9883                    let commit = Arc::make_mut(&mut self.outbox[index]);
9884                    for op in &mut commit.ops {
9885                        if acknowledged.iter().any(|earlier| chains_on(earlier, op)) {
9886                            op.base_version = Some(change.row_version);
9887                        }
9888                    }
9889                    let ops = serde_json::to_string(
9890                        &commit
9891                            .ops
9892                            .iter()
9893                            .map(CommitOperation::from)
9894                            .collect::<Vec<_>>(),
9895                    )
9896                    .map_err(|_| {
9897                        TransportError::new(
9898                            "storage.failed",
9899                            "sync.local_corrupt: unencodable outbox".to_owned(),
9900                        )
9901                    })?;
9902                    let id = commit.client_commit_id.clone();
9903                    self.conn
9904                        .execute(
9905                            "UPDATE _syncular_outbox SET ops_json=?1 WHERE commit_id=?2",
9906                            rusqlite::params![ops, id],
9907                        )
9908                        .map_err(|error| {
9909                            TransportError::new(
9910                                "storage.failed",
9911                                Self::sqlite_failure(&self.storage_failure, error),
9912                            )
9913                        })?;
9914                }
9915            }
9916            {
9917                let storage_failed = |error| {
9918                    TransportError::new(
9919                        "storage.failed",
9920                        Self::sqlite_failure(&self.storage_failure, error),
9921                    )
9922                };
9923                let pinned: HashSet<(&str, &str)> = self
9924                    .outbox
9925                    .iter()
9926                    .flat_map(|commit| &commit.ops)
9927                    .map(|op| (op.table.as_str(), op.row_id.as_str()))
9928                    .collect();
9929                for change in changes {
9930                    let table = tables.get(change.table_index as usize).ok_or_else(|| {
9931                        TransportError::new(
9932                            "sync.invalid_request",
9933                            "change tableIndex out of range".to_owned(),
9934                        )
9935                    })?;
9936                    if pinned.contains(&(table.as_str(), change.row_id.as_str())) {
9937                        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)")
9938                            .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
9939                            .map_err(storage_failed)?;
9940                    }
9941                    self.conn.prepare_cached("DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3")
9942                        .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
9943                        .map_err(storage_failed)?;
9944                }
9945            }
9946            self.apply_commit_changes(tables, changes)?;
9947            self.rebuild_overlay_if_dirty()
9948                .map_err(|message| TransportError::new("storage.failed", message))?;
9949            self.finish_observation("syncular_commit", batch)
9950                .map_err(|message| TransportError::new("storage.failed", message))
9951        })();
9952        if applied.is_err() {
9953            self.rollback_observation("syncular_commit");
9954            self.restore(rollback);
9955        }
9956        applied
9957    }
9958
9959    fn apply_commit_changes(
9960        &mut self,
9961        tables: &[String],
9962        changes: &[ssp2::model::Change],
9963    ) -> Result<(), TransportError> {
9964        // A clean overlay can reconcile changed primary keys independently
9965        // when their tables have no secondary unique constraints. Such a
9966        // constraint can change whether another row's write succeeds, so a
9967        // table with one and any local intent takes the table rebuild.
9968        let changed_tables: BTreeSet<&str> = changes
9969            .iter()
9970            .filter_map(|change| tables.get(change.table_index as usize))
9971            .map(String::as_str)
9972            .collect();
9973        let mut mirror_visible = !self.overlay_dirty.get();
9974        for name in &changed_tables {
9975            if mirror_visible
9976                && self
9977                    .schema
9978                    .table(name)
9979                    .is_some_and(|table| table.indexes.iter().any(|index| index.unique))
9980            {
9981                let (pending, protected) = self
9982                    .table_intent(name)
9983                    .map_err(|message| TransportError::new("storage.failed", message))?;
9984                mirror_visible = !pending && !protected;
9985            }
9986        }
9987        for change in changes {
9988            let table_name = tables.get(change.table_index as usize).ok_or_else(|| {
9989                TransportError::new(
9990                    "sync.invalid_request",
9991                    "change tableIndex out of range".to_owned(),
9992                )
9993            })?;
9994            let table = self.schema.table(table_name).ok_or_else(|| {
9995                TransportError::new(
9996                    "sync.schema_mismatch",
9997                    format!("change targets unknown table {table_name:?}"),
9998                )
9999            })?;
10000            let landed = match change.op {
10001                Op::Upsert => {
10002                    let payload = change.row.as_ref().ok_or_else(|| {
10003                        TransportError::new(
10004                            "sync.invalid_request",
10005                            "upsert change without row payload".to_owned(),
10006                        )
10007                    })?;
10008                    // §5.11: decrypt encrypted columns on apply, or seal the row.
10009                    let (row, sealed) = {
10010                        #[cfg(feature = "bench-internals")]
10011                        let _phase = self.benchmark_phases.start(Phase::RowDecode);
10012                        // §5.11: a decrypt failure keeps its own identity.
10013                        decode_row_bytes(table, payload, &self.encryption)?
10014                    };
10015                    let table_name = table.name.clone();
10016                    // §4.5 version guard: only a newer upsert lands.
10017                    let landed = self
10018                        .write_base_row(&table_name, &row, change.row_version, sealed.as_ref())
10019                        .map_err(|m| TransportError::new("sync.invalid_request", m))?;
10020                    if mirror_visible && landed {
10021                        self.write_row(
10022                            &visible_table(&table_name),
10023                            &table_name,
10024                            &row,
10025                            change.row_version,
10026                            sealed.as_ref(),
10027                        )
10028                        .map_err(|m| TransportError::new("sync.invalid_request", m))?;
10029                    }
10030                    landed
10031                }
10032                // §4.5 version guard: a delete at or below the local version
10033                // is skipped, a delete of an absent row is a no-op.
10034                Op::Delete => self
10035                    .delete_base_row(table_name, &change.row_id, change.row_version)
10036                    .map_err(|m| TransportError::new("sync.invalid_request", m))?,
10037            };
10038            // The change dropped the row's acknowledged intent either way
10039            // (§7.1), so the overlay of a skipped change rebuilds from the
10040            // unchanged base.
10041            self.overlay_dirty.table(table_name);
10042            if mirror_visible && !(landed && change.op == Op::Upsert) {
10043                let predicate = row_id_predicate(table);
10044                let visible = visible_table(table_name);
10045                let mut statements = vec![format!("DELETE FROM {visible} WHERE {predicate}")];
10046                if !landed {
10047                    statements.push(format!(
10048                        "INSERT INTO {visible} SELECT * FROM {} WHERE {predicate}",
10049                        base_table(table_name)
10050                    ));
10051                }
10052                for statement in &statements {
10053                    self.conn
10054                        .prepare_cached(statement)
10055                        .and_then(|mut statement| {
10056                            statement.execute(rusqlite::params![change.row_id])
10057                        })
10058                        .map_err(|error| {
10059                            TransportError::new("sync.invalid_request", error.to_string())
10060                        })?;
10061                }
10062            }
10063        }
10064        if mirror_visible {
10065            let changed_rows: HashSet<(&str, &str)> = changes
10066                .iter()
10067                .map(|change| {
10068                    (
10069                        tables[change.table_index as usize].as_str(),
10070                        change.row_id.as_str(),
10071                    )
10072                })
10073                .collect();
10074            self.replay_overlay(&changed_tables, Some(&changed_rows))
10075                .map_err(|message| TransportError::new("storage.failed", message))?;
10076            self.overlay_dirty.set(false);
10077        }
10078        Ok(())
10079    }
10080
10081    /// §5.6 segment application: validate against the generated schema,
10082    /// clear the pair's scope on the table's first page (fail closed
10083    /// without a mapping), then upsert each row with its segment-carried
10084    /// server version under the §4.5 version guard (§5.2).
10085    fn apply_segment(
10086        &mut self,
10087        table: &TableSchema,
10088        segment: &RowsSegment,
10089        first_page: bool,
10090        effective: &[(String, Vec<String>)],
10091        unit_id: &str,
10092    ) -> Result<u32, SectionError> {
10093        // §5.2: the column table validates against the generated schema —
10094        // order, names, types, nullability; mismatch is fatal. §5.11: the
10095        // server sends the WIRE types (bytes for an encrypted column), so
10096        // validate against wire_columns.
10097        let column = if segment.columns.len() != table.wire_columns.len() {
10098            Some(Value::from("count"))
10099        } else {
10100            segment
10101                .columns
10102                .iter()
10103                .zip(table.wire_columns.iter())
10104                .position(|(a, b)| a.name != b.name || a.ty != b.ty || a.nullable != b.nullable)
10105                .map(Value::from)
10106        };
10107        if segment.table != table.name
10108            || segment.schema_version != self.schema.version
10109            || column.is_some()
10110        {
10111            let mut details = Map::new();
10112            details.insert("table".to_owned(), Value::from(table.name.as_str()));
10113            if let Some(column) = column {
10114                details.insert("column".to_owned(), column);
10115            }
10116            return Err(SectionError::Transport(TransportError {
10117                code: "sync.schema_mismatch".to_owned(),
10118                message: "rows segment columns do not match the generated schema (§5.2)".to_owned(),
10119                details: Some(Value::Object(details)),
10120            }));
10121        }
10122        let mut applied = 0u32;
10123        let empty = Vec::new();
10124        let blocks = if segment.blocks.is_empty() {
10125            std::slice::from_ref(&empty)
10126        } else {
10127            &segment.blocks
10128        };
10129        for (index, block) in blocks.iter().enumerate() {
10130            let clear = first_page && index == 0;
10131            if !clear && block.is_empty() {
10132                continue;
10133            }
10134            let rollback = self.capture();
10135            let (pending, protected) = self
10136                .table_intent(&table.name)
10137                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10138            let reconcile_pending =
10139                !protected && pending && table.indexes.iter().any(|index| index.unique);
10140            let mirror_visible = !protected && !reconcile_pending;
10141            self.coalesce_unit(block.len())
10142                .and_then(|()| self.begin_observation("syncular_segment_block"))
10143                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10144            let outcome = (|| {
10145                self.rebuild_overlay_if_dirty()
10146                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10147                let mut changed_keys = Vec::new();
10148                let mut batch = ChangeAccumulator::default();
10149                if clear && self.clear_scope(table, effective, unit_id)? || !block.is_empty() {
10150                    batch.table(&table.name);
10151                }
10152                for (row_index, row) in block.iter().enumerate() {
10153                    let decrypted;
10154                    let mut sealed = None;
10155                    let values = if table.has_encrypted_columns() {
10156                        let mut values = row.values.clone();
10157                        sealed = crate::values::decrypt_segment_row(
10158                            table,
10159                            &mut values,
10160                            &self.encryption,
10161                        )
10162                        .map_err(SectionError::Transport)?;
10163                        decrypted = values;
10164                        &decrypted
10165                    } else {
10166                        &row.values
10167                    };
10168                    if !self
10169                        .write_base_row(&table.name, values, row.server_version, sealed.as_ref())
10170                        .map_err(|message| {
10171                            SectionError::Abort("sync.invalid_request".into(), message)
10172                        })?
10173                    {
10174                        continue;
10175                    }
10176                    if reconcile_pending {
10177                        changed_keys.push(
10178                            owned_sql_value(RowParam::Cell(&values[table.pk_index])).map_err(
10179                                |message| SectionError::Abort("storage.failed".into(), message),
10180                            )?,
10181                        );
10182                    }
10183                    if mirror_visible {
10184                        self.write_row(
10185                            &visible_table(&table.name),
10186                            &table.name,
10187                            values,
10188                            row.server_version,
10189                            sealed.as_ref(),
10190                        )
10191                        .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10192                    }
10193                    let processed = u64::from(applied) + row_index as u64 + 1;
10194                    if processed.is_multiple_of(1024) {
10195                        self.progress.update(|p| p.rows_processed = processed);
10196                    }
10197                }
10198                self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
10199                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10200                self.finish_observation("syncular_segment_block", batch)
10201                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))
10202            })();
10203            if let Err(error) = outcome {
10204                self.rollback_observation("syncular_segment_block");
10205                self.restore(rollback);
10206                return Err(error);
10207            }
10208            applied += block.len() as u32;
10209            self.progress
10210                .update(|p| p.rows_processed = u64::from(applied));
10211            std::thread::yield_now();
10212        }
10213        self.progress
10214            .update(|p| p.rows_processed = u64::from(applied));
10215        Ok(applied)
10216    }
10217
10218    /// §5.3 sqlite-image application: validate the in-file metadata
10219    /// against the descriptor, validate column names/order against the
10220    /// generated schema, run the §5.6 first-page clear when fresh, then
10221    /// replace-or-upsert every image row with its `_syncular_version`.
10222    /// Mechanics: the image lands in a temp file read through a second
10223    /// rusqlite connection, equivalent to ATTACH + INSERT…SELECT.
10224    /// Each image chunk commits its writes and revision before readers continue.
10225    #[allow(clippy::too_many_arguments)]
10226    fn apply_sqlite_segment(
10227        &mut self,
10228        table: &TableSchema,
10229        bytes: &[u8],
10230        first_page: bool,
10231        effective: &[(String, Vec<String>)],
10232        unit_id: &str,
10233        row_count: i64,
10234        as_of_commit_seq: i64,
10235        scope_digest: &str,
10236    ) -> Result<u32, SectionError> {
10237        let invalid = |detail: &str| {
10238            SectionError::Abort(
10239                "sync.invalid_request".to_owned(),
10240                format!("sqlite segment rejected: {detail} (§5.3)"),
10241            )
10242        };
10243        // §5.11: an image bypasses the decrypt seam, so a server cannot serve
10244        // one for a table with encrypted columns.
10245        if table.has_encrypted_columns() {
10246            return Err(invalid("table has encrypted columns"));
10247        }
10248
10249        // The image lands beside the replica so it shares the replica's
10250        // directory permissions and volume; an in-memory replica has no
10251        // directory and uses the system temp dir. The file is owner-only.
10252        let directory = self
10253            .previous_version_replica_path()
10254            .and_then(|replica| std::path::Path::new(&replica).parent().map(Into::into))
10255            .unwrap_or_else(std::env::temp_dir);
10256        let path = directory.join(format!(".syncular-image-{}.tmp", uuid::Uuid::new_v4()));
10257        let outcome = (|| {
10258            let mut options = std::fs::OpenOptions::new();
10259            options.write(true).create_new(true);
10260            #[cfg(unix)]
10261            std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);
10262            std::io::Write::write_all(
10263                &mut options
10264                    .open(&path)
10265                    .map_err(|_| invalid("image temp file write failed"))?,
10266                bytes,
10267            )
10268            .map_err(|_| invalid("image temp file write failed"))?;
10269            let img = rusqlite::Connection::open_with_flags(
10270                &path,
10271                rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
10272            )
10273            .map_err(|_| invalid("bytes do not open as a SQLite database"))?;
10274            self.apply_sqlite_image(
10275                &img,
10276                table,
10277                first_page,
10278                effective,
10279                unit_id,
10280                row_count,
10281                as_of_commit_seq,
10282                scope_digest,
10283            )
10284        })();
10285        let _ = std::fs::remove_file(&path);
10286        outcome
10287    }
10288
10289    #[allow(clippy::too_many_arguments)]
10290    fn apply_sqlite_image(
10291        &mut self,
10292        img: &rusqlite::Connection,
10293        table: &crate::schema::TableSchema,
10294        first_fresh_page: bool,
10295        effective: &[(String, Vec<String>)],
10296        unit_id: &str,
10297        row_count: i64,
10298        as_of_commit_seq: i64,
10299        scope_digest: &str,
10300    ) -> Result<u32, SectionError> {
10301        let invalid = |detail: String| {
10302            SectionError::Abort(
10303                "sync.invalid_request".to_owned(),
10304                format!("sqlite segment rejected: {detail} (§5.3)"),
10305            )
10306        };
10307
10308        // 1. Metadata vs descriptor + client state (§5.3 rule 2; exactly
10309        //    one row).
10310        type MetaRow = (i64, String, i64, i64, String, i64, i64);
10311        let meta: MetaRow = img
10312            .query_row(
10313                "SELECT format, \"table\", \"schemaVersion\", \"asOfCommitSeq\",
10314                        \"scopeDigest\", \"rowCount\",
10315                        (SELECT count(*) FROM _syncular_segment)
10316                 FROM _syncular_segment",
10317                [],
10318                |row| {
10319                    Ok((
10320                        row.get(0)?,
10321                        row.get(1)?,
10322                        row.get(2)?,
10323                        row.get(3)?,
10324                        row.get(4)?,
10325                        row.get(5)?,
10326                        row.get(6)?,
10327                    ))
10328                },
10329            )
10330            .map_err(|_| invalid("missing or unreadable _syncular_segment metadata".to_owned()))?;
10331        let (format, meta_table, schema_version, pin, digest, meta_rows, meta_count) = meta;
10332        if meta_count != 1 {
10333            return Err(invalid(format!(
10334                "_syncular_segment must contain exactly one row, found {meta_count}"
10335            )));
10336        }
10337        if format != 1 {
10338            return Err(invalid(format!("format {format}")));
10339        }
10340        if meta_table != table.name {
10341            return Err(invalid(format!("image table {meta_table:?}")));
10342        }
10343        if schema_version != i64::from(self.schema.version) {
10344            return Err(invalid(format!("schemaVersion {schema_version}")));
10345        }
10346        if pin != as_of_commit_seq {
10347            return Err(invalid(format!("asOfCommitSeq {pin}")));
10348        }
10349        if digest != scope_digest {
10350            return Err(invalid("scopeDigest mismatch".to_owned()));
10351        }
10352        if meta_rows != row_count {
10353            return Err(invalid(format!("rowCount {meta_rows}")));
10354        }
10355
10356        // 2. Column names and order vs the generated schema (§5.3 rule 3).
10357        let mut names: Vec<String> = Vec::new();
10358        let mut primary_keys: Vec<String> = Vec::new();
10359        {
10360            let mut stmt = img
10361                .prepare(&format!("PRAGMA table_info({})", quote_ident(&table.name)))
10362                .map_err(|_| invalid("image data table missing".to_owned()))?;
10363            let mut rows = stmt
10364                .query([])
10365                .map_err(|_| invalid("image data table unreadable".to_owned()))?;
10366            while let Some(row) = rows
10367                .next()
10368                .map_err(|_| invalid("image data table unreadable".to_owned()))?
10369            {
10370                if row
10371                    .get::<_, i64>(5)
10372                    .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?
10373                    > 0
10374                {
10375                    primary_keys.push(row.get(1).map_err(|error| {
10376                        invalid(Self::sqlite_failure(&self.storage_failure, error))
10377                    })?);
10378                }
10379                names.push(
10380                    row.get::<_, String>(1)
10381                        .map_err(|_| invalid("image data table unreadable".to_owned()))?,
10382                );
10383            }
10384        }
10385        let mut expected: Vec<&str> = table.columns.iter().map(|c| c.name.as_str()).collect();
10386        expected.push("_syncular_version");
10387        if names.len() != expected.len() || names.iter().zip(expected.iter()).any(|(a, b)| a != b) {
10388            return Err(SectionError::Transport(TransportError {
10389                code: "sync.schema_mismatch".to_owned(),
10390                message: "sqlite segment columns do not match the generated schema (§5.3)"
10391                    .to_owned(),
10392                details: Some(serde_json::json!({ "table": table.name })),
10393            }));
10394        }
10395
10396        if primary_keys != vec![table.primary_key.clone()] {
10397            return Err(invalid(
10398                "image primary key does not match generated schema".into(),
10399            ));
10400        }
10401        let actual_count: i64 = img
10402            .query_row(
10403                &format!("SELECT count(*) FROM {}", quote_ident(&table.name)),
10404                [],
10405                |row| row.get(0),
10406            )
10407            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10408        if actual_count != row_count {
10409            return Err(invalid("image row count does not match descriptor".into()));
10410        }
10411        let insert = self.insert_row_sql(&base_table(&table.name), table);
10412        let visible_insert = self.insert_row_sql(&visible_table(&table.name), table);
10413        let column_list = names
10414            .iter()
10415            .map(|n| quote_ident(n))
10416            .collect::<Vec<_>>()
10417            .join(", ");
10418        let mut stmt = img
10419            .prepare(&format!(
10420                "SELECT {column_list} FROM {} ORDER BY {}",
10421                quote_ident(&table.name),
10422                quote_ident(&table.primary_key)
10423            ))
10424            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10425        let mut rows = stmt
10426            .query([])
10427            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10428        let mut applied = 0u32;
10429        let mut limit = if first_fresh_page {
10430            1024
10431        } else {
10432            self.image_chunk_rows
10433                .get(&table.name)
10434                .copied()
10435                .unwrap_or(1024)
10436        };
10437        let (mut write, mut commit) = (std::time::Duration::ZERO, std::time::Duration::ZERO);
10438        loop {
10439            let clear = applied == 0 && first_fresh_page;
10440            let rollback = self.capture();
10441            let (pending, protected) = self
10442                .table_intent(&table.name)
10443                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10444            let reconcile_pending =
10445                !protected && pending && table.indexes.iter().any(|index| index.unique);
10446            let mirror_visible = !protected && !reconcile_pending;
10447            // §5.3: a table's first chunk holds 1,024 rows; a later range image
10448            // starts at the size its previous range reached. A later chunk holds at
10449            // least 1,024 rows, at most twice the rows of the one before, at
10450            // most 65,536, and at most the rows the one before applied per
10451            // 250 ms from its start to its COMMIT; a chunk that replays local
10452            // writes holds at most 1,024.
10453            let chunk = if pending || protected {
10454                limit.min(1024)
10455            } else {
10456                limit
10457            };
10458            self.coalesce_unit(chunk as usize)
10459                .and_then(|()| self.begin_observation("syncular_image_chunk"))
10460                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10461            let started = std::time::Instant::now();
10462            let result = (|| {
10463                self.rebuild_overlay_if_dirty()
10464                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10465                let mut changed_keys = Vec::new();
10466                let mut batch = ChangeAccumulator::default();
10467                if clear && self.clear_scope(table, effective, unit_id)? {
10468                    batch.table(&table.name);
10469                }
10470                let mut processed = 0u32;
10471                {
10472                    let mut ins = self.conn.prepare_cached(&insert).map_err(|error| {
10473                        invalid(Self::sqlite_failure(&self.storage_failure, error))
10474                    })?;
10475                    let mut mirror = if mirror_visible {
10476                        Some(self.conn.prepare_cached(&visible_insert).map_err(|error| {
10477                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10478                        })?)
10479                    } else {
10480                        None
10481                    };
10482                    for _ in 0..chunk {
10483                        let Some(row) = rows.next().map_err(|error| {
10484                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10485                        })?
10486                        else {
10487                            break;
10488                        };
10489                        for (i, column) in table.columns.iter().enumerate() {
10490                            let cell = row.get_ref(i).map_err(|error| {
10491                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10492                            })?;
10493                            let param = image_cell_param(column, cell).map_err(invalid)?;
10494                            ins.raw_bind_parameter(i + 1, &param).map_err(|error| {
10495                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10496                            })?;
10497                            if let Some(mirror) = &mut mirror {
10498                                mirror.raw_bind_parameter(i + 1, &param).map_err(|error| {
10499                                    invalid(Self::sqlite_failure(&self.storage_failure, error))
10500                                })?;
10501                            }
10502                        }
10503                        let version_index = table.columns.len();
10504                        let version: i64 = row.get(version_index).map_err(|error| {
10505                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10506                        })?;
10507                        if version < 1 {
10508                            return Err(invalid("image row version must be positive".into()));
10509                        }
10510                        ins.raw_bind_parameter(version_index + 1, version)
10511                            .map_err(|error| {
10512                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10513                            })?;
10514                        // §4.5 version guard: the base upsert decides.
10515                        let landed = ins.raw_execute().map_err(|error| {
10516                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10517                        })? > 0;
10518                        processed += 1;
10519                        if processed.is_multiple_of(1024) && processed < chunk {
10520                            self.progress
10521                                .update(|p| p.rows_processed = u64::from(applied + processed));
10522                        }
10523                        if !landed {
10524                            continue;
10525                        }
10526                        if let Some(mirror) = &mut mirror {
10527                            mirror
10528                                .raw_bind_parameter(version_index + 1, version)
10529                                .map_err(|error| {
10530                                    invalid(Self::sqlite_failure(&self.storage_failure, error))
10531                                })?;
10532                            mirror.raw_execute().map_err(|error| {
10533                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10534                            })?;
10535                        }
10536                        if reconcile_pending {
10537                            changed_keys.push(row.get::<_, SqlValue>(table.pk_index).map_err(
10538                                |error| invalid(Self::sqlite_failure(&self.storage_failure, error)),
10539                            )?);
10540                        }
10541                    }
10542                }
10543                if processed > 0 {
10544                    batch.table(&table.name);
10545                    self.overlay_dirty.table(&table.name);
10546                }
10547                self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
10548                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10549                let written = std::time::Instant::now();
10550                self.finish_observation("syncular_image_chunk", batch)
10551                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10552                Ok((processed, written))
10553            })();
10554            let (processed, written) = match result {
10555                Ok(done) => done,
10556                Err(error) => {
10557                    self.rollback_observation("syncular_image_chunk");
10558                    self.restore(rollback);
10559                    return Err(error);
10560                }
10561            };
10562            // The chunk commits before the yield, also inside a coalesced apply.
10563            let coalesced = self.coalesced.is_some();
10564            if coalesced {
10565                self.commit_coalesced_apply()
10566                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10567            }
10568            write += written - started;
10569            commit += written.elapsed();
10570            applied += processed;
10571            let last = processed < chunk || i64::from(applied) == actual_count;
10572            // A file replica's WAL keeps its high-water size until truncated.
10573            if last && self.conn.is_autocommit() {
10574                self.conn
10575                    .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
10576                    .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10577            }
10578            if coalesced {
10579                self.begin_coalesced_apply()
10580                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10581            }
10582            self.progress.update(|p| {
10583                p.rows_processed = u64::from(applied);
10584                p.import_write_ms = u64::try_from(write.as_millis()).ok();
10585                p.import_commit_ms = u64::try_from(commit.as_millis()).ok();
10586            });
10587            let duration = started.elapsed().as_secs_f64() * 1000.0;
10588            #[cfg(test)]
10589            let duration = self.image_chunk_ms.get().unwrap_or(duration);
10590            std::thread::yield_now();
10591            if last {
10592                break;
10593            }
10594            // A zero duration saturates the cast and leaves the doubling.
10595            limit = (processed * 2)
10596                .min(65_536)
10597                .min((f64::from(processed) * 250.0 / duration) as u32)
10598                .max(1024);
10599            self.image_chunk_rows.insert(table.name.clone(), limit);
10600        }
10601        if i64::from(applied) != actual_count {
10602            return Err(invalid(format!(
10603                "image yielded {applied} rows, expected {actual_count}"
10604            )));
10605        }
10606        Ok(applied)
10607    }
10608
10609    /// §7.1 keyed reconciliation of the rows `drained` commits touch: restore
10610    /// them from the base and replay their remaining intent. A table with a
10611    /// secondary unique index restores and replays every row with intent,
10612    /// since one row's value can admit or defer another row's write.
10613    fn reconcile_rows(&self, drained: &[Arc<OutboxCommit>]) -> Result<(), String> {
10614        let names: BTreeSet<&str> = drained
10615            .iter()
10616            .flat_map(|commit| &commit.ops)
10617            .map(|op| op.table.as_str())
10618            .collect();
10619        for name in names {
10620            let Some(table) = self.schema.table(name) else {
10621                continue;
10622            };
10623            let ops = drained.iter().flat_map(|commit| &commit.ops);
10624            let tables = BTreeSet::from([name]);
10625            let rows: HashSet<_> = ops
10626                .clone()
10627                .map(|op| (op.table.as_str(), op.row_id.as_str()))
10628                .collect();
10629            let unique = table.indexes.iter().any(|index| index.unique);
10630            let acknowledged = if unique {
10631                self.acknowledged_operations(None, Some(&tables))?
10632            } else {
10633                Vec::new()
10634            };
10635            let peers = acknowledged
10636                .iter()
10637                .chain(
10638                    self.failed_commits
10639                        .iter()
10640                        .flat_map(|(commit, _)| &commit.ops),
10641                )
10642                .chain(self.outbox.iter().flat_map(|commit| &commit.ops))
10643                .filter(|_| unique);
10644            self.restore_base_rows(table, &mut Vec::new(), peers.chain(ops.clone()))?;
10645            self.replay_overlay(&tables, (!unique).then_some(&rows))?;
10646        }
10647        Ok(())
10648    }
10649
10650    /// Whether `table` has pending outbox intent, and whether it has protected
10651    /// (acknowledged or retained failed) intent.
10652    fn table_intent(&self, table: &str) -> Result<(bool, bool), String> {
10653        let touches = |op: &OutboxOp| op.table == table;
10654        Ok((
10655            self.outbox
10656                .iter()
10657                .flat_map(|commit| &commit.ops)
10658                .any(touches),
10659            self.failed_commits
10660                .iter()
10661                .flat_map(|(commit, _)| &commit.ops)
10662                .any(touches)
10663                || self
10664                    .conn
10665                    .query_row(
10666                        "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows WHERE tbl=?1)",
10667                        [table],
10668                        |row| row.get(0),
10669                    )
10670                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10671        ))
10672    }
10673
10674    /// §7.1 reconciliation after an import block or chunk. Keyed replay covers
10675    /// only pending intent, so a table with protected intent rebuilds; a
10676    /// `restore` restores the imported `keys` and every pending row first.
10677    fn reconcile_import(
10678        &mut self,
10679        table: &TableSchema,
10680        keys: &mut Vec<SqlValue>,
10681        protected: bool,
10682        restore: bool,
10683    ) -> Result<(), String> {
10684        if protected {
10685            return self.rebuild_overlay_if_dirty();
10686        }
10687        let pending = self.outbox.iter().flat_map(|commit| &commit.ops);
10688        if restore {
10689            self.restore_base_rows(table, keys, pending.clone())?;
10690        }
10691        self.apply_outbox_ops(pending.filter(|op| op.table == table.name))?;
10692        self.overlay_dirty.set(false);
10693        Ok(())
10694    }
10695
10696    /// Restore the visible rows of `keys` and of the rows `ops` touch in
10697    /// `table` from the base before the caller replays their intent. The
10698    /// caller owns the transaction and publishes its revision after replay.
10699    fn restore_base_rows<'a>(
10700        &self,
10701        table: &TableSchema,
10702        keys: &mut Vec<SqlValue>,
10703        ops: impl IntoIterator<Item = &'a OutboxOp>,
10704    ) -> Result<(), String> {
10705        let visible = visible_table(&table.name);
10706        let base = base_table(&table.name);
10707        let pk = quote_ident(&table.primary_key);
10708        let predicate = row_id_predicate(table);
10709        let mut lookup = self.conn.prepare_cached(&format!(
10710            "SELECT {pk} FROM {base} WHERE {predicate} UNION SELECT {pk} FROM {visible} WHERE {predicate}"
10711        )).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10712        let mut deleted = HashSet::new();
10713        for op in ops.into_iter().filter(|op| op.table == table.name) {
10714            if op.upsert {
10715                if let Some(values) = &op.values {
10716                    let key = json_to_column_value(
10717                        &table.columns[table.pk_index],
10718                        values.get(&table.primary_key),
10719                    )?;
10720                    keys.push(owned_sql_value(RowParam::Cell(&key))?);
10721                }
10722            } else if deleted.insert(&op.row_id) {
10723                keys.extend(
10724                    lookup
10725                        .query_map([&op.row_id], |row| row.get::<_, SqlValue>(0))
10726                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
10727                        .collect::<Result<Vec<_>, _>>()
10728                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10729                );
10730            }
10731        }
10732        // Delete the complete affected set before restoring any base value, so
10733        // old optimistic unique values cannot collide with the new server rows.
10734        for chunk in keys.chunks(400) {
10735            let holes = vec!["?"; chunk.len()].join(",");
10736            self.conn
10737                .prepare_cached(&format!("DELETE FROM {visible} WHERE {pk} IN ({holes})"))
10738                .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
10739                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10740        }
10741        let updates = table
10742            .columns
10743            .iter()
10744            .map(|column| column.name.as_str())
10745            .chain(std::iter::once("_syncular_version"))
10746            .chain(table.sealed_columns().iter().copied())
10747            .filter(|name| *name != table.primary_key)
10748            .map(|name| {
10749                let name = quote_ident(name);
10750                format!("{name}=excluded.{name}")
10751            })
10752            .collect::<Vec<_>>()
10753            .join(",");
10754        for chunk in keys.chunks(400) {
10755            let holes = vec!["?"; chunk.len()].join(",");
10756            self.conn.prepare_cached(&format!("INSERT INTO {visible} SELECT * FROM {base} WHERE {pk} IN ({holes}) ON CONFLICT ({pk}) DO UPDATE SET {updates}"))
10757                .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
10758                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10759        }
10760        Ok(())
10761    }
10762
10763    // -- application-authorized local purge ---------------------------------------
10764
10765    fn compile_local_data_purge(
10766        &self,
10767        input: &LocalDataPurgeInput,
10768    ) -> Result<(Vec<CompiledLocalDataPurgeTarget>, String), String> {
10769        let invalid = |message: String| format!("sync.invalid_request: {message}");
10770        if input.purge_id.is_empty()
10771            || input.purge_id.len() > 128
10772            || !is_local_operation_code_like(&input.purge_id)
10773        {
10774            return Err(invalid(
10775                "local purge purgeId must be a 1–128 character code-like identifier".to_owned(),
10776            ));
10777        }
10778        if input.targets.is_empty() || input.targets.len() > MAX_LOCAL_PURGE_TARGETS {
10779            return Err(invalid(format!(
10780                "local purge needs between 1 and {MAX_LOCAL_PURGE_TARGETS} targets"
10781            )));
10782        }
10783
10784        let mut deduplicated: BTreeMap<
10785            String,
10786            (CompiledLocalDataPurgeTarget, LocalDataPurgeTarget),
10787        > = BTreeMap::new();
10788        for target in &input.targets {
10789            let table = self.schema.table(&target.table).ok_or_else(|| {
10790                invalid(format!(
10791                    "local purge names unknown table {:?}",
10792                    target.table
10793                ))
10794            })?;
10795            if target.selectors.is_empty() || target.selectors.len() > MAX_LOCAL_PURGE_SELECTORS {
10796                return Err(invalid(format!(
10797                    "local purge target {:?} needs between 1 and {MAX_LOCAL_PURGE_SELECTORS} selectors",
10798                    target.table
10799                )));
10800            }
10801            let mut selectors = Vec::with_capacity(target.selectors.len());
10802            let mut canonical_selectors = BTreeMap::new();
10803            for (column_name, raw_values) in &target.selectors {
10804                let Some((column_index, column)) = table
10805                    .columns
10806                    .iter()
10807                    .enumerate()
10808                    .find(|(_, column)| column.name == *column_name)
10809                else {
10810                    return Err(invalid(format!(
10811                        "local purge target {:?} names unknown column {:?}",
10812                        target.table, column_name
10813                    )));
10814                };
10815                let encrypted = table
10816                    .encrypted_columns
10817                    .iter()
10818                    .any(|candidate| candidate.index == column_index);
10819                if column.ty != ColumnType::String || encrypted {
10820                    return Err(invalid(format!(
10821                        "local purge selector {:?}.{:?} must be a plaintext string column",
10822                        target.table, column_name
10823                    )));
10824                }
10825                if raw_values.is_empty() || raw_values.len() > MAX_LOCAL_PURGE_VALUES {
10826                    return Err(invalid(format!(
10827                        "local purge selector {:?}.{:?} needs between 1 and {MAX_LOCAL_PURGE_VALUES} values",
10828                        target.table, column_name
10829                    )));
10830                }
10831                let mut values = raw_values.clone();
10832                values.sort();
10833                values.dedup();
10834                if values.iter().any(|value| {
10835                    value.is_empty()
10836                        || value.len() > MAX_LOCAL_PURGE_VALUE_LENGTH
10837                        || !is_local_operation_code_like(value)
10838                }) {
10839                    return Err(invalid(format!(
10840                        "local purge selector values must be 1–{MAX_LOCAL_PURGE_VALUE_LENGTH} character code-like identifiers"
10841                    )));
10842                }
10843                selectors.push((column_name.clone(), values.clone()));
10844                canonical_selectors.insert(column_name.clone(), values);
10845            }
10846            let canonical = LocalDataPurgeTarget {
10847                table: target.table.clone(),
10848                selectors: canonical_selectors,
10849            };
10850            let key = serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
10851            deduplicated.insert(
10852                key,
10853                (
10854                    CompiledLocalDataPurgeTarget {
10855                        table: target.table.clone(),
10856                        selectors,
10857                    },
10858                    canonical,
10859                ),
10860            );
10861        }
10862        let targets = deduplicated
10863            .values()
10864            .map(|(compiled, _)| compiled.clone())
10865            .collect::<Vec<_>>();
10866        let canonical = deduplicated
10867            .values()
10868            .map(|(_, target)| target.clone())
10869            .collect::<Vec<_>>();
10870        let canonical_plan =
10871            serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
10872        Ok((targets, canonical_plan))
10873    }
10874
10875    fn local_purge_base_row_ids(
10876        &self,
10877        targets: &[CompiledLocalDataPurgeTarget],
10878    ) -> Result<BTreeMap<String, BTreeSet<String>>, String> {
10879        let mut by_table: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
10880        for target in targets {
10881            let table = self
10882                .schema
10883                .table(&target.table)
10884                .ok_or_else(|| format!("sync.invalid_request: unknown table {:?}", target.table))?;
10885            let mut clauses = Vec::with_capacity(target.selectors.len());
10886            let mut params = Vec::new();
10887            for (column, values) in &target.selectors {
10888                clauses.push(format!(
10889                    "{} IN ({})",
10890                    quote_ident(column),
10891                    values.iter().map(|_| "?").collect::<Vec<_>>().join(", ")
10892                ));
10893                params.extend(values.iter().cloned().map(SqlValue::Text));
10894            }
10895            let sql = format!(
10896                "SELECT CAST({} AS TEXT) FROM {} WHERE {}",
10897                quote_ident(&table.primary_key),
10898                base_table(&target.table),
10899                clauses.join(" AND ")
10900            );
10901            let mut statement = self
10902                .conn
10903                .prepare(&sql)
10904                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10905            let rows = statement
10906                .query_map(rusqlite::params_from_iter(params), |row| {
10907                    let value = sql_ref_to_json(&table.columns[table.pk_index], row.get_ref(0)?);
10908                    render_row_id_json(Some(&value))
10909                        .map_err(|message| rusqlite::Error::ToSqlConversionFailure(message.into()))
10910                })
10911                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10912            let ids = by_table.entry(target.table.clone()).or_default();
10913            for row in rows {
10914                ids.insert(
10915                    row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10916                );
10917            }
10918        }
10919        Ok(by_table)
10920    }
10921
10922    fn local_purge_values_match(
10923        target: &CompiledLocalDataPurgeTarget,
10924        values: &Map<String, Value>,
10925    ) -> bool {
10926        target.selectors.iter().all(|(column, allowed)| {
10927            values
10928                .get(column)
10929                .and_then(Value::as_str)
10930                .is_some_and(|value| allowed.iter().any(|candidate| candidate == value))
10931        })
10932    }
10933
10934    /// Apply one host-authorized local security purge. The host MUST gate the
10935    /// corresponding subscriptions first; this primitive owns local SQLite
10936    /// cleanup and never grants/revokes server authority by itself.
10937    pub fn purge_local_data(
10938        &mut self,
10939        input: &LocalDataPurgeInput,
10940    ) -> Result<LocalDataPurgeResult, String> {
10941        let (targets, canonical_plan) = self.compile_local_data_purge(input)?;
10942        let meta_key = format!("localPurge:{}", input.purge_id);
10943        let applied_plan = self
10944            .conn
10945            .query_row(
10946                "SELECT value FROM _syncular_meta WHERE key = ?1",
10947                rusqlite::params![meta_key],
10948                |row| row.get::<_, String>(0),
10949            )
10950            .optional()
10951            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10952        if let Some(applied_plan) = applied_plan {
10953            if applied_plan != canonical_plan {
10954                return Err(format!(
10955                    "sync.invalid_request: local purge id {:?} was already used with a different plan",
10956                    input.purge_id
10957                ));
10958            }
10959            // A retry after a failed rewrite finishes it.
10960            self.erase_purged_pages()?;
10961            return Ok(LocalDataPurgeResult {
10962                already_applied: true,
10963                purged_rows: 0,
10964                dropped_commits: 0,
10965            });
10966        }
10967
10968        // RFC 0005 D7: the container file cannot be a purge target (its name is
10969        // not in the running schema), so purge drops it as a fixed step, before
10970        // any mirror row is touched and unconditionally.
10971        let _ = self.drop_previous_version();
10972
10973        let rollback = self.capture();
10974        self.begin_observation("syncular_local_purge")?;
10975        let applied = (|| -> Result<(ChangeAccumulator, LocalDataPurgeResult), String> {
10976            let row_ids = self.local_purge_base_row_ids(&targets)?;
10977            let retained_dropped = self.drop_failed_commits(|table, values| {
10978                targets.iter().any(|target| {
10979                    target.table == table && Self::local_purge_values_match(target, values)
10980                })
10981            })?;
10982            let doomed = self
10983                .outbox
10984                .iter()
10985                .filter(|commit| {
10986                    commit.ops.iter().any(|operation| {
10987                        let matching_targets = targets
10988                            .iter()
10989                            .filter(|target| target.table == operation.table)
10990                            .collect::<Vec<_>>();
10991                        if matching_targets.is_empty() {
10992                            return false;
10993                        }
10994                        if row_ids
10995                            .get(&operation.table)
10996                            .is_some_and(|ids| ids.contains(&operation.row_id))
10997                        {
10998                            return true;
10999                        }
11000                        operation.values.as_ref().is_some_and(|values| {
11001                            matching_targets
11002                                .iter()
11003                                .any(|target| Self::local_purge_values_match(target, values))
11004                        })
11005                    })
11006                })
11007                .cloned()
11008                .collect::<Vec<_>>();
11009            let doomed_ids = doomed
11010                .iter()
11011                .map(|commit| commit.client_commit_id.clone())
11012                .collect::<BTreeSet<_>>();
11013            let mut batch = ChangeAccumulator::default();
11014            for commit in &retained_dropped {
11015                batch.conflicts = true;
11016                batch.rejections = true;
11017                batch.outcomes = true;
11018                for operation in &commit.ops {
11019                    batch.table(&operation.table);
11020                }
11021            }
11022            let mut rejections = Vec::new();
11023            // §5.11 purge erasure: the journal keeps a dropped commit's identity and
11024            // codes, never its operations, so no purged value survives in it.
11025            for commit in &doomed {
11026                for operation in &commit.ops {
11027                    batch.table(&operation.table);
11028                    self.overlay_dirty.table(&operation.table);
11029                }
11030                let results = (0..commit.ops.len())
11031                    .map(|op_index| {
11032                        let rejection = RejectionRecord {
11033                            client_commit_id: commit.client_commit_id.clone(),
11034                            op_index: op_index as i32,
11035                            code: "client.local_data_purged".to_owned(),
11036                            message: "the commit was dropped by an application-authorized local data purge".to_owned(),
11037                            retryable: false,
11038                            details: None,
11039                            operation: None,
11040                        };
11041                        rejections.push(rejection.clone());
11042                        CommitOperationOutcome::Error { rejection }
11043                    })
11044                    .collect::<Vec<_>>();
11045                self.persist_commit_outcome(
11046                    &commit.client_commit_id,
11047                    CommitOutcomeStatus::Rejected,
11048                    &results,
11049                    None,
11050                )?;
11051                self.delete_outbox_persisted(&commit.client_commit_id)?;
11052            }
11053            if !doomed.is_empty() {
11054                self.outbox
11055                    .retain(|commit| !doomed_ids.contains(&commit.client_commit_id));
11056                self.rejections.extend(rejections);
11057                self.prune_commit_outcomes()?;
11058                batch.status = true;
11059                batch.rejections = true;
11060                batch.outcomes = true;
11061            }
11062
11063            let mut purged_rows = 0usize;
11064            for (table, ids) in &row_ids {
11065                if ids.is_empty() {
11066                    continue;
11067                }
11068                batch.table(table);
11069                self.overlay_dirty.table(table);
11070                for row_id in ids {
11071                    self.delete_base_row(table, row_id, i64::MAX)?;
11072                    purged_rows += 1;
11073                }
11074            }
11075            // §5.11 purge erasure: a journaled outcome with an operation or
11076            // conflict row the purge reaches keeps its identity, status, ids
11077            // and codes only.
11078            let touches = |table: &str, row_id: &str, values: Option<&Map<String, Value>>| {
11079                targets.iter().any(|target| {
11080                    target.table == table
11081                        && (row_ids.get(table).is_some_and(|ids| ids.contains(row_id))
11082                            || values.is_some_and(|values| {
11083                                Self::local_purge_values_match(target, values)
11084                            }))
11085                })
11086            };
11087            let entries = self
11088                .conn
11089                .prepare("SELECT client_commit_id, results_json, operations_json FROM _syncular_commit_outcomes")
11090                .and_then(|mut statement| {
11091                    statement
11092                        .query_map([], |row| {
11093                            Ok((
11094                                row.get::<_, String>(0)?,
11095                                row.get::<_, String>(1)?,
11096                                row.get::<_, Option<String>>(2)?,
11097                            ))
11098                        })?
11099                        .collect::<Result<Vec<_>, _>>()
11100                })
11101                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11102            for (client_commit_id, results_json, operations_json) in entries {
11103                let corrupt = |_| "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
11104                let mut results: Vec<CommitOperationOutcome> =
11105                    serde_json::from_str(&results_json).map_err(corrupt)?;
11106                let operations: Vec<CommitOperation> = operations_json
11107                    .map(|json| serde_json::from_str(&json))
11108                    .transpose()
11109                    .map_err(corrupt)?
11110                    .unwrap_or_default();
11111                let named = operations
11112                    .iter()
11113                    .chain(results.iter().filter_map(|result| match result {
11114                        CommitOperationOutcome::Conflict { conflict } => conflict.operation.as_ref(),
11115                        CommitOperationOutcome::Error { rejection } => rejection.operation.as_ref(),
11116                        CommitOperationOutcome::Applied { .. } => None,
11117                    }))
11118                    .any(|operation| touches(&operation.table, &operation.row_id, operation.values.as_ref()))
11119                    || results.iter().any(|result| {
11120                        matches!(result, CommitOperationOutcome::Conflict { conflict }
11121                            if touches(&conflict.table, &conflict.row_id, Some(&conflict.server_row)))
11122                    });
11123                if !named {
11124                    continue;
11125                }
11126                for result in &mut results {
11127                    match result {
11128                        CommitOperationOutcome::Conflict { conflict } => {
11129                            conflict.server_row = Map::new();
11130                            conflict.conflict_columns.clear();
11131                            conflict.operation = None;
11132                        }
11133                        CommitOperationOutcome::Error { rejection } => {
11134                            rejection.details = None;
11135                            rejection.operation = None;
11136                        }
11137                        CommitOperationOutcome::Applied { .. } => {}
11138                    }
11139                }
11140                let results_json = serde_json::to_string(&results).map_err(|error| error.to_string())?;
11141                self.conn
11142                    .execute(
11143                        "UPDATE _syncular_commit_outcomes SET results_json = ?1, operations_json = NULL WHERE client_commit_id = ?2",
11144                        rusqlite::params![results_json, client_commit_id],
11145                    )
11146                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11147                batch.outcomes = true;
11148            }
11149            self.rebuild_overlay_if_dirty()?;
11150            self.delete_unreferenced_cached_blobs()?;
11151            self.conn
11152                .execute(
11153                    "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
11154                    rusqlite::params![meta_key, canonical_plan],
11155                )
11156                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11157            Ok((
11158                batch,
11159                LocalDataPurgeResult {
11160                    already_applied: false,
11161                    purged_rows,
11162                    dropped_commits: doomed.len(),
11163                },
11164            ))
11165        })()
11166        .and_then(|(batch, result)| {
11167            self.finish_observation("syncular_local_purge", batch)
11168                .map(|()| result)
11169        });
11170        let result = match applied {
11171            Ok(result) => result,
11172            Err(error) => {
11173                self.rollback_observation("syncular_local_purge");
11174                self.restore(rollback);
11175                return Err(error);
11176            }
11177        };
11178        self.cancel_sync_round();
11179        self.erase_purged_pages()?;
11180        Ok(result)
11181    }
11182
11183    /// §5.11 purge erasure: SQLite leaves a deleted value in the freed pages of the
11184    /// database file, and the WAL keeps the frames written before the purge,
11185    /// until either is rewritten. VACUUM rebuilds the file from the remaining
11186    /// rows, and the checkpoint truncates the WAL.
11187    fn erase_purged_pages(&self) -> Result<(), String> {
11188        let erased = self
11189            .conn
11190            .execute_batch("PRAGMA secure_delete = ON; VACUUM;")
11191            .and_then(|()| {
11192                self.conn
11193                    .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
11194            });
11195        let reset = self.conn.execute_batch("PRAGMA secure_delete = OFF");
11196        erased
11197            .and(reset)
11198            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11199    }
11200
11201    /// Application-authorized recovery of the replicated projection. Unlike a
11202    /// local security purge, this retains the entire outbox, device identity,
11203    /// lease, outcomes, unit registrations, and protected bookkeeping.
11204    /// The projection reset, unit rewind, optimistic replay, and
11205    /// idempotency marker share one savepoint for interruption safety.
11206    pub fn rebootstrap_local_data(
11207        &mut self,
11208        input: &LocalDataRebootstrapInput,
11209    ) -> Result<LocalDataRebootstrapResult, String> {
11210        if input.rebootstrap_id.is_empty()
11211            || input.rebootstrap_id.len() > 128
11212            || !is_local_operation_code_like(&input.rebootstrap_id)
11213        {
11214            return Err(
11215                "sync.invalid_request: local rebootstrap rebootstrapId must be a 1–128 character code-like identifier"
11216                    .to_owned(),
11217            );
11218        }
11219        let meta_key = format!("localRebootstrap:{}", input.rebootstrap_id);
11220        if let Some(persisted) = meta_get(&self.conn, &meta_key).map_err(|_| {
11221            "sync.local_corrupt: persisted local rebootstrap receipt is unreadable".to_owned()
11222        })? {
11223            let (retained_commits, reset_subscriptions) =
11224                decode_local_rebootstrap_receipt(&persisted)?;
11225            return Ok(LocalDataRebootstrapResult {
11226                already_applied: true,
11227                retained_commits,
11228                reset_subscriptions,
11229            });
11230        }
11231        if self.stopped || self.schema_floor.is_some() {
11232            return Err(
11233                "sync.invalid_request: local rebootstrap cannot bypass an active schema-floor stop; update the application first"
11234                    .to_owned(),
11235            );
11236        }
11237
11238        let retained_commits = self.outbox.len();
11239        let reset_subscriptions = self.stored(load_units(&self.conn))?.len();
11240        let receipt = encode_local_rebootstrap_receipt(retained_commits, reset_subscriptions)?;
11241        let rollback = self.capture();
11242        self.begin_observation("syncular_local_rebootstrap")?;
11243        let mut batch = ChangeAccumulator::default();
11244        let applied = (|| -> Result<(), String> {
11245            self.run_schema_reset_observed(&mut batch, false)?;
11246            self.conn
11247                .execute(
11248                    "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
11249                    rusqlite::params![meta_key, receipt],
11250                )
11251                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11252            self.sync_needed = true;
11253            self.sync_intent_queue.push_back(SyncIntent::Interactive);
11254            batch.status = true;
11255            Ok(())
11256        })()
11257        .and_then(|()| self.finish_observation("syncular_local_rebootstrap", batch));
11258        if let Err(error) = applied {
11259            self.rollback_observation("syncular_local_rebootstrap");
11260            self.restore(rollback);
11261            return Err(error);
11262        }
11263
11264        Ok(LocalDataRebootstrapResult {
11265            already_applied: false,
11266            retained_commits,
11267            reset_subscriptions,
11268        })
11269    }
11270
11271    // -- scope purge + doomed outbox (§3.3) ----------------------------------------
11272
11273    /// Delete base and visible rows owned by the effective scopes
11274    /// ([`local_scope_predicate`]); `Ok(false)` = no local scope-column
11275    /// mapping for a key (the fail-closed case). A SQLite failure is an error.
11276    fn purge_scope_rows(
11277        &mut self,
11278        table_name: &str,
11279        effective: &[(String, Vec<String>)],
11280        owners: &[Vec<(String, Vec<String>)>],
11281    ) -> Result<bool, String> {
11282        let Some(table) = self.schema.table(table_name) else {
11283            return Ok(false);
11284        };
11285        let Ok(predicate) = local_scope_predicate(table, effective, owners) else {
11286            return Ok(false);
11287        };
11288        let Some((predicate, params)) = predicate else {
11289            return Ok(true);
11290        };
11291        self.overlay_dirty.table(table_name);
11292        for source in [base_table(table_name), visible_table(table_name)] {
11293            self.conn
11294                .execute(
11295                    &format!("DELETE FROM {source} WHERE {predicate}"),
11296                    rusqlite::params_from_iter(&params),
11297                )
11298                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11299        }
11300        Ok(true)
11301    }
11302
11303    /// §3.3: drop pending commits whose upserts provably land in the
11304    /// revoked effective scopes and no other owner covers (row ownership)
11305    /// — whole-commit, never per-operation.
11306    fn drop_doomed_outbox(
11307        &mut self,
11308        table: &TableSchema,
11309        effective: &[(String, Vec<String>)],
11310        owners: &[Vec<(String, Vec<String>)>],
11311    ) -> Result<bool, String> {
11312        let doomed: Vec<_> =
11313            self.outbox
11314                .iter()
11315                .filter(|commit| {
11316                    commit.ops.iter().any(|op| {
11317                        op.upsert
11318                            && op.table == table.name
11319                            && op.values.as_ref().is_some_and(|values| {
11320                                owns_local_row(table, effective, owners, values)
11321                            })
11322                    })
11323                })
11324                .cloned()
11325                .collect();
11326        if doomed.is_empty() {
11327            return Ok(false);
11328        }
11329        let mut rejections = Vec::new();
11330        for commit in &doomed {
11331            let results = commit
11332                .ops
11333                .iter()
11334                .enumerate()
11335                .map(|(op_index, operation)| {
11336                    self.overlay_dirty.table(&operation.table);
11337                    let rejection = RejectionRecord {
11338                        client_commit_id: commit.client_commit_id.clone(),
11339                        op_index: op_index as i32,
11340                        code: "sync.scope_revoked".to_owned(),
11341                        message: "the commit was dropped because its effective scope was revoked"
11342                            .to_owned(),
11343                        retryable: false,
11344                        details: None,
11345                        operation: Some(CommitOperation::from(operation)),
11346                    };
11347                    rejections.push(rejection.clone());
11348                    CommitOperationOutcome::Error { rejection }
11349                })
11350                .collect::<Vec<_>>();
11351            self.persist_commit_outcome(
11352                &commit.client_commit_id,
11353                CommitOutcomeStatus::Rejected,
11354                &results,
11355                Some(&commit.ops),
11356            )?;
11357            self.delete_outbox_persisted(&commit.client_commit_id)?;
11358        }
11359        self.prune_commit_outcomes()?;
11360        let doomed_ids = doomed
11361            .iter()
11362            .map(|commit| commit.client_commit_id.as_str())
11363            .collect::<BTreeSet<_>>();
11364        self.outbox
11365            .retain(|commit| !doomed_ids.contains(commit.client_commit_id.as_str()));
11366        self.rejections.extend(rejections);
11367        Ok(true)
11368    }
11369
11370    // -- blobs (§5.9) ----------------------------------------------------------------
11371
11372    /// §5.9.7: hash bytes into the content address, cache them, queue the
11373    /// upload (flushed before the next push, B4). Returns the canonical
11374    /// BlobRef JSON `{blobId, byteLength, mediaType?}` for a `blob_ref`
11375    /// column value.
11376    pub fn upload_blob(
11377        &mut self,
11378        bytes: &[u8],
11379        media_type: Option<String>,
11380        name: Option<String>,
11381    ) -> Result<Value, String> {
11382        let blob_id = blob_id_for(bytes);
11383        let now = self.clock_now_ms();
11384        let tx = self
11385            .conn
11386            .transaction()
11387            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11388        tx.execute(
11389            "INSERT INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,?,?)
11390             ON CONFLICT(blob_id) DO NOTHING",
11391            rusqlite::params![blob_id, bytes, bytes.len() as i64, media_type, now],
11392        )
11393        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11394        tx.execute(
11395            "INSERT OR IGNORE INTO _syncular_blob_uploads(blob_id, media_type, created_at_ms) VALUES (?,?,?)",
11396            rusqlite::params![blob_id, media_type, now],
11397        )
11398        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11399        tx.commit()
11400            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11401        self.enforce_blob_cache_cap();
11402        let mut obj = Map::new();
11403        obj.insert("blobId".to_owned(), Value::from(blob_id));
11404        obj.insert("byteLength".to_owned(), Value::from(bytes.len() as i64));
11405        if let Some(mt) = media_type {
11406            obj.insert("mediaType".to_owned(), Value::from(mt));
11407        }
11408        if let Some(n) = name {
11409            obj.insert("name".to_owned(), Value::from(n));
11410        }
11411        Ok(Value::Object(obj))
11412    }
11413
11414    /// §5.9.7: resolve an owned blob body without driver encoding. A
11415    /// content-addressed cache hit serves with no fetch (B1); a miss downloads
11416    /// (§5.9.5), verifies the address, caches the bytes, and returns them.
11417    pub fn fetch_blob_bytes(
11418        &mut self,
11419        transport: &mut dyn Transport,
11420        blob_id_or_ref: &str,
11421    ) -> Result<FetchedBlob, (String, String)> {
11422        let simple = |m: String| ("client.failed".to_owned(), m);
11423        // A BlobRef declares the size that caps the download (§5.9.5); a bare
11424        // blobId declares none.
11425        let (blob_id, byte_length) = if blob_id_or_ref.starts_with("sha256:") {
11426            (blob_id_or_ref.to_owned(), None)
11427        } else {
11428            let value: Value = serde_json::from_str(blob_id_or_ref)
11429                .map_err(|_| simple("blob ref is not JSON".to_owned()))?;
11430            (
11431                value
11432                    .get("blobId")
11433                    .and_then(Value::as_str)
11434                    .ok_or_else(|| simple("blob ref has no blobId".to_owned()))?
11435                    .to_owned(),
11436                value.get("byteLength").and_then(Value::as_u64),
11437            )
11438        };
11439        if let Some(cached) = self.get_cached_blob_bytes(&blob_id).map_err(simple)? {
11440            return Ok(cached);
11441        }
11442        if !self.transport_enabled {
11443            return Err(("sync.offline".into(), "transport gate is closed".into()));
11444        }
11445        // §5.9.5: propagate the server's blob.* code (blob.forbidden /
11446        // blob.not_found) verbatim so the harness can assert on it. The
11447        // authorized endpoint serves bytes inline OR (always-issue, presign
11448        // configured) a signed url the client fetches directly — no host auth,
11449        // no fall-through: failure => re-request (the caller's next fetch_blob_bytes).
11450        #[cfg(feature = "bench-internals")]
11451        let download_phase = self.benchmark_phases.start(Phase::BlobDownload);
11452        let bytes = match transport
11453            .blob_download(&blob_id, byte_length)
11454            .map_err(|e| (e.code, e.message))?
11455        {
11456            BlobDownload::Bytes(bytes) => bytes,
11457            BlobDownload::Url {
11458                url,
11459                url_expires_at_ms,
11460            } => {
11461                // §5.9.5: MUST NOT start a fetch at/past expiry.
11462                if url_expires_at_ms.is_some_and(|exp| exp <= self.clock_now_ms()) {
11463                    return Err((
11464                        "sync.segment_expired".to_owned(),
11465                        format!(
11466                            "blob url for {blob_id} expired before fetch — re-request mints a fresh url (§5.9.5)"
11467                        ),
11468                    ));
11469                }
11470                transport
11471                    .fetch_blob_url(&url, byte_length)
11472                    .map_err(|e| (e.code, e.message))?
11473            }
11474        };
11475        #[cfg(feature = "bench-internals")]
11476        drop(download_phase);
11477        #[cfg(feature = "bench-internals")]
11478        let validate_phase = self.benchmark_phases.start(Phase::BlobValidate);
11479        // §5.9.5 inherits §5.1: the declared size caps the body before the
11480        // content address is verified.
11481        if byte_length.is_some_and(|cap| bytes.len() as u64 > cap) {
11482            return Err((
11483                "sync.invalid_request".to_owned(),
11484                "blob exceeds its byteLength".to_owned(),
11485            ));
11486        }
11487        if blob_id_for(&bytes) != blob_id {
11488            return Err(simple(format!(
11489                "blob content address mismatch for {blob_id}"
11490            )));
11491        }
11492        #[cfg(feature = "bench-internals")]
11493        drop(validate_phase);
11494        #[cfg(feature = "bench-internals")]
11495        let insert_phase = self.benchmark_phases.start(Phase::BlobCacheInsert);
11496        let now = self.clock_now_ms();
11497        self.conn
11498            .execute(
11499                "INSERT OR IGNORE INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,NULL,?)",
11500                rusqlite::params![blob_id, bytes, bytes.len() as i64, now],
11501            )
11502            .map_err(|e| simple(e.to_string()))?;
11503        self.conn
11504            .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
11505            .map_err(|e| simple(e.to_string()))?;
11506        self.enforce_blob_cache_cap();
11507        #[cfg(feature = "bench-internals")]
11508        drop(insert_phase);
11509        self.get_cached_blob_bytes(&blob_id)
11510            .map_err(simple)?
11511            .ok_or_else(|| simple("blob cache write failed".to_owned()))
11512    }
11513
11514    fn get_cached_blob_bytes(&self, blob_id: &str) -> Result<Option<FetchedBlob>, String> {
11515        #[cfg(feature = "bench-internals")]
11516        let _phase = self.benchmark_phases.start(Phase::BlobCacheRead);
11517        let mut stmt = self
11518            .conn
11519            .prepare("SELECT bytes, byte_length, media_type FROM _syncular_blobs WHERE blob_id = ?")
11520            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11521        let mut rows = stmt
11522            .query(rusqlite::params![blob_id])
11523            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11524        if let Some(row) = rows
11525            .next()
11526            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11527        {
11528            let bytes: Vec<u8> = row
11529                .get(0)
11530                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11531            let byte_length: i64 = row
11532                .get(1)
11533                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11534            let media_type: Option<String> = row
11535                .get(2)
11536                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11537            return Ok(Some(FetchedBlob {
11538                blob_id: blob_id.to_owned(),
11539                byte_length,
11540                bytes,
11541                media_type,
11542            }));
11543        }
11544        Ok(None)
11545    }
11546
11547    /// §5.9.7 B4: upload every queued blob before push.
11548    fn pending_blob_uploads(&self) -> Result<Vec<crate::round::PendingUpload>, TransportError> {
11549        let pending: Vec<(String, Option<String>)> = {
11550            let mut stmt = self
11551                .conn
11552                .prepare(
11553                    "SELECT blob_id, media_type FROM (
11554                      SELECT blob_id, media_type, created_at_ms FROM _syncular_blob_uploads
11555                      UNION ALL
11556                      SELECT DISTINCT r.blob_id, b.media_type, 9223372036854775807 AS created_at_ms
11557                      FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id = r.blob_id
11558                      WHERE NOT EXISTS (SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id = r.blob_id)
11559                    ) ORDER BY created_at_ms, blob_id",
11560                )
11561                .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11562            let rows = stmt
11563                .query_map([], |row| {
11564                    Ok((row.get::<_, String>(0)?, row.get::<_, Option<String>>(1)?))
11565                })
11566                .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11567            rows.collect::<Result<_, _>>()
11568                .map_err(|error| match error {
11569                    rusqlite::Error::InvalidColumnType(..)
11570                    | rusqlite::Error::FromSqlConversionFailure(..) => TransportError::new(
11571                        "sync.local_corrupt",
11572                        "Pending blob upload metadata is invalid",
11573                    ),
11574                    _ => TransportError::new("client.failed", error.to_string()),
11575                })?
11576        };
11577        let mut uploads = Vec::new();
11578        for (blob_id, media_type) in pending {
11579            let bytes = (|| {
11580                let stored: Option<(SqlValue, SqlValue)> = self
11581                    .conn
11582                    .query_row(
11583                        "SELECT bytes, byte_length FROM _syncular_blobs WHERE blob_id = ?",
11584                        rusqlite::params![blob_id],
11585                        |row| Ok((row.get(0)?, row.get(1)?)),
11586                    )
11587                    .optional()
11588                    .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11589                let Some((SqlValue::Blob(bytes), SqlValue::Integer(byte_length))) = stored else {
11590                    return Err(TransportError::new(
11591                        "sync.local_corrupt",
11592                        "Pending blob upload body is missing or corrupt",
11593                    ));
11594                };
11595                if byte_length != bytes.len() as i64 || blob_id_for(&bytes) != blob_id {
11596                    return Err(TransportError::new(
11597                        "sync.local_corrupt",
11598                        "Pending blob upload body is missing or corrupt",
11599                    ));
11600                }
11601                Ok(bytes)
11602            })();
11603            let failed = bytes.is_err();
11604            uploads.push(crate::round::PendingUpload {
11605                id: blob_id,
11606                bytes,
11607                media_type,
11608            });
11609            if failed {
11610                break;
11611            }
11612        }
11613        Ok(uploads)
11614    }
11615
11616    fn visible_blob_ids_sql(&self) -> String {
11617        let mut selects = Vec::new();
11618        for table in &self.schema.tables {
11619            for column in table
11620                .columns
11621                .iter()
11622                .filter(|column| column.ty == ColumnType::BlobRef)
11623            {
11624                let identifier = quote_ident(&column.name);
11625                selects.push(format!(
11626                    "SELECT json_extract({identifier}, '$.blobId') AS blob_id FROM {} \
11627                     WHERE typeof({identifier}) = 'text' AND json_valid({identifier}) \
11628                     AND json_type({identifier}, '$.blobId') = 'text'",
11629                    quote_ident(&table.name),
11630                ));
11631            }
11632        }
11633        if selects.is_empty() {
11634            "SELECT NULL AS blob_id WHERE 0".to_owned()
11635        } else {
11636            selects.join(" UNION ")
11637        }
11638    }
11639
11640    /// §5.9.7 B1 size cap. Visible rows, pending commits, and
11641    /// staged uploads pin bodies directly; no derived refcount is stored.
11642    fn enforce_blob_cache_cap(&self) {
11643        let Some(max_bytes) = self.limits.blob_cache_max_bytes else {
11644            return;
11645        };
11646        let mut total: i64 = self
11647            .conn
11648            .query_row(
11649                "SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs",
11650                [],
11651                |row| row.get(0),
11652            )
11653            .unwrap_or(0);
11654        if total <= max_bytes {
11655            return;
11656        }
11657        let query = format!(
11658            "SELECT blob_id, byte_length FROM _syncular_blobs
11659             WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
11660               AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
11661               AND blob_id NOT IN ({})
11662             ORDER BY created_at_ms ASC, blob_id ASC",
11663            self.visible_blob_ids_sql(),
11664        );
11665        let candidates: Vec<(String, i64)> = {
11666            let Ok(mut stmt) = self.conn.prepare(&query) else {
11667                return;
11668            };
11669            let Ok(rows) = stmt.query_map([], |row| {
11670                Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
11671            }) else {
11672                return;
11673            };
11674            rows.filter_map(Result::ok).collect()
11675        };
11676        for (blob_id, byte_length) in candidates {
11677            if total <= max_bytes {
11678                break;
11679            }
11680            let _ = self.conn.execute(
11681                "DELETE FROM _syncular_blobs WHERE blob_id = ?",
11682                rusqlite::params![blob_id],
11683            );
11684            total -= byte_length;
11685        }
11686    }
11687
11688    fn delete_unreferenced_cached_blobs(&mut self) -> Result<(), String> {
11689        #[cfg(feature = "bench-internals")]
11690        let _phase = self.benchmark_phases.start(Phase::BlobRetention);
11691        if !self.schema_has_blobs() {
11692            return Ok(());
11693        }
11694        self.rebuild_overlay_if_dirty()?;
11695        self.conn
11696            .execute(
11697                &format!(
11698                    "DELETE FROM _syncular_blobs
11699                 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
11700                   AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
11701                   AND blob_id NOT IN ({})",
11702                    self.visible_blob_ids_sql(),
11703                ),
11704                [],
11705            )
11706            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11707        Ok(())
11708    }
11709
11710    // -- local row storage ----------------------------------------------------------
11711
11712    /// The cached per-table primary-key upsert SQL for `full_table` (see
11713    /// the `insert_sql` field: built once, reused per row).
11714    fn insert_row_sql(&self, full_table: &str, table: &crate::schema::TableSchema) -> String {
11715        if let Some(sql) = self.insert_sql.borrow().get(full_table) {
11716            return sql.clone();
11717        }
11718        let mut columns: Vec<String> = table.columns.iter().map(|c| quote_ident(&c.name)).collect();
11719        columns.push(quote_ident("_syncular_version"));
11720        columns.extend(table.sealed_columns().iter().map(|name| quote_ident(name)));
11721        let placeholders: Vec<&str> = columns.iter().map(|_| "?").collect();
11722        let primary_key = quote_ident(&table.primary_key);
11723        let updates = columns
11724            .iter()
11725            .filter(|column| **column != primary_key)
11726            .map(|column| format!("{column}=excluded.{column}"))
11727            .collect::<Vec<_>>()
11728            .join(", ");
11729        // §4.5 version guard: server state lands in the base table only above
11730        // the stored version; the visible overlay takes every write.
11731        let guard = if full_table == base_table(&table.name) {
11732            format!(" WHERE excluded._syncular_version > {full_table}._syncular_version")
11733        } else {
11734            String::new()
11735        };
11736        let sql = format!(
11737            "INSERT INTO {full_table} ({}) VALUES ({}) ON CONFLICT ({primary_key}) DO UPDATE SET {updates}{guard}",
11738            columns.join(", "),
11739            placeholders.join(", ")
11740        );
11741        self.insert_sql
11742            .borrow_mut()
11743            .insert(full_table.to_owned(), sql.clone());
11744        sql
11745    }
11746
11747    /// §4.5: write a server row under the version guard; returns whether it
11748    /// landed. `sealed` is its §5.11 sealed state, `None` for an unsealed row.
11749    fn write_base_row(
11750        &self,
11751        table_name: &str,
11752        row: &Row,
11753        version: i64,
11754        sealed: Option<&SealedRow>,
11755    ) -> Result<bool, String> {
11756        let landed = self.write_row(&base_table(table_name), table_name, row, version, sealed)?;
11757        if landed {
11758            self.overlay_dirty.table(table_name);
11759        }
11760        Ok(landed)
11761    }
11762
11763    fn write_row(
11764        &self,
11765        full_table: &str,
11766        table_name: &str,
11767        row: &Row,
11768        version: i64,
11769        sealed: Option<&SealedRow>,
11770    ) -> Result<bool, String> {
11771        #[cfg(feature = "bench-internals")]
11772        let _phase = self.benchmark_phases.start(Phase::RowWrite);
11773        let table = self
11774            .schema
11775            .table(table_name)
11776            .ok_or_else(|| format!("unknown table {table_name:?}"))?;
11777        let sql = self.insert_row_sql(full_table, table);
11778        let mut stmt = self
11779            .conn
11780            .prepare_cached(&sql)
11781            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11782        let params = row
11783            .iter()
11784            .map(RowParam::Cell)
11785            .chain(std::iter::once(RowParam::Version(version)))
11786            .chain(
11787                [
11788                    sealed.map(|sealed| sealed.key_id.as_str()),
11789                    sealed.map(|sealed| sealed.envelopes.as_str()),
11790                ]
11791                .into_iter()
11792                .take(table.sealed_columns().len())
11793                .map(RowParam::Text),
11794            );
11795        stmt.execute(rusqlite::params_from_iter(params))
11796            .map(|changed| changed > 0)
11797            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11798    }
11799
11800    /// §4.5: delete a server row whose stored version lies below `version`;
11801    /// returns whether a row left.
11802    fn delete_base_row(
11803        &self,
11804        table_name: &str,
11805        row_id: &str,
11806        version: i64,
11807    ) -> Result<bool, String> {
11808        let table = self
11809            .schema
11810            .table(table_name)
11811            .ok_or_else(|| format!("unknown table {table_name:?}"))?;
11812        let sql = format!(
11813            "DELETE FROM {} WHERE {} AND _syncular_version < ?2",
11814            base_table(table_name),
11815            row_id_predicate(table)
11816        );
11817        let mut stmt = self
11818            .conn
11819            .prepare_cached(&sql)
11820            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11821        let landed = stmt
11822            .execute(rusqlite::params![row_id, version])
11823            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11824            > 0;
11825        if landed {
11826            self.overlay_dirty.table(table_name);
11827        }
11828        Ok(landed)
11829    }
11830
11831    fn has_acknowledged_rows(&self) -> Result<bool, String> {
11832        self.conn
11833            .query_row(
11834                "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows)",
11835                [],
11836                |row| row.get(0),
11837            )
11838            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11839    }
11840
11841    fn acknowledged_operations(
11842        &self,
11843        rows: Option<&HashSet<(&str, &str)>>,
11844        tables: Option<&BTreeSet<&str>>,
11845    ) -> Result<Vec<OutboxOp>, String> {
11846        let keys = rows.map(|rows| serde_json::to_string(&rows).expect("row keys"));
11847        let mut statement = self
11848            .conn
11849            .prepare_cached(if keys.is_some() {
11850                ACKED_ROWS_BY_ROW
11851            } else {
11852                "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"
11853            })
11854            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11855        let rows = statement
11856            .query_map(
11857                rusqlite::params![
11858                    keys,
11859                    tables.map(|tables| serde_json::to_string(tables).expect("table keys"))
11860                ],
11861                |row| {
11862                    #[cfg(test)]
11863                    self.acknowledged_replay_count
11864                        .set(self.acknowledged_replay_count.get() + 1);
11865                    Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
11866                },
11867            )
11868            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11869        rows.map(|row| {
11870            let (op, intent) =
11871                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11872            let op: CommitOperation =
11873                serde_json::from_str(&op).map_err(|_| "sync.local_corrupt".to_owned())?;
11874            let table = self
11875                .schema
11876                .table(&op.table)
11877                .ok_or_else(|| "sync.unknown_table".to_owned())?;
11878            let values = if op.op == "upsert" && self.visible_row(table, &op.row_id)?.is_none() {
11879                Some(serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?)
11880            } else {
11881                op.values.clone()
11882            };
11883            Ok(OutboxOp {
11884                values,
11885                ..op.into()
11886            })
11887        })
11888        .collect()
11889    }
11890
11891    fn drop_acknowledged_rows(
11892        &self,
11893        matches: impl Fn(&str, &Map<String, Value>) -> bool,
11894    ) -> Result<Vec<OutboxCommit>, String> {
11895        let mut statement = self
11896            .conn
11897            .prepare("SELECT commit_id,tbl,intent_json,id FROM _syncular_acked_rows")
11898            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11899        let rows = statement
11900            .query_map([], |row| {
11901                Ok((
11902                    row.get::<_, String>(0)?,
11903                    row.get::<_, String>(1)?,
11904                    row.get::<_, String>(2)?,
11905                    row.get::<_, String>(3)?,
11906                ))
11907            })
11908            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11909        let mut doomed = HashSet::new();
11910        for row in rows {
11911            let (id, table, intent, row_id) =
11912                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11913            let values =
11914                serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
11915            let base_matches = self
11916                .schema
11917                .table(&table)
11918                .map(|schema| self.stored_row(schema, &row_id, true))
11919                .transpose()?
11920                .flatten()
11921                .is_some_and(|(base, _)| {
11922                    let schema = self.schema.table(&table).expect("acknowledged table");
11923                    let values = schema
11924                        .columns
11925                        .iter()
11926                        .zip(base.iter())
11927                        .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
11928                        .collect();
11929                    matches(&table, &values)
11930                });
11931            if matches(&table, &values) || base_matches {
11932                doomed.insert(id);
11933            }
11934        }
11935        let mut dropped = Vec::new();
11936        for id in doomed {
11937            let mut statement = self
11938                .conn
11939                .prepare("SELECT op_json FROM _syncular_acked_rows WHERE commit_id=?1 ORDER BY idx")
11940                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11941            let operations = statement
11942                .query_map([&id], |row| row.get::<_, String>(0))
11943                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11944            let mut ops = Vec::new();
11945            for operation in operations {
11946                let json = operation
11947                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11948                let op: CommitOperation =
11949                    serde_json::from_str(&json).map_err(|_| "sync.local_corrupt".to_owned())?;
11950                self.overlay_dirty.table(&op.table);
11951                ops.push(OutboxOp {
11952                    table: op.table,
11953                    row_id: op.row_id,
11954                    upsert: op.op == "upsert",
11955                    base_version: op.base_version,
11956                    values: op.values,
11957                    insert: op.insert,
11958                });
11959            }
11960            dropped.push(OutboxCommit {
11961                client_commit_id: id.clone(),
11962                ops,
11963            });
11964            self.conn
11965                .execute("DELETE FROM _syncular_acked_rows WHERE commit_id=?1", [id])
11966                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11967        }
11968        Ok(dropped)
11969    }
11970
11971    /// [`Self::rebuild_overlay`], skipped when neither the base tables nor
11972    /// the outbox changed since the last rebuild (the no-op sync round).
11973    fn rebuild_overlay_if_dirty(&mut self) -> Result<(), String> {
11974        if self.overlay_dirty.get() {
11975            self.rebuild_overlay()?;
11976        }
11977        Ok(())
11978    }
11979
11980    /// §7.1: local reads see outbox state applied optimistically — rebuild
11981    /// every visible table as (base server state) + (pending outbox replay
11982    /// on top). Optimistic rows carry version `-1`.
11983    fn rebuild_overlay(&mut self) -> Result<(), String> {
11984        #[cfg(feature = "bench-internals")]
11985        let _phase = self.benchmark_phases.start(Phase::OverlayRebuild);
11986        #[cfg(test)]
11987        self.overlay_rebuild_count
11988            .set(self.overlay_rebuild_count.get() + 1);
11989        let dirty = self.overlay_dirty.snapshot();
11990        let tables: Vec<_> = self
11991            .schema
11992            .tables
11993            .iter()
11994            .filter(|table| {
11995                dirty
11996                    .as_ref()
11997                    .is_none_or(|names| names.is_empty() || names.contains(&table.name))
11998            })
11999            .cloned()
12000            .collect();
12001        let names: BTreeSet<_> = tables.iter().map(|table| table.name.as_str()).collect();
12002        self.begin_observation("syncular_overlay")?;
12003        let rebuilt = (|| {
12004            for table in &tables {
12005                for index in &table.fts_indexes {
12006                    self.drop_fts_triggers(index)?;
12007                }
12008                let visible = visible_table(&table.name);
12009                let base = base_table(&table.name);
12010                self.conn
12011                    .execute_batch(&format!(
12012                        "DELETE FROM {visible}; INSERT INTO {visible} SELECT * FROM {base}"
12013                    ))
12014                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12015            }
12016            self.replay_overlay(&names, None)?;
12017            for table in &tables {
12018                for index in &table.fts_indexes {
12019                    self.rebuild_fts_projection(table, index)?;
12020                    self.create_fts_triggers(table, index)?;
12021                }
12022            }
12023            self.conn
12024                .execute_batch("RELEASE syncular_overlay")
12025                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12026            Ok(())
12027        })();
12028        if rebuilt.is_err() {
12029            self.conn
12030                .execute_batch("ROLLBACK TO syncular_overlay; RELEASE syncular_overlay")
12031                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12032        } else {
12033            self.overlay_dirty.set(false);
12034        }
12035        rebuilt
12036    }
12037
12038    /// §7.1 replay of acknowledged, retained failed and pending intent, in
12039    /// that order, for the operations of `tables` on `rows` (every row for
12040    /// `None`) over their current visible state.
12041    fn replay_overlay(
12042        &self,
12043        tables: &BTreeSet<&str>,
12044        rows: Option<&HashSet<(&str, &str)>>,
12045    ) -> Result<(), String> {
12046        let replays = |op: &&OutboxOp| {
12047            tables.contains(op.table.as_str())
12048                && rows.is_none_or(|rows| rows.contains(&(op.table.as_str(), op.row_id.as_str())))
12049        };
12050        self.apply_outbox_ops(&self.acknowledged_operations(rows, Some(tables))?)?;
12051        for (commit, initial) in self.failed_commits.iter() {
12052            for operation in commit.ops.iter().filter(replays) {
12053                let Some(table) = self.schema.table(&operation.table) else {
12054                    continue;
12055                };
12056                if operation.upsert
12057                    && self.visible_row(table, &operation.row_id)?.is_none()
12058                    && operation.presented_values(table).is_some_and(|values| {
12059                        table
12060                            .columns
12061                            .iter()
12062                            .all(|column| values.contains_key(&column.name))
12063                    })
12064                {
12065                    let key = serde_json::to_string(&(&operation.table, &operation.row_id))
12066                        .expect("row key serialization");
12067                    if let Some(Value::Object(values)) = initial.get(&key) {
12068                        self.apply_outbox_ops(&[OutboxOp {
12069                            values: Some(values.clone()),
12070                            ..operation.clone()
12071                        }])?;
12072                    }
12073                }
12074            }
12075            self.apply_outbox_ops(commit.ops.iter().filter(replays))?;
12076        }
12077        self.apply_outbox_ops(
12078            self.outbox
12079                .iter()
12080                .flat_map(|commit| &commit.ops)
12081                .filter(replays),
12082        )
12083    }
12084
12085    /// §7.1 replay: every operation is applied over the current visible
12086    /// state. An operation that no longer applies (a server row now holds its
12087    /// unique value) stays pending and invisible until a later replay admits
12088    /// it or the server answers its push.
12089    fn apply_outbox_ops<'a>(
12090        &self,
12091        ops: impl IntoIterator<Item = &'a OutboxOp>,
12092    ) -> Result<(), String> {
12093        #[cfg(feature = "bench-internals")]
12094        let mut phase = self.benchmark_phases.start(Phase::PendingReplay);
12095        for op in ops {
12096            #[cfg(feature = "bench-internals")]
12097            if let Some(phase) = &mut phase {
12098                phase.unit();
12099            }
12100            if op.upsert {
12101                if let Some((table, values)) = self
12102                    .schema
12103                    .table(&op.table)
12104                    .filter(|table| table.indexes.iter().any(|index| index.unique))
12105                    .and_then(|table| Some((table, op.presented_values(table)?)))
12106                {
12107                    let mut intended: Map<String, Value> = self
12108                        .visible_row(table, &op.row_id)?
12109                        .map(|(row, _)| {
12110                            table
12111                                .columns
12112                                .iter()
12113                                .zip(&row)
12114                                .map(|(column, value)| {
12115                                    (column.name.clone(), column_value_to_json(value))
12116                                })
12117                                .collect()
12118                        })
12119                        .unwrap_or_default();
12120                    intended.extend(values.into_owned());
12121                    if !self.unique_conflicts(table, &intended, false)?.is_empty() {
12122                        continue;
12123                    }
12124                }
12125            }
12126            self.apply_outbox_op(op)?;
12127        }
12128        Ok(())
12129    }
12130
12131    fn apply_outbox_op(&self, op: &OutboxOp) -> Result<(), String> {
12132        let Some(table) = self.schema.table(&op.table) else {
12133            return Ok(());
12134        };
12135        let visible = visible_table(&table.name);
12136        if !op.upsert {
12137            let sql = format!("DELETE FROM {visible} WHERE {}", row_id_predicate(table));
12138            self.conn
12139                .prepare_cached(&sql)
12140                .and_then(|mut statement| statement.execute(rusqlite::params![op.row_id]))
12141                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12142            return Ok(());
12143        }
12144        // §7.1: an insert-intent operation that lacks a non-nullable column
12145        // cannot encode; it stays invisible until the send-time prepass drops
12146        // it as sync.outbox_incompatible (§7.4.4).
12147        let Some(values) = op.presented_values(table) else {
12148            return Ok(());
12149        };
12150        // §7.1: the overlay applies the operation's PRESENT columns
12151        // over the current local row. A partial operation over an
12152        // absent local row leaves it absent — the server answers it
12153        // with sync.row_deleted or sync.row_missing (§6.2). An
12154        // insert-intent operation presents every column.
12155        let full = table
12156            .columns
12157            .iter()
12158            .all(|column| values.contains_key(&column.name));
12159        let local = self.visible_row(table, &op.row_id)?;
12160        if local.is_none() && !full {
12161            return Ok(());
12162        }
12163        let mut row: Row = Vec::with_capacity(table.columns.len());
12164        for (index, column) in table.columns.iter().enumerate() {
12165            let incoming = match values.get(&column.name) {
12166                Some(raw) => json_to_column_value(
12167                    if raw.get("$bytes").is_some()
12168                        && table
12169                            .encrypted_columns
12170                            .iter()
12171                            .any(|encrypted| encrypted.index == index)
12172                    {
12173                        &table.wire_columns[index]
12174                    } else {
12175                        column
12176                    },
12177                    Some(raw),
12178                ),
12179                None => Ok(local
12180                    .as_ref()
12181                    .and_then(|(values, _)| values.get(index).cloned())
12182                    .flatten()),
12183            };
12184            row.push(incoming.map_err(|_| {
12185                "sync.local_corrupt: persisted optimistic row value is invalid".to_owned()
12186            })?);
12187        }
12188        let version = local.as_ref().map_or(-1, |(_, version)| *version);
12189        self.write_row(&visible, &table.name, &row, version, None)
12190            .map(|_| ())
12191            .map_err(|error| {
12192                if error.starts_with("UNIQUE constraint failed:") {
12193                    "sync.constraint_violation: local write violates a unique constraint".to_owned()
12194                } else {
12195                    error
12196                }
12197            })
12198    }
12199
12200    /// Whether the row is present in the overlay. Existence reads only the
12201    /// key: locked encrypted values stay opaque, and decoding the complete row
12202    /// would reject a valid plain write.
12203    fn visible_row_exists(&self, table: &TableSchema, row_id: &str) -> Result<bool, String> {
12204        self.conn
12205            .query_row(
12206                &format!(
12207                    "SELECT EXISTS(SELECT 1 FROM {} WHERE {})",
12208                    visible_table(&table.name),
12209                    row_id_predicate(table)
12210                ),
12211                rusqlite::params![row_id],
12212                |row| row.get(0),
12213            )
12214            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
12215    }
12216
12217    /// §5.11: a sealed row is read-only; a write could otherwise send NULL
12218    /// over ciphertext this device cannot see.
12219    fn refuse_sealed_row(&self, table: &TableSchema, row_id: &str) -> Result<(), ClientError> {
12220        if !table.has_encrypted_columns() {
12221            return Ok(());
12222        }
12223        let key_id: Option<String> = self
12224            .conn
12225            .query_row(
12226                &format!(
12227                    "SELECT \"_sync_sealed_key\" FROM {} WHERE {}",
12228                    visible_table(&table.name),
12229                    row_id_predicate(table)
12230                ),
12231                rusqlite::params![row_id],
12232                |row| row.get(0),
12233            )
12234            .optional()
12235            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
12236            .flatten();
12237        match key_id {
12238            None => Ok(()),
12239            Some(key_id) => Err(ClientError {
12240                code: "client.encryption_key_missing".to_owned(),
12241                message: "the row is sealed under a key this device does not hold".to_owned(),
12242                details: Some(json!({ "table": table.name, "keyId": key_id })),
12243                retryable: false,
12244            }),
12245        }
12246    }
12247
12248    /// §5.11 reveal: decrypt every sealed base row whose envelope keys the
12249    /// keyring now holds into its columns and clear both reserved columns,
12250    /// one change batch per table. `client.decrypt_failed` fails the caller.
12251    fn reveal_sealed_rows(&mut self) -> Result<(), TransportError> {
12252        let storage = |message: String| TransportError::new("storage.failed", message);
12253        let tables: Vec<TableSchema> = self
12254            .schema
12255            .tables
12256            .iter()
12257            .filter(|table| table.has_encrypted_columns())
12258            .cloned()
12259            .collect();
12260        for table in &tables {
12261            let base = base_table(&table.name);
12262            let pk = quote_ident(&table.primary_key);
12263            let sealed: Vec<(SqlValue, i64, String)> = self
12264                .conn
12265                .prepare_cached(&format!(
12266                    "SELECT {pk}, \"_syncular_version\", \"_sync_sealed\" FROM {base} WHERE \"_sync_sealed_key\" IS NOT NULL"
12267                ))
12268                .and_then(|mut statement| {
12269                    statement
12270                        .query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?
12271                        .collect()
12272                })
12273                .map_err(|error| storage(Self::sqlite_failure(&self.storage_failure, error)))?;
12274            let mut revealed = Vec::new();
12275            for (key, version, envelopes) in sealed {
12276                if let Some(row) =
12277                    crate::values::reveal_sealed_row(table, &envelopes, &self.encryption)?
12278                {
12279                    revealed.push((key, version, row));
12280                }
12281            }
12282            if revealed.is_empty() {
12283                continue;
12284            }
12285            self.begin_observation("syncular_reveal").map_err(storage)?;
12286            let outcome = (|| {
12287                let assignments = table
12288                    .encrypted_columns
12289                    .iter()
12290                    .map(|enc| format!("{}=?", quote_ident(&table.columns[enc.index].name)))
12291                    .collect::<Vec<_>>()
12292                    .join(",");
12293                let mut statement = self
12294                    .conn
12295                    .prepare_cached(&format!(
12296                        "UPDATE {base} SET {assignments},\"_sync_sealed_key\"=NULL,\"_sync_sealed\"=NULL WHERE {pk}=? AND \"_syncular_version\"=?"
12297                    ))
12298                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12299                for (key, version, row) in &revealed {
12300                    let mut params = table
12301                        .encrypted_columns
12302                        .iter()
12303                        .map(|enc| owned_sql_value(RowParam::Cell(&row[enc.index])))
12304                        .collect::<Result<Vec<_>, _>>()?;
12305                    params.push(key.clone());
12306                    params.push(SqlValue::Integer(*version));
12307                    statement
12308                        .execute(rusqlite::params_from_iter(params))
12309                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12310                }
12311                drop(statement);
12312                self.overlay_dirty.table(&table.name);
12313                self.rebuild_overlay()?;
12314                let mut batch = ChangeAccumulator::default();
12315                batch.table(&table.name);
12316                self.finish_observation("syncular_reveal", batch)
12317            })();
12318            if outcome.is_err() {
12319                self.rollback_observation("syncular_reveal");
12320            }
12321            outcome.map_err(storage)?;
12322        }
12323        Ok(())
12324    }
12325
12326    /// The visible (optimistic) row's values plus version, or `None` when the
12327    /// row is absent from the overlay.
12328    fn visible_row(&self, table: &TableSchema, row_id: &str) -> Result<Option<(Row, i64)>, String> {
12329        self.stored_row(table, row_id, false)
12330    }
12331
12332    fn stored_row(
12333        &self,
12334        table: &TableSchema,
12335        row_id: &str,
12336        base: bool,
12337    ) -> Result<Option<(Row, i64)>, String> {
12338        let sql = format!(
12339            "SELECT * FROM {} WHERE {}",
12340            if base {
12341                base_table(&table.name)
12342            } else {
12343                visible_table(&table.name)
12344            },
12345            row_id_predicate(table)
12346        );
12347        let mut stmt = self
12348            .conn
12349            .prepare_cached(&sql)
12350            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12351        let mut rows = stmt
12352            .query(rusqlite::params![row_id])
12353            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12354        let Some(row) = rows
12355            .next()
12356            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
12357        else {
12358            return Ok(None);
12359        };
12360        let mut values = Vec::with_capacity(table.columns.len());
12361        for (index, column) in table.columns.iter().enumerate() {
12362            let raw = row
12363                .get_ref(index)
12364                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12365            if let rusqlite::types::ValueRef::Blob(bytes) = raw {
12366                if table
12367                    .encrypted_columns
12368                    .iter()
12369                    .any(|encrypted| encrypted.index == index)
12370                {
12371                    values.push(Some(ColumnValue::Bytes(bytes.to_vec())));
12372                    continue;
12373                }
12374            }
12375            let json = sql_ref_to_json(column, raw);
12376            values.push(json_to_column_value(column, Some(&json)).map_err(|_| {
12377                "sync.local_corrupt: persisted local row value is invalid".to_owned()
12378            })?);
12379        }
12380        let version: i64 = row
12381            .get(table.columns.len())
12382            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12383        Ok(Some((values, version)))
12384    }
12385
12386    // -- realtime (§8) ---------------------------------------------------------------
12387
12388    /// §8.8: the configured realtime policy.
12389    #[must_use]
12390    pub fn realtime_policy(&self) -> RealtimePolicy {
12391        self.realtime_policy
12392    }
12393
12394    /// §8.8: the explicit realtime availability state.
12395    #[must_use]
12396    pub fn realtime_state(&self) -> RealtimeState {
12397        self.realtime_state
12398    }
12399
12400    /// §8.8: set the realtime policy. Refused while the socket is connected:
12401    /// a policy change never silently re-routes an ownership state.
12402    pub fn set_realtime_policy(&mut self, policy: RealtimePolicy) -> Result<(), String> {
12403        if self.realtime_state == RealtimeState::Connected && policy != self.realtime_policy {
12404            return Err(
12405                "sync.invalid_request: disconnect realtime before changing the realtime policy"
12406                    .to_owned(),
12407            );
12408        }
12409        self.realtime_policy = policy;
12410        match policy {
12411            RealtimePolicy::Off => self.set_realtime_state(RealtimeState::Disabled, None),
12412            RealtimePolicy::Required | RealtimePolicy::Optional
12413                if self.realtime_state == RealtimeState::Disabled =>
12414            {
12415                self.set_realtime_state(RealtimeState::Disconnected, None);
12416            }
12417            RealtimePolicy::Required | RealtimePolicy::Optional => {}
12418        }
12419        Ok(())
12420    }
12421
12422    /// Record an availability transition, keeping the reason code bounded and
12423    /// code-like (§7.6) and clearing it where it cannot apply.
12424    fn set_realtime_state(&mut self, state: RealtimeState, reason_code: Option<&str>) {
12425        self.realtime_state = state;
12426        self.realtime_reason_code = reason_code.map(Self::diagnostic_code);
12427        if matches!(state, RealtimeState::Connected | RealtimeState::Disabled) {
12428            self.realtime_reason_code = None;
12429            self.realtime_retry_delay_ms = None;
12430        }
12431    }
12432
12433    #[must_use]
12434    fn realtime_connected(&self) -> bool {
12435        self.realtime_state == RealtimeState::Connected
12436    }
12437
12438    pub fn connect_realtime(&mut self, transport: &mut dyn Transport) -> Result<(), String> {
12439        if !self.transport_enabled {
12440            return Err("sync.offline: transport gate is closed".into());
12441        }
12442        if self.realtime_policy == RealtimePolicy::Off {
12443            return Err(
12444                "sync.invalid_request: realtime is off; realtime connect is refused".to_owned(),
12445            );
12446        }
12447        if self.realtime_connected() {
12448            return Ok(());
12449        }
12450        self.realtime_state = RealtimeState::Connecting;
12451        match transport.realtime_connect_for_client(&self.client_id) {
12452            Ok(()) => {
12453                self.set_realtime_state(RealtimeState::Connected, None);
12454                Ok(())
12455            }
12456            Err(error) => {
12457                self.set_realtime_state(RealtimeState::Refused, Some(&error.code));
12458                Err(format!("{}: {}", error.code, error.message))
12459            }
12460        }
12461    }
12462
12463    pub fn disconnect_realtime(&mut self, transport: &mut dyn Transport) {
12464        self.cancel_sync_round();
12465        // A deliberately disconnected or policy-disabled client has nothing
12466        // to release; a `lost` socket still does (the host owns the handle).
12467        if self.realtime_state == RealtimeState::Disconnected
12468            || self.realtime_state == RealtimeState::Disabled
12469        {
12470            return;
12471        }
12472        let _ = transport.realtime_close();
12473        self.set_realtime_state(
12474            if self.realtime_policy == RealtimePolicy::Off {
12475                RealtimeState::Disabled
12476            } else {
12477                RealtimeState::Disconnected
12478            },
12479            None,
12480        );
12481        self.presence.clear(); // §8.6.1: presence is per-connection
12482    }
12483
12484    /// §8.8: the host observed the socket end without disconnecting it (a
12485    /// peer close, an I/O error, a failed send; the native transport reports
12486    /// these as `Inbound::Disconnected`). Releases the transport, moves a
12487    /// `Connected` state to `Lost` with the transport's code as the reason, and schedules
12488    /// one background retry intent so the host reconnects and catches up.
12489    pub fn realtime_lost(&mut self, transport: &mut dyn Transport, error: &TransportError) {
12490        if self.realtime_state != RealtimeState::Connected {
12491            return;
12492        }
12493        self.cancel_sync_round();
12494        let _ = transport.realtime_close();
12495        self.set_realtime_state(RealtimeState::Lost, Some(&error.code));
12496        self.realtime_retry_delay_ms = Some(self.schedule_background_retry());
12497        self.presence.clear();
12498    }
12499
12500    /// §8.6.2: publish (or clear, `doc: None`) this client's presence
12501    /// document for `scope_key`. Requires a live socket; the document is
12502    /// ephemeral (lost on disconnect). Authorization is the connection's
12503    /// registration (§8.6.3) — an unheld key is rejected loudly by the
12504    /// server with `presence.forbidden`.
12505    pub fn set_presence(
12506        &mut self,
12507        transport: &mut dyn Transport,
12508        scope_key: &str,
12509        doc: Option<&Value>,
12510    ) -> Result<(), String> {
12511        if !self.transport_enabled {
12512            return Err("sync.offline: transport gate is closed".into());
12513        }
12514        if !self.realtime_connected() {
12515            return Err("setPresence requires a connected realtime socket (§8.6)".to_string());
12516        }
12517        let text = encode_presence_publish(scope_key, doc);
12518        transport
12519            .realtime_send(&text)
12520            .map_err(|e| format!("{}: {}", e.code, e.message))
12521    }
12522
12523    /// §8.6: the peers currently present on a scope key (ephemeral).
12524    pub fn presence(&self, scope_key: &str) -> Vec<PresencePeer> {
12525        self.presence
12526            .get(scope_key)
12527            .map(|peers| peers.values().cloned().collect())
12528            .unwrap_or_default()
12529    }
12530
12531    /// §8.6 apply an inbound presence fanout to the local map.
12532    fn apply_presence(
12533        &mut self,
12534        scope_key: String,
12535        kind: Option<PresenceKind>,
12536        actor_id: Option<String>,
12537        client_id: Option<String>,
12538        doc: Option<Value>,
12539        error: Option<String>,
12540    ) {
12541        // A refused publish (§8.6.2) changes no peer; the native host surfaces
12542        // it as a `presence` event carrying the server's `error` code.
12543        if error.is_some() {
12544            return;
12545        }
12546        let (Some(kind), Some(actor_id), Some(client_id)) = (kind, actor_id, client_id) else {
12547            return;
12548        };
12549        let peer_key = format!("{actor_id} {client_id}");
12550        match kind {
12551            PresenceKind::Leave => {
12552                if let Some(peers) = self.presence.get_mut(&scope_key) {
12553                    peers.remove(&peer_key);
12554                    if peers.is_empty() {
12555                        self.presence.remove(&scope_key);
12556                    }
12557                }
12558            }
12559            _ => {
12560                let doc = match doc {
12561                    Some(Value::Object(_)) => doc.unwrap(),
12562                    _ => return,
12563                };
12564                self.presence.entry(scope_key).or_default().insert(
12565                    peer_key,
12566                    PresencePeer {
12567                        actor_id,
12568                        client_id,
12569                        doc,
12570                    },
12571                );
12572            }
12573        }
12574    }
12575
12576    /// Inbound JSON control message (§8.1). Unknown events are tolerated.
12577    pub fn on_realtime_text(&mut self, text: &str) {
12578        if self.stopped || !self.transport_enabled || self.security_preflight {
12579            return;
12580        }
12581        match parse_control(text) {
12582            Ok(ControlMessage::Hello { requires_sync, .. }) => {
12583                if requires_sync {
12584                    // §8.1: pull before trusting the socket for continuity.
12585                    self.set_sync_needed(true, true);
12586                }
12587            }
12588            Ok(ControlMessage::Presence {
12589                scope_key,
12590                kind,
12591                actor_id,
12592                client_id,
12593                doc,
12594                error,
12595                ..
12596            }) => {
12597                self.apply_presence(scope_key, kind, actor_id, client_id, doc, error);
12598            }
12599            Ok(ControlMessage::Wake { .. }) => {
12600                // §8.3: any wake-up means "run a pull soon", never data.
12601                self.set_sync_needed(true, true);
12602            }
12603            _ => {}
12604        }
12605    }
12606
12607    /// Inbound binary delta: a complete SSP2 response (§8.2), applied like
12608    /// a pull response per section; an unapplied delta is a wake-up.
12609    /// Mailbox hosts send durable acknowledgements on their I/O executor.
12610    pub fn on_realtime_binary_queued(&mut self, bytes: &[u8]) -> Vec<String> {
12611        let mut transport = crate::round::DownloadResults::default();
12612        self.on_realtime_binary(&mut transport, bytes);
12613        transport.controls
12614    }
12615
12616    /// §8.2: a delta applies exactly like a live section and sets the replica
12617    /// cursor to its `throughSeq`; one at or below the replica cursor is a
12618    /// duplicate. A delta the client does not apply (no live unit, a status
12619    /// other than `active`, a decode or apply failure) is a drop and raises
12620    /// sync-needed.
12621    pub fn on_realtime_binary(&mut self, transport: &mut dyn Transport, bytes: &[u8]) {
12622        if self.stopped || !self.transport_enabled || self.security_preflight {
12623            return;
12624        }
12625        #[cfg(feature = "bench-internals")]
12626        let decode_phase = self.benchmark_phases.start(Phase::ResponseDecode);
12627        let message = match decode_message(bytes) {
12628            Ok(m) if m.msg_kind == MsgKind::Response => m,
12629            _ => {
12630                self.set_sync_needed(true, true);
12631                return;
12632            }
12633        };
12634        #[cfg(feature = "bench-internals")]
12635        drop(decode_phase);
12636        // §8.2: a delta's header means what a pull response's header means. A
12637        // schema floor (§1.6) is recorded, stops syncing and applies nothing.
12638        if let Some(Frame::RespHeader {
12639            required_schema_version: Some(required),
12640            latest_schema_version,
12641            ..
12642        }) = message.frames.first()
12643        {
12644            let floor = SchemaFloor {
12645                required_schema_version: Some(*required),
12646                latest_schema_version: *latest_schema_version,
12647            };
12648            if self.set_schema_floor(Some(floor)).is_err() {
12649                self.set_sync_needed(true, true);
12650            }
12651            return;
12652        }
12653        let through = message.frames.iter().find_map(|frame| match frame {
12654            Frame::LiveEnd { through_seq, .. } => Some(*through_seq),
12655            _ => None,
12656        });
12657        let epoch = self.get_meta(LOG_EPOCH_KEY).ok().flatten();
12658        let mut dropped = !matches!(message.frames.first(), Some(Frame::RespHeader {
12659                reset_required: false,
12660                log_epoch,
12661                ..
12662            }) if Some(log_epoch) == epoch.as_ref());
12663        let mut applied: Option<i64> = None;
12664        dropped |= self.begin_coalesced_apply().is_err();
12665        let mut receivers: Option<Vec<UnitRecord>> = None;
12666        for frame in message.frames {
12667            if dropped {
12668                break;
12669            }
12670            match frame {
12671                Frame::LiveStart { status, .. } => {
12672                    let Ok(cursor) = self.stored(replica_cursor(&self.conn)) else {
12673                        dropped = true;
12674                        break;
12675                    };
12676                    if status != LiveStatus::Active || cursor < 0 {
12677                        dropped = true;
12678                    } else if !through.is_some_and(|through| through <= cursor) {
12679                        // A catching-up unit receives no delta (§8.2).
12680                        receivers = self.stored(load_units(&self.conn)).ok().map(|units| {
12681                            units
12682                                .into_iter()
12683                                .filter(|unit| {
12684                                    unit.status == UnitStatus::Active
12685                                        && unit.echo.is_some()
12686                                        && unit.cursor.is_none()
12687                                })
12688                                .collect()
12689                        });
12690                        dropped = receivers.is_none();
12691                    }
12692                }
12693                Frame::Commit {
12694                    commit_seq,
12695                    tables,
12696                    changes,
12697                    ..
12698                } => {
12699                    let Some(receivers) = receivers.clone() else {
12700                        continue;
12701                    };
12702                    dropped = self
12703                        .apply_live_commit(
12704                            &receivers,
12705                            &tables,
12706                            changes,
12707                            commit_seq,
12708                            AppliedServerCommitSource::Delta,
12709                        )
12710                        .is_err();
12711                }
12712                Frame::LiveEnd { through_seq, .. } if receivers.is_some() => {
12713                    dropped = self
12714                        .set_meta(REPLICA_CURSOR_KEY, &through_seq.to_string())
12715                        .is_err();
12716                    applied = Some(through_seq);
12717                }
12718                Frame::Error { .. } => dropped = true,
12719                _ => {}
12720            }
12721        }
12722        // §1.4 rule 4: the ack follows the COMMIT. A failed COMMIT restored
12723        // the replica cursor, so the delta counts as a drop.
12724        if self.finish_coalesced_apply().is_err() || dropped {
12725            applied = None;
12726            dropped = true;
12727        }
12728        if let Some(cursor) = applied {
12729            // §8.2 ack point: the delta's throughSeq.
12730            let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
12731            let _ = transport.realtime_send(&ack);
12732        }
12733        if dropped {
12734            self.set_sync_needed(true, true);
12735        }
12736    }
12737
12738    /// §8.2 ack point after a pull round on a live connection: the replica
12739    /// cursor while it is at least `0`.
12740    fn ack_after_pull(&mut self, transport: &mut dyn Transport) {
12741        if !self.realtime_connected() {
12742            return;
12743        }
12744        if let Ok(cursor @ 0..) = self.stored(replica_cursor(&self.conn)) {
12745            let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
12746            let _ = transport.realtime_send(&ack);
12747        }
12748    }
12749}
12750
12751#[cfg(test)]
12752mod previous_version_wiring_tests;
12753
12754#[cfg(test)]
12755mod identity_tests;
12756
12757#[cfg(test)]
12758mod insert_intent_tests;
12759
12760#[cfg(test)]
12761mod robustness_tests;
12762
12763#[cfg(test)]
12764mod range_image_tests;