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, PendingCommit, 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, UnitRestriction,
48    UnitScopes, UnitStatus, 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.4.3: table name → generation, persisted with the declaration evidence.
97const TABLE_GENERATIONS_KEY: &str = "localTableGenerations";
98/// §7.1: the identity of the outbox sequence.
99const OUTBOX_ID_KEY: &str = "outboxId";
100const CLIENT_ID_KEY: &str = "clientId";
101const LEASE_STATE_KEY: &str = "leaseState";
102const SCHEMA_FLOOR_KEY: &str = "schemaFloor";
103pub(crate) const LOG_EPOCH_KEY: &str = "logEpoch";
104/// Persisted fail-closed quarantine marker: present while a security preflight
105/// is pending and `activateSecurity` has yet to run. Storing it in the replica
106/// keeps the gate with the data it protects, so a rebuilt host handle reopening
107/// the same file returns in preflight even though its in-memory state is fresh.
108const SECURITY_PREFLIGHT_PENDING_KEY: &str = "securityPreflightPending";
109const LOCAL_REBOOTSTRAP_RECEIPT_VERSION: u8 = 2;
110const MAX_JS_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
111/// §7.4.4 client-local code: a pending outbox commit cannot re-encode under
112/// the new schema after a bump. Never a wire code (§10.3).
113const OUTBOX_INCOMPATIBLE_CODE: &str = "sync.outbox_incompatible";
114/// §5.11 client-local code: an encode at the push seam resolved no usable key
115/// id or named an unknown key. Never a wire code (§10.3).
116const ENCRYPT_FAILED_CODE: &str = "client.encrypt_failed";
117const INVALID_REQUEST_CODE: &str = "sync.invalid_request:";
118/// §7.4.4: static text for a persisted commit the current codec refuses.
119const LEGACY_VALUE_REFUSAL_MESSAGE: &str =
120    "the persisted commit carries values the current codec refuses";
121/// §7.4.4: bounded reason on every intrinsic value drop.
122const INVALID_STORED_VALUES_REASON: &str = "invalid_stored_values";
123/// §7.2.2: an outcome with a pending decision accepts no other resolution.
124const REPLACEMENT_PENDING: &str =
125    "client.replacement_pending: the outcome has a pending replacement";
126/// §7.2.2 client-local code: a pending replacement was not written.
127const REPLACEMENT_REFUSED_CODE: &str = "sync.replacement_refused";
128
129#[derive(Debug, Serialize, Deserialize)]
130#[serde(rename_all = "camelCase", deny_unknown_fields)]
131struct PersistedLocalDataRebootstrapReceipt {
132    version: u8,
133    retained_commits: u64,
134    reset_subscriptions: u64,
135}
136
137fn invalid_local_rebootstrap_receipt() -> String {
138    "sync.local_corrupt: persisted local rebootstrap receipt is invalid".to_owned()
139}
140
141fn encode_local_rebootstrap_receipt(
142    retained_commits: usize,
143    reset_subscriptions: usize,
144) -> Result<String, String> {
145    let retained_commits =
146        u64::try_from(retained_commits).map_err(|_| invalid_local_rebootstrap_receipt())?;
147    let reset_subscriptions =
148        u64::try_from(reset_subscriptions).map_err(|_| invalid_local_rebootstrap_receipt())?;
149    if retained_commits > MAX_JS_SAFE_INTEGER || reset_subscriptions > MAX_JS_SAFE_INTEGER {
150        return Err(invalid_local_rebootstrap_receipt());
151    }
152    serde_json::to_string(&PersistedLocalDataRebootstrapReceipt {
153        version: LOCAL_REBOOTSTRAP_RECEIPT_VERSION,
154        retained_commits,
155        reset_subscriptions,
156    })
157    .map_err(|_| invalid_local_rebootstrap_receipt())
158}
159
160fn decode_local_rebootstrap_receipt(value: &str) -> Result<(usize, usize), String> {
161    // Pre-0.15.36 markers proved application but did not retain the receipt.
162    if value == "v1" {
163        return Ok((0, 0));
164    }
165    let receipt: PersistedLocalDataRebootstrapReceipt =
166        serde_json::from_str(value).map_err(|_| invalid_local_rebootstrap_receipt())?;
167    if receipt.version != LOCAL_REBOOTSTRAP_RECEIPT_VERSION
168        || receipt.retained_commits > MAX_JS_SAFE_INTEGER
169        || receipt.reset_subscriptions > MAX_JS_SAFE_INTEGER
170    {
171        return Err(invalid_local_rebootstrap_receipt());
172    }
173    Ok((
174        usize::try_from(receipt.retained_commits)
175            .map_err(|_| invalid_local_rebootstrap_receipt())?,
176        usize::try_from(receipt.reset_subscriptions)
177            .map_err(|_| invalid_local_rebootstrap_receipt())?,
178    ))
179}
180
181#[cfg(test)]
182mod observation_tests;
183
184/// Internal state for hosts that perform network I/O outside the client owner.
185#[doc(hidden)]
186#[derive(Clone)]
187pub struct CurrentBasePreparation {
188    client_commit_id: String,
189    sequence: i64,
190    /// §7.2.2: the pending replacement a drive evaluates; `None` for
191    /// `proveCurrentBase`.
192    replacement: Option<String>,
193    units: Vec<UnitRecord>,
194    transport_epoch: u64,
195    registration_epoch: u64,
196    security_epoch: u64,
197}
198
199#[cfg(test)]
200mod units_tests;
201
202#[cfg(test)]
203mod replace_outcome_tests;
204
205#[derive(Debug, Clone)]
206struct OutboxOp {
207    upsert: bool,
208    table: String,
209    row_id: String,
210    base_version: Option<i64>,
211    /// Schema-agnostic local form (§0): driver JSON values, encoded with
212    /// the current codec at send time. A key's presence IS the §6.1 sparse
213    /// presence set — both the overlay and the wire payload derive from it.
214    values: Option<Map<String, Value>>,
215    /// §7.1 insert intent: `mutate` recorded this upsert while the row was
216    /// absent from the visible replica. Replay and send-time encoding present
217    /// every current-schema column; a column `values` lacks is NULL.
218    insert: bool,
219}
220
221impl OutboxOp {
222    /// The values this upsert presents under the current `table` (§7.1). An
223    /// insert-intent operation presents every column, a missing one as NULL;
224    /// `None` when a missing column is non-nullable, which leaves the commit
225    /// unencodable (§7.4.4), or when the operation carries no values.
226    fn presented_values(&self, table: &TableSchema) -> Option<Cow<'_, Map<String, Value>>> {
227        let values = self.values.as_ref()?;
228        if !self.insert || table.columns.iter().all(|c| values.contains_key(&c.name)) {
229            return Some(Cow::Borrowed(values));
230        }
231        full_row_values(table, values.clone()).ok().map(Cow::Owned)
232    }
233}
234
235impl From<CommitOperation> for OutboxOp {
236    fn from(operation: CommitOperation) -> Self {
237        Self {
238            upsert: operation.op == "upsert",
239            table: operation.table,
240            row_id: operation.row_id,
241            base_version: operation.base_version,
242            values: operation.values,
243            insert: operation.insert,
244        }
245    }
246}
247
248/// §7.5 static authoring refusal; the table and column travel in details.
249fn invalid_authoring(message: &str, details: Value) -> ClientError {
250    ClientError {
251        code: "sync.invalid_request".to_owned(),
252        message: message.to_owned(),
253        details: Some(details),
254        retryable: false,
255    }
256}
257
258/// §7.1 chained base: `later` repeats `earlier`'s positive base on the same
259/// row and presents only columns `earlier` presents.
260fn chains_on(earlier: &OutboxOp, later: &OutboxOp) -> bool {
261    // Only an upsert carries values, and it always carries its primary key.
262    earlier.row_id == later.row_id
263        && earlier.table == later.table
264        && later.base_version.is_some_and(|base| base > 0)
265        && earlier.base_version == later.base_version
266        && later.values.as_ref().is_some_and(|values| {
267            values.keys().all(|column| {
268                earlier
269                    .values
270                    .as_ref()
271                    .is_some_and(|earlier| earlier.contains_key(column))
272            })
273        })
274}
275
276impl From<&OutboxOp> for CommitOperation {
277    fn from(operation: &OutboxOp) -> Self {
278        Self {
279            table: operation.table.clone(),
280            row_id: operation.row_id.clone(),
281            op: if operation.upsert { "upsert" } else { "delete" }.to_owned(),
282            base_version: operation.base_version,
283            values: operation.values.clone(),
284            insert: operation.insert,
285        }
286    }
287}
288
289#[derive(Debug, Clone)]
290struct OutboxCommit {
291    client_commit_id: String,
292    ops: Vec<OutboxOp>,
293}
294
295/// One commit's `(table, value keys, insert intent)` per upsert operation — the classification
296/// shape the §7.4.4 send-time drop and the RFC 0005 D6 audit share, so the two
297/// can never disagree about which commits cannot re-encode.
298fn commit_audit_operations(commit: &OutboxCommit) -> Vec<(&str, Vec<&str>, bool)> {
299    commit
300        .ops
301        .iter()
302        .filter(|operation| operation.upsert)
303        .map(|operation| {
304            (
305                operation.table.as_str(),
306                operation
307                    .values
308                    .as_ref()
309                    .map(|values| values.keys().map(String::as_str).collect())
310                    .unwrap_or_default(),
311                operation.insert,
312            )
313        })
314        .collect()
315}
316
317type FailedCommit = (OutboxCommit, Map<String, Value>);
318
319#[derive(Debug, Clone)]
320struct CompiledLocalDataPurgeTarget {
321    table: String,
322    selectors: Vec<(String, Vec<String>)>,
323}
324
325struct StoredCommitOutcomeRow {
326    sequence: i64,
327    client_commit_id: String,
328    status: String,
329    recorded_at_ms: i64,
330    results_json: String,
331    operations_json: Option<String>,
332    resolution: String,
333    resolved_at_ms: Option<i64>,
334    replacement_client_commit_id: Option<String>,
335}
336
337impl StoredCommitOutcomeRow {
338    fn from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<Self> {
339        Ok(Self {
340            sequence: row.get(0)?,
341            client_commit_id: row.get(1)?,
342            status: row.get(2)?,
343            recorded_at_ms: row.get(3)?,
344            results_json: row.get(4)?,
345            operations_json: row.get(5)?,
346            resolution: row.get(6)?,
347            resolved_at_ms: row.get(7)?,
348            replacement_client_commit_id: row.get(8)?,
349        })
350    }
351}
352
353/// Section outcome distinguishing the §5.6 unit-local fail-closed
354/// path from a round-aborting failure (§1.4 rule 5).
355/// §4.4 a unit section's `SUB_START`.
356struct SectionStart {
357    id: String,
358    status: SubStatus,
359    reason_code: String,
360    bootstrap: bool,
361    fenced: Vec<FencedRecord>,
362}
363
364enum SectionError {
365    FailClosed,
366    /// §5.5: the server refused a segment with `sync.forbidden`.
367    Refused,
368    /// §5.3 client memory: the round deferred this image's body to a later
369    /// pull of the same resume token.
370    Deferred,
371    Abort(String, String),
372    Transport(TransportError),
373}
374
375#[derive(Debug)]
376pub(crate) struct RequestMeta {
377    pushed_ids: Vec<String>,
378    /// Hex of the registration digest this pull carried; the server stores
379    /// that list once the round completes (§4.1).
380    registration_digest: String,
381    pub(crate) accept: u8,
382    /// §6.1 splitBatch: outbox commits held back from THIS request because
383    /// the running operation count reached the push cap — the next round
384    /// pushes them (`sync_needed` stays set while any remain).
385    deferred_commits: usize,
386    /// §5.6 applied-segment record per unit: segment id → rows applied at
387    /// the unit's current cursor and token.
388    pub(crate) applied: BTreeMap<String, BTreeMap<String, i64>>,
389    /// §5.3 client memory: (unit, segment id) of the first image whose body
390    /// the round did not fetch because the batch already holds two images.
391    /// That unit's section stops there without persisting `SUB_END`.
392    pub(crate) deferred: BTreeSet<(String, String)>,
393}
394
395#[derive(Default)]
396struct ChangeAccumulator {
397    /// None means table-wide; Some is the exact scoped domain.
398    tables: BTreeMap<String, Option<BTreeSet<String>>>,
399    windows: BTreeMap<String, BTreeSet<String>>,
400    status: bool,
401    conflicts: bool,
402    rejections: bool,
403    outcomes: bool,
404}
405
406impl ChangeAccumulator {
407    fn table(&mut self, table: &str) {
408        self.tables.insert(table.to_owned(), None);
409    }
410
411    fn scope(&mut self, table: &str, key: String) {
412        match self.tables.get_mut(table) {
413            Some(None) => {}
414            Some(Some(keys)) => {
415                keys.insert(key);
416            }
417            None => {
418                self.tables
419                    .insert(table.to_owned(), Some(BTreeSet::from([key])));
420            }
421        }
422    }
423
424    fn window(&mut self, base_key: &str, value: &str) {
425        self.windows
426            .entry(base_key.to_owned())
427            .or_default()
428            .insert(value.to_owned());
429    }
430
431    fn touched(&self) -> bool {
432        !self.tables.is_empty()
433            || !self.windows.is_empty()
434            || self.status
435            || self.conflicts
436            || self.rejections
437            || self.outcomes
438    }
439}
440
441/// §6.1: the server caps total operations per request (reference default
442/// 500) and rejects the whole batch with `sync.too_many_operations`; the
443/// client "splits and retries". Splitting happens at build time: commits are
444/// included IN ORDER until the operation budget is spent, the rest wait for
445/// the next round.
446const PUSH_OPS_PER_REQUEST: usize = 500;
447const MAX_LOCAL_PURGE_TARGETS: usize = 64;
448const MAX_LOCAL_PURGE_SELECTORS: usize = 8;
449const MAX_LOCAL_PURGE_VALUES: usize = 128;
450const MAX_LOCAL_PURGE_VALUE_LENGTH: usize = 256;
451pub const SECURITY_PREFLIGHT_REQUIRED_CODE: &str = "client.security_preflight_required";
452
453/// Dirty visible tables; `None` means a whole-replica recovery/reset.
454struct OverlayDirty(RefCell<Option<BTreeSet<String>>>);
455
456impl OverlayDirty {
457    fn clean() -> Self {
458        Self(RefCell::new(Some(BTreeSet::new())))
459    }
460    fn get(&self) -> bool {
461        self.0
462            .borrow()
463            .as_ref()
464            .is_none_or(|tables| !tables.is_empty())
465    }
466    fn set(&self, dirty: bool) {
467        *self.0.borrow_mut() = if dirty { None } else { Some(BTreeSet::new()) };
468    }
469    fn table(&self, table: &str) {
470        if let Some(tables) = self.0.borrow_mut().as_mut() {
471            tables.insert(table.to_owned());
472        }
473    }
474    fn snapshot(&self) -> Option<BTreeSet<String>> {
475        self.0.borrow().clone()
476    }
477    fn restore(&self, tables: Option<BTreeSet<String>>) {
478        *self.0.borrow_mut() = tables;
479    }
480}
481
482/// A copy-on-write in-memory mirror: a [`Rollback`] shares it, and the first
483/// write after a capture copies it once.
484#[derive(Debug, Clone, Default)]
485struct Shared<T>(Arc<T>);
486
487impl<T> std::ops::Deref for Shared<T> {
488    type Target = T;
489    fn deref(&self) -> &T {
490        &self.0
491    }
492}
493
494impl<T: Clone> std::ops::DerefMut for Shared<T> {
495    fn deref_mut(&mut self) -> &mut T {
496        Arc::make_mut(&mut self.0)
497    }
498}
499
500impl<T> From<T> for Shared<T> {
501    fn from(value: T) -> Self {
502        Self(Arc::new(value))
503    }
504}
505
506/// The in-memory mirrors of durable state, captured before a local
507/// transaction and restored when it rolls back. Queues only grow inside a
508/// transaction, so their lengths suffice.
509#[derive(Debug, Clone)]
510struct Rollback {
511    outbox: Shared<Vec<Arc<OutboxCommit>>>,
512    failed_commits: Shared<Vec<FailedCommit>>,
513    conflicts: Shared<Vec<ConflictRecord>>,
514    rejections: Shared<Vec<RejectionRecord>>,
515    schema_floor: Option<SchemaFloor>,
516    lease_state: Option<LeaseState>,
517    stopped: bool,
518    upgrading: bool,
519    sync_needed: bool,
520    active_round: Option<(uuid::Uuid, i64, u64)>,
521    overlay_dirty: Option<BTreeSet<String>>,
522    change_queue: usize,
523    sync_intent_queue: usize,
524    last_change: Option<DiagnosticLastChange>,
525}
526
527pub struct SyncClient {
528    #[cfg(feature = "bench-internals")]
529    benchmark_phases: Recorder,
530    conn: Connection,
531    schema: ClientSchema,
532    client_id: String,
533    limits: ClientLimits,
534    outbox: Shared<Vec<Arc<OutboxCommit>>>,
535    failed_commits: Shared<Vec<FailedCommit>>,
536    retain_failed_commits: bool,
537    conflicts: Shared<Vec<ConflictRecord>>,
538    rejections: Shared<Vec<RejectionRecord>>,
539    schema_floor: Option<SchemaFloor>,
540    /// §7.3.5: the opaque auth-lease state (from LEASE frames + lease errors).
541    lease_state: Option<LeaseState>,
542    /// §1.6: the schema-floor response stops syncing until an upgrade.
543    stopped: bool,
544    /// §7.4.5: true while a schema-bump reset + first re-bootstrap is in flight.
545    upgrading: bool,
546    /// §8.4 coalesced sync-needed signal.
547    sync_needed: bool,
548    /// §8.8: how sync rounds treat the realtime binding, and its exact
549    /// availability state with the evidence behind a lost or refused one.
550    realtime_policy: RealtimePolicy,
551    realtime_state: RealtimeState,
552    realtime_reason_code: Option<String>,
553    realtime_retry_delay_ms: Option<u64>,
554    /// §8.6 presence: scopeKey → (`actorId clientId` peer key → peer).
555    presence: HashMap<String, HashMap<String, PresencePeer>>,
556    /// Client clock (epoch ms) for the §5.4 `urlExpiresAtMs` check and the
557    /// §7.8 drive deadline; the host may pin it and move the pinned value
558    /// (conformance runs on a virtual clock).
559    now_ms: Option<std::sync::Arc<std::sync::atomic::AtomicI64>>,
560    /// §5.11 client-side encryption keys (`keyId → key bytes`). Empty ⇒ E2EE
561    /// off. The encrypt/decrypt seam (`values.rs`) is compiled only under the
562    /// `e2ee` feature; without it, a schema with encrypted columns fails loud.
563    encryption: crate::values::EncryptionConfig,
564    /// Fail-closed host bootstrap gate. While set, command hosts permit only
565    /// status/lifecycle inspection and an exact authorized local purge.
566    security_preflight: bool,
567    security_epoch: u64,
568    transport_enabled: bool,
569    transport_epoch: u64,
570    /// Raised by every registration change; a current-base proof spanning
571    /// one reports missing coverage.
572    registration_epoch: u64,
573    /// RFC 0005 D2/D8: the previous-version capture config. `None` (default)
574    /// means the feature is off; the descriptor write and the container orphan
575    /// sweep still happen.
576    previous_version: Option<PreviousVersionContextConfig>,
577    /// Per-table primary-key upsert SQL, built once per (full table name) —
578    /// the row write path runs per row during bootstrap (§5.6), so the SQL
579    /// string (and, via `prepare_cached`, its compiled statement) is reused
580    /// instead of being rebuilt and re-prepared per row. Cleared on a §7.4.3
581    /// schema reset (the column lists may have changed).
582    insert_sql: RefCell<HashMap<String, String>>,
583    /// §7.1: reconcile only tables whose base/outbox changed. Whole-replica
584    /// reset and restart explicitly invalidate every table.
585    overlay_dirty: OverlayDirty,
586    // First SQLite failure of the current operation, before savepoint cleanup.
587    storage_failure: RefCell<Option<QueryReadFailure>>,
588    /// Test-only structural performance signal: response processing must not
589    /// turn a batch of acknowledgements into one full overlay rebuild each.
590    #[cfg(test)]
591    overlay_rebuild_count: Cell<usize>,
592    #[cfg(test)]
593    acknowledged_replay_count: Cell<usize>,
594    /// Test-only structural performance signal: outcome retention is enforced
595    /// once per response rather than once per acknowledgement.
596    #[cfg(test)]
597    outcome_prune_count: Cell<usize>,
598    /// Test-only pinned duration of every §5.3 image chunk, in ms.
599    #[cfg(test)]
600    image_chunk_ms: Cell<Option<f64>>,
601    /// Exact observer-transaction output drained by command/FFI hosts.
602    progress: ProgressObserver,
603    /// §7.6: random per core instance, never persisted or sent.
604    epoch: String,
605    change_queue: VecDeque<ClientChangeBatch>,
606    sync_intent_queue: VecDeque<SyncIntent>,
607    /// §8.7 `scopes` events received since the last drain.
608    scopes_changed: usize,
609    /// Explicit exponential retry policy for transient transport failures.
610    retry_delay_ms: u64,
611    /// §7.7: the background retry the current round scheduled, if any.
612    round_retry_delay_ms: Option<u64>,
613    /// §5.3: a table's next image chunk size, carried from one range image
614    /// of the table to the next.
615    image_chunk_rows: HashMap<String, u32>,
616    /// A round whose response never completed (§1.5): the client keeps its
617    /// code and reports it on every following request until a round receives a
618    /// complete, decodable response. The server already recorded the round, so
619    /// nothing else can tell it the round failed on this side.
620    round_failure: Option<String>,
621    /// The in-flight round: its id, `started_at_ms` and progress attempt.
622    active_round: Option<(uuid::Uuid, i64, u64)>,
623    last_round: Option<DiagnosticLastRound>,
624    last_change: Option<DiagnosticLastChange>,
625    /// §7.6: latest failed owned snapshot read per owner id, oldest first.
626    query_failures: Vec<DiagnosticQueryFailure>,
627    /// SPEC §1.4 rule 4: the open coalesced apply transaction of a response.
628    coalesced: Option<CoalescedApply>,
629    /// A coalesced apply transaction of the current response failed; every
630    /// later observation of that response fails until it ends.
631    coalesced_failure: Option<String>,
632}
633
634/// SPEC §1.4 rule 4: the frames and blocks of one response share one local
635/// write transaction of at most `COALESCED_APPLY_ROWS` rows. The in-memory
636/// state captured at its `BEGIN` is restored when its `COMMIT` fails.
637struct CoalescedApply {
638    rows: usize,
639    rollback: Rollback,
640}
641
642const COALESCED_APPLY_ROWS: usize = 1024;
643
644pub(crate) fn quote_ident(name: &str) -> String {
645    format!("\"{}\"", name.replace('"', "\"\""))
646}
647/// §7.4.1 `_syncular_meta` helpers. Free functions so RFC 0005's
648/// previous-version module reads and writes the SAME records as the client
649/// instead of growing a parallel meta layer.
650pub(crate) fn meta_get(conn: &Connection, key: &str) -> rusqlite::Result<Option<String>> {
651    conn.query_row(
652        "SELECT value FROM _syncular_meta WHERE key = ?1",
653        rusqlite::params![key],
654        |row| row.get::<_, String>(0),
655    )
656    .optional()
657}
658
659pub(crate) fn meta_set(conn: &Connection, key: &str, value: &str) -> rusqlite::Result<()> {
660    conn.execute(
661        "INSERT OR REPLACE INTO _syncular_meta (key, value) VALUES (?1, ?2)",
662        rusqlite::params![key, value],
663    )
664    .map(|_| ())
665}
666
667pub(crate) fn meta_delete(conn: &Connection, key: &str) -> rusqlite::Result<()> {
668    conn.execute(
669        "DELETE FROM _syncular_meta WHERE key = ?1",
670        rusqlite::params![key],
671    )
672    .map(|_| ())
673}
674
675/// Seek by the existing key while retaining the exact legacy text match.
676fn row_id_predicate(table: &TableSchema) -> String {
677    let key = quote_ident(&table.primary_key);
678    let text_match = format!("CAST({key} AS TEXT) = ?1");
679    match table.columns[table.pk_index].ty {
680        ColumnType::String | ColumnType::Json => {
681            format!("{key} = ?1 AND {text_match}")
682        }
683        // Native columns have no declared SQLite affinity. Match the stored
684        // integer bind type explicitly. Unary + removes expression affinity so
685        // SQLite can seek the typeless key; the text check preserves exact IDs.
686        ColumnType::Integer | ColumnType::Boolean => {
687            format!("{key} = +CAST(?1 AS INTEGER) AND {text_match}")
688        }
689        // REAL-to-text conversion can round distinct values to the same text.
690        // Narrowing those matches by numeric equality would change behavior.
691        _ => text_match,
692    }
693}
694
695/// §3.3/§4.8/§5.6 row ownership: rows whose local scope columns match
696/// `effective` and that no entry of `owners` matches. `owners` holds the
697/// pair scopes of every owner of the table (§3.3 row ownership); a scoped delete never removes a row one of them still covers.
698/// Scope values bind by the column's declared type, as `row_id_predicate`
699/// does. `Ok(None)` matches nothing (an empty map or value list); `Err(())`
700/// is a missing local scope-column mapping (the fail-closed case).
701fn local_scope_predicate(
702    table: &TableSchema,
703    effective: &[(String, Vec<String>)],
704    owners: &[Vec<(String, Vec<String>)>],
705) -> Result<Option<(String, Vec<SqlValue>)>, ()> {
706    if effective.is_empty() || effective.iter().any(|(_, values)| values.is_empty()) {
707        return Ok(None);
708    }
709    let column = |variable: &str| {
710        let name = table.scope_column(variable).ok_or(())?;
711        let column = table
712            .columns
713            .iter()
714            .find(|column| column.name == name)
715            .ok_or(())?;
716        Ok((quote_ident(name), column.ty == ColumnType::Integer))
717    };
718    let mut clauses = Vec::new();
719    let mut params = Vec::new();
720    for (variable, values) in effective {
721        let (key, integer) = column(variable)?;
722        let holes = vec!["?"; values.len()].join(", ");
723        clauses.push(if integer {
724            params.extend(values.iter().cloned().map(SqlValue::Text));
725            let seek = vec!["+CAST(? AS INTEGER)"; values.len()].join(", ");
726            format!("{key} IN ({seek}) AND CAST({key} AS TEXT) IN ({holes})")
727        } else {
728            format!("{key} IN ({holes})")
729        });
730        params.extend(values.iter().cloned().map(SqlValue::Text));
731    }
732    // Owners bind as one JSON parameter per variable set, so the statement
733    // keeps its size at any owner count; owners of one variable bind the
734    // union of their values. An owner holding other values of a variable
735    // `effective` names owns none of its rows and drops out. Values compare
736    // as text, the exact semantics of the effective clauses.
737    let mut groups: BTreeMap<Vec<&str>, Vec<Vec<&[String]>>> = BTreeMap::new();
738    for owner in owners {
739        if owner.is_empty()
740            || owner.iter().any(|(variable, values)| {
741                values.is_empty()
742                    || effective.iter().any(|(name, wanted)| {
743                        name == variable && wanted.iter().all(|value| !values.contains(value))
744                    })
745            })
746        {
747            continue;
748        }
749        let mut owner: Vec<_> = owner.iter().collect();
750        owner.sort_by(|a, b| a.0.cmp(&b.0));
751        groups
752            .entry(
753                owner
754                    .iter()
755                    .map(|(variable, _)| variable.as_str())
756                    .collect(),
757            )
758            .or_default()
759            .push(owner.iter().map(|(_, values)| values.as_slice()).collect());
760    }
761    let within = |variable: &str, list: &str| {
762        let (key, integer) = column(variable)?;
763        let key = if integer {
764            format!("CAST({key} AS TEXT)")
765        } else {
766            key
767        };
768        Ok(format!("{key} IN (SELECT value FROM json_each({list}))"))
769    };
770    for (variables, tuples) in groups {
771        if let [variable] = variables[..] {
772            let values: BTreeSet<&String> = tuples.iter().flatten().copied().flatten().collect();
773            params.push(SqlValue::Text(
774                Value::from_iter(values.into_iter().cloned()).to_string(),
775            ));
776            clauses.push(format!("NOT {}", within(variable, "?")?));
777        } else {
778            params.push(SqlValue::Text(
779                serde_json::to_string(&tuples).expect("owner tuples serialize"),
780            ));
781            let matches = variables
782                .iter()
783                .enumerate()
784                .map(|(index, variable)| within(variable, &format!("o.value,'$[{index}]'")))
785                .collect::<Result<Vec<_>, ()>>()?;
786            clauses.push(format!(
787                "NOT EXISTS (SELECT 1 FROM json_each(?) o WHERE {})",
788                matches.join(" AND ")
789            ));
790        }
791    }
792    Ok(Some((clauses.join(" AND "), params)))
793}
794
795/// [`local_scope_predicate`] over decoded row values (retained rows).
796fn owns_local_row(
797    table: &TableSchema,
798    effective: &[(String, Vec<String>)],
799    owners: &[Vec<(String, Vec<String>)>],
800    values: &Map<String, Value>,
801) -> bool {
802    let matches = |scopes: &[(String, Vec<String>)]| {
803        !scopes.is_empty()
804            && scopes.iter().all(|(variable, allowed)| {
805                table
806                    .scope_column(variable)
807                    .and_then(|column| values.get(column))
808                    .filter(|value| !value.is_null())
809                    .is_some_and(|value| {
810                        allowed.contains(
811                            &value
812                                .as_str()
813                                .map_or_else(|| value.to_string(), str::to_owned),
814                        )
815                    })
816            })
817    };
818    matches(effective) && !owners.iter().any(|owner| matches(owner))
819}
820
821fn is_local_operation_code_like(value: &str) -> bool {
822    let bytes = value.as_bytes();
823    bytes.first().is_some_and(u8::is_ascii_alphanumeric)
824        && bytes
825            .iter()
826            .all(|byte| byte.is_ascii_alphanumeric() || matches!(*byte, b'.' | b'_' | b':' | b'-'))
827}
828
829fn base_table(name: &str) -> String {
830    quote_ident(&format!("_syncular_base_{name}"))
831}
832
833/// §4.8 deferred eviction record: (unit id, table, effective scope map).
834type PendingEvict = (String, String, Vec<(String, Vec<String>)>);
835
836/// §4.8: a stable key for a window base: variable + canonical fixed scopes.
837fn window_base_key(base: &WindowBase) -> String {
838    format!(
839        "{}\0{}",
840        base.variable,
841        ssp2::registration::canonical_unit_json(&scope_pairs(&base.fixed_scopes))
842    )
843}
844
845/// The unit of one window value: the fixed scopes plus the value.
846fn window_unit_scopes(base: &WindowBase, value: &str) -> UnitScopes {
847    let mut scopes = base.fixed_scopes.clone();
848    scopes.insert(base.variable.clone(), value.to_owned());
849    scopes
850}
851
852/// A unit's scope map as the codec and the digests take it.
853fn scope_pairs(scopes: &UnitScopes) -> Vec<(String, String)> {
854    let mut pairs: Vec<(String, String)> = scopes
855        .iter()
856        .map(|(variable, value)| (variable.clone(), value.clone()))
857        .collect();
858    pairs.sort_by(|a, b| a.0.encode_utf16().cmp(b.0.encode_utf16()));
859    pairs
860}
861
862/// §4.1: the unit covers every table declaring all of its variables.
863fn covers(table: &TableSchema, scopes: &UnitScopes) -> bool {
864    scopes
865        .keys()
866        .all(|variable| table.scope_column(variable).is_some())
867}
868
869/// §4.4: the effective scopes of the (unit, table) pair under `echo`: the
870/// scope map as one-element lists plus the fenced lists. `None` when the
871/// fence revoked the pair.
872fn pair_scopes(
873    scopes: &UnitScopes,
874    table: &str,
875    echo: Option<&[EchoRecord]>,
876) -> Option<Vec<(String, Vec<String>)>> {
877    let fenced = echo.and_then(|echo| echo.iter().find(|record| record.table == table));
878    if fenced.is_some_and(|record| record.status == "revoked") {
879        return None;
880    }
881    let mut effective: BTreeMap<String, Vec<String>> = fenced
882        .map(|record| record.scopes.clone())
883        .unwrap_or_default();
884    for (variable, value) in scopes {
885        effective.insert(variable.clone(), vec![value.clone()]);
886    }
887    Some(effective.into_iter().collect())
888}
889
890/// §3.3 row ownership: the pair scopes of every owner of `table` except
891/// `except_id`. An owner is active with a persisted echo and live or
892/// post-bootstrap, or bootstrapping with a segment of the table in its
893/// current bootstrap, or holding a restriction that excludes the table.
894fn unit_owners(
895    units: &[UnitRecord],
896    table: &TableSchema,
897    except_id: &str,
898) -> Vec<Vec<(String, Vec<String>)>> {
899    units
900        .iter()
901        .filter(|unit| {
902            unit.id != except_id
903                && unit.status == UnitStatus::Active
904                && unit.echo.is_some()
905                && (!unit.bootstrapping()
906                    || unit.seeded.contains(&table.name)
907                    || unit
908                        .restriction
909                        .as_ref()
910                        .is_some_and(|restriction| !restriction.tables.contains(&table.name)))
911                && covers(table, &unit.scopes)
912        })
913        .filter_map(|unit| pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()))
914        .collect()
915}
916
917/// §5.5 / §5.6: the unit's scope map, each value a one-element list.
918fn unit_scope_lists(scopes: &UnitScopes) -> Vec<(String, Vec<String>)> {
919    scopes
920        .iter()
921        .map(|(variable, value)| (variable.clone(), vec![value.clone()]))
922        .collect()
923}
924
925/// §7.1 acknowledged intent of the rows `?1` names (`[[table, id], ...]`).
926/// It joins through the (tbl, id) index: a scan per acknowledgement would
927/// make draining a batch quadratic.
928const 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";
929
930const UNIT_COLUMNS: &str =
931    "id, scopes, explicit, status, reason_code, cursor, bootstrap_state, seeded, echo, restriction";
932
933/// A unit row; a field that does not parse is a conversion failure, which
934/// both read paths classify as `sync.local_corrupt`.
935fn unit_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<UnitRecord> {
936    fn json<T: serde::de::DeserializeOwned>(index: usize, raw: &str) -> rusqlite::Result<T> {
937        serde_json::from_str(raw).map_err(|error| {
938            rusqlite::Error::FromSqlConversionFailure(
939                index,
940                rusqlite::types::Type::Text,
941                Box::new(error),
942            )
943        })
944    }
945    Ok(UnitRecord {
946        id: row.get(0)?,
947        scopes: json(1, &row.get::<_, String>(1)?)?,
948        explicit: row.get::<_, i64>(2)? == 1,
949        status: json(
950            3,
951            &serde_json::to_string(&row.get::<_, String>(3)?).expect("text"),
952        )?,
953        reason_code: row.get(4)?,
954        cursor: row.get(5)?,
955        bootstrap_state: row.get(6)?,
956        seeded: json(7, &row.get::<_, String>(7)?)?,
957        echo: row
958            .get::<_, Option<String>>(8)?
959            .map(|echo| json::<Vec<EchoRecord>>(8, &echo))
960            .transpose()?
961            .map(|echo| {
962                if echo
963                    .iter()
964                    .all(|record| record.status == "active" || record.status == "revoked")
965                {
966                    Ok(echo)
967                } else {
968                    Err(rusqlite::Error::FromSqlConversionFailure(
969                        8,
970                        rusqlite::types::Type::Text,
971                        "echo status is neither active nor revoked".into(),
972                    ))
973                }
974            })
975            .transpose()?,
976        restriction: row
977            .get::<_, Option<String>>(9)?
978            .map(|raw| json::<UnitRestriction>(9, &raw))
979            .transpose()?,
980    })
981}
982
983/// Every unit in registration order (§4.1).
984fn load_units(conn: &Connection) -> rusqlite::Result<Vec<UnitRecord>> {
985    conn.prepare_cached(&format!(
986        "SELECT {UNIT_COLUMNS} FROM _syncular_units ORDER BY rowid"
987    ))?
988    .query_map([], unit_from_row)?
989    .collect()
990}
991
992fn get_unit(conn: &Connection, id: &str) -> rusqlite::Result<Option<UnitRecord>> {
993    conn.query_row(
994        &format!("SELECT {UNIT_COLUMNS} FROM _syncular_units WHERE id = ?1"),
995        [id],
996        unit_from_row,
997    )
998    .optional()
999}
1000
1001/// Insert or update in place: an update keeps the registration order. The
1002/// §5.6 applied-segment record ends when the cursor or the token changes.
1003fn save_unit(conn: &Connection, unit: &UnitRecord) -> rusqlite::Result<()> {
1004    conn.prepare_cached(&format!(
1005        "INSERT INTO _syncular_units({UNIT_COLUMNS}) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9,?10)
1006         ON CONFLICT(id) DO UPDATE SET explicit=excluded.explicit, status=excluded.status,
1007           reason_code=excluded.reason_code, cursor=excluded.cursor,
1008           bootstrap_state=excluded.bootstrap_state, seeded=excluded.seeded, echo=excluded.echo,
1009           restriction=excluded.restriction,
1010           applied=CASE WHEN cursor IS excluded.cursor
1011             AND bootstrap_state IS excluded.bootstrap_state THEN applied END"
1012    ))?
1013    .execute(rusqlite::params![
1014        unit.id,
1015        serde_json::to_string(&unit.scopes).expect("scope map serializes"),
1016        i64::from(unit.explicit),
1017        unit.status.name(),
1018        unit.reason_code,
1019        unit.cursor,
1020        unit.bootstrap_state,
1021        serde_json::to_string(&unit.seeded).expect("table list serializes"),
1022        unit.echo
1023            .as_ref()
1024            .map(|echo| serde_json::to_string(echo).expect("echo serializes")),
1025        unit.restriction
1026            .as_ref()
1027            .map(|restriction| serde_json::to_string(restriction).expect("restriction serializes")),
1028    ])
1029    .map(|_| ())
1030}
1031
1032/// §5.6 applied-segment record of unit `id`: segment id → rows applied at
1033/// its current cursor and token.
1034fn applied_rows(conn: &Connection, id: &str) -> rusqlite::Result<BTreeMap<String, i64>> {
1035    conn.query_row(
1036        "SELECT applied FROM _syncular_units WHERE id = ?1",
1037        [id],
1038        |row| row.get::<_, Option<String>>(0),
1039    )
1040    .optional()?
1041    .flatten()
1042    .map_or(Ok(BTreeMap::new()), |raw| {
1043        serde_json::from_str(&raw).map_err(|error| {
1044            rusqlite::Error::FromSqlConversionFailure(
1045                0,
1046                rusqlite::types::Type::Text,
1047                Box::new(error),
1048            )
1049        })
1050    })
1051}
1052
1053/// §5.6: `rows` rows of `segment_id` applied at unit `id`'s position. Runs
1054/// in the transaction that commits them.
1055fn record_applied_rows(
1056    conn: &Connection,
1057    id: &str,
1058    segment_id: &str,
1059    rows: i64,
1060) -> rusqlite::Result<()> {
1061    conn.prepare_cached(
1062        "UPDATE _syncular_units SET applied=json_patch(coalesce(applied,'{}'),?1) WHERE id=?2",
1063    )?
1064    .execute(rusqlite::params![
1065        serde_json::json!({ segment_id: rows }).to_string(),
1066        id
1067    ])
1068    .map(|_| ())
1069}
1070
1071/// §4.1 references: every window registry entry `(base, value)` holding a unit.
1072fn window_refs(conn: &Connection, unit_id: &str) -> rusqlite::Result<Vec<(String, String)>> {
1073    conn.prepare_cached("SELECT base, unit FROM _syncular_windows WHERE sub_id = ?1")?
1074        .query_map([unit_id], |row| Ok((row.get(0)?, row.get(1)?)))?
1075        .collect()
1076}
1077
1078/// §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
1079/// registrations and discard the synced state of every unit outside `keep`,
1080/// so the next round sends the list and bootstraps those units. A schema bump
1081/// passes `restrictions`: every reset unit keeps its echo and takes its
1082/// restriction from the map, if any (§7.4.3); the other resets discard both.
1083/// The replica cursor survives only while a kept unit is live. The caller
1084/// owns the transaction.
1085fn reset_units(
1086    conn: &Connection,
1087    keep: &BTreeSet<String>,
1088    restrictions: Option<&BTreeMap<String, UnitRestriction>>,
1089) -> rusqlite::Result<()> {
1090    conn.execute(
1091        "UPDATE _syncular_units SET status='active', reason_code=NULL, cursor=-1,
1092           bootstrap_state=NULL, seeded='[]', applied=NULL,
1093           echo=CASE WHEN ?2 IS NULL THEN NULL ELSE echo END,
1094           restriction=(SELECT value FROM json_each(?2) WHERE key=_syncular_units.id)
1095         WHERE id NOT IN (SELECT value FROM json_each(?1))",
1096        rusqlite::params![
1097            serde_json::to_string(keep).expect("unit ids serialize"),
1098            restrictions.map(|map| serde_json::to_string(map).expect("restrictions serialize")),
1099        ],
1100    )?;
1101    conn.execute_batch(
1102        "DELETE FROM _syncular_meta WHERE key IN ('echoDigest','registrationDigest');
1103         DELETE FROM _syncular_meta WHERE key='replicaCursor'
1104           AND NOT EXISTS (SELECT 1 FROM _syncular_units WHERE cursor IS NULL);",
1105    )
1106}
1107
1108/// §4.5: the replica cursor, `-1` while no unit is live.
1109fn replica_cursor(conn: &Connection) -> rusqlite::Result<i64> {
1110    meta_get(conn, REPLICA_CURSOR_KEY)?.map_or(Ok(-1), |raw| {
1111        raw.parse().map_err(|error| {
1112            rusqlite::Error::FromSqlConversionFailure(
1113                0,
1114                rusqlite::types::Type::Text,
1115                Box::new(error),
1116            )
1117        })
1118    })
1119}
1120
1121fn visible_table(name: &str) -> String {
1122    quote_ident(name)
1123}
1124
1125const FTS_SOURCE_ID_COLUMN: &str = "_syncular_source_id";
1126
1127/// §7.4.3: is a `sqlite_master` table name a synced table (visible or base),
1128/// i.e. NOT one of the durable bookkeeping tables the reset preserves?
1129fn is_synced_table_name(name: &str) -> bool {
1130    if name.starts_with("sqlite_") {
1131        return false;
1132    }
1133    if name.starts_with("_syncular_base_") {
1134        return true; // the base half of a synced table pair
1135    }
1136    // Bookkeeping: outbox, units, meta, blob cache/uploads.
1137    !name.starts_with("_syncular_")
1138}
1139
1140/// `"sha256:" + hex` of the bytes — the content address (§5.9.1).
1141fn blob_id_for(bytes: &[u8]) -> String {
1142    let digest = Sha256::digest(bytes);
1143    format!("sha256:{}", bytes_to_hex(&digest))
1144}
1145
1146/// One [`SyncClient::write_row`] bind parameter, borrowing the row-codec
1147/// value it wraps — strings/JSON/bytes bind as borrowed TEXT/BLOB (no copy
1148/// per row on the §5.6 bootstrap path), scalars bind owned.
1149enum RowParam<'a> {
1150    Cell(&'a Option<ColumnValue>),
1151    Version(i64),
1152    Text(Option<&'a str>),
1153}
1154
1155impl rusqlite::ToSql for RowParam<'_> {
1156    fn to_sql(&self) -> rusqlite::Result<ToSqlOutput<'_>> {
1157        Ok(match self {
1158            RowParam::Version(v) => ToSqlOutput::Owned(SqlValue::Integer(*v)),
1159            RowParam::Text(text) => match text {
1160                Some(text) => ToSqlOutput::Borrowed(ValueRef::Text(text.as_bytes())),
1161                None => ToSqlOutput::Owned(SqlValue::Null),
1162            },
1163            RowParam::Cell(cell) => match cell {
1164                None => ToSqlOutput::Owned(SqlValue::Null),
1165                Some(ColumnValue::String(s)) => ToSqlOutput::Borrowed(ValueRef::Text(s.as_bytes())),
1166                Some(ColumnValue::Integer(i)) => ToSqlOutput::Owned(SqlValue::Integer(*i)),
1167                Some(ColumnValue::Float(f)) => ToSqlOutput::Owned(SqlValue::Real(*f)),
1168                Some(ColumnValue::Boolean(b)) => {
1169                    ToSqlOutput::Owned(SqlValue::Integer(i64::from(*b)))
1170                }
1171                Some(ColumnValue::Json(raw)) | Some(ColumnValue::BlobRef(raw)) => {
1172                    ToSqlOutput::Borrowed(ValueRef::Text(raw.0.as_bytes()))
1173                }
1174                // §5.10: crdt bytes store as BLOB, like bytes.
1175                Some(ColumnValue::Bytes(b)) | Some(ColumnValue::Crdt(b)) => {
1176                    ToSqlOutput::Borrowed(ValueRef::Blob(b))
1177                }
1178            },
1179        })
1180    }
1181}
1182
1183// Retain a typed primary key across the current import chunk without copying row payloads.
1184fn owned_sql_value(param: impl rusqlite::ToSql) -> Result<SqlValue, String> {
1185    match param.to_sql().map_err(|error| error.to_string())? {
1186        ToSqlOutput::Owned(value) => Ok(value),
1187        ToSqlOutput::Borrowed(value) => {
1188            SqlValue::try_from(value).map_err(|error| error.to_string())
1189        }
1190        _ => Err("sync.invalid_request: unsupported SQLite key parameter".into()),
1191    }
1192}
1193
1194/// §5.3 image cell → bind parameter, strict per the declared column type
1195/// (`boolean` from INTEGER 0/1, `json` from its raw TEXT, NULL only when
1196/// nullable). Mismatches are image-producer violations. Returns the cell
1197/// borrowed when the stored representation already matches what the row
1198/// codec would write, or the normalized scalar (boolean → 0/1, float from
1199/// INTEGER → REAL) otherwise — the local write is byte-identical to the
1200/// old convert-then-insert path without allocating per cell.
1201fn image_cell_param<'a>(column: &Column, value: ValueRef<'a>) -> Result<ToSqlOutput<'a>, String> {
1202    use ssp2::segment::ColumnType;
1203    let mismatch = || {
1204        Err(format!(
1205            "image column {:?} holds a value of the wrong type",
1206            column.name
1207        ))
1208    };
1209    match value {
1210        ValueRef::Null => {
1211            if !column.nullable {
1212                return Err(format!(
1213                    "image column {:?} is NULL but not nullable",
1214                    column.name
1215                ));
1216            }
1217            Ok(ToSqlOutput::Owned(SqlValue::Null))
1218        }
1219        ValueRef::Integer(i) => match column.ty {
1220            ColumnType::Integer => Ok(ToSqlOutput::Borrowed(value)),
1221            ColumnType::Boolean => Ok(ToSqlOutput::Owned(SqlValue::Integer(i64::from(i != 0)))),
1222            ColumnType::Float => Ok(ToSqlOutput::Owned(SqlValue::Real(i as f64))),
1223            _ => mismatch(),
1224        },
1225        ValueRef::Real(_) => match column.ty {
1226            ColumnType::Float => Ok(ToSqlOutput::Borrowed(value)),
1227            _ => mismatch(),
1228        },
1229        ValueRef::Text(t) => {
1230            std::str::from_utf8(t)
1231                .map_err(|_| format!("image column {:?} is not UTF-8", column.name))?;
1232            match column.ty {
1233                ColumnType::String | ColumnType::Json | ColumnType::BlobRef => {
1234                    Ok(ToSqlOutput::Borrowed(value))
1235                }
1236                _ => mismatch(),
1237            }
1238        }
1239        ValueRef::Blob(_) => match column.ty {
1240            // §5.10: a crdt column stores its opaque bytes as BLOB, like bytes.
1241            ColumnType::Bytes | ColumnType::Crdt => Ok(ToSqlOutput::Borrowed(value)),
1242            _ => mismatch(),
1243        },
1244    }
1245}
1246
1247pub(crate) fn sql_ref_to_json(column: &Column, value: rusqlite::types::ValueRef<'_>) -> Value {
1248    use rusqlite::types::ValueRef;
1249    match value {
1250        ValueRef::Null => Value::Null,
1251        ValueRef::Integer(i) => match column.ty {
1252            ssp2::segment::ColumnType::Boolean => Value::Bool(i != 0),
1253            ssp2::segment::ColumnType::Float => {
1254                serde_json::Number::from_f64(i as f64).map_or(Value::Null, Value::Number)
1255            }
1256            _ => Value::from(i),
1257        },
1258        ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1259        ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1260        ValueRef::Blob(b) => {
1261            let mut map = Map::new();
1262            map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1263            Value::Object(map)
1264        }
1265    }
1266}
1267
1268/// Bind a driver JSON value form as a rusqlite parameter for [`SyncClient::query`].
1269/// Objects are accepted in lossless `{"$bytes": hex}` and
1270/// `{"$bigint": decimal}` envelope forms.
1271fn json_param_to_sql(value: &Value) -> Result<SqlValue, String> {
1272    Ok(match value {
1273        Value::Null => SqlValue::Null,
1274        Value::Bool(b) => SqlValue::Integer(i64::from(*b)),
1275        Value::Number(n) => {
1276            if let Some(i) = n.as_i64() {
1277                SqlValue::Integer(i)
1278            } else if let Some(f) = n.as_f64() {
1279                SqlValue::Real(f)
1280            } else {
1281                return Err(format!("query param number {n} is out of range"));
1282            }
1283        }
1284        Value::String(s) => SqlValue::Text(s.clone()),
1285        Value::Object(_) => {
1286            if let Some(hex) = value.get("$bytes").and_then(Value::as_str) {
1287                SqlValue::Blob(crate::values::hex_to_bytes(hex)?)
1288            } else if let Some(decimal) = value.get("$bigint").and_then(Value::as_str) {
1289                SqlValue::Integer(decimal.parse::<i64>().map_err(|_| {
1290                    format!("query bigint param {decimal:?} is outside SQLite's i64 range")
1291                })?)
1292            } else {
1293                return Err(
1294                    "query object param must be a {$bytes: hex} or {$bigint: decimal} value"
1295                        .to_owned(),
1296                );
1297            }
1298        }
1299        Value::Array(_) => return Err("query array params are not supported".to_owned()),
1300    })
1301}
1302
1303/// Map a rusqlite value with no schema column to consult (arbitrary query
1304/// output): integers/reals/text pass through by stored affinity, blobs ride
1305/// as `{"$bytes": hex}`. Distinct from [`sql_ref_to_json`], which uses the
1306/// schema column type to recover booleans/floats/json.
1307fn sql_ref_to_json_dynamic(value: rusqlite::types::ValueRef<'_>) -> Value {
1308    use rusqlite::types::ValueRef;
1309    match value {
1310        ValueRef::Null => Value::Null,
1311        ValueRef::Integer(i) => {
1312            // JSON/Tauri IPC cannot represent every SQLite i64 exactly. Keep
1313            // ordinary UI-sized integers ergonomic and envelope only values
1314            // beyond JavaScript's safe range.
1315            const MAX_SAFE_INTEGER: i64 = 9_007_199_254_740_991;
1316            if (-MAX_SAFE_INTEGER..=MAX_SAFE_INTEGER).contains(&i) {
1317                Value::from(i)
1318            } else {
1319                let mut map = Map::new();
1320                map.insert("$bigint".to_owned(), Value::from(i.to_string()));
1321                Value::Object(map)
1322            }
1323        }
1324        ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1325        ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1326        ValueRef::Blob(b) => {
1327            let mut map = Map::new();
1328            map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1329            Value::Object(map)
1330        }
1331    }
1332}
1333
1334/// §7.5: SQLite failures classify by result code into [`QueryReadFailure`].
1335fn query_connection(
1336    conn: &Connection,
1337    sql: &str,
1338    params: &[QueryValue],
1339) -> Result<Vec<QueryRow>, QueryReadFailure> {
1340    let lowered_sql = crate::query_guard::lower_public_query_sql(sql);
1341    let mut stmt = crate::query_guard::prepare_read_only(conn, &lowered_sql)?;
1342    let bound: Vec<SqlValue> = params
1343        .iter()
1344        .map(json_param_to_sql)
1345        .collect::<Result<_, _>>()?;
1346    // §2.4: an unaliased physical version column stays engine-internal, so a
1347    // `SELECT *` row feeds straight back into mutation values. An explicit
1348    // alias (`_sync_version AS v`) returns it as ordinary query data. The
1349    // §5.11 sealed columns follow the same rule.
1350    let columns: Vec<(usize, String)> = stmt
1351        .column_names()
1352        .enumerate()
1353        .filter(|(_, name)| {
1354            !matches!(
1355                *name,
1356                "_syncular_version" | "_sync_sealed_key" | "_sync_sealed"
1357            )
1358        })
1359        .map(|(i, name)| (i, name.to_owned()))
1360        .collect();
1361    let bound_refs: Vec<&dyn rusqlite::ToSql> =
1362        bound.iter().map(|v| v as &dyn rusqlite::ToSql).collect();
1363    let mut sql_rows = stmt.query(bound_refs.as_slice())?;
1364    let mut out = Vec::new();
1365    while let Some(row) = sql_rows.next()? {
1366        let mut record = Map::new();
1367        for (i, name) in &columns {
1368            let value = row.get_ref(*i)?;
1369            record.insert(name.clone(), sql_ref_to_json_dynamic(value));
1370        }
1371        out.push(record);
1372    }
1373    Ok(out)
1374}
1375
1376fn persisted_window_state(
1377    conn: &Connection,
1378    base: &WindowBase,
1379) -> Result<WindowState, QueryReadFailure> {
1380    let mut stmt = conn.prepare(
1381        "SELECT windows.unit, units.status, units.cursor, units.bootstrap_state
1382           FROM _syncular_windows AS windows
1383           LEFT JOIN _syncular_units AS units ON units.id = windows.sub_id
1384          WHERE windows.base = ?1
1385          ORDER BY windows.unit ASC",
1386    )?;
1387    let rows = stmt.query_map(rusqlite::params![window_base_key(base)], |row| {
1388        Ok((
1389            row.get::<_, String>(0)?,
1390            row.get::<_, Option<String>>(1)?,
1391            row.get::<_, Option<i64>>(2)?,
1392            row.get::<_, Option<String>>(3)?,
1393        ))
1394    })?;
1395    let mut units = Vec::new();
1396    let mut pending = Vec::new();
1397    for row in rows {
1398        let (unit, status, cursor, bootstrap_state) = row?;
1399        // §4.8: complete iff registered, active and not bootstrapping.
1400        if status.as_deref() != Some("active")
1401            || cursor.is_some_and(|cursor| cursor < 0 || bootstrap_state.is_some())
1402        {
1403            pending.push(unit.clone());
1404        }
1405        units.push(unit);
1406    }
1407    Ok(WindowState { units, pending })
1408}
1409
1410/// One read-only statement in a §7.5 snapshot read.
1411#[derive(Debug, Clone, Copy)]
1412pub struct SnapshotStatement<'a> {
1413    pub sql: &'a str,
1414    pub params: &'a [Value],
1415}
1416
1417/// A §7.5 atomic read request: read-only statements, window coverage, unit
1418/// catch-up states, and commit deliveries, all resolved from one SQLite read
1419/// transaction and one revision.
1420#[derive(Debug, Clone, Default)]
1421pub struct SnapshotReadRequest<'a> {
1422    pub statements: Vec<SnapshotStatement<'a>>,
1423    pub coverage: &'a [WindowCoverage],
1424    pub units: Vec<String>,
1425    pub commit_ids: Vec<String>,
1426}
1427
1428#[cfg(test)]
1429thread_local! {
1430    /// Test-only rendezvous that runs between the statements of one snapshot
1431    /// read. A test uses it to commit on another connection mid-read and prove
1432    /// the read transaction's snapshot and revision stay stable.
1433    static SNAPSHOT_READ_HOOK: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
1434        std::cell::RefCell::new(None);
1435}
1436
1437#[cfg(test)]
1438fn run_snapshot_read_hook() {
1439    SNAPSHOT_READ_HOOK.with(|slot| {
1440        if let Some(hook) = slot.borrow_mut().take() {
1441            hook();
1442        }
1443    });
1444}
1445
1446/// §7.5: resolve a request over one SQLite read transaction. The revision,
1447/// every statement's rows, coverage, catch-up states, and deliveries are
1448/// captured under one `SAVEPOINT`; any statement's failure rolls the whole
1449/// read back and releases the connection.
1450fn snapshot_read_connection(
1451    conn: &Connection,
1452    request: &SnapshotReadRequest<'_>,
1453) -> Result<SnapshotRead, QueryReadFailure> {
1454    conn.execute_batch("SAVEPOINT syncular_snapshot_read")?;
1455    let corrupt = |message: &str| QueryReadFailure {
1456        code: Some("sync.local_corrupt"),
1457        sqlite_code: None,
1458        sqlite_message: None,
1459        rollback_failure: None,
1460        message: message.to_owned(),
1461    };
1462    let stored_failure = |error: rusqlite::Error, message: &str| match error {
1463        rusqlite::Error::Utf8Error(..)
1464        | rusqlite::Error::InvalidColumnType(..)
1465        | rusqlite::Error::FromSqlConversionFailure(..)
1466        | rusqlite::Error::IntegralValueOutOfRange(..) => corrupt(message),
1467        _ => QueryReadFailure::from(error),
1468    };
1469    let result: Result<SnapshotRead, QueryReadFailure> = (|| {
1470        // The durable revision as a canonical decimal `u64`; a missing marker
1471        // is the legacy zero, and any other non-canonical value is corrupt.
1472        let revision: Option<String> = conn
1473            .query_row(
1474                "SELECT value FROM _syncular_meta WHERE key = ?1",
1475                rusqlite::params![LOCAL_REVISION_KEY],
1476                |row| row.get(0),
1477            )
1478            .optional()
1479            .map_err(|error| stored_failure(error, "persisted local revision is invalid"))?;
1480        let revision = match revision {
1481            None => "0".to_owned(),
1482            Some(value)
1483                if value == "0"
1484                    || (matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1485                        && value.bytes().all(|b| b.is_ascii_digit())
1486                        && value.parse::<u64>().is_ok()) =>
1487            {
1488                value
1489            }
1490            Some(_) => return Err(corrupt("persisted local revision is invalid")),
1491        };
1492        let mut queries = Vec::with_capacity(request.statements.len());
1493        for statement in &request.statements {
1494            queries.push(query_connection(conn, statement.sql, statement.params)?);
1495            #[cfg(test)]
1496            run_snapshot_read_hook();
1497        }
1498        let mut pending = Vec::new();
1499        let mut missing = Vec::new();
1500        for requested in request.coverage {
1501            let base_key = window_base_key(&requested.base);
1502            let state = persisted_window_state(conn, &requested.base)?;
1503            for unit in BTreeSet::from_iter(requested.units.iter().cloned()) {
1504                let reference = WindowUnitRef {
1505                    base_key: base_key.clone(),
1506                    unit: unit.clone(),
1507                };
1508                if !state.units.iter().any(|held| held == &unit) {
1509                    missing.push(reference);
1510                } else if state.pending.iter().any(|held| held == &unit) {
1511                    pending.push(reference);
1512                }
1513            }
1514        }
1515        let mut units = Vec::with_capacity(request.units.len());
1516        for id in &request.units {
1517            let exists: bool = conn.query_row(
1518                "SELECT EXISTS(SELECT 1 FROM _syncular_units WHERE id = ?1)",
1519                [id],
1520                |row| row.get(0),
1521            )?;
1522            if !exists {
1523                units.push(UnitCatchup::Unknown { id: id.clone() });
1524                continue;
1525            }
1526            // Every persisted field is required to be well typed; a corrupt
1527            // record fails typed instead of inventing a state.
1528            let unit = get_unit(conn, id)
1529                .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?
1530                .ok_or_else(|| corrupt("persisted unit state is invalid"))?;
1531            let cursor = match unit.cursor {
1532                Some(cursor) => cursor,
1533                None => replica_cursor(conn)
1534                    .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?,
1535            };
1536            if cursor.unsigned_abs() > MAX_JS_SAFE_INTEGER {
1537                return Err(corrupt("persisted unit state is invalid"));
1538            }
1539            let active = unit.status == UnitStatus::Active;
1540            let pending = unit.bootstrapping();
1541            units.push(UnitCatchup::Known {
1542                id: id.clone(),
1543                status: unit.status,
1544                live: unit.cursor.is_none(),
1545                cursor,
1546                has_resume_token: unit.bootstrap_state.is_some(),
1547                bootstrap_complete: active && !pending,
1548                known_pending_pages: active && pending,
1549                reason_code: unit.reason_code,
1550            });
1551        }
1552        let mut deliveries = Vec::with_capacity(request.commit_ids.len());
1553        for id in &request.commit_ids {
1554            let pending: bool = conn.query_row(
1555                "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id = ?1)",
1556                rusqlite::params![id],
1557                |row| row.get(0),
1558            )?;
1559            if pending {
1560                deliveries.push(CommitDelivery::Pending {
1561                    client_commit_id: id.clone(),
1562                });
1563                continue;
1564            }
1565            let row = conn
1566                .query_row(
1567                    "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
1568                            resolution, resolved_at_ms, replacement_client_commit_id
1569                       FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
1570                    rusqlite::params![id],
1571                    StoredCommitOutcomeRow::from_row,
1572                )
1573                .optional()
1574                .map_err(|error| stored_failure(error, "persisted commit outcome is invalid"))?;
1575            deliveries.push(match row {
1576                Some(row) => CommitDelivery::Known {
1577                    client_commit_id: id.clone(),
1578                    outcome: SyncClient::outcome_from_row(row)
1579                        .map_err(|_| corrupt("persisted commit outcome is invalid"))?,
1580                },
1581                None => CommitDelivery::Unknown {
1582                    client_commit_id: id.clone(),
1583                },
1584            });
1585        }
1586        Ok(SnapshotRead {
1587            revision,
1588            queries,
1589            coverage: CoverageSnapshot {
1590                complete: pending.is_empty() && missing.is_empty(),
1591                pending,
1592                missing,
1593            },
1594            units,
1595            deliveries,
1596        })
1597    })();
1598    match result {
1599        Ok(read) => {
1600            conn.execute_batch("RELEASE syncular_snapshot_read")?;
1601            Ok(read)
1602        }
1603        Err(mut error) => {
1604            if let Err(rollback) = conn
1605                .execute_batch("ROLLBACK TO syncular_snapshot_read; RELEASE syncular_snapshot_read")
1606            {
1607                error.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
1608            }
1609            Err(error)
1610        }
1611    }
1612}
1613
1614fn snapshot_connection(
1615    conn: &Connection,
1616    sql: &str,
1617    params: &[Value],
1618    coverage: &[WindowCoverage],
1619) -> Result<QuerySnapshot, QueryReadFailure> {
1620    let read = snapshot_read_connection(
1621        conn,
1622        &SnapshotReadRequest {
1623            statements: vec![SnapshotStatement { sql, params }],
1624            coverage,
1625            units: Vec::new(),
1626            commit_ids: Vec::new(),
1627        },
1628    )?;
1629    Ok(QuerySnapshot {
1630        revision: read.revision,
1631        rows: read
1632            .queries
1633            .into_iter()
1634            .next()
1635            .expect("single-query snapshot returns one result"),
1636        coverage: read.coverage,
1637    })
1638}
1639
1640/// A long-lived read-only SQLite sidecar for latency-critical native views.
1641/// Network rounds stay serialized on the mutable core owner, while atomic
1642/// query snapshots use this independent connection and therefore never queue
1643/// behind HTTP/WebSocket latency.
1644pub struct FileQuerySnapshotReader {
1645    path: String,
1646    conn: Option<Connection>,
1647}
1648
1649impl FileQuerySnapshotReader {
1650    #[must_use]
1651    pub fn new(path: impl Into<String>) -> Self {
1652        Self {
1653            path: path.into(),
1654            conn: None,
1655        }
1656    }
1657
1658    fn connection(&mut self) -> Result<&Connection, QueryReadFailure> {
1659        if self.conn.is_none() {
1660            let conn = Connection::open_with_flags(
1661                &self.path,
1662                OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
1663            )
1664            .map_err(QueryReadFailure::from)?;
1665            conn.busy_timeout(std::time::Duration::from_millis(250))
1666                .map_err(QueryReadFailure::from)?;
1667            self.conn = Some(conn);
1668        }
1669        self.conn
1670            .as_ref()
1671            .ok_or_else(|| QueryReadFailure::from("read sidecar connection missing".to_owned()))
1672    }
1673
1674    /// One atomic read over the shared primitive: every statement, coverage,
1675    /// catch-up, and delivery under one `SAVEPOINT` and one revision.
1676    pub fn snapshot_read(
1677        &mut self,
1678        request: &SnapshotReadRequest<'_>,
1679    ) -> Result<SnapshotRead, QueryReadFailure> {
1680        snapshot_read_connection(self.connection()?, request)
1681    }
1682
1683    /// The current durable local revision. A host can skip a read when it is
1684    /// unchanged; a corrupt or unreadable marker fails typed.
1685    pub fn local_revision(&mut self) -> Result<String, QueryReadFailure> {
1686        Ok(self
1687            .snapshot_read(&SnapshotReadRequest::default())?
1688            .revision)
1689    }
1690
1691    /// One unit's persisted catch-up state (see the §7.5 contract).
1692    pub fn unit_catchup(&mut self, id: &str) -> Result<UnitCatchup, QueryReadFailure> {
1693        let read = self.snapshot_read(&SnapshotReadRequest {
1694            units: vec![id.to_owned()],
1695            ..Default::default()
1696        })?;
1697        Ok(read
1698            .units
1699            .into_iter()
1700            .next()
1701            .expect("one requested catch-up"))
1702    }
1703
1704    /// One client commit's delivery status: pending, its retained outcome, or
1705    /// an explicit unknown (never held, or pruned by retention).
1706    pub fn commit_delivery(&mut self, id: &str) -> Result<CommitDelivery, QueryReadFailure> {
1707        let read = self.snapshot_read(&SnapshotReadRequest {
1708            commit_ids: vec![id.to_owned()],
1709            ..Default::default()
1710        })?;
1711        Ok(read
1712            .deliveries
1713            .into_iter()
1714            .next()
1715            .expect("one requested delivery"))
1716    }
1717
1718    /// Hosts report an owned failure, and the first success after it, to the
1719    /// owning core through [`SyncClient::record_query_read`] (§7.6).
1720    pub fn query_snapshot(
1721        &mut self,
1722        sql: &str,
1723        params: &[Value],
1724        coverage: &[WindowCoverage],
1725    ) -> Result<QuerySnapshot, QueryReadFailure> {
1726        snapshot_connection(self.connection()?, sql, params, coverage)
1727    }
1728}
1729
1730fn validate_authority_reads(
1731    schema: &ClientSchema,
1732    declarations: &[crate::api::AuthorityReadDeclaration],
1733) -> Result<(), String> {
1734    let mut seen = BTreeSet::new();
1735    for read in declarations {
1736        let table = schema
1737            .table(&read.table)
1738            .ok_or("client.authority_read_forbidden: authority table is not declared")?;
1739        let plain = |name: &str| {
1740            table.columns.iter().enumerate().any(|(i, c)| {
1741                c.name == name
1742                    && name != "authority_version"
1743                    && !name.starts_with("_sync")
1744                    && !table.encrypted_columns.iter().any(|e| e.index == i)
1745                    && matches!(
1746                        c.ty,
1747                        ssp2::segment::ColumnType::String
1748                            | ssp2::segment::ColumnType::Integer
1749                            | ssp2::segment::ColumnType::Float
1750                            | ssp2::segment::ColumnType::Boolean
1751                            | ssp2::segment::ColumnType::Json
1752                    )
1753            })
1754        };
1755        if !seen.insert(&read.table)
1756            || read.columns.is_empty()
1757            || read.columns.iter().collect::<BTreeSet<_>>().len() != read.columns.len()
1758            || !read.columns.contains(&table.primary_key)
1759            || !read.columns.iter().all(|c| plain(c))
1760            || read.scopes.is_empty()
1761            || !read.scopes.iter().all(|(v, values)| {
1762                table
1763                    .scope_column(v)
1764                    .is_some_and(|c| read.columns.iter().any(|column| column == c) && plain(c))
1765                    && !values.is_empty()
1766                    && values.iter().all(|v| !v.is_empty() && v != "*")
1767            })
1768        {
1769            return Err("client.authority_read_forbidden: authority reads require plain columns, a primary key and nonempty plain scope selectors".into());
1770        }
1771    }
1772    Ok(())
1773}
1774
1775// §7.4.2: every open and recreation checks before any persistent writes.
1776/// A marker read that hit a recognized SQLite storage failure keeps that
1777/// classification (BUSY/LOCKED stay retryable); only an unclassified read
1778/// failure is the invalid-marker `sync.local_corrupt`.
1779fn schema_marker_read_failure(error: rusqlite::Error) -> String {
1780    let failure = QueryReadFailure::from(error);
1781    if failure.code.is_some() {
1782        failure.to_string()
1783    } else {
1784        "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned()
1785    }
1786}
1787
1788/// §7.1: reject an invalid configured client limit before any storage is
1789/// opened or written. Zero would wedge the push queue and an out-of-range
1790/// value would differ per target; the TS core enforces the same bounds.
1791fn validate_client_limits(limits: &crate::api::ClientLimits) -> Result<(), String> {
1792    if limits.outcome_retention_max_entries == Some(0) {
1793        return Err("sync.invalid_request: outcomeRetentionMaxEntries must be positive".to_owned());
1794    }
1795    if [
1796        limits.max_push_commits_per_request,
1797        limits.max_push_operations_per_request,
1798        limits.max_push_request_bytes,
1799    ]
1800    .into_iter()
1801    .flatten()
1802    .any(|value| value == 0 || value > u32::MAX as usize)
1803    {
1804        return Err(
1805            "sync.invalid_request: push limit must be an integer in 1..=4294967295".to_owned(),
1806        );
1807    }
1808    Ok(())
1809}
1810
1811fn read_local_schema_version(conn: &Connection, requested: i32) -> Result<Option<i32>, String> {
1812    let corrupt =
1813        || "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned();
1814    let table_type: Option<String> = conn
1815        .query_row(
1816            "SELECT type FROM sqlite_master WHERE name = '_syncular_meta'",
1817            [],
1818            |row| row.get(0),
1819        )
1820        .optional()
1821        .map_err(schema_marker_read_failure)?;
1822    let Some(table_type) = table_type else {
1823        return Ok(None);
1824    };
1825    if table_type != "table" {
1826        return Err(corrupt());
1827    }
1828    // §7.4.2: a duplicated marker cannot be resolved. `query_row` would take
1829    // whichever row SQLite returns first, and an older one would drive a
1830    // destructive reset over a newer replica.
1831    let mut statement = conn
1832        .prepare("SELECT value FROM _syncular_meta WHERE key = ?1")
1833        .map_err(schema_marker_read_failure)?;
1834    let mut rows = statement
1835        .query([LOCAL_SCHEMA_VERSION_KEY])
1836        .map_err(schema_marker_read_failure)?;
1837    let value: Option<String> = rows
1838        .next()
1839        .map_err(schema_marker_read_failure)?
1840        .map(|row| row.get(0))
1841        .transpose()
1842        .map_err(schema_marker_read_failure)?;
1843    if rows.next().map_err(schema_marker_read_failure)?.is_some() {
1844        return Err(corrupt());
1845    }
1846    let Some(value) = value else {
1847        let has_descriptor = conn
1848            .query_row(
1849                "SELECT 1 FROM _syncular_meta WHERE key = ?1 LIMIT 1",
1850                [crate::previous_version::LOCAL_SCHEMA_DESCRIPTOR_KEY],
1851                |_| Ok(()),
1852            )
1853            .optional()
1854            .map_err(schema_marker_read_failure)?
1855            .is_some();
1856        if has_descriptor {
1857            return Err(corrupt());
1858        }
1859        return Ok(None);
1860    };
1861    if !matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1862        || !value.bytes().all(|b| b.is_ascii_digit())
1863    {
1864        return Err(corrupt());
1865    }
1866    let version = value.parse::<i32>().map_err(|_| corrupt())?;
1867    if version > requested {
1868        return Err(
1869            "client.schema_downgrade: persisted local schema is newer than the requested schema"
1870                .to_owned(),
1871        );
1872    }
1873    Ok(Some(version))
1874}
1875
1876/// Open a replica file. On a browser worker the file must recover a hot
1877/// journal before any statement reads it: `wasm_vfs` replaces the installed
1878/// OPFS VFS's reserved lock callback before the connection opens its file. A
1879/// new browser replica uses 64 KiB pages (§5.3), because every OPFS call costs
1880/// the same whatever its size; a database with tables keeps its page size. Its
1881/// page cache holds 64 MiB, because SQLite's 2,000 KiB default is 31 such pages
1882/// and every cache miss is an OPFS call.
1883fn open_replica(path: &str) -> Result<Connection, String> {
1884    let browser = cfg!(all(target_arch = "wasm32", target_os = "unknown"))
1885        && !path.is_empty()
1886        && path != ":memory:";
1887    #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
1888    if browser {
1889        crate::wasm_vfs::disable_foreign_lock_check()?;
1890    }
1891    let conn = Connection::open(path).map_err(|e| format!("open db {path:?}: {e}"))?;
1892    if browser {
1893        conn.execute_batch("PRAGMA page_size = 65536; PRAGMA cache_size = -65536")
1894            .map_err(|e| format!("open db {path:?}: {e}"))?;
1895    }
1896    Ok(conn)
1897}
1898
1899impl SyncClient {
1900    pub fn new_with_identity(
1901        client_id: Option<String>,
1902        schema_json: &Value,
1903        limits: ClientLimits,
1904    ) -> Result<Self, String> {
1905        let resolved = client_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
1906        let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1907        Self::with_connection(resolved, schema_json, limits, conn)
1908    }
1909
1910    pub fn new(
1911        client_id: String,
1912        schema_json: &Value,
1913        limits: ClientLimits,
1914    ) -> Result<Self, String> {
1915        let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1916        Self::with_connection(client_id, schema_json, limits, conn)
1917    }
1918
1919    /// Build a client backed by an on-disk SQLite database at `path` — the
1920    /// seam a native host (Tauri plugin, FFI file-DB variant) uses to persist
1921    /// across process restarts. `create_tables` runs `IF NOT EXISTS`, so
1922    /// re-opening the same file reuses the persisted rows. Keeps rusqlite out
1923    /// of the command router's dependency set (the router only holds a path).
1924    pub fn open_path(
1925        client_id: String,
1926        schema_json: &Value,
1927        limits: ClientLimits,
1928        path: &str,
1929    ) -> Result<Self, String> {
1930        validate_client_limits(&limits)?;
1931        parse_schema_json(schema_json)?;
1932        let conn = open_replica(path)?;
1933        Self::with_connection(client_id, schema_json, limits, conn)
1934    }
1935
1936    /// Open a file replica and resolve its client id. Native targets require
1937    /// WAL for the independent snapshot reader; `wasm32-unknown-unknown`
1938    /// accepts the sqlite-wasm worker journal instead.
1939    pub fn open_path_with_identity(
1940        client_id: Option<String>,
1941        schema_json: &Value,
1942        limits: ClientLimits,
1943        path: &str,
1944    ) -> Result<Self, String> {
1945        Self::open_path_with_identity_journal(
1946            client_id,
1947            schema_json,
1948            limits,
1949            path,
1950            !cfg!(all(target_arch = "wasm32", target_os = "unknown")),
1951        )
1952    }
1953
1954    fn open_path_with_identity_journal(
1955        client_id: Option<String>,
1956        schema_json: &Value,
1957        limits: ClientLimits,
1958        path: &str,
1959        require_wal: bool,
1960    ) -> Result<Self, String> {
1961        validate_client_limits(&limits)?;
1962        // §7.4.2: an invalid requested version is refused before the replica is
1963        // even created, so a rejected constructor leaves no file behind.
1964        parse_schema_json(schema_json)?;
1965        let conn = open_replica(path)?;
1966        // A file-backed native client uses an independent read connection for
1967        // latency-critical snapshots. WAL is SQLite's intended reader/writer
1968        // concurrency mode: a view read never holds a rollback-journal lock
1969        // that delays the client's next commit. The busy timeout must precede
1970        // this replica's own startup transaction; WAL is applied only after
1971        // startup succeeded, because a refused open must leave the replica's
1972        // journal mode and contents untouched (§7.4.2).
1973        conn.busy_timeout(std::time::Duration::from_millis(250))
1974            .map_err(|error| format!("configure db {path:?} busy timeout: {error}"))?;
1975        // Durability is the caller's contract here, not the VFS default: a
1976        // rollback-journal commit needs FULL before it writes the database
1977        // pages, or a killed worker can leave a half-written image behind.
1978        // WAL below inherits the same setting.
1979        conn.pragma_update(None, "synchronous", "FULL")
1980            .map_err(|error| format!("configure db {path:?} synchronous: {error}"))?;
1981        let client = Self::with_connection_identity(client_id, schema_json, limits, conn)?;
1982        // A browser worker's sqlite-wasm VFS has no WAL mode, and the wasm
1983        // host has no independent snapshot reader. The WAL requirement exists
1984        // for native file replicas, where it is the reader/writer boundary.
1985        if require_wal {
1986            let journal_mode: String = client
1987                .conn
1988                .pragma_update_and_check(None, "journal_mode", "WAL", |row| row.get(0))
1989                .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
1990            if journal_mode != "wal" {
1991                return Err(
1992                    "sync.invalid_request: file-backed client requires WAL journal mode".to_owned(),
1993                );
1994            }
1995        }
1996        Ok(client)
1997    }
1998
1999    /// Delete a file replica at `path`, including its `-journal`, `-wal`, and
2000    /// `-shm` sidecars, through the VFS that owns it. Use this after
2001    /// `client.storage_corrupt`: an OPFS SAH pool stores those files under
2002    /// opaque names, so deleting the pool directory behind SQLite bypasses the
2003    /// pool's slot accounting.
2004    ///
2005    /// Close the client and every [`FileQuerySnapshotReader`] on `path` first;
2006    /// a VFS cannot delete a file another handle still owns. A file that does
2007    /// not exist counts as deleted, so a cleanly closed replica without
2008    /// sidecars resets. The next open
2009    /// creates a fresh replica (new client id) and re-bootstraps from the
2010    /// server. A memory replica has nothing to delete and fails with
2011    /// `sync.invalid_request`.
2012    pub fn reset_replica(path: &str) -> Result<(), String> {
2013        if path.is_empty() || path == ":memory:" {
2014            return Err("sync.invalid_request: a memory replica has nothing to reset".to_owned());
2015        }
2016        // SAFETY: a null VFS name asks SQLite for its process-wide default VFS,
2017        // the same one `Connection::open(path)` above selects. `xDelete` is
2018        // that VFS's own function pointer, and `c_name` outlives the call.
2019        let vfs = unsafe { rusqlite::ffi::sqlite3_vfs_find(std::ptr::null()) };
2020        if vfs.is_null() {
2021            return Err("client.storage_io: no SQLite VFS is registered".to_owned());
2022        }
2023        let delete = unsafe { (*vfs).xDelete }
2024            .ok_or_else(|| "client.storage_io: the SQLite VFS cannot delete files".to_owned())?;
2025        for suffix in ["-wal", "-shm", "-journal", ""] {
2026            let file_name = format!("{path}{suffix}");
2027            let c_name = std::ffi::CString::new(file_name.as_str()).map_err(|_| {
2028                format!("sync.invalid_request: replica path {file_name:?} contains a NUL byte")
2029            })?;
2030            // SAFETY: `vfs` and its `xDelete` pointer come from the live
2031            // SQLite library; `c_name` is a valid NUL-terminated path.
2032            let code = unsafe { delete(vfs, c_name.as_ptr(), 1) };
2033            // A cleanly closed WAL replica has no sidecars; a missing file is
2034            // already deleted.
2035            if code != rusqlite::ffi::SQLITE_OK && code != rusqlite::ffi::SQLITE_IOERR_DELETE_NOENT
2036            {
2037                return Err(format!(
2038                    "client.storage_io: deleting replica file {file_name:?} failed with SQLite code {code}"
2039                ));
2040            }
2041        }
2042        Ok(())
2043    }
2044
2045    #[must_use]
2046    pub fn client_id(&self) -> &str {
2047        &self.client_id
2048    }
2049
2050    /// Rotate the caller's client id (§1.5) and return the new one. Use it
2051    /// after a `sync.invalid_client_id` refusal (`recommendedAction:
2052    /// resetClientId`): the next round carries the new id. A live realtime
2053    /// socket is closed so the next connection registers with the new id.
2054    /// The replica and its outbox stay in place; wipe them yourself when the
2055    /// stored data belongs to the account that signed out.
2056    pub fn reset_client_id(&mut self, transport: &mut dyn Transport) -> Result<String, String> {
2057        self.disconnect_realtime(transport);
2058        let client_id = uuid::Uuid::new_v4().to_string();
2059        self.set_meta(CLIENT_ID_KEY, &client_id)?;
2060        self.client_id.clone_from(&client_id);
2061        self.round_failure = None;
2062        Ok(client_id)
2063    }
2064
2065    /// Build a client over a caller-supplied rusqlite connection — the seam a
2066    /// native host (Tauri plugin, FFI file-DB variant) uses to back the core
2067    /// with an on-disk database (`Connection::open(path)`) rather than the
2068    /// default `:memory:`. The connection MUST be fresh (no pre-existing
2069    /// syncular tables); `create_tables` runs `IF NOT EXISTS`, so re-opening
2070    /// the same file across process restarts reuses the persisted rows.
2071    pub fn with_connection(
2072        client_id: String,
2073        schema_json: &Value,
2074        limits: ClientLimits,
2075        conn: Connection,
2076    ) -> Result<Self, String> {
2077        Self::with_connection_identity(Some(client_id), schema_json, limits, conn)
2078    }
2079
2080    /// [`Self::with_connection`] for `open_path_with_identity`: no requested id
2081    /// means a durable replica's persisted `clientId` wins over a fresh one.
2082    fn with_connection_identity(
2083        client_id: Option<String>,
2084        schema_json: &Value,
2085        limits: ClientLimits,
2086        conn: Connection,
2087    ) -> Result<Self, String> {
2088        validate_client_limits(&limits)?;
2089        let schema = parse_schema_json(schema_json)?;
2090        validate_authority_reads(&schema, &limits.authority_reads)?;
2091        // RFC 0005 D8: resolve the previous-version config before the opening
2092        // reset runs — the capture happens inside it. Bad bounds fail loud.
2093        let previous_version = match limits.previous_version_context {
2094            Some(config) => {
2095                config.validate()?;
2096                Some(config)
2097            }
2098            None => None,
2099        };
2100        let mut client = SyncClient {
2101            #[cfg(feature = "bench-internals")]
2102            benchmark_phases: Recorder::default(),
2103            conn,
2104            schema,
2105            client_id: client_id
2106                .clone()
2107                .unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
2108            limits,
2109            outbox: Shared::default(),
2110            failed_commits: Shared::default(),
2111            retain_failed_commits: false,
2112            conflicts: Shared::default(),
2113            rejections: Shared::default(),
2114            schema_floor: None,
2115            lease_state: None,
2116            stopped: false,
2117            upgrading: false,
2118            sync_needed: false,
2119            realtime_policy: RealtimePolicy::Optional,
2120            realtime_state: RealtimeState::Disconnected,
2121            realtime_reason_code: None,
2122            realtime_retry_delay_ms: None,
2123            presence: HashMap::new(),
2124            now_ms: None,
2125            encryption: crate::values::EncryptionConfig::default(),
2126            security_preflight: false,
2127            security_epoch: 0,
2128            transport_enabled: true,
2129            transport_epoch: 0,
2130            registration_epoch: 0,
2131            previous_version,
2132            insert_sql: RefCell::new(HashMap::new()),
2133            overlay_dirty: OverlayDirty::clean(),
2134            storage_failure: RefCell::new(None),
2135            #[cfg(test)]
2136            overlay_rebuild_count: Cell::new(0),
2137            #[cfg(test)]
2138            acknowledged_replay_count: Cell::new(0),
2139            #[cfg(test)]
2140            outcome_prune_count: Cell::new(0),
2141            #[cfg(test)]
2142            image_chunk_ms: Cell::new(None),
2143            progress: ProgressObserver::default(),
2144            epoch: uuid::Uuid::new_v4().to_string(),
2145            change_queue: VecDeque::new(),
2146            sync_intent_queue: VecDeque::new(),
2147            scopes_changed: 0,
2148            retry_delay_ms: 250,
2149            round_retry_delay_ms: None,
2150            image_chunk_rows: HashMap::new(),
2151            round_failure: None,
2152            active_round: None,
2153            last_round: None,
2154            last_change: None,
2155            query_failures: Vec::new(),
2156            coalesced: None,
2157            coalesced_failure: None,
2158        };
2159        // The row write path leans on the prepared-statement cache (two
2160        // insert statements per synced table, plus the bookkeeping
2161        // statements); size it so a multi-table schema never thrashes.
2162        client
2163            .conn
2164            .set_prepared_statement_cache_capacity(64.max(client.schema.tables.len() * 4));
2165        // §7.4.2: one write transaction (SQLite `BEGIN IMMEDIATE`, a reserved
2166        // writer) covers the marker read, the identity check, and every
2167        // bookkeeping/schema write, so a concurrent open that upgraded the
2168        // replica cannot interleave between the guard and the writes, and a
2169        // refusal leaves the replica unchanged.
2170        client
2171            .conn
2172            .execute_batch("BEGIN IMMEDIATE")
2173            .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2174        let startup = (|| -> Result<(), String> {
2175            // The marker guard runs inside the write transaction, so the version
2176            // it validates is the version every write below commits under.
2177            let marker = read_local_schema_version(&client.conn, client.schema.version)?;
2178            // New app indexes may reference columns that only exist after a
2179            // version-bump reset.
2180            client.create_bookkeeping_tables()?;
2181            match client.get_meta(CLIENT_ID_KEY)? {
2182                Some(existing) => match client_id {
2183                    Some(requested) if existing != requested => {
2184                        return Err(format!(
2185                            "client.identity_mismatch: this database belongs to {existing:?}; refusing to rebind it to {requested:?}"
2186                        ))
2187                    }
2188                    _ => client.client_id = existing,
2189                },
2190                None => client.set_meta(CLIENT_ID_KEY, &client.client_id)?,
2191            }
2192            client.restore_persisted_state()?;
2193            client.failed_commits = client.load_failed_commits()?.into();
2194            match marker {
2195                None => {
2196                    client.create_synced_tables()?;
2197                    client.persist_schema_version()?;
2198                    client.save_unit_scope_schema()?;
2199                }
2200                Some(version) if version == client.schema.version => {
2201                    client.create_synced_tables()?;
2202                    // RFC 0005 D1: the same-version open backfills the descriptor
2203                    // for a database first opened by an unaware binary, so the
2204                    // NEXT bump can capture without needing a schema bump first.
2205                    set_local_schema_descriptor(&client.conn, &client.schema)
2206                        .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2207                    client.save_unit_scope_schema()?;
2208                }
2209                Some(_) => client.run_schema_reset()?,
2210            }
2211            // RFC 0005 D9: the reset sweep cannot see a container whose capture
2212            // committed in its OWN file while the replica's savepoint never
2213            // released — a crash at that seam leaves a container beside a matching
2214            // OLD marker, and the next open at that version runs no reset. Discard
2215            // it before anything can read it. No-op when no container exists.
2216            client.reconcile_previous_version_at_boot()?;
2217            client.clear_satisfied_persisted_schema_floor()?;
2218            client.prune_unknown_units(false)?;
2219            // §7.1/§7.4.4: recover intrinsically codec-invalid persisted values at
2220            // the full startup/reset reconciliation boundary, inside this open
2221            // transaction and after the schema and identity guards, so a commit
2222            // an earlier version accepted is dropped with durable rejection
2223            // evidence before any replay. A table the current schema removed
2224            // keeps the §7.4.4 send-time classification, and an unresolved
2225            // encryption key stays with the send seam because hosts configure
2226            // keys after open.
2227            client.drop_unencodable_outbox(false, None)?;
2228            if marker == Some(client.schema.version)
2229                && (!client.outbox.is_empty()
2230                    || !client.failed_commits.is_empty()
2231                    || client.has_acknowledged_rows()?)
2232            {
2233                // Reconstruct the visible optimistic overlay from the durable
2234                // base plus outbox instead of trusting a process-interrupted
2235                // mirror.
2236                client.overlay_dirty.set(true);
2237                client.rebuild_overlay()?;
2238            }
2239            // Every persisted active unit needs one catch-up pull on
2240            // open: realtime only covers changes after connection, while an
2241            // idempotent setWindow correctly creates no fresh command effect.
2242            // Pending outbox work has the same restart requirement. The core
2243            // owns this intent so native hosts never poll or require an
2244            // application-issued sync().
2245            client.enqueue_startup_sync_if_needed()?;
2246            Ok(())
2247        })();
2248        match startup {
2249            Ok(()) => match client.conn.execute_batch("COMMIT") {
2250                // §4.8: an eviction a crash interrupted finishes before any
2251                // read, with or without a transport; a replica reopened in
2252                // preflight finishes it at activation.
2253                Ok(()) => {
2254                    if !client.security_preflight {
2255                        client.drain_pending_evictions()?;
2256                    }
2257                    Ok(client)
2258                }
2259                Err(error) => {
2260                    let failure = Self::sqlite_failure(&client.storage_failure, error);
2261                    if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2262                        // Keep a failed rollback's typed storage classification.
2263                        let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2264                    }
2265                    Err(failure)
2266                }
2267            },
2268            Err(error) => {
2269                if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2270                    // Keep a failed rollback's typed storage classification.
2271                    let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2272                }
2273                Err(error)
2274            }
2275        }
2276    }
2277
2278    /// Pin the client clock (epoch ms) — the §5.4 expiry check runs
2279    /// against this instead of system time (conformance virtual clock).
2280    pub fn set_now_ms(&mut self, now_ms: i64) {
2281        self.now_ms = Some(std::sync::Arc::new(now_ms.into()));
2282    }
2283
2284    /// The pinned clock, shared: a host that stores into it moves the client
2285    /// clock while a call runs (a virtual clock that advances per request).
2286    pub fn pinned_clock(&self) -> Option<std::sync::Arc<std::sync::atomic::AtomicI64>> {
2287        self.now_ms.clone()
2288    }
2289
2290    /// §5.11: install the client-side encryption keys (`keyId → key bytes`).
2291    /// The command router parses these from the `create` command's
2292    /// `encryption` config (keys as `{$bytes: hex}`).
2293    pub fn set_encryption(&mut self, encryption: crate::values::EncryptionConfig) {
2294        self.encryption = encryption;
2295    }
2296
2297    #[must_use]
2298    pub fn security_lifecycle(&self) -> &'static str {
2299        if self.security_preflight {
2300            "preflight"
2301        } else {
2302            "active"
2303        }
2304    }
2305
2306    #[must_use]
2307    pub fn security_preflight(&self) -> bool {
2308        self.security_preflight
2309    }
2310
2311    /// Host-owned, non-persisted network gate. Local operations remain available.
2312    pub fn set_transport_enabled(&mut self, transport: &mut dyn Transport, enabled: bool) {
2313        if self.transport_enabled != enabled {
2314            self.transport_enabled = enabled;
2315            self.transport_epoch = self.transport_epoch.wrapping_add(1);
2316            self.sync_intent_queue.clear();
2317            self.sync_intent_queue
2318                .push_back(if enabled && !self.security_preflight {
2319                    SyncIntent::Interactive
2320                } else {
2321                    SyncIntent::None
2322                });
2323        }
2324        // A captured reply keeps its normal apply/revocation semantics.
2325        if !enabled && self.active_round.is_none() {
2326            self.disconnect_realtime(transport);
2327        }
2328    }
2329
2330    pub fn transport_enabled(&self) -> bool {
2331        self.transport_enabled
2332    }
2333
2334    /// Quarantine this replica: enter the fail-closed gate, release all
2335    /// core-owned key material, and record the gate in the database so
2336    /// reopening re-enters preflight until `activate_security` clears it.
2337    ///
2338    /// Use [`SyncClient::seal_security_on_teardown`] for the shutdown barrier,
2339    /// which must NOT leave that durable mark.
2340    pub fn begin_security_preflight(&mut self) -> Result<(), String> {
2341        let entering = !self.security_preflight;
2342        self.seal_security_on_teardown();
2343        // Persist the quarantine so it survives handle teardown and restart:
2344        // reopening this replica re-enters preflight until activation clears it.
2345        self.set_meta(SECURITY_PREFLIGHT_PENDING_KEY, "1")?;
2346        if entering {
2347            self.emit_status_batch()?;
2348        }
2349        Ok(())
2350    }
2351
2352    /// One change batch carrying the status snapshot (§5.11 lifecycle).
2353    fn emit_status_batch(&mut self) -> Result<(), String> {
2354        self.begin_observation("syncular_status")?;
2355        let batch = ChangeAccumulator {
2356            status: true,
2357            ..ChangeAccumulator::default()
2358        };
2359        self.finish_observation("syncular_status", batch)
2360            .inspect_err(|_| self.rollback_observation("syncular_status"))
2361    }
2362
2363    /// Release core-owned key material as a host tears the client down,
2364    /// WITHOUT recording a quarantine.
2365    ///
2366    /// Shutting an activated client down is not a quarantine event. Persisting
2367    /// the gate here marks every cleanly closed replica as pending, and the
2368    /// next plain `create` is then refused permanently: the reopen path
2369    /// restores the flag from the marker and the create guard rejects it. The
2370    /// in-memory flag still closes the gate for anything still holding this
2371    /// instance, which is all a teardown barrier needs.
2372    pub fn seal_security_on_teardown(&mut self) {
2373        self.cancel_sync_round();
2374        self.security_preflight = true;
2375        self.security_epoch = self.security_epoch.wrapping_add(1);
2376        self.encryption = crate::values::EncryptionConfig::default();
2377        self.sync_intent_queue.clear();
2378    }
2379
2380    /// Install the post-authentication keyring and release the host loop.
2381    pub fn activate_security(
2382        &mut self,
2383        encryption: crate::values::EncryptionConfig,
2384    ) -> Result<(), String> {
2385        if !self.security_preflight {
2386            return Err(
2387                "sync.invalid_request: activateSecurity requires security preflight".to_owned(),
2388            );
2389        }
2390        // §4.8: an interrupted eviction finishes before protected reads open.
2391        self.drain_pending_evictions()?;
2392        self.enqueue_startup_sync_if_needed()?;
2393        self.delete_meta(SECURITY_PREFLIGHT_PENDING_KEY)?;
2394        self.encryption = encryption;
2395        self.security_preflight = false;
2396        // §5.11: rows sealed under a key this keyring now holds open at once.
2397        self.reveal_sealed_rows()
2398            .map_err(|error| format!("{}: {}", error.code, error.message))?;
2399        self.emit_status_batch()
2400    }
2401
2402    fn clock_now_ms(&self) -> i64 {
2403        self.now_ms
2404            .as_ref()
2405            .map_or_else(crate::wall_clock_ms, |clock| {
2406                clock.load(std::sync::atomic::Ordering::Relaxed)
2407            })
2408    }
2409
2410    fn create_bookkeeping_tables(&self) -> Result<(), String> {
2411        let exists = |name: &str| {
2412            self.conn
2413                .query_row(
2414                    "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1)",
2415                    [name],
2416                    |row| row.get::<_, bool>(0),
2417                )
2418                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2419        };
2420        let outbox_existed = exists("_syncular_outbox")?;
2421        // Durable client bookkeeping (outbox + units + meta).
2422        self.conn
2423            .execute_batch(
2424                "CREATE TABLE IF NOT EXISTS _syncular_outbox (
2425                   seq INTEGER PRIMARY KEY AUTOINCREMENT,
2426                   commit_id TEXT NOT NULL UNIQUE, ops_json TEXT NOT NULL,
2427                   created_at_ms INTEGER NOT NULL DEFAULT 0);
2428                 CREATE TABLE IF NOT EXISTS _syncular_row_deliveries (
2429                   tbl TEXT NOT NULL, id TEXT NOT NULL, commit_seq INTEGER NOT NULL, PRIMARY KEY(tbl,id));
2430                 CREATE TABLE IF NOT EXISTS _syncular_acked_rows (
2431                   commit_id TEXT NOT NULL, idx INTEGER NOT NULL, tbl TEXT NOT NULL, id TEXT NOT NULL,
2432                   commit_seq INTEGER NOT NULL, op_json TEXT NOT NULL, intent_json TEXT,
2433                   PRIMARY KEY(commit_id, idx));
2434                 CREATE INDEX IF NOT EXISTS _syncular_acked_rows_row
2435                   ON _syncular_acked_rows(tbl, id);
2436                 CREATE TABLE IF NOT EXISTS _syncular_failed_commits (
2437                   seq INTEGER PRIMARY KEY AUTOINCREMENT, client_commit_id TEXT NOT NULL UNIQUE,
2438                   operations_json TEXT NOT NULL, initial_json TEXT NOT NULL);
2439                 CREATE TABLE IF NOT EXISTS _syncular_commit_outcomes (
2440                   seq INTEGER PRIMARY KEY AUTOINCREMENT,
2441                   client_commit_id TEXT NOT NULL UNIQUE,
2442                   status TEXT NOT NULL CHECK(status IN ('applied', 'cached', 'conflict', 'rejected')),
2443                   recorded_at_ms INTEGER NOT NULL,
2444                   results_json TEXT NOT NULL,
2445                   operations_json TEXT,
2446                   resolution TEXT NOT NULL DEFAULT 'active'
2447                     CHECK(resolution IN ('active', 'resolved_keep_server', 'superseded', 'dismissed')),
2448                   resolved_at_ms INTEGER,
2449                   replacement_client_commit_id TEXT);
2450                 CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq
2451                   ON _syncular_commit_outcomes(resolution, seq);
2452                 CREATE TABLE IF NOT EXISTS _syncular_units (
2453                   id TEXT PRIMARY KEY, scopes TEXT NOT NULL,
2454                   explicit INTEGER NOT NULL DEFAULT 0,
2455                   status TEXT NOT NULL DEFAULT 'active', reason_code TEXT,
2456                   cursor INTEGER DEFAULT -1, bootstrap_state TEXT,
2457                   seeded TEXT NOT NULL DEFAULT '[]', echo TEXT, applied TEXT, restriction TEXT);
2458                 CREATE TABLE IF NOT EXISTS _syncular_meta (
2459                   key TEXT PRIMARY KEY, value TEXT NOT NULL);
2460                 CREATE TABLE IF NOT EXISTS _syncular_windows (
2461                   base TEXT NOT NULL, unit TEXT NOT NULL, sub_id TEXT NOT NULL,
2462                   PRIMARY KEY (base, unit));
2463                 CREATE INDEX IF NOT EXISTS _syncular_windows_unit ON _syncular_windows(sub_id);
2464                 CREATE TABLE IF NOT EXISTS _syncular_pending_evictions (
2465                   unit_id TEXT NOT NULL, tbl TEXT NOT NULL,
2466                   effective_scopes TEXT NOT NULL, PRIMARY KEY (unit_id, tbl));
2467                 CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
2468                   commit_id TEXT NOT NULL, blob_id TEXT NOT NULL,
2469                   PRIMARY KEY(commit_id, blob_id));
2470                 CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body
2471                   ON _syncular_blob_commit_refs(blob_id);",
2472            )
2473            .map_err(|e| e.to_string())?;
2474        // The §5.6 applied-segment record and the §7.4.3 restriction, added
2475        // after the units table shipped.
2476        for column in ["applied", "restriction"] {
2477            if !self
2478                .conn
2479                .prepare("SELECT 1 FROM pragma_table_info('_syncular_units') WHERE name = ?1")
2480                .and_then(|mut stmt| stmt.exists([column]))
2481                .map_err(|e| e.to_string())?
2482            {
2483                self.conn
2484                    .execute_batch(&format!(
2485                        "ALTER TABLE _syncular_units ADD COLUMN {column} TEXT"
2486                    ))
2487                    .map_err(|e| e.to_string())?;
2488            }
2489        }
2490        // An outbox created before `pendingCommits` carried creation times.
2491        let _ = self.conn.execute_batch(
2492            "ALTER TABLE _syncular_outbox ADD COLUMN created_at_ms INTEGER NOT NULL DEFAULT 0",
2493        );
2494        // Migrate an outcome journal created before failed aggregate
2495        // envelopes were retained. Historical rows intentionally stay NULL.
2496        let _ = self
2497            .conn
2498            .execute_batch("ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations_json TEXT");
2499        if self.get_meta(LOCAL_REVISION_KEY)?.is_none() {
2500            self.set_meta(LOCAL_REVISION_KEY, "0")?;
2501        }
2502        // §7.1: `outboxId` names the outbox sequence. A new outbox table starts
2503        // a new sequence, so it replaces the id in the same transaction.
2504        if !outbox_existed || self.get_meta(OUTBOX_ID_KEY)?.is_none() {
2505            self.set_meta(OUTBOX_ID_KEY, &uuid::Uuid::new_v4().to_string())?;
2506        }
2507        // §9: a replica written under wire version 3 keeps its outbox, journal,
2508        // rows and pending evictions and registers its units fresh. Its
2509        // subscriptions, cursors, echoes, resume tokens and window entries go;
2510        // units left from an earlier version 4 life restart.
2511        if exists("_syncular_window_pending_evict")? {
2512            let invalid: bool = self
2513                .conn
2514                .query_row(
2515                    "SELECT EXISTS(SELECT 1 FROM _syncular_window_pending_evict
2516                       WHERE NOT json_valid(effective_scopes)
2517                          OR json_type(effective_scopes) <> 'object'
2518                          OR EXISTS(SELECT 1 FROM json_each(effective_scopes)
2519                               WHERE type <> 'array'
2520                                  OR EXISTS(SELECT 1 FROM json_each(value) AS v
2521                                       WHERE v.type <> 'text')))",
2522                    [],
2523                    |row| row.get(0),
2524                )
2525                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2526            if invalid {
2527                return Err(
2528                    "sync.local_corrupt: a version 3 pending eviction cannot be upgraded"
2529                        .to_owned(),
2530                );
2531            }
2532            self.conn
2533                .execute_batch(
2534                    "INSERT OR REPLACE INTO _syncular_pending_evictions
2535                       SELECT sub_id, tbl, effective_scopes FROM _syncular_window_pending_evict;
2536                     DROP TABLE _syncular_window_pending_evict;
2537                     DROP TABLE IF EXISTS _syncular_subscriptions;
2538                     DELETE FROM _syncular_windows;",
2539                )
2540                .and_then(|()| reset_units(&self.conn, &BTreeSet::new(), None))
2541                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2542        }
2543        // §5.9.7 blob cache. Mutable upload state stays off the body row so
2544        // completing a large upload does not rewrite its BLOB record.
2545        if self.schema_has_blobs() {
2546            if exists("_syncular_blobs")? {
2547                let mut statement = self
2548                    .conn
2549                    .prepare("PRAGMA table_info(_syncular_blobs)")
2550                    .map_err(|e| e.to_string())?;
2551                let mut columns = statement
2552                    .query_map([], |row| row.get::<_, String>(1))
2553                    .map_err(|e| e.to_string())?
2554                    .collect::<Result<Vec<_>, _>>()
2555                    .map_err(|e| e.to_string())?;
2556                columns.sort();
2557                let mut expected = vec![
2558                    "blob_id",
2559                    "byte_length",
2560                    "bytes",
2561                    "created_at_ms",
2562                    "media_type",
2563                ];
2564                expected.sort_unstable();
2565                if columns != expected {
2566                    return Err(
2567                        "sync.schema_mismatch: Local blob schema is incompatible".to_owned()
2568                    );
2569                }
2570            } else {
2571                self.conn
2572                    .execute_batch(
2573                        "CREATE TABLE _syncular_blobs(
2574                           blob_id TEXT PRIMARY KEY,
2575                           bytes BLOB NOT NULL,
2576                           byte_length INTEGER NOT NULL,
2577                           media_type TEXT,
2578                           created_at_ms INTEGER NOT NULL);",
2579                    )
2580                    .map_err(|e| e.to_string())?;
2581            }
2582            self.conn
2583                .execute_batch(
2584                    "CREATE TABLE IF NOT EXISTS _syncular_blob_uploads(
2585                       blob_id TEXT PRIMARY KEY,
2586                       media_type TEXT,
2587                       created_at_ms INTEGER NOT NULL);",
2588                )
2589                .map_err(|e| e.to_string())?;
2590        }
2591        Ok(())
2592    }
2593
2594    /// True iff any synced table declares a `blob_ref` column (§5.9).
2595    fn schema_has_blobs(&self) -> bool {
2596        self.schema
2597            .tables
2598            .iter()
2599            .any(|t| t.columns.iter().any(|c| c.ty == ColumnType::BlobRef))
2600    }
2601
2602    // -- meta (§7.4.1 marker, bookkeeping) ------------------------------------
2603
2604    fn get_meta(&self, key: &str) -> Result<Option<String>, String> {
2605        meta_get(&self.conn, key)
2606            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2607    }
2608
2609    // The caller holds the startup/reset transaction. Either both schema
2610    // records persist or the enclosing operation fails and rolls back.
2611    fn persist_schema_version(&self) -> Result<(), String> {
2612        self.conn
2613            .execute(
2614                "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
2615                rusqlite::params![LOCAL_SCHEMA_VERSION_KEY, self.schema.version.to_string()],
2616            )
2617            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2618        set_local_schema_descriptor(&self.conn, &self.schema)
2619            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2620    }
2621
2622    pub(crate) fn set_meta(&self, key: &str, value: &str) -> Result<(), String> {
2623        meta_set(&self.conn, key, value)
2624            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2625    }
2626
2627    fn delete_meta(&self, key: &str) -> Result<(), String> {
2628        meta_delete(&self.conn, key)
2629            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2630    }
2631
2632    /// §7.1: the durable outbox in FIFO order, in schema-agnostic local form.
2633    fn load_outbox(&self) -> Result<Vec<Arc<OutboxCommit>>, String> {
2634        let mut stmt = self
2635            .conn
2636            .prepare("SELECT commit_id, ops_json FROM _syncular_outbox ORDER BY seq ASC")
2637            .map_err(|error| error.to_string())?;
2638        let rows = stmt
2639            .query_map([], |row| {
2640                Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
2641            })
2642            .map_err(|error| error.to_string())?;
2643        let mut commits = Vec::new();
2644        for row in rows {
2645            let (client_commit_id, raw) = row.map_err(|error| error.to_string())?;
2646            let entries: Vec<Value> = serde_json::from_str(&raw).map_err(|error| {
2647                format!("invalid persisted outbox {client_commit_id:?}: {error}")
2648            })?;
2649            let mut ops = Vec::with_capacity(entries.len());
2650            for entry in entries {
2651                let op = entry.get("op").and_then(Value::as_str).unwrap_or("delete");
2652                ops.push(OutboxOp {
2653                    upsert: op == "upsert",
2654                    table: entry
2655                        .get("table")
2656                        .and_then(Value::as_str)
2657                        .ok_or_else(|| "persisted outbox operation missing table".to_owned())?
2658                        .to_owned(),
2659                    row_id: entry
2660                        .get("rowId")
2661                        .and_then(Value::as_str)
2662                        .ok_or_else(|| "persisted outbox operation missing rowId".to_owned())?
2663                        .to_owned(),
2664                    base_version: entry.get("baseVersion").and_then(Value::as_i64),
2665                    // A legacy entry's `changedFields` key is ignored:
2666                    // the values map is the presence set (§6.1).
2667                    values: entry.get("values").and_then(Value::as_object).cloned(),
2668                    insert: entry.get("insert") == Some(&Value::Bool(true)),
2669                });
2670            }
2671            commits.push(Arc::new(OutboxCommit {
2672                client_commit_id,
2673                ops,
2674            }));
2675        }
2676        Ok(commits)
2677    }
2678
2679    fn restore_persisted_state(&mut self) -> Result<(), String> {
2680        self.outbox = self.load_outbox()?.into();
2681
2682        self.prune_commit_outcomes()?;
2683        let active = self.commit_outcomes(CommitOutcomeQuery {
2684            active_only: true,
2685            ..CommitOutcomeQuery::default()
2686        })?;
2687        self.conflicts = active
2688            .iter()
2689            .flat_map(|outcome| outcome.results.iter())
2690            .filter_map(|result| match result {
2691                CommitOperationOutcome::Conflict { conflict } => Some(conflict.clone()),
2692                _ => None,
2693            })
2694            .collect::<Vec<_>>()
2695            .into();
2696        self.rejections = active
2697            .iter()
2698            .flat_map(|outcome| outcome.results.iter())
2699            .filter_map(|result| match result {
2700                CommitOperationOutcome::Error { rejection } => Some(rejection.clone()),
2701                _ => None,
2702            })
2703            .collect::<Vec<_>>()
2704            .into();
2705
2706        self.lease_state = self
2707            .get_meta(LEASE_STATE_KEY)?
2708            .map(|raw| serde_json::from_str(&raw))
2709            .transpose()
2710            .map_err(|error| format!("invalid persisted lease state: {error}"))?;
2711        self.schema_floor = self
2712            .get_meta(SCHEMA_FLOOR_KEY)?
2713            .map(|raw| serde_json::from_str(&raw))
2714            .transpose()
2715            .map_err(|error| format!("invalid persisted schema floor: {error}"))?;
2716        self.stopped = self.schema_floor.is_some();
2717        // A replica left in unactivated preflight reopens gated: the quarantine
2718        // decision persists with the data across handle teardown and restart.
2719        if self.get_meta(SECURITY_PREFLIGHT_PENDING_KEY)?.as_deref() == Some("1") {
2720            self.security_preflight = true;
2721        }
2722        Ok(())
2723    }
2724
2725    fn save_unit_scope_schema(&self) -> Result<(), String> {
2726        let declarations: BTreeMap<_, BTreeMap<_, _>> = self
2727            .schema
2728            .tables
2729            .iter()
2730            .map(|table| {
2731                (
2732                    table.name.clone(),
2733                    table
2734                        .scope_variables
2735                        .iter()
2736                        .map(|scope| {
2737                            (
2738                                scope.variable.clone(),
2739                                [scope.prefix.clone(), scope.column.clone()],
2740                            )
2741                        })
2742                        .collect(),
2743                )
2744            })
2745            .collect();
2746        self.set_meta(
2747            "subscriptionScopeSchema",
2748            &serde_json::to_string(&declarations).expect("scope schema serialization"),
2749        )?;
2750        let generations: BTreeMap<_, _> = self
2751            .schema
2752            .tables
2753            .iter()
2754            .filter_map(|table| Some((&table.name, table.generation.as_ref()?)))
2755            .collect();
2756        self.set_meta(
2757            TABLE_GENERATIONS_KEY,
2758            &serde_json::to_string(&generations).expect("generations serialize"),
2759        )
2760    }
2761
2762    /// Drop units that cover no table of the running schema, with their window
2763    /// registry rows and pending evictions; never translate scopes. At a bump
2764    /// (§7.4.3) a unit also needs every variable unchanged in prefix and column
2765    /// on every table it covered before.
2766    fn prune_unknown_units(&mut self, bump: bool) -> Result<(), String> {
2767        let previous: Option<BTreeMap<String, BTreeMap<String, [String; 2]>>> = if bump {
2768            self.get_meta("subscriptionScopeSchema")?
2769                .map(|raw| serde_json::from_str(&raw))
2770                .transpose()
2771                .map_err(|_| "sync.local_corrupt: invalid persisted scope schema".to_owned())?
2772        } else {
2773            None
2774        };
2775        // A table keeps the variables' meaning when each has the same prefix
2776        // and column as before. An old binary stored no declaration evidence;
2777        // matching names cannot prove unchanged meaning, so the app registers
2778        // again.
2779        let unchanged = |name: &str, variables: &[&String]| {
2780            let (Some(old), Some(table)) = (
2781                previous.as_ref().and_then(|previous| previous.get(name)),
2782                self.schema.table(name),
2783            ) else {
2784                return false;
2785            };
2786            variables.iter().all(|variable| {
2787                table
2788                    .scope_variables
2789                    .iter()
2790                    .find(|scope| &scope.variable == *variable)
2791                    .is_some_and(|scope| {
2792                        old.get(*variable) == Some(&[scope.prefix.clone(), scope.column.clone()])
2793                    })
2794            })
2795        };
2796        let compatible = |scopes: &UnitScopes| {
2797            if !self.schema.tables.iter().any(|table| covers(table, scopes)) {
2798                return false;
2799            }
2800            if !bump {
2801                return true;
2802            }
2803            let Some(previous) = &previous else {
2804                return false;
2805            };
2806            previous.iter().all(|(name, old)| {
2807                !scopes.keys().all(|variable| old.contains_key(variable))
2808                    || unchanged(name, &scopes.keys().collect::<Vec<_>>())
2809            })
2810        };
2811        let mut stale: BTreeSet<String> = self
2812            .stored(load_units(&self.conn))?
2813            .into_iter()
2814            .filter(|unit| !compatible(&unit.scopes))
2815            .map(|unit| unit.id)
2816            .collect();
2817        // A shrunk window's deferred eviction outlives its unit row and keeps
2818        // its per-table scopes. A table the schema no longer has cannot be
2819        // evicted, and at a bump a table whose scope declarations changed must
2820        // not be evicted by the outdated rule.
2821        for (id, table, effective) in self.load_pending_evictions()? {
2822            if self.schema.table(&table).is_none()
2823                || (bump
2824                    && !unchanged(
2825                        &table,
2826                        &effective
2827                            .iter()
2828                            .map(|(variable, _)| variable)
2829                            .collect::<Vec<_>>(),
2830                    ))
2831            {
2832                stale.insert(id);
2833            }
2834        }
2835        for id in &stale {
2836            for sql in [
2837                "DELETE FROM _syncular_windows WHERE sub_id = ?1",
2838                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
2839                "DELETE FROM _syncular_units WHERE id = ?1",
2840            ] {
2841                self.conn
2842                    .execute(sql, rusqlite::params![id])
2843                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2844            }
2845        }
2846        Ok(())
2847    }
2848
2849    pub fn local_revision(&self) -> Result<u64, String> {
2850        Ok(self
2851            .get_meta(LOCAL_REVISION_KEY)?
2852            .and_then(|value| value.parse().ok())
2853            .unwrap_or(0))
2854    }
2855
2856    /// §7.5: resolve a snapshot read on the mutable owner connection through
2857    /// the same primitive the read-only sidecar uses, so the command surface
2858    /// and the file sidecar return one revision, rows, coverage, catch-up, and
2859    /// delivery shape. The structured [`QueryReadFailure`] is preserved; an
2860    /// `owner` records its failure (and its next success) in diagnostics.
2861    pub fn snapshot_read(
2862        &mut self,
2863        request: &SnapshotReadRequest<'_>,
2864        owner: Option<QueryOwner<'_>>,
2865    ) -> Result<SnapshotRead, QueryReadFailure> {
2866        let result = snapshot_read_connection(&self.conn, request);
2867        if let Some(owner) = owner {
2868            self.record_query_read(owner, result.as_ref().err());
2869        }
2870        result
2871    }
2872
2873    #[must_use]
2874    pub fn status_snapshot(&self) -> SyncStatusSnapshot {
2875        SyncStatusSnapshot {
2876            current_schema_version: self.schema.version,
2877            outbox: self.outbox.len(),
2878            upgrading: self.upgrading,
2879            lease_state: self.lease_state.clone(),
2880            schema_floor: self.schema_floor.clone(),
2881            sync_needed: self.sync_needed,
2882            previous_version_context: self.previous_version_status(),
2883            security_lifecycle: self.security_lifecycle(),
2884        }
2885    }
2886
2887    /// RFC 0005 A2: container presence for a host that must act on it (Diego's
2888    /// rollback precondition), read without creating the file.
2889    fn previous_version_status(&self) -> PreviousVersionStatus {
2890        let Some(replica_path) = self.previous_version_replica_path() else {
2891            return PreviousVersionStatus {
2892                present: false,
2893                created_at_ms: None,
2894            };
2895        };
2896        match crate::previous_version::read_previous_version_record(&replica_path) {
2897            Ok(Some(record)) => PreviousVersionStatus {
2898                present: true,
2899                created_at_ms: Some(record.created_at_ms),
2900            },
2901            _ => PreviousVersionStatus {
2902                present: std::path::Path::new(
2903                    &crate::previous_version::previous_version_container_path(&replica_path),
2904                )
2905                .exists(),
2906                created_at_ms: None,
2907            },
2908        }
2909    }
2910
2911    /// RFC 0005 D7: read captured rows from the previous local schema. `state`
2912    /// is always `previousVersion`; the container never makes
2913    /// `query_snapshot()` coverage complete. Lease stop/expiry, scope
2914    /// revocation, coverage completion and the TTL DISCARD the container and
2915    /// close the read with their own reason.
2916    pub fn previous_version_snapshot(
2917        &self,
2918        spec: &PreviousVersionReadSpec,
2919    ) -> Result<PreviousVersionSnapshot, String> {
2920        let now_ms = self.clock_now_ms();
2921        crate::previous_version::previous_version_snapshot(
2922            &self.conn,
2923            self.previous_version_replica_path().as_deref(),
2924            self.previous_version.as_ref(),
2925            PreviousVersionLifecycle {
2926                lease_inactive: self.previous_version_lease_inactive(now_ms),
2927                scope_revoked: self
2928                    .stored(load_units(&self.conn))?
2929                    .iter()
2930                    .any(|unit| unit.status == UnitStatus::Revoked),
2931                coverage_complete: self.previous_version_coverage_complete()?,
2932            },
2933            now_ms,
2934            self.schema.version,
2935            spec,
2936        )
2937    }
2938
2939    /// RFC 0005 D6: the advisory pre-reset compatibility audit.
2940    pub fn previous_version_audit(
2941        &self,
2942    ) -> Result<Option<crate::previous_version::PreviousVersionAudit>, String> {
2943        crate::previous_version::stored_previous_version_audit(&self.conn)
2944            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2945    }
2946
2947    /// RFC 0005 A2/D9: the executable downgrade step. Drop the container file
2948    /// and both metadata records, and report whether anything was present.
2949    /// Idempotent: absence is a successful no-op.
2950    pub fn previous_version_discard(
2951        &self,
2952    ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2953        self.drop_previous_version()
2954    }
2955
2956    fn drop_previous_version(
2957        &self,
2958    ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2959        let Some(replica_path) = self.previous_version_replica_path() else {
2960            return Ok(crate::previous_version::PreviousVersionDiscardOutcome {
2961                present: false,
2962                discarded: false,
2963            });
2964        };
2965        crate::previous_version::discard_previous_version(&self.conn, &replica_path)
2966    }
2967
2968    /// RFC 0005 D7: `leaseState.errorCode` or an expired lease.
2969    fn previous_version_lease_inactive(&self, now_ms: i64) -> bool {
2970        let Some(lease) = &self.lease_state else {
2971            return false;
2972        };
2973        if lease.error_code.is_some() {
2974            return true;
2975        }
2976        lease.expires_at_ms.is_some_and(|expires| expires <= now_ms)
2977    }
2978
2979    /// RFC 0005 D7: §7.4.5 replacement coverage — no active unit is
2980    /// bootstrapping. An empty active set is not completion (mirrors the TS
2981    /// predicate exactly).
2982    fn previous_version_coverage_complete(&self) -> Result<bool, String> {
2983        let units = self.stored(load_units(&self.conn))?;
2984        let mut active = units
2985            .iter()
2986            .filter(|unit| unit.status == UnitStatus::Active)
2987            .peekable();
2988        Ok(active.peek().is_some() && !active.any(UnitRecord::bootstrapping))
2989    }
2990
2991    /// RFC 0005 D7: lifetime triggers evaluated once per sync round, after the
2992    /// apply. A container that no longer has a reason to exist is discarded so
2993    /// the rows do not outlive the window they were kept for.
2994    fn previous_version_lifetime_check(&self) {
2995        let Some(config) = self.previous_version.filter(|config| config.enabled) else {
2996            return;
2997        };
2998        let now_ms = self.clock_now_ms();
2999        if self.previous_version_lease_inactive(now_ms) {
3000            let _ = self.drop_previous_version();
3001            return;
3002        }
3003        let Some(replica_path) = self.previous_version_replica_path() else {
3004            return;
3005        };
3006        let Ok(Some(record)) = crate::previous_version::read_previous_version_record(&replica_path)
3007        else {
3008            return;
3009        };
3010        let Ok(units) = load_units(&self.conn) else {
3011            return;
3012        };
3013        if units.iter().any(|unit| unit.status == UnitStatus::Revoked) {
3014            let _ = self.drop_previous_version();
3015            return;
3016        }
3017        if now_ms - record.created_at_ms > config.max_age_ms {
3018            let _ = self.drop_previous_version();
3019            return;
3020        }
3021        if self.previous_version_coverage_complete() == Ok(true) {
3022            let _ = self.drop_previous_version();
3023        }
3024    }
3025
3026    pub fn diagnostics_snapshot(&self) -> Result<ClientDiagnosticsSnapshot, String> {
3027        let registered = self.stored(load_units(&self.conn))?;
3028        // Both meta values in one statement: the FFI host recomputes
3029        // diagnostics after every command.
3030        let (local_revision, replica_cursor): (Option<String>, Option<String>) = self.stored(
3031            self.conn
3032                .prepare_cached(
3033                    "SELECT (SELECT value FROM _syncular_meta WHERE key = ?1),
3034                            (SELECT value FROM _syncular_meta WHERE key = ?2)",
3035                )
3036                .and_then(|mut statement| {
3037                    statement.query_row([LOCAL_REVISION_KEY, REPLICA_CURSOR_KEY], |row| {
3038                        Ok((row.get(0)?, row.get(1)?))
3039                    })
3040                }),
3041        )?;
3042        let mut units = DiagnosticUnits::default();
3043        for unit in &registered {
3044            *match unit.status {
3045                UnitStatus::Revoked => &mut units.revoked,
3046                UnitStatus::Failed => &mut units.failed,
3047                UnitStatus::Active if !unit.bootstrapping() => &mut units.complete,
3048                UnitStatus::Active
3049                    if unit.reason_code.as_deref() == Some("sync.cursor_expired") =>
3050                {
3051                    &mut units.reset
3052                }
3053                UnitStatus::Active => &mut units.bootstrapping,
3054            } += 1;
3055        }
3056        units.reason_codes = registered
3057            .iter()
3058            .filter_map(|unit| unit.reason_code.as_deref().map(Self::diagnostic_code))
3059            .collect::<BTreeSet<_>>()
3060            .into_iter()
3061            .collect();
3062        let captured_at_ms = self.clock_now_ms();
3063        let lease = if let Some(error_code) = self
3064            .lease_state
3065            .as_ref()
3066            .and_then(|state| state.error_code.clone())
3067        {
3068            ClientDiagnosticsLease {
3069                state: "stopped".to_owned(),
3070                expires_at_ms: self
3071                    .lease_state
3072                    .as_ref()
3073                    .and_then(|state| state.expires_at_ms),
3074                error_code: Some(Self::diagnostic_code(&error_code)),
3075            }
3076        } else if let Some(expires_at_ms) = self
3077            .lease_state
3078            .as_ref()
3079            .and_then(|state| state.expires_at_ms)
3080        {
3081            ClientDiagnosticsLease {
3082                state: if expires_at_ms <= captured_at_ms {
3083                    "expired".to_owned()
3084                } else {
3085                    "active".to_owned()
3086                },
3087                expires_at_ms: Some(expires_at_ms),
3088                error_code: None,
3089            }
3090        } else {
3091            ClientDiagnosticsLease {
3092                state: "none".to_owned(),
3093                expires_at_ms: None,
3094                error_code: None,
3095            }
3096        };
3097        let connectivity = match self.last_round.as_ref() {
3098            _ if !self.transport_enabled && self.active_round.is_none() => "offline",
3099            Some(round) if round.status == "succeeded" => "online",
3100            Some(round)
3101                if round.status == "failed"
3102                    && matches!(
3103                        round.cause_kind,
3104                        Some(
3105                            crate::TransportCauseKind::Network | crate::TransportCauseKind::Connect
3106                        )
3107                    ) =>
3108            {
3109                "offline"
3110            }
3111            Some(round) if round.status == "failed" && round.http_status.is_some() => "online",
3112            _ => "unknown",
3113        };
3114        Ok(ClientDiagnosticsSnapshot {
3115            version: CLIENT_DIAGNOSTICS_VERSION,
3116            captured_at_ms,
3117            host: ClientDiagnosticsHost {
3118                kind: "direct".to_owned(),
3119                role: "single".to_owned(),
3120                connectivity: connectivity.to_owned(),
3121                realtime: self.realtime_state,
3122                realtime_policy: self.realtime_policy,
3123                realtime_reason_code: self.realtime_reason_code.clone(),
3124                realtime_retry_delay_ms: self.realtime_retry_delay_ms,
3125            },
3126            security_lifecycle: self.security_lifecycle().to_owned(),
3127            schema: ClientDiagnosticsSchema {
3128                current_version: self.schema.version,
3129                upgrading: self.upgrading,
3130                required_version: self
3131                    .schema_floor
3132                    .as_ref()
3133                    .and_then(|floor| floor.required_schema_version),
3134                latest_version: self
3135                    .schema_floor
3136                    .as_ref()
3137                    .and_then(|floor| floor.latest_schema_version),
3138            },
3139            replica: ClientDiagnosticsReplica {
3140                local_revision: local_revision
3141                    .and_then(|value| value.parse::<u64>().ok())
3142                    .unwrap_or(0)
3143                    .to_string(),
3144                sync_needed: self.sync_needed,
3145                pending_outbox: self.outbox.len(),
3146            },
3147            lease,
3148            active_units: registered
3149                .iter()
3150                .filter(|unit| unit.status == UnitStatus::Active)
3151                .count(),
3152            units,
3153            replica_cursor: replica_cursor.map_or(Ok(-1), |raw| {
3154                raw.parse()
3155                    .map_err(|_| "sync.local_corrupt: persisted unit state is invalid".to_owned())
3156            })?,
3157            last_round: self.last_round.clone(),
3158            last_change: self.last_change.clone(),
3159            storage: self.diagnostics_storage(),
3160            query_failures: self.query_failures.clone(),
3161        })
3162    }
3163
3164    fn diagnostics_storage(&self) -> ClientDiagnosticsStorage {
3165        let read = || -> Result<ClientDiagnosticsStorage, rusqlite::Error> {
3166            let page_count: i64 = self
3167                .conn
3168                .query_row("PRAGMA page_count", [], |row| row.get(0))?;
3169            let page_size: i64 = self
3170                .conn
3171                .query_row("PRAGMA page_size", [], |row| row.get(0))?;
3172            // One cached aggregate, since the FFI host recomputes diagnostics
3173            // after every command; every invocation still reads current storage.
3174            let (outbox_bytes, outcome_entries, outcome_bytes): (i64, i64, i64) = self
3175                .conn
3176                .prepare_cached(
3177                    "SELECT (SELECT COALESCE(SUM(LENGTH(ops_json)), 0) FROM _syncular_outbox),
3178                            COUNT(*), COALESCE(SUM(LENGTH(results_json) + COALESCE(LENGTH(operations_json), 0)), 0)
3179                       FROM _syncular_commit_outcomes",
3180                )?
3181                .query_row([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?;
3182            let blob_bytes = if self.schema_has_blobs() {
3183                self.conn
3184                    .prepare_cached("SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs")?
3185                    .query_row([], |row| row.get(0))?
3186            } else {
3187                0
3188            };
3189            let pressure = self
3190                .limits
3191                .blob_cache_max_bytes
3192                .is_some_and(|limit| blob_bytes > limit);
3193            Ok(ClientDiagnosticsStorage {
3194                status: if pressure { "pressure" } else { "healthy" }.to_owned(),
3195                database_bytes_approx: Some(page_count.saturating_mul(page_size).max(0)),
3196                pending_outbox_bytes_approx: Some(outbox_bytes.max(0)),
3197                retained_outcome_bytes_approx: Some(outcome_bytes.max(0)),
3198                retained_outcome_entries: Some(outcome_entries.max(0)),
3199                blob_cache_bytes_approx: Some(blob_bytes.max(0)),
3200                pressure_reason_code: pressure.then(|| "client.blob_cache_over_limit".to_owned()),
3201            })
3202        };
3203        read().unwrap_or_else(|_| ClientDiagnosticsStorage {
3204            status: "unreadable".to_owned(),
3205            database_bytes_approx: None,
3206            pending_outbox_bytes_approx: None,
3207            retained_outcome_bytes_approx: None,
3208            retained_outcome_entries: None,
3209            blob_cache_bytes_approx: None,
3210            pressure_reason_code: None,
3211        })
3212    }
3213
3214    pub fn drain_change_batches(&mut self) -> Vec<ClientChangeBatch> {
3215        self.change_queue.drain(..).collect()
3216    }
3217
3218    pub fn drain_sync_intents(&mut self) -> Vec<SyncIntent> {
3219        let intents = self.sync_intent_queue.drain(..).collect();
3220        if self.transport_enabled {
3221            intents
3222        } else {
3223            vec![SyncIntent::None]
3224        }
3225    }
3226
3227    /// §8.7 host announcement: the number of `scopes` events received since
3228    /// the last drain. The event changes no sync state; the host surfaces each
3229    /// one to the app, whose discovery registers the newly readable units.
3230    pub fn drain_scopes_changed(&mut self) -> usize {
3231        std::mem::take(&mut self.scopes_changed)
3232    }
3233
3234    fn schedule_background_retry(&mut self) -> u64 {
3235        let delay_ms = self.retry_delay_ms;
3236        self.sync_intent_queue
3237            .push_back(SyncIntent::Background { delay_ms });
3238        self.retry_delay_ms = (self.retry_delay_ms * 2).min(30_000);
3239        self.round_retry_delay_ms = Some(delay_ms);
3240        delay_ms
3241    }
3242
3243    fn reset_background_retry(&mut self) {
3244        self.retry_delay_ms = 250;
3245    }
3246
3247    fn retryable_transport_code(code: &str) -> bool {
3248        code == "transport.failed"
3249            || code == "transport.timeout"
3250            || code == "transport.unavailable"
3251            || code == "sync.transport_failed"
3252    }
3253
3254    /// §1.8: the transport reported a refused or unreachable endpoint. The
3255    /// native transport says `connect` (DNS failure, connection refused,
3256    /// reset, or aborted); a browser fetch transport says `network`. Repeating
3257    /// the request on a backoff repairs neither, so no retry is scheduled.
3258    fn unreachable_transport(details: &Option<serde_json::Value>) -> bool {
3259        matches!(
3260            details
3261                .as_ref()
3262                .and_then(|details| details.get("causeKind"))
3263                .and_then(serde_json::Value::as_str),
3264            Some("connect" | "network")
3265        )
3266    }
3267
3268    /// §1.5: a segment fetch that fails inside an otherwise complete round is
3269    /// invisible to the server (the round response arrived whole), so its code
3270    /// rides the following requests like a socket-round failure. A code the
3271    /// frame grammar rejects is not reportable and the previous code stays.
3272    fn segment_fetch_failed(&mut self, error: TransportError) -> SectionError {
3273        if ssp2::model::valid_round_failure_code(&error.code) {
3274            self.round_failure = Some(error.code.clone());
3275        }
3276        SectionError::Transport(error)
3277    }
3278
3279    /// A failed round worth a background retry: a transport failure, or a
3280    /// §10.2 code the catalog marks retryable (clients may hardcode the
3281    /// catalog metadata, §10.1). Matches the TypeScript core, which retries
3282    /// on the server's `retryable` flag.
3283    fn retryable_failure_code(code: &str) -> bool {
3284        Self::retryable_transport_code(code)
3285            || matches!(
3286                code,
3287                "sync.auth_required"
3288                    | "sync.auth_lease_required"
3289                    | "sync.auth_lease_revoked"
3290                    | "sync.internal_error"
3291                    | "sync.idempotency_cache_miss"
3292                    | "sync.schema_not_ready"
3293                    | "sync.segment_expired"
3294                    | "sync.rate_limited"
3295                    | "sync.websocket_connection_limit"
3296                    | "sync.idle_timeout"
3297            )
3298    }
3299
3300    fn diagnostic_code(code: &str) -> String {
3301        let valid = !code.is_empty()
3302            && code.len() <= 96
3303            && code.contains('.')
3304            && code
3305                .bytes()
3306                .next()
3307                .is_some_and(|byte| byte.is_ascii_lowercase())
3308            && code.bytes().all(|byte| {
3309                byte.is_ascii_lowercase()
3310                    || byte.is_ascii_digit()
3311                    || matches!(byte, b'.' | b'_' | b'-')
3312            });
3313        if valid {
3314            code.to_owned()
3315        } else {
3316            "client.unknown_failure".to_owned()
3317        }
3318    }
3319
3320    fn set_sync_needed(&mut self, value: bool, interactive: bool) {
3321        if self.sync_needed != value {
3322            if self.begin_observation("syncular_status").is_ok() {
3323                self.sync_needed = value;
3324                let batch = ChangeAccumulator {
3325                    status: true,
3326                    ..ChangeAccumulator::default()
3327                };
3328                if self.finish_observation("syncular_status", batch).is_err() {
3329                    self.rollback_observation("syncular_status");
3330                }
3331            } else {
3332                self.sync_needed = value;
3333            }
3334        }
3335        if value && interactive {
3336            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3337        }
3338    }
3339
3340    /// A unit-store result: a row that does not parse is `sync.local_corrupt`;
3341    /// every other SQLite error keeps its storage classification.
3342    fn stored<T>(&self, result: rusqlite::Result<T>) -> Result<T, String> {
3343        result.map_err(|error| match error {
3344            rusqlite::Error::FromSqlConversionFailure(..) => {
3345                "sync.local_corrupt: persisted unit state is invalid".to_owned()
3346            }
3347            error => Self::sqlite_failure(&self.storage_failure, error),
3348        })
3349    }
3350
3351    fn sqlite_failure(
3352        storage_failure: &RefCell<Option<QueryReadFailure>>,
3353        error: rusqlite::Error,
3354    ) -> String {
3355        let message = error.to_string();
3356        let failure = QueryReadFailure::from(error);
3357        let code = failure.code;
3358        if code.is_some() && storage_failure.borrow().is_none() {
3359            *storage_failure.borrow_mut() = Some(failure);
3360        }
3361        match code {
3362            Some(code) => format!("{code}: {message}"),
3363            None => message,
3364        }
3365    }
3366
3367    fn begin_observation(&self, name: &str) -> Result<(), String> {
3368        if let Some(failure) = &self.coalesced_failure {
3369            return Err(failure.clone());
3370        }
3371        // SQLite rolls a whole transaction back on some I/O and capacity
3372        // errors; later frames must not commit on their own after that.
3373        if self.coalesced.is_some() && self.conn.is_autocommit() {
3374            return Err("the coalesced apply transaction was rolled back".to_owned());
3375        }
3376        self.conn
3377            .execute_batch(&format!("SAVEPOINT {name}"))
3378            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3379    }
3380
3381    /// SPEC §1.4 rule 4: open a coalesced apply transaction unless a caller
3382    /// already owns one.
3383    fn begin_coalesced_apply(&mut self) -> Result<(), String> {
3384        if self.coalesced.is_some() || !self.conn.is_autocommit() {
3385            return Ok(());
3386        }
3387        self.conn
3388            .execute_batch("BEGIN")
3389            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3390        self.coalesced = Some(CoalescedApply {
3391            rows: 0,
3392            rollback: self.capture(),
3393        });
3394        Ok(())
3395    }
3396
3397    fn capture(&self) -> Rollback {
3398        Rollback {
3399            outbox: self.outbox.clone(),
3400            failed_commits: self.failed_commits.clone(),
3401            conflicts: self.conflicts.clone(),
3402            rejections: self.rejections.clone(),
3403            schema_floor: self.schema_floor.clone(),
3404            lease_state: self.lease_state.clone(),
3405            stopped: self.stopped,
3406            upgrading: self.upgrading,
3407            sync_needed: self.sync_needed,
3408            active_round: self.active_round,
3409            overlay_dirty: self.overlay_dirty.snapshot(),
3410            change_queue: self.change_queue.len(),
3411            sync_intent_queue: self.sync_intent_queue.len(),
3412            last_change: self.last_change.clone(),
3413        }
3414    }
3415
3416    fn restore(&mut self, rollback: Rollback) {
3417        self.outbox = rollback.outbox;
3418        self.failed_commits = rollback.failed_commits;
3419        self.conflicts = rollback.conflicts;
3420        self.rejections = rollback.rejections;
3421        self.schema_floor = rollback.schema_floor;
3422        self.lease_state = rollback.lease_state;
3423        self.stopped = rollback.stopped;
3424        self.upgrading = rollback.upgrading;
3425        self.sync_needed = rollback.sync_needed;
3426        self.active_round = rollback.active_round;
3427        self.overlay_dirty.restore(rollback.overlay_dirty);
3428        self.change_queue.truncate(rollback.change_queue);
3429        self.sync_intent_queue.truncate(rollback.sync_intent_queue);
3430        self.last_change = rollback.last_change;
3431    }
3432
3433    /// Account the rows of the next frame or block. A unit that would take the
3434    /// coalesced transaction past the bound commits the earlier units first.
3435    fn coalesce_unit(&mut self, rows: usize) -> Result<(), String> {
3436        let Some(open) = &self.coalesced else {
3437            return Ok(());
3438        };
3439        if open.rows > 0 && open.rows + rows > COALESCED_APPLY_ROWS {
3440            self.commit_coalesced_apply()?;
3441            self.begin_coalesced_apply()?;
3442        }
3443        if let Some(open) = &mut self.coalesced {
3444            open.rows += rows;
3445        }
3446        Ok(())
3447    }
3448
3449    /// COMMIT the coalesced transaction. A failed COMMIT rolls every coalesced
3450    /// frame back, restores the in-memory state of its `BEGIN`, drops the
3451    /// change batches and sync intents queued since, and fails the rest of the
3452    /// response.
3453    fn commit_coalesced_apply(&mut self) -> Result<(), String> {
3454        let Some(open) = self.coalesced.take() else {
3455            return Ok(());
3456        };
3457        let committed = if self.conn.is_autocommit() {
3458            Err("the coalesced apply transaction was rolled back".to_owned())
3459        } else {
3460            self.conn
3461                .execute_batch("COMMIT")
3462                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3463        };
3464        let Err(error) = committed else {
3465            return Ok(());
3466        };
3467        if !self.conn.is_autocommit() {
3468            if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3469                let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3470            }
3471        }
3472        self.restore(open.rollback);
3473        self.coalesced_failure = Some(error.clone());
3474        Err(error)
3475    }
3476
3477    /// End the response's coalescing: COMMIT what is open and clear a failure.
3478    fn finish_coalesced_apply(&mut self) -> Result<(), String> {
3479        let committed = self.commit_coalesced_apply();
3480        match self.coalesced_failure.take() {
3481            Some(failure) => Err(failure),
3482            None => committed,
3483        }
3484    }
3485
3486    fn rollback_observation(&self, name: &str) {
3487        if let Err(error) = self
3488            .conn
3489            .execute_batch(&format!("ROLLBACK TO {name}; RELEASE {name}"))
3490        {
3491            if let Some(failure) = self.storage_failure.borrow_mut().as_mut() {
3492                if failure.rollback_failure.is_none() {
3493                    failure.rollback_failure = Some(Box::new(QueryReadFailure::from(error)));
3494                }
3495            }
3496        }
3497    }
3498
3499    fn finish_observation(
3500        &mut self,
3501        name: &str,
3502        mut batch: ChangeAccumulator,
3503    ) -> Result<(), String> {
3504        #[cfg(feature = "bench-internals")]
3505        let _phase = self.benchmark_phases.start(Phase::ObservationCommit);
3506        if self.failed_commits.iter().any(|(commit, _)| {
3507            commit
3508                .ops
3509                .iter()
3510                .any(|operation| batch.tables.contains_key(&operation.table))
3511        }) {
3512            batch.outcomes = true;
3513        }
3514        if !batch.touched() {
3515            self.conn
3516                .execute_batch(&format!("RELEASE {name}"))
3517                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3518            return Ok(());
3519        }
3520        let revision = self
3521            .local_revision()?
3522            .checked_add(1)
3523            .ok_or_else(|| "local revision exhausted u64".to_owned())?;
3524        self.conn
3525            .execute(
3526                "INSERT OR REPLACE INTO _syncular_meta(key, value) VALUES (?1, ?2)",
3527                rusqlite::params![LOCAL_REVISION_KEY, revision.to_string()],
3528            )
3529            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3530        let status = batch.status.then(|| self.status_snapshot());
3531        let event = ClientChangeBatch {
3532            revision: revision.to_string(),
3533            tables: batch
3534                .tables
3535                .into_iter()
3536                .map(|(table, scope_keys)| TableChange {
3537                    table,
3538                    scope_keys: scope_keys.map(|keys| keys.into_iter().collect()),
3539                })
3540                .collect(),
3541            windows: batch
3542                .windows
3543                .into_iter()
3544                .map(|(base_key, units)| WindowChange {
3545                    base_key,
3546                    units: units.into_iter().collect(),
3547                })
3548                .collect(),
3549            status,
3550            conflicts_changed: batch.conflicts,
3551            rejections_changed: batch.rejections,
3552            outcomes_changed: batch.outcomes,
3553            applied_commits: Vec::new(),
3554        };
3555        self.conn
3556            .execute_batch(&format!("RELEASE {name}"))
3557            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3558        let mut diagnostic_tables = event
3559            .tables
3560            .iter()
3561            .map(|entry| entry.table.clone())
3562            .collect::<BTreeSet<_>>()
3563            .into_iter()
3564            .collect::<Vec<_>>();
3565        // §7.6: the selected variables of the changed window bases.
3566        let mut diagnostic_windows = event
3567            .windows
3568            .iter()
3569            .map(|entry| {
3570                entry
3571                    .base_key
3572                    .split('\0')
3573                    .next()
3574                    .unwrap_or_default()
3575                    .to_owned()
3576            })
3577            .collect::<BTreeSet<_>>()
3578            .into_iter()
3579            .collect::<Vec<_>>();
3580        let domains_truncated = diagnostic_tables.len() > MAX_DIAGNOSTIC_DOMAINS
3581            || diagnostic_windows.len() > MAX_DIAGNOSTIC_DOMAINS;
3582        diagnostic_tables.truncate(MAX_DIAGNOSTIC_DOMAINS);
3583        diagnostic_windows.truncate(MAX_DIAGNOSTIC_DOMAINS);
3584        self.last_change = Some(DiagnosticLastChange {
3585            revision: event.revision.clone(),
3586            recorded_at_ms: self.clock_now_ms(),
3587            tables: diagnostic_tables,
3588            windows: diagnostic_windows,
3589            domains_truncated,
3590            status_changed: event.status.is_some(),
3591            conflicts_changed: event.conflicts_changed,
3592            rejections_changed: event.rejections_changed,
3593            outcomes_changed: event.outcomes_changed,
3594        });
3595        self.change_queue.push_back(event);
3596        Ok(())
3597    }
3598
3599    fn record_scope_map(
3600        &self,
3601        batch: &mut ChangeAccumulator,
3602        table_name: &str,
3603        scopes: &[(String, Vec<String>)],
3604    ) {
3605        let Some(table) = self.schema.table(table_name) else {
3606            return;
3607        };
3608        // A bulk scoped delete whose map leaves a declared variable unnamed
3609        // cannot list the deleted rows' keys for it: the change is table-wide.
3610        if table.scope_variables.iter().any(|scope| {
3611            !scopes
3612                .iter()
3613                .any(|(variable, _)| *variable == scope.variable)
3614        }) {
3615            batch.table(table_name);
3616            return;
3617        }
3618        for (variable, values) in scopes {
3619            let Some(scope) = table
3620                .scope_variables
3621                .iter()
3622                .find(|scope| &scope.variable == variable)
3623            else {
3624                continue;
3625            };
3626            for value in values {
3627                batch.scope(table_name, format!("{}:{value}", scope.prefix));
3628            }
3629        }
3630    }
3631
3632    /// Record a row's current scope keys from the base or visible table.
3633    fn record_row_scopes(
3634        &self,
3635        batch: &mut ChangeAccumulator,
3636        table_name: &str,
3637        row_id: &str,
3638        base: bool,
3639    ) -> bool {
3640        let Some(table) = self.schema.table(table_name) else {
3641            return false;
3642        };
3643        if table.scope_variables.is_empty() {
3644            return false;
3645        }
3646        let columns = table
3647            .scope_variables
3648            .iter()
3649            .map(|scope| quote_ident(&scope.column))
3650            .collect::<Vec<_>>()
3651            .join(", ");
3652        let full_table = if base {
3653            base_table(table_name)
3654        } else {
3655            visible_table(table_name)
3656        };
3657        let sql = format!(
3658            "SELECT {columns} FROM {full_table} WHERE {} LIMIT 1",
3659            row_id_predicate(table)
3660        );
3661        let Ok(mut stmt) = self.conn.prepare_cached(&sql) else {
3662            return false;
3663        };
3664        let values = stmt.query_row(rusqlite::params![row_id], |row| {
3665            let mut values = Vec::with_capacity(table.scope_variables.len());
3666            for index in 0..table.scope_variables.len() {
3667                values.push(row.get::<_, Option<String>>(index)?);
3668            }
3669            Ok(values)
3670        });
3671        let Ok(values) = values else {
3672            return false;
3673        };
3674        let mut recorded = false;
3675        for (scope, value) in table.scope_variables.iter().zip(values) {
3676            if let Some(value) = value {
3677                batch.scope(table_name, format!("{}:{value}", scope.prefix));
3678                recorded = true;
3679            }
3680        }
3681        recorded
3682    }
3683
3684    fn record_commit_changes(
3685        &self,
3686        batch: &mut ChangeAccumulator,
3687        tables: &[String],
3688        changes: &[ssp2::model::Change],
3689    ) {
3690        #[cfg(feature = "bench-internals")]
3691        let _phase = self.benchmark_phases.start(Phase::ObservationPrepare);
3692        for change in changes {
3693            let Some(table_name) = tables.get(change.table_index as usize) else {
3694                continue;
3695            };
3696            let mut precise = self.record_row_scopes(batch, table_name, &change.row_id, true);
3697            if let Some(table) = self.schema.table(table_name) {
3698                for (variable, value) in &change.scopes {
3699                    if let Some(scope) = table
3700                        .scope_variables
3701                        .iter()
3702                        .find(|scope| &scope.variable == variable)
3703                    {
3704                        batch.scope(table_name, format!("{}:{value}", scope.prefix));
3705                        precise = true;
3706                    }
3707                }
3708            }
3709            if !precise {
3710                batch.table(table_name);
3711            }
3712        }
3713    }
3714
3715    /// Whether a base or visible row matches the scope predicate; `false`
3716    /// without a local scope-column mapping. A SQLite failure is an error.
3717    fn scoped_rows_exist(
3718        &self,
3719        table_name: &str,
3720        effective: &[(String, Vec<String>)],
3721        owners: &[Vec<(String, Vec<String>)>],
3722    ) -> Result<bool, String> {
3723        let Some(table) = self.schema.table(table_name) else {
3724            return Ok(false);
3725        };
3726        let Ok(Some((predicate, params))) = local_scope_predicate(table, effective, owners) else {
3727            return Ok(false);
3728        };
3729        for source in [base_table(table_name), visible_table(table_name)] {
3730            if self
3731                .conn
3732                .query_row(
3733                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
3734                    rusqlite::params_from_iter(&params),
3735                    |row| row.get::<_, bool>(0),
3736                )
3737                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
3738            {
3739                return Ok(true);
3740            }
3741        }
3742        Ok(false)
3743    }
3744
3745    /// §5.6 first-page clear of `unit_id`'s pair: delete its rows except
3746    /// those another owner covers (§3.3), failing closed without a local
3747    /// scope-column mapping. Owners are read only when a row matches, inside
3748    /// the caller's transaction. Returns whether rows matched.
3749    fn clear_scope(
3750        &mut self,
3751        table: &TableSchema,
3752        effective: &[(String, Vec<String>)],
3753        unit_id: &str,
3754    ) -> Result<bool, SectionError> {
3755        let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
3756        let matched = self
3757            .scoped_rows_exist(&table.name, effective, &[])
3758            .map_err(storage)?;
3759        let owners = if matched {
3760            unit_owners(
3761                &self.stored(load_units(&self.conn)).map_err(storage)?,
3762                table,
3763                unit_id,
3764            )
3765        } else {
3766            Vec::new()
3767        };
3768        let changed = matched
3769            && (owners.is_empty()
3770                || self
3771                    .scoped_rows_exist(&table.name, effective, &owners)
3772                    .map_err(storage)?);
3773        if !self
3774            .purge_scope_rows(&table.name, effective, &owners)
3775            .map_err(storage)?
3776        {
3777            return Err(SectionError::FailClosed);
3778        }
3779        Ok(changed)
3780    }
3781
3782    /// §7.4.5: true while a schema-bump reset + first re-bootstrap runs.
3783    pub fn upgrading(&self) -> bool {
3784        self.upgrading
3785    }
3786
3787    /// §7.4.2 "app ships new code": swap to a NEW generated schema while
3788    /// keeping this client's local database (identity, outbox, tables). The
3789    /// §7.4.1 marker check then fires the wipe/re-bootstrap flow when the
3790    /// version increases. Recreation runs the same marker guard as opening
3791    /// a durable replica, holds the guard and every write it authorizes under
3792    /// one write transaction, and preserves the current client (compiled
3793    /// schema, outbox, tables) on refusal.
3794    pub fn recreate_with_schema(&mut self, schema_json: &Value) -> Result<(), String> {
3795        let new_schema = parse_schema_json(schema_json)?;
3796        validate_authority_reads(&new_schema, &self.limits.authority_reads)?;
3797        self.conn
3798            .execute_batch("BEGIN IMMEDIATE")
3799            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3800        let prior_schema = std::mem::replace(&mut self.schema, new_schema);
3801        // §7.4.3/§7.4.4: a reset inside this transaction mutates in-memory
3802        // state (dropped outbox commits, rejections, upgrade and floor flags,
3803        // overlay dirtiness) and appends change/intent batches. A COMMIT that
3804        // fails after the reset succeeded rolls the database back, so every
3805        // one of those fields is captured here and restored with it.
3806        let rollback = self.capture();
3807        let guarded = (|| -> Result<(), String> {
3808            // §7.4.2: the marker is re-read under the write lock the caller
3809            // holds, so a replica another process upgraded meanwhile refuses
3810            // this recreation instead of having its marker and tables
3811            // downgraded.
3812            let marker = read_local_schema_version(&self.conn, self.schema.version)?;
3813            self.create_bookkeeping_tables()?;
3814            match marker {
3815                Some(version) if version < self.schema.version => self.run_schema_reset()?,
3816                None => {
3817                    self.create_synced_tables()?;
3818                    self.persist_schema_version()?;
3819                }
3820                _ => {}
3821            }
3822            // §7.4.2: recreation IS the boot for the in-memory core, so reload the
3823            // durable outbox the same-version path is about to replay. Only the
3824            // outbox is reloaded: the recovery below reads it, and the caller's
3825            // rollback snapshot already covers this field.
3826            self.outbox = self.load_outbox()?.into();
3827            // §7.1/§7.4.4: recover intrinsically codec-invalid persisted values at
3828            // this guarded boundary once the schema and marker agree. A bump went
3829            // through `run_schema_reset`, which performs the same recovery after
3830            // it creates the new physical tables and before its final replay.
3831            self.drop_unencodable_outbox(false, None)?;
3832            if marker == Some(self.schema.version)
3833                && (!self.outbox.is_empty()
3834                    || !self.failed_commits.is_empty()
3835                    || self.has_acknowledged_rows()?)
3836            {
3837                self.overlay_dirty.set(true);
3838                self.rebuild_overlay()?;
3839            }
3840            self.prune_unknown_units(false)?;
3841            self.save_unit_scope_schema()?;
3842            // The conformance recreate is the in-memory equivalent of reopening
3843            // a durable client. Apply the same startup catch-up contract even
3844            // when the schema itself did not change.
3845            self.enqueue_startup_sync_if_needed()?;
3846            Ok(())
3847        })();
3848        let outcome = match guarded {
3849            Ok(()) => self
3850                .conn
3851                .execute_batch("COMMIT")
3852                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error)),
3853            Err(error) => Err(error),
3854        };
3855        if let Err(error) = outcome {
3856            if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3857                // Keep a failed rollback's typed storage classification.
3858                let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3859            }
3860            self.schema = prior_schema;
3861            self.restore(rollback);
3862            // Prepared insert statements were derived from the reverted schema.
3863            self.insert_sql.borrow_mut().clear();
3864            return Err(error);
3865        }
3866        if !self.security_preflight {
3867            self.drain_pending_evictions()?;
3868        }
3869        Ok(())
3870    }
3871
3872    fn enqueue_startup_sync_if_needed(&mut self) -> Result<(), String> {
3873        let startup_work = !self.stopped
3874            && (!self.outbox.is_empty()
3875                || self.has_acknowledged_rows()?
3876                || !self.load_pending_evictions()?.is_empty()
3877                || self
3878                    .stored(load_units(&self.conn))?
3879                    .iter()
3880                    .any(|unit| unit.status == UnitStatus::Active));
3881        if startup_work {
3882            self.sync_needed = true;
3883            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3884        }
3885        Ok(())
3886    }
3887
3888    /// A native client persists schema-floor stops across process restarts.
3889    /// Once the running app already satisfies that floor, the persisted stop
3890    /// is only stale evidence from an older server round (for example, the
3891    /// server was restarted after catching up to an app that was ahead).
3892    /// Clear it and let the normal startup pull re-negotiate. If the server is
3893    /// still incompatible it will return the floor again in that first round.
3894    fn clear_satisfied_persisted_schema_floor(&mut self) -> Result<(), String> {
3895        let satisfied = self
3896            .schema_floor
3897            .as_ref()
3898            .and_then(|floor| floor.required_schema_version)
3899            .is_some_and(|required| self.schema.version >= required);
3900        if !satisfied {
3901            return Ok(());
3902        }
3903        self.delete_meta(SCHEMA_FLOOR_KEY)?;
3904        self.schema_floor = None;
3905        self.stopped = false;
3906        Ok(())
3907    }
3908
3909    /// RFC 0005 D1: discard an orphan or stale container at boot. The reset
3910    /// path already swept it; this covers a same-version or fresh-install open,
3911    /// which runs no reset and therefore no sweep — plus the D7 TTL, which only
3912    /// an aware binary can apply.
3913    fn reconcile_previous_version_at_boot(&self) -> Result<(), String> {
3914        let Some(replica_path) = self.previous_version_replica_path() else {
3915            return Ok(());
3916        };
3917        let max_age_ms = self
3918            .previous_version
3919            .filter(|config| config.enabled)
3920            .map(|config| config.max_age_ms);
3921        reconcile_previous_version_at_boot(
3922            &self.conn,
3923            &replica_path,
3924            self.schema.version,
3925            max_age_ms,
3926            self.clock_now_ms(),
3927        )
3928    }
3929
3930    /// RFC 0005 D3: the sibling container path, or `None` when the replica has
3931    /// no file — an in-memory replica returns an empty path, and a `file:` URI
3932    /// has no plain sibling path — so the feature resolves as off there.
3933    fn previous_version_replica_path(&self) -> Option<String> {
3934        let path = self.conn.path()?;
3935        if path.is_empty() || path.starts_with("file:") {
3936            return None;
3937        }
3938        Some(path.to_owned())
3939    }
3940
3941    /// §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
3942    /// and leaseState. Drops/recreates every synced table from the new
3943    /// schema, resets unit sync state (keeping registrations), clears
3944    /// the schema-floor stop state, rewrites the marker, drops outbox commits
3945    /// that cannot re-encode (§7.4.4), and replays the survivors on top.
3946    fn run_schema_reset(&mut self) -> Result<(), String> {
3947        self.begin_observation("syncular_schema_reset")?;
3948        let rollback = self.capture();
3949        let mut batch = ChangeAccumulator::default();
3950        let result = self
3951            .run_schema_reset_observed(&mut batch, true)
3952            .and_then(|()| self.finish_observation("syncular_schema_reset", batch));
3953        if let Err(error) = result {
3954            self.rollback_observation("syncular_schema_reset");
3955            self.restore(rollback);
3956            return Err(error);
3957        }
3958        // After the commit: a rolled-back reset keeps the in-flight round.
3959        self.cancel_sync_round();
3960        Ok(())
3961    }
3962
3963    fn run_log_epoch_reset(&mut self, log_epoch: &str) -> Result<Vec<String>, String> {
3964        if self.get_meta(LOG_EPOCH_KEY)?.is_none() {
3965            self.begin_observation("syncular_epoch_acquisition")?;
3966            let rollback = self.capture();
3967            if let Err(error) = self.conn.execute(
3968                "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3969                rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3970            ) {
3971                self.rollback_observation("syncular_epoch_acquisition");
3972                return Err(Self::sqlite_failure(&self.storage_failure, error));
3973            }
3974            self.sync_needed = true;
3975            let batch = ChangeAccumulator {
3976                status: true,
3977                ..ChangeAccumulator::default()
3978            };
3979            if let Err(error) = self.finish_observation("syncular_epoch_acquisition", batch) {
3980                self.rollback_observation("syncular_epoch_acquisition");
3981                self.restore(rollback);
3982                return Err(error);
3983            }
3984            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3985            return Ok(Vec::new());
3986        }
3987        let resets = self
3988            .stored(load_units(&self.conn))?
3989            .into_iter()
3990            .map(|unit| unit.id)
3991            .collect();
3992        self.begin_observation("syncular_log_epoch_reset")?;
3993        let rollback = self.capture();
3994        let mut batch = ChangeAccumulator::default();
3995        let result = self
3996            .run_schema_reset_observed(&mut batch, false)
3997            .and_then(|()| {
3998                self.conn
3999                    .execute(
4000                        "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
4001                        rusqlite::params![LOG_EPOCH_KEY, log_epoch],
4002                    )
4003                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4004                self.sync_needed = true;
4005                batch.status = true;
4006                self.finish_observation("syncular_log_epoch_reset", batch)
4007            });
4008        if let Err(error) = result {
4009            self.rollback_observation("syncular_log_epoch_reset");
4010            self.restore(rollback);
4011            return Err(error);
4012        }
4013        self.cancel_sync_round();
4014        self.sync_intent_queue.push_back(SyncIntent::Interactive);
4015        Ok(resets)
4016    }
4017
4018    fn run_schema_reset_observed(
4019        &mut self,
4020        batch: &mut ChangeAccumulator,
4021        capture: bool,
4022    ) -> Result<(), String> {
4023        // §7.4.2: the reset is the only path that wipes local tables for a
4024        // version bump, and it rewrites the marker last. Re-read the marker
4025        // under this reset's transaction: a replica another process upgraded
4026        // meanwhile refuses here instead of being reset to this client's
4027        // older schema.
4028        read_local_schema_version(&self.conn, self.schema.version)?;
4029        // §7.4.3: a schema bump keeps every table whose generation equals the
4030        // persisted one; the log-epoch reset keeps nothing. The previous
4031        // declaration evidence decides which units cover only kept tables.
4032        let mut kept = BTreeSet::new();
4033        let mut previous_declarations: Option<BTreeMap<String, BTreeMap<String, Value>>> = None;
4034        if capture {
4035            let persisted: BTreeMap<String, String> = self
4036                .get_meta(TABLE_GENERATIONS_KEY)?
4037                .map(|raw| serde_json::from_str(&raw))
4038                .transpose()
4039                .map_err(|_| "sync.local_corrupt: invalid persisted table generations".to_owned())?
4040                .unwrap_or_default();
4041            kept = self
4042                .schema
4043                .tables
4044                .iter()
4045                .filter(|table| {
4046                    table.generation.is_some()
4047                        && table.generation.as_ref() == persisted.get(&table.name)
4048                })
4049                .map(|table| table.name.clone())
4050                .collect();
4051            previous_declarations = self
4052                .get_meta("subscriptionScopeSchema")?
4053                .map(|raw| serde_json::from_str(&raw))
4054                .transpose()
4055                .map_err(|_| "sync.local_corrupt: invalid persisted scope schema".to_owned())?;
4056        }
4057        // Kept tables keep both halves, their FTS projections with the FTS5
4058        // shadow tables and id mapping, and their row-level bookkeeping.
4059        let mut kept_objects = BTreeSet::new();
4060        for table in self
4061            .schema
4062            .tables
4063            .iter()
4064            .filter(|table| kept.contains(&table.name))
4065        {
4066            kept_objects.insert(table.name.clone());
4067            kept_objects.insert(format!("_syncular_base_{}", table.name));
4068            for index in &table.fts_indexes {
4069                kept_objects.insert(index.name.clone());
4070                for shadow in ["data", "idx", "content", "docsize", "config"] {
4071                    kept_objects.insert(format!("{}_{shadow}", index.name));
4072                }
4073            }
4074        }
4075        let kept_json = serde_json::to_string(&kept).expect("table names serialize");
4076        for sql in [
4077            "DELETE FROM _syncular_acked_rows WHERE tbl NOT IN (SELECT value FROM json_each(?1))",
4078            "DELETE FROM _syncular_row_deliveries WHERE tbl NOT IN (SELECT value FROM json_each(?1))",
4079        ] {
4080            self.conn
4081                .execute(sql, [&kept_json])
4082                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4083        }
4084        self.upgrading = true;
4085        batch.status = true;
4086        // RFC 0005 D6: classify the pending outbox against the NEW compiled
4087        // schema BEFORE the wipe, and record the advisory audit. This pass
4088        // drops nothing, so the audit sees the original pending intent; the
4089        // §7.4.4 send-time drop and the intrinsic value recovery later in this
4090        // reset are the paths that remove a commit. The classification is
4091        // shared with the send-time drop so the two cannot disagree about what
4092        // is incompatible.
4093        if self.previous_version.is_some_and(|config| config.enabled) {
4094            let previous_version = self
4095                .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
4096                .and_then(|value| value.parse::<i32>().ok())
4097                .unwrap_or(self.schema.version);
4098            let pending = self
4099                .outbox
4100                .iter()
4101                .map(|commit| PendingCommitAudit {
4102                    commit_id: &commit.client_commit_id,
4103                    operations: commit_audit_operations(commit),
4104                })
4105                .collect::<Vec<_>>();
4106            crate::previous_version::write_previous_version_audit(
4107                &self.conn,
4108                &crate::previous_version::build_previous_version_audit(
4109                    &self.schema,
4110                    &pending,
4111                    previous_version,
4112                    self.schema.version,
4113                    self.clock_now_ms(),
4114                ),
4115            )?;
4116        }
4117        // RFC 0005 D5: the container lives in its own FILE, so the reset can
4118        // never reach it. Sweep first (unconditional — also on the log-epoch
4119        // reset, which captures nothing), then capture BEFORE the wipe drops
4120        // any row. A refused capture records its reason and leaves no file.
4121        if let Some(replica_path) = self.previous_version_replica_path() {
4122            sweep_previous_version_container(&self.conn, &replica_path)?;
4123            if capture {
4124                if let Some(config) = self.previous_version.filter(|config| config.enabled) {
4125                    let previous_version = self
4126                        .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
4127                        .and_then(|value| value.parse::<i32>().ok())
4128                        .unwrap_or(self.schema.version);
4129                    capture_previous_version_from_replica(
4130                        &self.conn,
4131                        &replica_path,
4132                        previous_version,
4133                        self.schema.version,
4134                        &config,
4135                        self.clock_now_ms(),
4136                    )?;
4137                }
4138            }
4139        }
4140        for table in self
4141            .schema
4142            .tables
4143            .iter()
4144            .filter(|table| !kept.contains(&table.name))
4145        {
4146            batch.table(&table.name);
4147        }
4148        for (base_key, value) in self.load_window_registry()? {
4149            batch.window(&base_key, &value);
4150        }
4151        if capture {
4152            self.prune_unknown_units(true)?;
4153        }
4154        // The per-table insert SQL is derived from the OLD column lists.
4155        self.insert_sql.borrow_mut().clear();
4156        self.overlay_dirty.set(true);
4157        // Drop every synced table (base + visible) that currently exists —
4158        // discovered from sqlite_master so a bump that adds/removes tables is
4159        // handled. Bookkeeping tables (`_syncular_outbox/_units/_meta`
4160        // and the blob cache) are preserved; base tables are `_syncular_base_*`
4161        // so they are matched explicitly, not by the bookkeeping filter.
4162        // Drop virtual tables first so SQLite removes every FTS shadow table
4163        // atomically instead of the generic discovery tearing it apart.
4164        let virtual_tables: Vec<String> = {
4165            let mut stmt = self
4166                .conn
4167                .prepare(
4168                    "SELECT name FROM sqlite_master WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%'",
4169                )
4170                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4171            let rows = stmt
4172                .query_map([], |row| row.get::<_, String>(0))
4173                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4174            rows.filter_map(Result::ok)
4175                .filter(|name| is_synced_table_name(name) && !kept_objects.contains(name))
4176                .collect()
4177        };
4178        for name in virtual_tables {
4179            self.conn
4180                .execute_batch(&format!(
4181                    "DROP TABLE IF EXISTS {}",
4182                    quote_ident(&format!("_syncular_fts_{name}"))
4183                ))
4184                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4185            self.conn
4186                .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
4187                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4188        }
4189        let existing: Vec<String> = {
4190            let mut stmt = self
4191                .conn
4192                .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
4193                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4194            let rows = stmt
4195                .query_map([], |row| row.get::<_, String>(0))
4196                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4197            rows.filter_map(Result::ok)
4198                .filter(|name| is_synced_table_name(name) && !kept_objects.contains(name))
4199                .collect()
4200        };
4201        for name in &existing {
4202            if let Some(table) = name.strip_prefix("_syncular_base_") {
4203                batch.table(table);
4204            } else if !name.starts_with("_syncular_") {
4205                batch.table(name);
4206            }
4207        }
4208        for name in existing {
4209            self.conn
4210                .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
4211                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4212        }
4213        // Recreate the synced tables from the NEW schema.
4214        self.create_synced_tables()?;
4215        // Reset the sync state of every unit that covers a table the reset
4216        // did not keep, under the previous declarations or the new schema,
4217        // keeping the registration.
4218        let keep_units = match &previous_declarations {
4219            Some(previous) if !kept.is_empty() => self
4220                .stored(load_units(&self.conn))?
4221                .into_iter()
4222                .filter(|unit| {
4223                    previous.iter().all(|(name, old)| {
4224                        kept.contains(name) || !unit.scopes.keys().all(|v| old.contains_key(v))
4225                    }) && self
4226                        .schema
4227                        .tables
4228                        .iter()
4229                        .all(|table| kept.contains(&table.name) || !covers(table, &unit.scopes))
4230                })
4231                .map(|unit| unit.id)
4232                .collect(),
4233            _ => BTreeSet::new(),
4234        };
4235        // §7.4.3 restriction: an active unit that is not kept and whose rows
4236        // of a kept table are complete through a cursor C (its restriction's,
4237        // its post-bootstrap P, or the replica cursor it is live under)
4238        // bootstraps only its other covered tables and joins at C.
4239        let restrictions = if capture {
4240            let replica = self.stored(replica_cursor(&self.conn))?;
4241            let mut restrictions = BTreeMap::new();
4242            for unit in self.stored(load_units(&self.conn))? {
4243                if keep_units.contains(&unit.id) || unit.status != UnitStatus::Active {
4244                    continue;
4245                }
4246                let cursor = match (&unit.restriction, unit.cursor) {
4247                    (Some(restriction), _) => restriction.cursor,
4248                    (None, Some(cursor)) if cursor >= 0 && unit.bootstrap_state.is_none() => cursor,
4249                    (None, None) if replica >= 0 => replica,
4250                    _ => continue,
4251                };
4252                let covered: Vec<&String> = self
4253                    .schema
4254                    .tables
4255                    .iter()
4256                    .filter(|table| covers(table, &unit.scopes))
4257                    .map(|table| &table.name)
4258                    .collect();
4259                let mut tables: Vec<String> = covered
4260                    .iter()
4261                    .filter(|name| {
4262                        !kept.contains(**name)
4263                            || unit
4264                                .restriction
4265                                .as_ref()
4266                                .is_some_and(|restriction| restriction.tables.contains(name))
4267                    })
4268                    .map(|name| (*name).clone())
4269                    .collect();
4270                if tables.is_empty() || tables.len() == covered.len() {
4271                    continue;
4272                }
4273                tables.sort_by(|a, b| a.encode_utf16().cmp(b.encode_utf16()));
4274                restrictions.insert(unit.id, UnitRestriction { cursor, tables });
4275            }
4276            Some(restrictions)
4277        } else {
4278            None
4279        };
4280        reset_units(&self.conn, &keep_units, restrictions.as_ref())
4281            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4282        // The stop state is over: this client now ships a servable schema.
4283        self.stopped = false;
4284        self.schema_floor = None;
4285        self.delete_meta(SCHEMA_FLOOR_KEY)?;
4286        // Rewrite the marker LAST so a crash mid-reset re-runs the reset.
4287        self.persist_schema_version()?;
4288        self.save_unit_scope_schema()?;
4289        // §7.1/§7.4.4: the previous-version capture and audit above saw the
4290        // original pending intent; the synced tables now carry the new schema, so
4291        // recover intrinsically codec-invalid persisted values here, before the
4292        // final replay. A pending upsert that names a column the new schema
4293        // removed stays pending for the send-time `drop_incompatible_outbox`
4294        // prepass. The reset wrapper snapshots and restores the outbox,
4295        // rejections, and change queues, so a failed commit rolls this recovery
4296        // back with the rest of the reset.
4297        // §7.4.4: the enclosing reset observation owns the publication, so the
4298        // recovery contributes its rejection, outcome, and table domains to it.
4299        self.drop_unencodable_outbox(false, Some(batch))?;
4300        // Re-apply the surviving outbox optimistically over the empty tables.
4301        self.rebuild_overlay()?;
4302        Ok(())
4303    }
4304
4305    /// §7.4.4 send-time prepass: a persisted upsert whose values reference a
4306    /// column the current schema lacks (or a removed table) cannot be encoded
4307    /// (`commit_audit_operations` inspects upserts, so a value-free delete stays
4308    /// encodable and is validated by the server), nor can an insert-intent
4309    /// upsert that lacks a non-nullable column (§7.1, the audit's
4310    /// `missing-required-column`). Drop the commit, undo
4311    /// its optimistic projection, and raise a client-local
4312    /// `sync.outbox_incompatible` rejection.
4313    fn drop_incompatible_outbox(&mut self) -> Result<bool, String> {
4314        let incompatible = self
4315            .outbox
4316            .iter()
4317            .filter(|commit| {
4318                first_incompatibility(&self.schema, &commit_audit_operations(commit)).is_some()
4319            })
4320            .cloned()
4321            .collect::<Vec<_>>();
4322        if incompatible.is_empty() {
4323            return Ok(false);
4324        }
4325        self.drop_outbox_commits(
4326            &incompatible,
4327            OUTBOX_INCOMPATIBLE_CODE,
4328            "the persisted commit cannot encode under the current schema",
4329        )?;
4330        Ok(true)
4331    }
4332
4333    /// §7.4.4 incompatible-commit path, also taken by a refused blob upload
4334    /// (§5.9.7) with the server's code: reject every operation of `commits`,
4335    /// remove them from the outbox, and undo their optimistic rows.
4336    fn drop_outbox_commits(
4337        &mut self,
4338        incompatible: &[Arc<OutboxCommit>],
4339        code: &str,
4340        message: &str,
4341    ) -> Result<(), String> {
4342        // §7.4.4: one observation covers the durable outcome writes, the outbox
4343        // removal, the in-memory drop, and the overlay rebuild, so a storage
4344        // fault leaves the replica and the client unchanged and publishes no
4345        // change; a successful drop publishes exactly one batch carrying the
4346        // rejections, outcomes, status, and the tables whose projection changed.
4347        let rollback = self.capture();
4348        let owns_transaction = self.conn.is_autocommit();
4349        self.begin_observation("syncular_outbox_drop")?;
4350        let mut batch = ChangeAccumulator::default();
4351        let dropped = (|| -> Result<(), String> {
4352            let mut rejections = Vec::new();
4353            for commit in incompatible {
4354                let results = commit
4355                    .ops
4356                    .iter()
4357                    .enumerate()
4358                    .map(|(op_index, operation)| {
4359                        let rejection = RejectionRecord {
4360                            client_commit_id: commit.client_commit_id.clone(),
4361                            op_index: op_index as i32,
4362                            code: code.to_owned(),
4363                            message: message.to_owned(),
4364                            retryable: false,
4365                            details: None,
4366                            operation: Some(CommitOperation::from(operation)),
4367                        };
4368                        rejections.push(rejection.clone());
4369                        CommitOperationOutcome::Error { rejection }
4370                    })
4371                    .collect::<Vec<_>>();
4372                self.persist_commit_outcome(
4373                    &commit.client_commit_id,
4374                    CommitOutcomeStatus::Rejected,
4375                    &results,
4376                    Some(&commit.ops),
4377                )?;
4378                self.delete_outbox_persisted(&commit.client_commit_id)?;
4379                // A removed table has no local projection to invalidate; every
4380                // surviving table the dropped commit touched does.
4381                for operation in &commit.ops {
4382                    if self.schema.table(&operation.table).is_some() {
4383                        batch.table(&operation.table);
4384                    }
4385                }
4386            }
4387            self.prune_commit_outcomes()?;
4388            let incompatible_ids = incompatible
4389                .iter()
4390                .map(|commit| commit.client_commit_id.as_str())
4391                .collect::<BTreeSet<_>>();
4392            self.outbox
4393                .retain(|commit| !incompatible_ids.contains(commit.client_commit_id.as_str()));
4394            self.rejections.extend(rejections);
4395            // The dropped commits' purely-optimistic rows are undone: the
4396            // visible projection is re-derived from the surviving base + outbox.
4397            self.overlay_dirty.set(true);
4398            self.rebuild_overlay()?;
4399            batch.status = true;
4400            batch.rejections = true;
4401            batch.outcomes = true;
4402            Ok(())
4403        })();
4404        let result = dropped.and_then(|()| self.finish_observation("syncular_outbox_drop", batch));
4405        if let Err(error) = result {
4406            // An outer RELEASE is the COMMIT. Roll back that transaction
4407            // directly: retrying RELEASE after ROLLBACK TO still needs the
4408            // reader's lock. A nested observation only rolls back its savepoint.
4409            if owns_transaction {
4410                if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
4411                    let mut failure = self.storage_failure.borrow_mut();
4412                    let failure =
4413                        failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
4414                    failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
4415                }
4416            } else {
4417                self.rollback_observation("syncular_outbox_drop");
4418            }
4419            self.restore(rollback);
4420            return Err(error);
4421        }
4422        Ok(())
4423    }
4424
4425    /// §7.4.3: (re)create the base + visible table pair for every synced
4426    /// table in the CURRENT schema (idempotent — `IF NOT EXISTS`).
4427    fn create_synced_tables(&self) -> Result<(), String> {
4428        for table in &self.schema.tables {
4429            // The base half + the visible half form the synced-table pair. An
4430            // index name is global in SQLite, so the base half's indexes are
4431            // name-prefixed (`_syncular_base_<index>`) to stay distinct.
4432            for (full, index_prefix) in [
4433                (base_table(&table.name), "_syncular_base_"),
4434                (visible_table(&table.name), ""),
4435            ] {
4436                let mut cols: Vec<String> =
4437                    table.columns.iter().map(|c| quote_ident(&c.name)).collect();
4438                cols.push("\"_syncular_version\" INTEGER NOT NULL".to_owned());
4439                cols.extend(
4440                    table
4441                        .sealed_columns()
4442                        .iter()
4443                        .map(|name| format!("{} TEXT", quote_ident(name))),
4444                );
4445                let sql = format!(
4446                    "CREATE TABLE IF NOT EXISTS {full} ({} , PRIMARY KEY ({}))",
4447                    cols.join(", "),
4448                    quote_ident(&table.primary_key)
4449                );
4450                self.conn
4451                    .execute(&sql, [])
4452                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4453                // §5.11: a replica created before sealed apply gains the
4454                // reserved columns in place, on both halves in the same order,
4455                // so data, indexes and the FTS projection stay.
4456                for name in table.sealed_columns() {
4457                    let present: bool = self
4458                        .conn
4459                        .query_row(
4460                            "SELECT EXISTS(SELECT 1 FROM pragma_table_info(?1) WHERE name = ?2)",
4461                            rusqlite::params![format!("{index_prefix}{}", table.name), name],
4462                            |row| row.get(0),
4463                        )
4464                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4465                    if !present {
4466                        self.conn
4467                            .execute(
4468                                &format!(
4469                                    "ALTER TABLE {full} ADD COLUMN {} TEXT",
4470                                    quote_ident(name)
4471                                ),
4472                                [],
4473                            )
4474                            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4475                    }
4476                }
4477                // The reveal at every round start reads the sealed rows of the
4478                // base half through this partial index.
4479                if table.has_encrypted_columns() && !index_prefix.is_empty() {
4480                    self.conn
4481                        .execute(
4482                            &format!(
4483                                "CREATE INDEX IF NOT EXISTS {} ON {full} (\"_sync_sealed_key\") WHERE \"_sync_sealed_key\" IS NOT NULL",
4484                                quote_ident(&format!("_syncular_sealed_{}", table.name))
4485                            ),
4486                            [],
4487                        )
4488                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4489                }
4490                // Local secondary indexes (CREATE INDEX subset). Created on
4491                // both halves so mirror reads hit an index on either. Runs on
4492                // both the initial create and the §7.4.3 reset recreate path.
4493                for index in &table.indexes {
4494                    let unique = if index.unique { "UNIQUE " } else { "" };
4495                    let index_name = quote_ident(&format!("{index_prefix}{}", index.name));
4496                    let cols_sql = index
4497                        .columns
4498                        .iter()
4499                        .map(|c| quote_ident(c))
4500                        .collect::<Vec<_>>()
4501                        .join(", ");
4502                    let index_sql = format!(
4503                        "CREATE {unique}INDEX IF NOT EXISTS {index_name} ON {full} ({cols_sql})"
4504                    );
4505                    self.conn
4506                        .execute(&index_sql, [])
4507                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4508                }
4509            }
4510        }
4511        // FTS exists only on the visible half. It is a local search
4512        // projection, never a synced/base table or a wire-schema member.
4513        for table in &self.schema.tables {
4514            for index in &table.fts_indexes {
4515                self.create_fts_projection(table, index)?;
4516            }
4517        }
4518        Ok(())
4519    }
4520
4521    fn fts_projection_exists(&self, index: &FtsIndexSchema) -> Result<bool, String> {
4522        let count: i64 = self
4523            .conn
4524            .query_row(
4525                "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?1",
4526                rusqlite::params![index.name],
4527                |row| row.get(0),
4528            )
4529            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4530        Ok(count > 0)
4531    }
4532
4533    fn drop_fts_triggers(&self, index: &FtsIndexSchema) -> Result<(), String> {
4534        for suffix in ["ai", "ad", "au"] {
4535            self.conn
4536                .execute(
4537                    &format!(
4538                        "DROP TRIGGER IF EXISTS {}",
4539                        quote_ident(&format!("{}_{suffix}", index.name))
4540                    ),
4541                    [],
4542                )
4543                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4544        }
4545        Ok(())
4546    }
4547
4548    fn create_fts_triggers(
4549        &self,
4550        table: &TableSchema,
4551        index: &FtsIndexSchema,
4552    ) -> Result<(), String> {
4553        let fts = quote_ident(&index.name);
4554        let source = visible_table(&table.name);
4555        let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4556        let pk = quote_ident(&table.primary_key);
4557        let projection_columns = std::iter::once(source_id.clone())
4558            .chain(index.columns.iter().map(|column| quote_ident(column)))
4559            .collect::<Vec<_>>()
4560            .join(", ");
4561        let new_values = std::iter::once(format!("CAST(new.{pk} AS TEXT)"))
4562            .chain(
4563                index
4564                    .columns
4565                    .iter()
4566                    .map(|column| format!("new.{}", quote_ident(column))),
4567            )
4568            .collect::<Vec<_>>()
4569            .join(", ");
4570        let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4571        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)");
4572        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)");
4573        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})");
4574        let bi = quote_ident(&format!("{}_bi", index.name));
4575        let ai = quote_ident(&format!("{}_ai", index.name));
4576        let ad = quote_ident(&format!("{}_ad", index.name));
4577        let au = quote_ident(&format!("{}_au", index.name));
4578        let replacement_exists = format!("EXISTS (SELECT 1 FROM {source} WHERE {pk} = new.{pk})");
4579        let sql = format!(
4580            "DROP TRIGGER IF EXISTS {bi};
4581             DROP TRIGGER IF EXISTS {ai};
4582             DROP TRIGGER IF EXISTS {ad};
4583             DROP TRIGGER IF EXISTS {au};
4584             CREATE TRIGGER {bi} BEFORE INSERT ON {source} WHEN {replacement_exists} BEGIN {delete_new}; END;
4585             CREATE TRIGGER {ai} AFTER INSERT ON {source} BEGIN {insert_new}; END;
4586             CREATE TRIGGER {ad} AFTER DELETE ON {source} BEGIN {delete_old}; END;
4587             CREATE TRIGGER {au} AFTER UPDATE ON {source} BEGIN {delete_old}; {delete_new}; {insert_new}; END;",
4588        );
4589        self.conn
4590            .execute_batch(&sql)
4591            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4592    }
4593
4594    fn rebuild_fts_projection(
4595        &self,
4596        table: &TableSchema,
4597        index: &FtsIndexSchema,
4598    ) -> Result<(), String> {
4599        let fts = quote_ident(&index.name);
4600        let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4601        let pk = quote_ident(&table.primary_key);
4602        let indexed_columns = index
4603            .columns
4604            .iter()
4605            .map(|column| quote_ident(column))
4606            .collect::<Vec<_>>();
4607        let projection_columns = std::iter::once(source_id.clone())
4608            .chain(indexed_columns.iter().cloned())
4609            .collect::<Vec<_>>()
4610            .join(", ");
4611        let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4612        let sql = format!(
4613            "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};",
4614            columns = indexed_columns.join(", "),
4615            source = visible_table(&table.name),
4616        );
4617        self.conn
4618            .execute_batch(&sql)
4619            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4620    }
4621
4622    fn create_fts_projection(
4623        &self,
4624        table: &TableSchema,
4625        index: &FtsIndexSchema,
4626    ) -> Result<(), String> {
4627        self.begin_observation("syncular_fts_schema")?;
4628        let result = (|| {
4629            let existed = self.fts_projection_exists(index)?;
4630            let tokenizer = index.tokenize.replace('\'', "''");
4631            let columns = index
4632                .columns
4633                .iter()
4634                .map(|column| quote_ident(column))
4635                .collect::<Vec<_>>()
4636                .join(", ");
4637            let sql = format!(
4638            "CREATE VIRTUAL TABLE IF NOT EXISTS {fts} USING fts5({source_id} UNINDEXED, {columns}, tokenize='{tokenizer}')",
4639            fts = quote_ident(&index.name),
4640            source_id = quote_ident(FTS_SOURCE_ID_COLUMN),
4641        );
4642            self.conn.execute(&sql, []).map_err(|error| {
4643                format!(
4644                    "cannot create local FTS5 projection {:?}: {error}",
4645                    index.name
4646                )
4647            })?;
4648            let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4649            let mapped: bool = self
4650                .conn
4651                .query_row(
4652                    "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1)",
4653                    [format!("_syncular_fts_{}", index.name)],
4654                    |row| row.get(0),
4655                )
4656                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4657            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))?;
4658            if !mapped && existed {
4659                self.conn
4660                    .execute_batch(&format!(
4661                        "INSERT INTO {mapping}(id, source_id) SELECT rowid, {} FROM {}",
4662                        quote_ident(FTS_SOURCE_ID_COLUMN),
4663                        quote_ident(&index.name)
4664                    ))
4665                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4666            }
4667            self.create_fts_triggers(table, index)?;
4668            // Every visible row has exactly one mapping row, so a count
4669            // mismatch marks a projection an earlier release damaged; the
4670            // open rebuilds it.
4671            let stale: bool = !existed
4672                || self
4673                    .conn
4674                    .query_row(
4675                        &format!(
4676                            "SELECT (SELECT count(*) FROM {mapping}) != (SELECT count(*) FROM {})",
4677                            visible_table(&table.name)
4678                        ),
4679                        [],
4680                        |row| row.get(0),
4681                    )
4682                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4683            if stale {
4684                self.rebuild_fts_projection(table, index)?;
4685            }
4686            Ok(())
4687        })();
4688        if let Err(error) = result {
4689            self.rollback_observation("syncular_fts_schema");
4690            return Err(error);
4691        }
4692        if let Err(error) = self.conn.execute_batch("RELEASE syncular_fts_schema") {
4693            self.rollback_observation("syncular_fts_schema");
4694            return Err(error.to_string());
4695        }
4696        Ok(())
4697    }
4698
4699    // -- persistence write-through --------------------------------------------
4700
4701    fn persist_outbox_insert(&self, commit: &OutboxCommit) -> Result<(), String> {
4702        let ops: Vec<Value> = commit
4703            .ops
4704            .iter()
4705            .map(|op| {
4706                let mut entry = serde_json::json!({
4707                    "op": if op.upsert { "upsert" } else { "delete" },
4708                    "table": op.table,
4709                    "rowId": op.row_id,
4710                    "baseVersion": op.base_version,
4711                    "values": op.values.clone().map(Value::Object),
4712                });
4713                if op.insert {
4714                    entry["insert"] = Value::Bool(true);
4715                }
4716                entry
4717            })
4718            .collect();
4719        self.conn
4720            .execute(
4721                "INSERT OR REPLACE INTO _syncular_outbox (commit_id, ops_json, created_at_ms) VALUES (?1, ?2, ?3)",
4722                rusqlite::params![
4723                    commit.client_commit_id,
4724                    Value::Array(ops).to_string(),
4725                    self.clock_now_ms()
4726                ],
4727            )
4728            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4729        for operation in &commit.ops {
4730            let Some(values) = &operation.values else {
4731                continue;
4732            };
4733            let Some(table) = self.schema.table(&operation.table) else {
4734                continue;
4735            };
4736            for column in table
4737                .columns
4738                .iter()
4739                .filter(|column| column.ty == ColumnType::BlobRef)
4740            {
4741                let Some(Value::String(raw)) = values.get(&column.name) else {
4742                    continue;
4743                };
4744                let Ok(blob_ref) = serde_json::from_str::<Value>(raw) else {
4745                    continue;
4746                };
4747                let Some(blob_id) = blob_ref.get("blobId").and_then(Value::as_str) else {
4748                    continue;
4749                };
4750                self.conn
4751                    .execute(
4752                        "INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id, blob_id)
4753                         SELECT ?1, ?2 WHERE EXISTS (SELECT 1 FROM _syncular_blobs WHERE blob_id = ?2)",
4754                        rusqlite::params![commit.client_commit_id, blob_id],
4755                    )
4756                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4757            }
4758        }
4759        Ok(())
4760    }
4761
4762    fn delete_outbox_persisted(&self, client_commit_id: &str) -> Result<(), String> {
4763        self.conn
4764            .execute(
4765                "DELETE FROM _syncular_blob_commit_refs WHERE commit_id = ?1",
4766                rusqlite::params![client_commit_id],
4767            )
4768            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4769        self.conn
4770            .execute(
4771                "DELETE FROM _syncular_outbox WHERE commit_id = ?1",
4772                rusqlite::params![client_commit_id],
4773            )
4774            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4775        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)", [])
4776            .map(|_| ())
4777            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4778    }
4779
4780    fn outcome_status_name(status: CommitOutcomeStatus) -> &'static str {
4781        match status {
4782            CommitOutcomeStatus::Applied => "applied",
4783            CommitOutcomeStatus::Cached => "cached",
4784            CommitOutcomeStatus::Conflict => "conflict",
4785            CommitOutcomeStatus::Rejected => "rejected",
4786        }
4787    }
4788
4789    fn outcome_resolution_name(resolution: CommitOutcomeResolution) -> &'static str {
4790        match resolution {
4791            CommitOutcomeResolution::Active => "active",
4792            CommitOutcomeResolution::ResolvedKeepServer => "resolved_keep_server",
4793            CommitOutcomeResolution::Superseded => "superseded",
4794            CommitOutcomeResolution::Dismissed => "dismissed",
4795        }
4796    }
4797
4798    fn parse_outcome_status(value: &str) -> Result<CommitOutcomeStatus, String> {
4799        match value {
4800            "applied" => Ok(CommitOutcomeStatus::Applied),
4801            "cached" => Ok(CommitOutcomeStatus::Cached),
4802            "conflict" => Ok(CommitOutcomeStatus::Conflict),
4803            "rejected" => Ok(CommitOutcomeStatus::Rejected),
4804            _ => Err(format!("invalid persisted commit outcome status {value:?}")),
4805        }
4806    }
4807
4808    fn parse_outcome_resolution(value: &str) -> Result<CommitOutcomeResolution, String> {
4809        match value {
4810            "active" => Ok(CommitOutcomeResolution::Active),
4811            "resolved_keep_server" => Ok(CommitOutcomeResolution::ResolvedKeepServer),
4812            "superseded" => Ok(CommitOutcomeResolution::Superseded),
4813            "dismissed" => Ok(CommitOutcomeResolution::Dismissed),
4814            _ => Err(format!(
4815                "invalid persisted commit outcome resolution {value:?}"
4816            )),
4817        }
4818    }
4819
4820    fn persist_commit_outcome(
4821        &self,
4822        client_commit_id: &str,
4823        status: CommitOutcomeStatus,
4824        results: &[CommitOperationOutcome],
4825        operations: Option<&[OutboxOp]>,
4826    ) -> Result<(), String> {
4827        let results_json = serde_json::to_string(results).map_err(|error| error.to_string())?;
4828        let operations_json = operations
4829            .map(|items| {
4830                serde_json::to_string(&items.iter().map(CommitOperation::from).collect::<Vec<_>>())
4831            })
4832            .transpose()
4833            .map_err(|error| error.to_string())?;
4834        self.conn
4835            .execute(
4836                "INSERT INTO _syncular_commit_outcomes (
4837                   client_commit_id, status, recorded_at_ms, results_json,
4838                   operations_json, resolution
4839                 ) VALUES (?1, ?2, ?3, ?4, ?5, 'active')",
4840                rusqlite::params![
4841                    client_commit_id,
4842                    Self::outcome_status_name(status),
4843                    self.clock_now_ms(),
4844                    results_json,
4845                    operations_json
4846                ],
4847            )
4848            .map(|_| ())
4849            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4850    }
4851
4852    /// §7.2: the journal holds a stored cell only in its canonical shape. A cell
4853    /// the byte-envelope rule refuses cannot be journaled verbatim.
4854    fn stored_cell_is_representable(cell: &Value) -> bool {
4855        cell.is_null()
4856            || cell.is_string()
4857            || cell.is_boolean()
4858            || cell.is_number()
4859            || is_canonical_bytes_envelope(cell)
4860    }
4861
4862    fn stored_row_is_representable(value: &Value) -> bool {
4863        value
4864            .as_object()
4865            .is_some_and(|row| row.values().all(Self::stored_cell_is_representable))
4866    }
4867
4868    fn stored_operation_is_representable(value: &Value) -> bool {
4869        value.get("table").is_some_and(Value::is_string)
4870            && value.get("rowId").is_some_and(Value::is_string)
4871            && value.get("baseVersion").is_none_or(|v| {
4872                v.as_i64()
4873                    .is_some_and(|n| n.unsigned_abs() <= MAX_JS_SAFE_INTEGER)
4874            })
4875            && match value.get("op").and_then(Value::as_str) {
4876                Some("upsert") => {
4877                    value
4878                        .get("values")
4879                        .is_some_and(Self::stored_row_is_representable)
4880                        && value
4881                            .get("insert")
4882                            .is_none_or(|insert| *insert == Value::Bool(true))
4883                }
4884                Some("delete") => value.get("values").is_none() && value.get("insert").is_none(),
4885                _ => false,
4886            }
4887    }
4888
4889    /// §7.2/§7.4.4: a dropped commit keeps its operation envelope in the journal
4890    /// only when the journal reader accepts the serialized operation, which is the
4891    /// rule `outcome_from_row` applies to this same row later.
4892    fn outbox_op_is_journalable(operation: &OutboxOp) -> bool {
4893        serde_json::to_value(CommitOperation::from(operation))
4894            .is_ok_and(|value| Self::stored_operation_is_representable(&value))
4895    }
4896
4897    fn outcome_from_row(row: StoredCommitOutcomeRow) -> Result<CommitOutcome, String> {
4898        let StoredCommitOutcomeRow {
4899            sequence,
4900            client_commit_id,
4901            status,
4902            recorded_at_ms,
4903            results_json,
4904            operations_json,
4905            resolution,
4906            resolved_at_ms,
4907            replacement_client_commit_id,
4908        } = row;
4909        if sequence.unsigned_abs() > MAX_JS_SAFE_INTEGER
4910            || recorded_at_ms.unsigned_abs() > MAX_JS_SAFE_INTEGER
4911            || resolved_at_ms.is_some_and(|value| value.unsigned_abs() > MAX_JS_SAFE_INTEGER)
4912        {
4913            return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned());
4914        }
4915        let invalid = || "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
4916        let stored: Vec<Value> = serde_json::from_str(&results_json).map_err(|_| invalid())?;
4917        for result in &stored {
4918            let nested = match result.get("status").and_then(Value::as_str) {
4919                Some("conflict") => result.get("conflict"),
4920                Some("error") => result.get("rejection"),
4921                _ => None,
4922            };
4923            if nested
4924                .and_then(|record| record.get("operation"))
4925                .is_some_and(|op| !Self::stored_operation_is_representable(op))
4926                || (result.get("status").and_then(Value::as_str) == Some("conflict")
4927                    && nested
4928                        .and_then(|record| record.get("serverRow"))
4929                        .is_some_and(|row| !Self::stored_row_is_representable(row)))
4930            {
4931                return Err(invalid());
4932            }
4933        }
4934        let results: Vec<CommitOperationOutcome> =
4935            serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())?;
4936        let has_conflict = results
4937            .iter()
4938            .any(|result| matches!(result, CommitOperationOutcome::Conflict { .. }));
4939        let has_error = results
4940            .iter()
4941            .any(|result| matches!(result, CommitOperationOutcome::Error { .. }));
4942        let status = Self::parse_outcome_status(&status).map_err(|_| invalid())?;
4943        let redacted = results.is_empty() && operations_json.is_none();
4944        if match status {
4945            CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => has_conflict || has_error,
4946            CommitOutcomeStatus::Conflict => !(has_conflict || redacted),
4947            CommitOutcomeStatus::Rejected => has_conflict || !(has_error || redacted),
4948        } {
4949            return Err(invalid());
4950        }
4951        let operations: Option<Vec<CommitOperation>> = operations_json
4952            .map(|raw| {
4953                let stored: Vec<Value> = serde_json::from_str(&raw).map_err(|_| invalid())?;
4954                if !stored.iter().all(Self::stored_operation_is_representable) {
4955                    return Err(invalid());
4956                }
4957                serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())
4958            })
4959            .transpose()?;
4960        for result in &results {
4961            match result {
4962                CommitOperationOutcome::Conflict { conflict }
4963                    if conflict.server_version.unsigned_abs() > MAX_JS_SAFE_INTEGER =>
4964                {
4965                    return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned())
4966                }
4967                CommitOperationOutcome::Error { rejection } => {
4968                    if let Some(details) = &rejection.details {
4969                        let encoded = serde_json::to_string(details).map_err(|_| {
4970                            "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4971                        })?;
4972                        RejectionDetails::parse(&encoded).map_err(|_| {
4973                            "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4974                        })?;
4975                    }
4976                }
4977                _ => {}
4978            }
4979        }
4980        Ok(CommitOutcome {
4981            sequence,
4982            client_commit_id,
4983            status,
4984            recorded_at_ms,
4985            results,
4986            operations,
4987            retained_rows: None,
4988            resolution: Self::parse_outcome_resolution(&resolution)?,
4989            resolved_at_ms,
4990            replacement_client_commit_id,
4991        })
4992    }
4993
4994    /// Resolve declared unique keys through SQLite, including affinity and NULL semantics.
4995    fn unique_conflicts(
4996        &self,
4997        table: &TableSchema,
4998        values: &Map<String, Value>,
4999        base: bool,
5000    ) -> Result<Vec<RetainedUniqueConflict>, String> {
5001        let source = if base {
5002            base_table(&table.name)
5003        } else {
5004            visible_table(&table.name)
5005        };
5006        let mut conflicts = Vec::new();
5007        for index in table.indexes.iter().filter(|index| index.unique) {
5008            let mut params = vec![json_param_to_sql(
5009                values.get(&table.primary_key).ok_or("sync.local_corrupt")?,
5010            )?];
5011            for name in &index.columns {
5012                let column = table
5013                    .columns
5014                    .iter()
5015                    .find(|column| column.name == *name)
5016                    .ok_or("sync.local_corrupt")?;
5017                let cell = json_to_column_value(column, values.get(name))?;
5018                params.push(owned_sql_value(RowParam::Cell(&cell))?);
5019            }
5020            let sql = format!(
5021                "SELECT * FROM {source} WHERE {} != ? AND {}",
5022                quote_ident(&table.primary_key),
5023                index
5024                    .columns
5025                    .iter()
5026                    .map(|column| format!("{} = ?", quote_ident(column)))
5027                    .collect::<Vec<_>>()
5028                    .join(" AND ")
5029            );
5030            let mut statement = self
5031                .conn
5032                .prepare_cached(&sql)
5033                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5034            let records = statement
5035                .query_map(rusqlite::params_from_iter(params), |record| {
5036                    let values = table
5037                        .columns
5038                        .iter()
5039                        .enumerate()
5040                        .map(|(index, column)| {
5041                            let value = sql_ref_to_json(column, record.get_ref(index)?);
5042                            json_to_column_value(column, Some(&value)).map_err(|message| {
5043                                rusqlite::Error::ToSqlConversionFailure(message.into())
5044                            })
5045                        })
5046                        .collect::<Result<Row, _>>()?;
5047                    Ok((values, record.get::<_, i64>(table.columns.len())?))
5048                })
5049                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5050            for record in records {
5051                let (row, version) =
5052                    record.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5053                let row_id = render_row_id_json(Some(&column_value_to_json(&row[table.pk_index])))?;
5054                conflicts.push(RetainedUniqueConflict {
5055                    index: index.name.clone(),
5056                    columns: index.columns.clone(),
5057                    row_id,
5058                    server_row: table
5059                        .columns
5060                        .iter()
5061                        .zip(&row)
5062                        .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
5063                        .collect(),
5064                    server_version: version,
5065                });
5066            }
5067        }
5068        Ok(conflicts)
5069    }
5070
5071    fn attach_retained_rows(&self, mut outcome: CommitOutcome) -> Result<CommitOutcome, String> {
5072        if let Some((commit, initial)) = self
5073            .failed_commits
5074            .iter()
5075            .find(|(commit, _)| commit.client_commit_id == outcome.client_commit_id)
5076        {
5077            let mut rows = Vec::new();
5078            for operation in &commit.ops {
5079                // A table the current schema removed has no rows to retain.
5080                let Some(table) = self.schema.table(&operation.table) else {
5081                    continue;
5082                };
5083                let key =
5084                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5085                        .map_err(|_| "sync.local_corrupt".to_owned())?;
5086                let base = self.stored_row(table, &operation.row_id, true)?;
5087                rows.push(RetainedCommitRow {
5088                    table: operation.table.clone(),
5089                    row_id: operation.row_id.clone(),
5090                    unique_conflicts: if operation.upsert {
5091                        self.unique_conflicts(
5092                            table,
5093                            initial
5094                                .get(&key)
5095                                .and_then(Value::as_object)
5096                                .or(operation.values.as_ref())
5097                                .ok_or("sync.local_corrupt")?,
5098                            true,
5099                        )?
5100                    } else {
5101                        Vec::new()
5102                    },
5103                    local_row: if operation.upsert {
5104                        initial
5105                            .get(&key)
5106                            .and_then(Value::as_object)
5107                            .cloned()
5108                            .or_else(|| operation.values.clone())
5109                    } else {
5110                        None
5111                    },
5112                    server_row: base.as_ref().map(|(values, _)| {
5113                        table
5114                            .columns
5115                            .iter()
5116                            .zip(values)
5117                            .map(|(column, value)| {
5118                                (column.name.clone(), column_value_to_json(value))
5119                            })
5120                            .collect()
5121                    }),
5122                    server_version: base.map(|(_, version)| version),
5123                });
5124            }
5125            outcome.retained_rows = Some(rows);
5126        }
5127        Ok(outcome)
5128    }
5129
5130    pub fn commit_outcome(&self, client_commit_id: &str) -> Result<Option<CommitOutcome>, String> {
5131        let row = self
5132            .conn
5133            .query_row(
5134                "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
5135                        resolution, resolved_at_ms, replacement_client_commit_id
5136                   FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
5137                rusqlite::params![client_commit_id],
5138                |row| {
5139                    Ok(StoredCommitOutcomeRow {
5140                        sequence: row.get(0)?,
5141                        client_commit_id: row.get(1)?,
5142                        status: row.get(2)?,
5143                        recorded_at_ms: row.get(3)?,
5144                        results_json: row.get(4)?,
5145                        operations_json: row.get(5)?,
5146                        resolution: row.get(6)?,
5147                        resolved_at_ms: row.get(7)?,
5148                        replacement_client_commit_id: row.get(8)?,
5149                    })
5150                },
5151            )
5152            .optional()
5153            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5154        row.map(|row| self.attach_retained_rows(Self::outcome_from_row(row)?))
5155            .transpose()
5156    }
5157
5158    /// Internal host step. The host must run its idle drive before finishing.
5159    #[doc(hidden)]
5160    pub fn prepare_current_base(
5161        &self,
5162        client_commit_id: &str,
5163        sequence: i64,
5164    ) -> Result<CurrentBasePreparation, CurrentBaseProof> {
5165        let outcome = self
5166            .commit_outcome(client_commit_id)
5167            .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?;
5168        let valid = outcome.as_ref().is_some_and(|outcome| {
5169            outcome.sequence == sequence
5170                && outcome.resolution == CommitOutcomeResolution::Active
5171                && matches!(
5172                    outcome.status,
5173                    CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
5174                )
5175                && outcome
5176                    .operations
5177                    .as_ref()
5178                    .zip(outcome.retained_rows.as_ref())
5179                    .is_some_and(|(operations, rows)| {
5180                        !rows.is_empty() && operations.len() == rows.len()
5181                    })
5182        });
5183        if !valid {
5184            return Err(CurrentBaseProof::failure(
5185                CurrentBaseProofReason::OutcomeUnavailable,
5186            ));
5187        }
5188        if !self.transport_enabled {
5189            return Err(CurrentBaseProof::failure(CurrentBaseProofReason::Offline));
5190        }
5191        Ok(CurrentBasePreparation {
5192            client_commit_id: client_commit_id.to_owned(),
5193            sequence,
5194            replacement: None,
5195            units: load_units(&self.conn)
5196                .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?,
5197            transport_epoch: self.transport_epoch,
5198            registration_epoch: self.registration_epoch,
5199            security_epoch: self.security_epoch,
5200        })
5201    }
5202
5203    /// Internal host step after the completed post-rejection idle drive.
5204    #[doc(hidden)]
5205    pub fn finish_current_base(
5206        &mut self,
5207        prepared: CurrentBasePreparation,
5208        drive: SyncOutcome,
5209    ) -> CurrentBaseProof {
5210        if !self.transport_enabled || self.transport_epoch != prepared.transport_epoch {
5211            return CurrentBaseProof::failure(CurrentBaseProofReason::Offline);
5212        }
5213        if self.registration_epoch != prepared.registration_epoch {
5214            return CurrentBaseProof::failure(CurrentBaseProofReason::MissingCoverage);
5215        }
5216        if self.security_preflight || self.security_epoch != prepared.security_epoch {
5217            return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed);
5218        }
5219        let report = match drive {
5220            SyncOutcome::Ok(report) => report,
5221            SyncOutcome::BudgetExhausted(_) => {
5222                return CurrentBaseProof::failure(CurrentBaseProofReason::BudgetExhausted)
5223            }
5224            _ => return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed),
5225        };
5226        if report.schema_floor.is_some() {
5227            return CurrentBaseProof::failure(CurrentBaseProofReason::SchemaFloor);
5228        }
5229        if self
5230            .conn
5231            .execute_batch("SAVEPOINT syncular_base_proof")
5232            .is_err()
5233        {
5234            return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
5235        }
5236        let proof = (|| {
5237            let snapshot = snapshot_read_connection(
5238                &self.conn,
5239                &SnapshotReadRequest {
5240                    units: prepared.units.iter().map(|unit| unit.id.clone()).collect(),
5241                    commit_ids: vec![prepared.client_commit_id.clone()],
5242                    ..Default::default()
5243                },
5244            )
5245            .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
5246            let current = self
5247                .commit_outcome(&prepared.client_commit_id)
5248                .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
5249            let unavailable = if report.revoked.is_empty() {
5250                CurrentBaseProofReason::OutcomeUnavailable
5251            } else {
5252                CurrentBaseProofReason::Revoked
5253            };
5254            let Some(outcome) = current else {
5255                return Err(unavailable);
5256            };
5257            if !matches!(
5258                snapshot.deliveries.first(),
5259                Some(CommitDelivery::Known { .. })
5260            ) || outcome.sequence != prepared.sequence
5261                || outcome.resolution != CommitOutcomeResolution::Active
5262                || !matches!(
5263                    outcome.status,
5264                    CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
5265                )
5266            {
5267                return Err(unavailable);
5268            }
5269            let (Some(operations), Some(rows)) = (outcome.operations, outcome.retained_rows) else {
5270                return Err(unavailable);
5271            };
5272            if rows.is_empty() || operations.len() != rows.len() {
5273                return Err(unavailable);
5274            }
5275            let after =
5276                load_units(&self.conn).map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
5277            let complete: HashSet<&str> = snapshot
5278                .units
5279                .iter()
5280                .filter_map(|unit| match unit {
5281                    UnitCatchup::Known {
5282                        id,
5283                        bootstrap_complete: true,
5284                        ..
5285                    } => Some(id.as_str()),
5286                    _ => None,
5287                })
5288                .collect();
5289            // A unit id names one scope map (§4.1), so the same id before and
5290            // after the drive is the same registration.
5291            let candidates: Vec<&UnitRecord> = after
5292                .iter()
5293                .filter(|unit| {
5294                    complete.contains(unit.id.as_str())
5295                        && prepared.units.iter().any(|before| before.id == unit.id)
5296                })
5297                .collect();
5298            let covered = |table_name: &str, row: &Map<String, Value>| {
5299                let Some(table) = self.schema.table(table_name) else {
5300                    return false;
5301                };
5302                candidates.iter().any(|unit| {
5303                    covers(table, &unit.scopes)
5304                        && pair_scopes(&unit.scopes, table_name, unit.echo.as_deref()).is_some_and(
5305                            |scopes| {
5306                                scopes.iter().all(|(variable, allowed)| {
5307                                    table
5308                                        .scope_column(variable)
5309                                        .and_then(|column| match row.get(column) {
5310                                            Some(Value::String(value)) => Some(value.clone()),
5311                                            Some(Value::Bool(value)) => Some(value.to_string()),
5312                                            Some(Value::Number(value)) => {
5313                                                value.as_f64().map(|number| {
5314                                                    ryu_js::Buffer::new()
5315                                                        .format_finite(number)
5316                                                        .to_owned()
5317                                                })
5318                                            }
5319                                            _ => None,
5320                                        })
5321                                        .is_some_and(|value| {
5322                                            !value.is_empty() && allowed.contains(&value)
5323                                        })
5324                                })
5325                            },
5326                        )
5327                })
5328            };
5329            for row in &rows {
5330                let Some(base) = row.server_row.as_ref().or(row.local_row.as_ref()) else {
5331                    return Err(if report.revoked.is_empty() {
5332                        CurrentBaseProofReason::MissingCoverage
5333                    } else {
5334                        CurrentBaseProofReason::Revoked
5335                    });
5336                };
5337                if !covered(&row.table, base)
5338                    || row
5339                        .unique_conflicts
5340                        .iter()
5341                        .any(|conflict| !covered(&row.table, &conflict.server_row))
5342                {
5343                    return Err(if report.revoked.is_empty() {
5344                        CurrentBaseProofReason::MissingCoverage
5345                    } else {
5346                        CurrentBaseProofReason::Revoked
5347                    });
5348                }
5349            }
5350            Ok(rows)
5351        })();
5352        if self
5353            .conn
5354            .execute_batch("RELEASE syncular_base_proof")
5355            .is_err()
5356        {
5357            return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
5358        }
5359        match proof {
5360            Ok(rows) => CurrentBaseProof {
5361                proven: true,
5362                rows: Some(rows),
5363                reason: None,
5364            },
5365            Err(reason) => CurrentBaseProof::failure(reason),
5366        }
5367    }
5368
5369    pub fn prove_current_base(
5370        &mut self,
5371        transport: &mut dyn Transport,
5372        client_commit_id: &str,
5373        sequence: i64,
5374        max_rounds: Option<u32>,
5375    ) -> CurrentBaseProof {
5376        let prepared = match self.prepare_current_base(client_commit_id, sequence) {
5377            Ok(prepared) => prepared,
5378            Err(proof) => return proof,
5379        };
5380        let drive = self.sync_until_idle(transport, max_rounds);
5381        self.finish_current_base(prepared, drive)
5382    }
5383
5384    pub fn commit_outcomes(&self, query: CommitOutcomeQuery) -> Result<Vec<CommitOutcome>, String> {
5385        if query.limit == Some(0) {
5386            return Err("sync.invalid_request: commit outcome limit must be positive".to_owned());
5387        }
5388        let mut sql = String::from(
5389            "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
5390                    resolution, resolved_at_ms, replacement_client_commit_id
5391               FROM _syncular_commit_outcomes",
5392        );
5393        if query.active_only {
5394            sql.push_str(" WHERE resolution = 'active' AND status IN ('conflict', 'rejected')");
5395        }
5396        sql.push_str(" ORDER BY seq DESC");
5397        if let Some(limit) = query.limit {
5398            sql.push_str(&format!(" LIMIT {limit}"));
5399        }
5400        let mut stmt = self
5401            .conn
5402            .prepare(&sql)
5403            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5404        let rows = stmt
5405            .query_map([], |row| {
5406                Ok(StoredCommitOutcomeRow {
5407                    sequence: row.get(0)?,
5408                    client_commit_id: row.get(1)?,
5409                    status: row.get(2)?,
5410                    recorded_at_ms: row.get(3)?,
5411                    results_json: row.get(4)?,
5412                    operations_json: row.get(5)?,
5413                    resolution: row.get(6)?,
5414                    resolved_at_ms: row.get(7)?,
5415                    replacement_client_commit_id: row.get(8)?,
5416                })
5417            })
5418            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5419        let mut outcomes = Vec::new();
5420        for row in rows {
5421            outcomes.push(self.attach_retained_rows(Self::outcome_from_row(
5422                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
5423            )?)?);
5424        }
5425        Ok(outcomes)
5426    }
5427
5428    fn prune_commit_outcomes(&self) -> Result<(), String> {
5429        #[cfg(test)]
5430        self.outcome_prune_count
5431            .set(self.outcome_prune_count.get() + 1);
5432        let max_entries = self.limits.outcome_retention_max_entries.unwrap_or(1_000);
5433        let count = self
5434            .conn
5435            .query_row(
5436                "SELECT COUNT(*) FROM _syncular_commit_outcomes",
5437                [],
5438                |row| row.get::<_, i64>(0),
5439            )
5440            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5441            as usize;
5442        let excess = count.saturating_sub(max_entries);
5443        if excess == 0 {
5444            return Ok(());
5445        }
5446        let mut stmt = self
5447            .conn
5448            .prepare(
5449                "SELECT seq FROM _syncular_commit_outcomes
5450                  WHERE status IN ('applied', 'cached') OR resolution != 'active'
5451                  ORDER BY seq ASC LIMIT ?1",
5452            )
5453            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5454        let rows = stmt
5455            .query_map(rusqlite::params![excess as i64], |row| row.get::<_, i64>(0))
5456            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5457        let sequences = rows
5458            .collect::<Result<Vec<_>, _>>()
5459            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5460        drop(stmt);
5461        for sequence in sequences {
5462            self.conn
5463                .execute(
5464                    "DELETE FROM _syncular_commit_outcomes WHERE seq = ?1",
5465                    rusqlite::params![sequence],
5466                )
5467                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5468        }
5469        Ok(())
5470    }
5471
5472    // -- units (§4.1) ------------------------------------------------------------
5473
5474    /// Every registered unit in registration order (§4.1).
5475    pub fn units(&self) -> Result<Vec<UnitRecord>, String> {
5476        self.stored(load_units(&self.conn))
5477    }
5478
5479    pub fn unit(&self, id: &str) -> Result<Option<UnitRecord>, String> {
5480        self.stored(get_unit(&self.conn, id))
5481    }
5482
5483    /// Register one unit (§4.1) and return its id.
5484    pub fn subscribe(&mut self, scopes: UnitScopes) -> Result<String, String> {
5485        Ok(self.subscribe_many(vec![scopes])?.remove(0))
5486    }
5487
5488    /// Register several units in one local transaction and return their ids:
5489    /// one commit for all of them (on OPFS a commit costs milliseconds, so a
5490    /// cold start with hundreds of units pays it once). An error rolls back
5491    /// every registration of the call. Registering an active unit again
5492    /// changes nothing; a revoked unit re-arms (§3.3). A call that registers or
5493    /// re-arms a unit raises sync-needed with an interactive intent.
5494    pub fn subscribe_many(&mut self, units: Vec<UnitScopes>) -> Result<Vec<String>, String> {
5495        self.begin_observation("syncular_subscribe")?;
5496        let mut changed = false;
5497        let registered = (|| {
5498            let mut ids = Vec::with_capacity(units.len());
5499            for scopes in units {
5500                let (id, held) = self.hold_unit(scopes, true)?;
5501                changed |= held;
5502                ids.push(id);
5503            }
5504            self.conn
5505                .execute_batch("RELEASE syncular_subscribe")
5506                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5507            Ok(ids)
5508        })();
5509        let ids = match registered {
5510            Ok(ids) => ids,
5511            Err(error) => {
5512                self.rollback_observation("syncular_subscribe");
5513                return Err(error);
5514            }
5515        };
5516        if changed {
5517            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5518            self.set_sync_needed(true, true);
5519        }
5520        Ok(ids)
5521    }
5522
5523    /// Release the explicit reference to a unit. The unit leaves the
5524    /// registration list when no window base holds it (§4.1); its rows stay.
5525    pub fn unsubscribe(&mut self, id: &str) -> Result<(), String> {
5526        let Some(unit) = self.stored(get_unit(&self.conn, id))? else {
5527            return Ok(());
5528        };
5529        if !unit.explicit {
5530            return Ok(());
5531        }
5532        if !self.stored(window_refs(&self.conn, id))?.is_empty() {
5533            return self.stored(save_unit(
5534                &self.conn,
5535                &UnitRecord {
5536                    explicit: false,
5537                    ..unit
5538                },
5539            ));
5540        }
5541        self.conn
5542            .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5543            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5544        self.registration_epoch = self.registration_epoch.wrapping_add(1);
5545        if unit.status == UnitStatus::Active {
5546            self.set_sync_needed(true, true);
5547        }
5548        Ok(())
5549    }
5550
5551    /// Take one reference on a unit (§4.1): validate the scope map, register a
5552    /// new unit catching up with cursor `-1`, re-arm a revoked one (§3.3).
5553    /// Returns the id and whether the registration list changed.
5554    fn hold_unit(&mut self, scopes: UnitScopes, explicit: bool) -> Result<(String, bool), String> {
5555        if scopes.is_empty()
5556            || scopes.values().any(|value| value == "*")
5557            || !self
5558                .schema
5559                .tables
5560                .iter()
5561                .any(|table| covers(table, &scopes))
5562        {
5563            return Err("sync.invalid_subscription: a unit names one non-wildcard value per variable and covers a table".to_owned());
5564        }
5565        let id = ssp2::registration::unit_id(&scope_pairs(&scopes));
5566        let existing = self.stored(get_unit(&self.conn, &id))?;
5567        if let Some(existing) = existing
5568            .as_ref()
5569            .filter(|unit| unit.status != UnitStatus::Revoked)
5570        {
5571            if explicit && !existing.explicit {
5572                self.stored(save_unit(
5573                    &self.conn,
5574                    &UnitRecord {
5575                        explicit,
5576                        ..existing.clone()
5577                    },
5578                ))?;
5579            }
5580            return Ok((id, false));
5581        }
5582        self.delete_pending_evict(&id)?;
5583        self.stored(save_unit(
5584            &self.conn,
5585            &UnitRecord {
5586                id: id.clone(),
5587                scopes,
5588                explicit: explicit || existing.is_some_and(|unit| unit.explicit),
5589                status: UnitStatus::Active,
5590                reason_code: None,
5591                cursor: Some(-1),
5592                bootstrap_state: None,
5593                seeded: Vec::new(),
5594                echo: None,
5595                restriction: None,
5596            },
5597        ))?;
5598        Ok((id, true))
5599    }
5600
5601    // -- windows (§4.8) -----------------------------------------------------------
5602
5603    /// §4.8: set the windowed-in values of a base, one unit per value. Added
5604    /// values take a reference on their unit (a new unit bootstraps on the
5605    /// next sync); removed values release theirs, and a unit no reference
5606    /// holds leaves the registration list fused with its first eviction chunk
5607    /// (E1–E4). Idempotent; re-entry cancels a deferred eviction.
5608    pub fn set_window(
5609        &mut self,
5610        base: &WindowBase,
5611        units: &[String],
5612    ) -> Result<CommandEffects, String> {
5613        let base_key = window_base_key(base);
5614        let live = self.load_window_units(&base_key)?;
5615        let mut changed = false;
5616        // §7.8: the added values register in one transaction.
5617        let added: Vec<&String> = units
5618            .iter()
5619            .filter(|value| !live.iter().any(|(held, _)| held == *value))
5620            .collect();
5621        if !added.is_empty() {
5622            let rollback = self.capture();
5623            self.begin_observation("syncular_window")?;
5624            let widened = (|| {
5625                let mut batch = ChangeAccumulator::default();
5626                for value in &added {
5627                    let (id, registered) =
5628                        self.hold_unit(window_unit_scopes(base, value), false)?;
5629                    self.sync_needed |= registered;
5630                    self.conn
5631                        .execute(
5632                            "INSERT OR REPLACE INTO _syncular_windows(base, unit, sub_id) VALUES (?1, ?2, ?3)",
5633                            rusqlite::params![base_key, value, id],
5634                        )
5635                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5636                    batch.window(&base_key, value);
5637                }
5638                batch.status = true;
5639                self.finish_observation("syncular_window", batch)
5640            })();
5641            if let Err(error) = widened {
5642                self.rollback_observation("syncular_window");
5643                self.restore(rollback);
5644                return Err(error);
5645            }
5646            changed = true;
5647            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5648        }
5649        for (value, id) in live {
5650            if units.contains(&value) {
5651                continue;
5652            }
5653            self.rebuild_overlay_if_dirty()?;
5654            let rollback = self.capture();
5655            self.begin_observation("syncular_window")?;
5656            let remaining = self.release_window_unit(&base_key, &value, &id);
5657            let remaining = match remaining {
5658                Ok(remaining) => remaining,
5659                Err(error) => {
5660                    self.rollback_observation("syncular_window");
5661                    self.restore(rollback);
5662                    return Err(error);
5663                }
5664            };
5665            changed = true;
5666            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5667            if remaining {
5668                self.drain_pending_evictions()?;
5669            }
5670        }
5671        Ok(if changed && self.transport_enabled {
5672            CommandEffects::interactive()
5673        } else {
5674            CommandEffects::none()
5675        })
5676    }
5677
5678    /// §4.8 completeness oracle: the windowed-in values of a base and those
5679    /// whose unit is not complete. A value is complete once its unit is active
5680    /// and no longer bootstrapping; registration alone is not completeness.
5681    pub fn window_state(&self, base: &WindowBase) -> Result<WindowState, String> {
5682        persisted_window_state(&self.conn, base).map_err(|failure| failure.message)
5683    }
5684
5685    /// Registry rows for a base, ordered by value: (value, unit id).
5686    fn load_window_units(&self, base_key: &str) -> Result<Vec<(String, String)>, String> {
5687        let mut statement = self
5688            .conn
5689            .prepare_cached(
5690                "SELECT unit, sub_id FROM _syncular_windows WHERE base = ?1 ORDER BY unit ASC",
5691            )
5692            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5693        let rows = statement
5694            .query_map([base_key], |row| Ok((row.get(0)?, row.get(1)?)))
5695            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5696        rows.collect::<Result<_, _>>()
5697            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5698    }
5699
5700    /// Every window registry row: (base key, value).
5701    fn load_window_registry(&self) -> Result<Vec<(String, String)>, String> {
5702        let mut statement = self
5703            .conn
5704            .prepare_cached("SELECT base, unit FROM _syncular_windows ORDER BY base, unit")
5705            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5706        let rows = statement
5707            .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
5708            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5709        rows.collect::<Result<_, _>>()
5710            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5711    }
5712
5713    /// §4.8: release a window value's reference inside the caller's
5714    /// observation. When no reference holds the unit, unregister it fused with
5715    /// its first eviction chunk (E3): delete the rows of every covered table
5716    /// matching the persisted echo, except rows pinned by the outbox (E1) or
5717    /// owned by another unit (§3.3), and park the per-table scopes of what
5718    /// remains in the pending-eviction registry. Fails closed without a local
5719    /// scope-column mapping. Returns whether unpinned rows remain.
5720    fn release_window_unit(
5721        &mut self,
5722        base_key: &str,
5723        value: &str,
5724        id: &str,
5725    ) -> Result<bool, String> {
5726        self.conn
5727            .execute(
5728                "DELETE FROM _syncular_windows WHERE base = ?1 AND unit = ?2",
5729                rusqlite::params![base_key, value],
5730            )
5731            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5732        let mut batch = ChangeAccumulator::default();
5733        batch.window(base_key, value);
5734        batch.status = true;
5735        let unit = self.stored(get_unit(&self.conn, id))?;
5736        let mut remaining = false;
5737        if let Some(unit) = unit.filter(|unit| !unit.explicit) {
5738            if self.stored(window_refs(&self.conn, id))?.is_empty() {
5739                let units = self.stored(load_units(&self.conn))?;
5740                self.conn
5741                    .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5742                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5743                self.sync_needed = true;
5744                for table in self.schema.tables.clone() {
5745                    let Some(effective) = unit
5746                        .echo
5747                        .as_deref()
5748                        .filter(|_| covers(&table, &unit.scopes))
5749                        .and_then(|echo| pair_scopes(&unit.scopes, &table.name, Some(echo)))
5750                    else {
5751                        continue;
5752                    };
5753                    let pinned = self.pinned_row_ids(&table.name);
5754                    let owners = unit_owners(&units, &table, id);
5755                    let (more, deferred) =
5756                        self.evict_scope_rows(&table.name, &effective, &owners, &pinned)?;
5757                    remaining |= more;
5758                    if deferred {
5759                        self.save_pending_evict(id, &table.name, &effective)?;
5760                    }
5761                    self.record_scope_map(&mut batch, &table.name, &effective);
5762                }
5763            }
5764        }
5765        self.finish_observation("syncular_window", batch)?;
5766        Ok(remaining)
5767    }
5768
5769    /// §4.8 E1: delete base rows owned by the effective scopes
5770    /// ([`local_scope_predicate`]) EXCEPT pinned primary keys. Returns (more
5771    /// unpinned work, any scoped rows remain). A missing scope-column mapping
5772    /// fails without deleting rows.
5773    fn evict_scope_rows(
5774        &self,
5775        table_name: &str,
5776        effective: &[(String, Vec<String>)],
5777        owners: &[Vec<(String, Vec<String>)>],
5778        pinned: &std::collections::HashSet<String>,
5779    ) -> Result<(bool, bool), String> {
5780        let table = self.schema.table(table_name).ok_or("sync.unknown_table")?;
5781        let Some((scope, mut params)) = local_scope_predicate(table, effective, owners)
5782            .map_err(|()| "sync.scope_revoked".to_owned())?
5783        else {
5784            return Ok((false, false));
5785        };
5786        let scope_params = params.len();
5787        let pk = quote_ident(&table.primary_key);
5788        // Pinned ids are rowId text; the text form matches every key type.
5789        let predicate = if pinned.is_empty() {
5790            scope.clone()
5791        } else {
5792            params.extend(pinned.iter().cloned().map(SqlValue::Text));
5793            let holes = vec!["?"; pinned.len()].join(", ");
5794            format!("{scope} AND CAST({pk} AS TEXT) NOT IN ({holes})")
5795        };
5796        let base = base_table(table_name);
5797        let visible = visible_table(table_name);
5798        let mut ids: Vec<SqlValue> = Vec::new();
5799        for source in [&base, &visible] {
5800            let mut stmt = self
5801                .conn
5802                .prepare_cached(&format!(
5803                    "SELECT {pk} FROM {source} WHERE {predicate} LIMIT 1024"
5804                ))
5805                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5806            ids = stmt
5807                .query_map(rusqlite::params_from_iter(&params), |row| row.get(0))
5808                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5809                .collect::<Result<_, _>>()
5810                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5811            if !ids.is_empty() {
5812                break;
5813            }
5814        }
5815        if !ids.is_empty() {
5816            for id in &ids {
5817                self.conn
5818                    .execute(
5819                        "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2",
5820                        rusqlite::params![table_name, id],
5821                    )
5822                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5823            }
5824            let holes = vec!["?"; ids.len()].join(", ");
5825            for source in [&base, &visible] {
5826                self.conn
5827                    .execute(
5828                        &format!("DELETE FROM {source} WHERE {pk} IN ({holes})"),
5829                        rusqlite::params_from_iter(&ids),
5830                    )
5831                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5832            }
5833        }
5834        let mut remaining = false;
5835        let mut deferred = false;
5836        for source in [&base, &visible] {
5837            remaining |= self
5838                .conn
5839                .query_row(
5840                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
5841                    rusqlite::params_from_iter(&params),
5842                    |row| row.get::<_, bool>(0),
5843                )
5844                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5845            deferred |= self
5846                .conn
5847                .query_row(
5848                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {scope})"),
5849                    rusqlite::params_from_iter(&params[..scope_params]),
5850                    |row| row.get::<_, bool>(0),
5851                )
5852                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5853        }
5854        Ok((remaining, deferred))
5855    }
5856
5857    /// §4.8 E1: continue deferred evictions after the outbox drains or between
5858    /// chunks, retaining outbox pins and their durable marker. A unit that
5859    /// re-entered the window has no pending entry left.
5860    fn drain_pending_evictions(&mut self) -> Result<(), String> {
5861        let pending = self.load_pending_evictions()?;
5862        if pending.is_empty() {
5863            return Ok(());
5864        }
5865        self.rebuild_overlay_if_dirty()?;
5866        for (unit_id, table_name, effective) in pending {
5867            let Some(table) = self.schema.table(&table_name).cloned() else {
5868                self.delete_pending_evict_table(&unit_id, &table_name)?;
5869                continue;
5870            };
5871            loop {
5872                std::thread::yield_now();
5873                self.begin_observation("syncular_evict")?;
5874                let chunk = (|| {
5875                    let pinned = self.pinned_row_ids(&table_name);
5876                    let owners =
5877                        unit_owners(&self.stored(load_units(&self.conn))?, &table, &unit_id);
5878                    let (remaining, deferred) =
5879                        self.evict_scope_rows(&table_name, &effective, &owners, &pinned)?;
5880                    if !deferred {
5881                        self.delete_pending_evict_table(&unit_id, &table_name)?;
5882                    }
5883                    let mut batch = ChangeAccumulator::default();
5884                    self.record_scope_map(&mut batch, &table_name, &effective);
5885                    self.finish_observation("syncular_evict", batch)?;
5886                    Ok(remaining)
5887                })();
5888                match chunk {
5889                    Ok(true) => {}
5890                    Ok(false) => break,
5891                    Err(error) => {
5892                        self.rollback_observation("syncular_evict");
5893                        return Err(error);
5894                    }
5895                }
5896            }
5897        }
5898        Ok(())
5899    }
5900
5901    /// §4.8 E1: primary keys of `table` referenced by a pending outbox
5902    /// commit — rows that MUST NOT be evicted until the commit drains.
5903    fn pinned_row_ids(&self, table: &str) -> std::collections::HashSet<String> {
5904        let mut pinned = std::collections::HashSet::new();
5905        for commit in self
5906            .outbox
5907            .iter()
5908            .map(|commit| &**commit)
5909            .chain(self.failed_commits.iter().map(|(commit, _)| commit))
5910        {
5911            for op in &commit.ops {
5912                if op.table == table {
5913                    pinned.insert(op.row_id.clone());
5914                }
5915            }
5916        }
5917        pinned
5918    }
5919
5920    fn save_pending_evict(
5921        &self,
5922        unit_id: &str,
5923        table: &str,
5924        effective: &[(String, Vec<String>)],
5925    ) -> Result<(), String> {
5926        self.conn.execute(
5927            "INSERT OR REPLACE INTO _syncular_pending_evictions(unit_id, tbl, effective_scopes) VALUES (?1, ?2, ?3)",
5928            rusqlite::params![unit_id, table, scope_map_to_json(effective).to_string()],
5929        ).map(|_| ()).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5930    }
5931
5932    /// Re-entry cancels every pending eviction of the unit.
5933    fn delete_pending_evict(&self, unit_id: &str) -> Result<(), String> {
5934        self.conn
5935            .execute(
5936                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
5937                [unit_id],
5938            )
5939            .map(|_| ())
5940            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5941    }
5942
5943    fn delete_pending_evict_table(&self, unit_id: &str, table: &str) -> Result<(), String> {
5944        self.conn
5945            .execute(
5946                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1 AND tbl = ?2",
5947                [unit_id, table],
5948            )
5949            .map(|_| ())
5950            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5951    }
5952
5953    fn load_pending_evictions(&self) -> Result<Vec<PendingEvict>, String> {
5954        let mut stmt = self
5955            .conn
5956            .prepare("SELECT unit_id, tbl, effective_scopes FROM _syncular_pending_evictions")
5957            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5958        let rows = stmt
5959            .query_map([], |row| {
5960                Ok((
5961                    row.get::<_, String>(0)?,
5962                    row.get::<_, String>(1)?,
5963                    row.get::<_, String>(2)?,
5964                ))
5965            })
5966            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5967        rows.map(|row| {
5968            let (unit_id, table, json) =
5969                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5970            let value: Value = serde_json::from_str(&json)
5971                .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5972            let effective = json_to_scope_map(&value)
5973                .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5974            Ok((unit_id, table, effective))
5975        })
5976        .collect()
5977    }
5978
5979    /// Select failed-intent retention; reload durable retained aggregates.
5980    pub fn set_retain_failed_commits(&mut self, enabled: bool) -> Result<(), String> {
5981        self.retain_failed_commits = enabled;
5982        for (commit, _) in self.failed_commits.iter() {
5983            for operation in &commit.ops {
5984                self.overlay_dirty.table(&operation.table);
5985            }
5986        }
5987        self.failed_commits = self.load_failed_commits()?.into();
5988        for (commit, _) in self.failed_commits.iter() {
5989            for operation in &commit.ops {
5990                self.overlay_dirty.table(&operation.table);
5991            }
5992        }
5993        Ok(())
5994    }
5995
5996    fn load_failed_commits(&self) -> Result<Vec<FailedCommit>, String> {
5997        let mut statement = self.conn.prepare("SELECT client_commit_id, operations_json, initial_json FROM _syncular_failed_commits ORDER BY seq")
5998            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5999        let rows = statement
6000            .query_map([], |row| {
6001                Ok((
6002                    row.get::<_, String>(0)?,
6003                    row.get::<_, String>(1)?,
6004                    row.get::<_, String>(2)?,
6005                ))
6006            })
6007            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6008        rows.map(|row| {
6009            let (id, operations, initial) =
6010                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6011            let operations: Vec<CommitOperation> =
6012                serde_json::from_str(&operations).map_err(|_| "sync.local_corrupt".to_owned())?;
6013            let initial =
6014                serde_json::from_str(&initial).map_err(|_| "sync.local_corrupt".to_owned())?;
6015            Ok((
6016                OutboxCommit {
6017                    client_commit_id: id,
6018                    ops: operations
6019                        .into_iter()
6020                        .map(|op| OutboxOp {
6021                            upsert: op.op == "upsert",
6022                            table: op.table,
6023                            row_id: op.row_id,
6024                            base_version: op.base_version,
6025                            values: op.values,
6026                            insert: op.insert,
6027                        })
6028                        .collect(),
6029                },
6030                initial,
6031            ))
6032        })
6033        .collect()
6034    }
6035
6036    fn retain_failed_commit(&mut self, id: &str, operations: &[OutboxOp]) -> Result<(), String> {
6037        let mut initial = Map::new();
6038        for operation in operations {
6039            // A table the current schema removed has no rows to retain.
6040            let Some(table) = self.schema.table(&operation.table) else {
6041                continue;
6042            };
6043            let initial_row = match self.stored_row(table, &operation.row_id, true)? {
6044                Some(row) => Some(row),
6045                None => self.visible_row(table, &operation.row_id)?,
6046            };
6047            if let Some((values, _)) = initial_row {
6048                let mut intended: Map<String, Value> = table
6049                    .columns
6050                    .iter()
6051                    .zip(values.iter())
6052                    .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
6053                    .collect();
6054                if let Some(patch) = &operation.values {
6055                    intended.extend(patch.clone());
6056                }
6057                initial.insert(
6058                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
6059                        .map_err(|_| "sync.local_corrupt".to_owned())?,
6060                    Value::Object(intended),
6061                );
6062            }
6063        }
6064        self.conn.execute("INSERT INTO _syncular_failed_commits(client_commit_id, operations_json, initial_json) VALUES (?1, ?2, ?3)", rusqlite::params![id,
6065            serde_json::to_string(&operations.iter().map(CommitOperation::from).collect::<Vec<_>>()).map_err(|_| "sync.local_corrupt".to_owned())?,
6066            serde_json::to_string(&initial).map_err(|_| "sync.local_corrupt".to_owned())?])
6067            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6068        self.failed_commits.push((
6069            OutboxCommit {
6070                client_commit_id: id.to_owned(),
6071                ops: operations.to_vec(),
6072            },
6073            initial,
6074        ));
6075        Ok(())
6076    }
6077
6078    fn drop_failed_commits(
6079        &mut self,
6080        matches: impl Fn(&str, &Map<String, Value>) -> bool,
6081    ) -> Result<Vec<OutboxCommit>, String> {
6082        let mut doomed = self.drop_acknowledged_rows(&matches)?;
6083        for (commit, initial) in self.failed_commits.iter() {
6084            for operation in &commit.ops {
6085                let key =
6086                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
6087                        .map_err(|_| "sync.local_corrupt".to_owned())?;
6088                if initial
6089                    .get(&key)
6090                    .and_then(Value::as_object)
6091                    .is_some_and(|values| matches(&operation.table, values))
6092                {
6093                    doomed.push(commit.clone());
6094                    break;
6095                }
6096            }
6097        }
6098        for commit in &doomed {
6099            self.conn
6100                .execute(
6101                    "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
6102                    rusqlite::params![commit.client_commit_id],
6103                )
6104                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6105        }
6106        for commit in &doomed {
6107            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))?;
6108        }
6109        self.conflicts.retain(|record| {
6110            !doomed
6111                .iter()
6112                .any(|commit| commit.client_commit_id == record.client_commit_id)
6113        });
6114        self.rejections.retain(|record| {
6115            !doomed
6116                .iter()
6117                .any(|commit| commit.client_commit_id == record.client_commit_id)
6118        });
6119        self.failed_commits.retain(|(commit, _)| {
6120            !doomed
6121                .iter()
6122                .any(|dropped| dropped.client_commit_id == commit.client_commit_id)
6123        });
6124        for commit in &doomed {
6125            for operation in &commit.ops {
6126                self.overlay_dirty.table(&operation.table);
6127            }
6128        }
6129        Ok(doomed)
6130    }
6131
6132    /// Record one commit of local mutations. The returned commit ID is the
6133    /// §2.3 idempotency key. Failures are structured so callers read
6134    /// `code`/`message`/`details` instead of parsing a string prefix.
6135    pub fn mutate(&mut self, mutations: Vec<Mutation>) -> Result<String, ClientError> {
6136        self.mutate_with_commit_id(mutations, None)
6137    }
6138
6139    /// [`Self::mutate`] under a caller-supplied `clientCommitId` (§7.1), so an
6140    /// app that loses the reply knows its commit. The ID is non-empty (§6.1);
6141    /// one this replica still holds fails with `client.commit_id_reused`.
6142    pub fn mutate_with_commit_id(
6143        &mut self,
6144        mutations: Vec<Mutation>,
6145        client_commit_id: Option<String>,
6146    ) -> Result<String, ClientError> {
6147        let prior = self.storage_failure.borrow_mut().take();
6148        if let Some(id) = &client_commit_id {
6149            let held = if id.is_empty() {
6150                Err("sync.invalid_request: clientCommitId is empty".to_owned())
6151            } else {
6152                self.conn
6153                    .query_row(
6154                        "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id=?1 UNION ALL SELECT 1 FROM _syncular_commit_outcomes WHERE client_commit_id=?1)",
6155                        [id],
6156                        |row| row.get(0),
6157                    )
6158                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
6159            };
6160            match held {
6161                Ok(false) => {}
6162                Ok(true) => {
6163                    return self.finish_authoring(
6164                        prior,
6165                        Err(ClientError {
6166                            code: "client.commit_id_reused".to_owned(),
6167                            message: "clientCommitId is held".to_owned(),
6168                            details: Some(json!({ "clientCommitId": id })),
6169                            retryable: false,
6170                        }),
6171                    )
6172                }
6173                Err(message) => return self.finish_authoring(prior, Err(message.into())),
6174            }
6175        }
6176        let outcome = self
6177            .prepare_mutations(mutations)
6178            .and_then(|ops| Ok(self.record_outbox_commit(ops, client_commit_id, None)?));
6179        self.finish_authoring(prior, outcome)
6180    }
6181
6182    /// §7.1: validate one commit's mutations into outbox operations.
6183    fn prepare_mutations(&self, mutations: Vec<Mutation>) -> Result<Vec<OutboxOp>, ClientError> {
6184        {
6185            if mutations.is_empty() {
6186                return Err(
6187                    "sync.invalid_request: a commit must contain at least one operation (§6.1)"
6188                        .to_owned()
6189                        .into(),
6190                );
6191            }
6192            let mut ops = Vec::with_capacity(mutations.len());
6193            // §7.1: a patch reads the row as the commit's earlier operations
6194            // leave it: the values an earlier upsert wrote, or None after an
6195            // earlier delete. A patch changes neither presence nor a scope
6196            // column, so it records nothing.
6197            let mut staged: HashMap<(String, String), Option<Map<String, Value>>> = HashMap::new();
6198            for mutation in mutations {
6199                match mutation {
6200                    Mutation::Patch {
6201                        table,
6202                        values,
6203                        base_version,
6204                    } => {
6205                        let schema_table = self
6206                            .schema
6207                            .table(&table)
6208                            .ok_or_else(|| "sync.unknown_table".to_owned())?;
6209                        let values = normalize_values_casing(schema_table, values)?;
6210                        let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
6211                        let base = staged.get(&(table.clone(), row_id.clone()));
6212                        ops.push(self.prepare_patch(
6213                            &table,
6214                            &row_id,
6215                            values,
6216                            base_version,
6217                            base,
6218                        )?);
6219                    }
6220                    Mutation::Upsert {
6221                        table,
6222                        values,
6223                        base_version,
6224                    } => {
6225                        let schema_table = self.schema.table(&table).ok_or_else(|| {
6226                            format!("sync.unknown_table: unknown table {table:?}")
6227                        })?;
6228                        // §5: value keys are accepted in snake_case AND the
6229                        // generated row types' camelCase; normalize to SQL truth
6230                        // before the pk lookup / codec see them.
6231                        let values = normalize_values_casing(schema_table, values)?;
6232                        let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
6233                        // §6.7 `mutate` marks every column present: fill missing
6234                        // nullable columns with NULL before the payload is built.
6235                        let values = full_row_values(schema_table, values)?;
6236                        self.refuse_sealed_row(schema_table, &row_id)?;
6237                        // §5.11: validate the payload encodes with the current
6238                        // codec. A key-selection or unknown-key failure is a
6239                        // durable rejection at the push seam (§10.3), never an
6240                        // author-time error. Full-row `mutate` presents every
6241                        // column, so no stored fallback is needed.
6242                        self.validate_author_encode(schema_table, &row_id, &values)?;
6243                        // §7.1 insert intent: the row is absent from the
6244                        // visible replica at call time, before this batch
6245                        // applies anything.
6246                        let insert = !self.visible_row_exists(schema_table, &row_id)?;
6247                        staged.insert((table.clone(), row_id.clone()), Some(values.clone()));
6248                        ops.push(OutboxOp {
6249                            upsert: true,
6250                            table,
6251                            row_id,
6252                            base_version,
6253                            values: Some(values),
6254                            insert,
6255                        });
6256                    }
6257                    Mutation::Delete {
6258                        table,
6259                        row_id,
6260                        base_version,
6261                    } => {
6262                        let schema_table = self.schema.table(&table).ok_or_else(|| {
6263                            format!("sync.unknown_table: unknown table {table:?}")
6264                        })?;
6265                        self.refuse_sealed_row(schema_table, &row_id)?;
6266                        // §2.4: the server rejects a rowId holding U+0000.
6267                        if row_id.contains('\0') {
6268                            return Err("sync.invalid_request: rowId holds U+0000 (§2.4)"
6269                                .to_owned()
6270                                .into());
6271                        }
6272                        staged.insert((table.clone(), row_id.clone()), None);
6273                        ops.push(OutboxOp {
6274                            upsert: false,
6275                            table,
6276                            row_id,
6277                            base_version,
6278                            values: None,
6279                            insert: false,
6280                        });
6281                    }
6282                }
6283            }
6284            Ok(ops)
6285        }
6286    }
6287
6288    /// Scope the retained `storage_failure` diagnostic to this call so an
6289    /// earlier operation's failure cannot classify a new one, and surface the
6290    /// call's own classified failure with its details. A fresh classified
6291    /// failure replaces the retained diagnostic; otherwise the earlier one is
6292    /// kept for the next sync.
6293    fn finish_authoring(
6294        &self,
6295        prior: Option<QueryReadFailure>,
6296        outcome: Result<String, ClientError>,
6297    ) -> Result<String, ClientError> {
6298        let fresh = self.storage_failure.borrow_mut().take();
6299        *self.storage_failure.borrow_mut() = fresh.clone().or(prior);
6300        outcome.map_err(|error| fresh.map(ClientError::from).unwrap_or(error))
6301    }
6302
6303    /// `decides` names the active outcome this commit replaces (§7.2.2); the
6304    /// outcome records it as its pending decision in the same transaction.
6305    fn record_outbox_commit(
6306        &mut self,
6307        ops: Vec<OutboxOp>,
6308        client_commit_id: Option<String>,
6309        decides: Option<&str>,
6310    ) -> Result<String, String> {
6311        let commit = OutboxCommit {
6312            client_commit_id: client_commit_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
6313            ops,
6314        };
6315        self.begin_observation("syncular_mutation")?;
6316        let mut batch = ChangeAccumulator::default();
6317        for op in &commit.ops {
6318            let mut precise = self.record_row_scopes(&mut batch, &op.table, &op.row_id, false);
6319            if let Some(values) = &op.values {
6320                if let Some(table) = self.schema.table(&op.table) {
6321                    for scope in &table.scope_variables {
6322                        if let Some(Value::String(value)) = values.get(&scope.column) {
6323                            batch.scope(&op.table, format!("{}:{value}", scope.prefix));
6324                            precise = true;
6325                        }
6326                    }
6327                }
6328            }
6329            if !precise {
6330                batch.table(&op.table);
6331            }
6332        }
6333        let persisted = self.persist_outbox_insert(&commit).and_then(|()| {
6334            let Some(outcome) = decides else {
6335                return Ok(());
6336            };
6337            batch.outcomes = true;
6338            let updated = self
6339                .conn
6340                .execute(
6341                    "UPDATE _syncular_commit_outcomes SET replacement_client_commit_id = ?1
6342                      WHERE client_commit_id = ?2 AND resolution = 'active'
6343                        AND replacement_client_commit_id IS NULL",
6344                    rusqlite::params![commit.client_commit_id, outcome],
6345                )
6346                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6347            if updated == 1 {
6348                Ok(())
6349            } else {
6350                Err(REPLACEMENT_PENDING.to_owned())
6351            }
6352        });
6353        if let Err(error) = persisted {
6354            self.rollback_observation("syncular_mutation");
6355            return Err(error);
6356        }
6357        // A clean overlay contains the FIFO fold of every previous commit, so
6358        // the new commit applies over it. §7.1: an operation that does not
6359        // apply (a secondary unique collision) fails the whole commit; the
6360        // savepoint rollback removes the outbox entry and every visible write.
6361        // The append undoes itself: a rollback capture would copy the outbox.
6362        let was_dirty = self.overlay_dirty.snapshot();
6363        let id = commit.client_commit_id.clone();
6364        let appended = self.rebuild_overlay_if_dirty().and_then(|()| {
6365            commit
6366                .ops
6367                .iter()
6368                .try_for_each(|op| self.apply_outbox_op(op))?;
6369            self.outbox.push(Arc::new(commit));
6370            batch.status = true;
6371            self.finish_observation("syncular_mutation", batch)
6372                .inspect_err(|_| drop(self.outbox.pop()))
6373        });
6374        if let Err(error) = appended {
6375            self.rollback_observation("syncular_mutation");
6376            self.overlay_dirty.restore(was_dirty);
6377            return Err(error);
6378        }
6379        Ok(id)
6380    }
6381
6382    /// Record one §6.1 sparse upsert: the primary key plus the supplied
6383    /// non-scope columns are present; every other column is absent and stays
6384    /// untouched on the server and in the local overlay. An absent local base
6385    /// refuses the whole batch with sync.row_missing before enqueueing (§7.1).
6386    /// Failures are structured so callers read `code`/`message`/`details`.
6387    pub fn patch(
6388        &mut self,
6389        table: &str,
6390        row_id: &str,
6391        partial: Map<String, Value>,
6392        base_version: Option<i64>,
6393    ) -> Result<String, ClientError> {
6394        let prior = self.storage_failure.borrow_mut().take();
6395        let outcome = self.perform_patch(table, row_id, partial, base_version);
6396        self.finish_authoring(prior, outcome)
6397    }
6398
6399    /// The unscoped patch body. Public authoring entry points scope
6400    /// `storage_failure` around the whole operation, including any pre-read.
6401    fn perform_patch(
6402        &mut self,
6403        table: &str,
6404        row_id: &str,
6405        partial: Map<String, Value>,
6406        base_version: Option<i64>,
6407    ) -> Result<String, ClientError> {
6408        let operation = self.prepare_patch(table, row_id, partial, base_version, None)?;
6409        Ok(self.record_outbox_commit(vec![operation], None, None)?)
6410    }
6411
6412    /// `staged` is the row as the batch's earlier operations leave it
6413    /// (`Some(None)` after a delete); `None` reads the visible replica.
6414    fn prepare_patch(
6415        &self,
6416        table: &str,
6417        row_id: &str,
6418        partial: Map<String, Value>,
6419        base_version: Option<i64>,
6420        staged: Option<&Option<Map<String, Value>>>,
6421    ) -> Result<OutboxOp, ClientError> {
6422        let schema_table = self
6423            .schema
6424            .table(table)
6425            .ok_or_else(|| format!("sync.unknown_table: unknown table {table:?}"))?;
6426        let partial = normalize_values_casing(schema_table, partial)?;
6427        if let Some(pk) = partial.get(&schema_table.primary_key) {
6428            if render_row_id_json(Some(pk)).ok().as_deref() != Some(row_id) {
6429                return Err(invalid_authoring(
6430                    "patch cannot change the primary key",
6431                    json!({ "table": table }),
6432                ));
6433            }
6434        }
6435        let exists = match staged {
6436            Some(row) => row.is_some(),
6437            None => self.visible_row_exists(schema_table, row_id)?,
6438        };
6439        if !exists {
6440            return Err("sync.row_missing: a sparse patch requires a local row"
6441                .to_owned()
6442                .into());
6443        }
6444        self.refuse_sealed_row(schema_table, row_id)?;
6445        // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
6446        // server accepts a present scope column whose value equals the
6447        // stored row and applies it as a no-op, so a decoded envelope
6448        // round-trips. The local row is the only value the client can prove
6449        // equality against; when the row is absent locally the client cannot
6450        // prove equality against the server's stored row and fails closed.
6451        // A primary key that is also a scope column needs no stored-row
6452        // read: the primary key in a sparse payload is by construction the
6453        // row id being patched (§6.1), so its value is proven equal already.
6454        for scope in &schema_table.scope_variables {
6455            if !partial.contains_key(&scope.column) || scope.column == schema_table.primary_key {
6456                continue;
6457            }
6458            let Some(column) = schema_table
6459                .columns
6460                .iter()
6461                .find(|column| column.name == scope.column)
6462            else {
6463                continue;
6464            };
6465            let stored = match staged {
6466                Some(row) => row.as_ref().and_then(|row| {
6467                    json_to_column_value(column, row.get(&scope.column))
6468                        .ok()
6469                        .map(|value| column_value_to_json(&value))
6470                }),
6471                None => self
6472                    .conn
6473                    .query_row(
6474                        &format!(
6475                            "SELECT {} FROM {} WHERE {}",
6476                            quote_ident(&scope.column),
6477                            visible_table(&schema_table.name),
6478                            row_id_predicate(schema_table)
6479                        ),
6480                        rusqlite::params![row_id],
6481                        |row| Ok(sql_ref_to_json(column, row.get_ref(0)?)),
6482                    )
6483                    .optional()
6484                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
6485            };
6486            // Decode the supplied value through the same column-type path the
6487            // rest of the patch encoding uses, so a value that only equals
6488            // the stored one in another number representation still compares
6489            // equal.
6490            let incoming = json_to_column_value(column, partial.get(&scope.column))
6491                .ok()
6492                .map(|value| column_value_to_json(&value));
6493            // A stored blob never equals a patch value, matching the server's
6494            // scope-column comparison (§3.4): bytes are unstorable as scope
6495            // values.
6496            let equal = stored.as_ref().is_some_and(|stored| {
6497                stored.get("$bytes").is_none() && incoming.as_ref() == Some(stored)
6498            });
6499            if !equal {
6500                return Err(invalid_authoring(
6501                    "patch cannot write a scope column (§3.4)",
6502                    json!({ "table": table, "column": scope.column }),
6503                ));
6504            }
6505        }
6506        let mut values = partial;
6507        // Presence-set semantics: a proven-equal scope column is dropped, so
6508        // the patch leaves the stored value untouched (§6.2).
6509        for scope in &schema_table.scope_variables {
6510            values.remove(&scope.column);
6511        }
6512        let pk_value = match schema_table.columns[schema_table.pk_index].ty {
6513            // §2.4: the rowId of an integer key is its canonical decimal form.
6514            ColumnType::Integer => match row_id.parse::<i64>() {
6515                Ok(v)
6516                    if v.to_string() == row_id
6517                        && (-ssp2::primitives::I64_SAFE_MAX..=ssp2::primitives::I64_SAFE_MAX)
6518                            .contains(&v) =>
6519                {
6520                    Value::from(v)
6521                }
6522                _ => {
6523                    return Err(format!(
6524                    "sync.invalid_request: table {table:?}: invalid integer primary key {row_id:?}"
6525                )
6526                    .into())
6527                }
6528            },
6529            ColumnType::Boolean => match row_id {
6530                "true" => Value::Bool(true),
6531                "false" => Value::Bool(false),
6532                _ => {
6533                    return Err(format!(
6534                    "sync.invalid_request: table {table:?}: invalid boolean primary key {row_id:?}"
6535                )
6536                    .into())
6537                }
6538            },
6539            _ => Value::from(row_id.to_owned()),
6540        };
6541        values.insert(schema_table.primary_key.clone(), pk_value);
6542        // §6.1: a patch cannot null a non-nullable column.
6543        if let Some(column) = schema_table
6544            .columns
6545            .iter()
6546            .find(|column| !column.nullable && values.get(&column.name) == Some(&Value::Null))
6547        {
6548            return Err(invalid_authoring(
6549                "a non-nullable column is null (§6.1)",
6550                json!({ "table": table, "column": column.name }),
6551            ));
6552        }
6553        // §5.11: structural validation only; an absent key-id selector is
6554        // resolved at the push seam from the stored local row, and a
6555        // key-selection or unknown-key failure becomes a durable
6556        // `client.encrypt_failed` rejection there (§10.3), never an
6557        // author-time error.
6558        self.validate_author_encode(schema_table, row_id, &values)?;
6559        Ok(OutboxOp {
6560            upsert: true,
6561            table: table.to_owned(),
6562            row_id: row_id.to_owned(),
6563            base_version,
6564            values: Some(values),
6565            insert: false,
6566        })
6567    }
6568
6569    /// §5.11 key-id fallback: the stored local row's selector value as a
6570    /// positional row (only the selector slot filled). Returns None when no
6571    /// selector is configured, the row is locally absent, or the stored
6572    /// value is not a usable key id. A failed storage read is an error.
6573    fn stored_key_fallback(
6574        &self,
6575        table: &TableSchema,
6576        row_id: &str,
6577    ) -> Result<Option<Row>, String> {
6578        let Some(selector) = self.encryption.key_id_columns.get(&table.name) else {
6579            return Ok(None);
6580        };
6581        let Some(index) = table
6582            .columns
6583            .iter()
6584            .position(|column| &column.name == selector)
6585        else {
6586            return Ok(None);
6587        };
6588        let sql = format!(
6589            "SELECT {} FROM {} WHERE {}",
6590            quote_ident(selector),
6591            visible_table(&table.name),
6592            row_id_predicate(table)
6593        );
6594        let key = self
6595            .conn
6596            .query_row(&sql, rusqlite::params![row_id], |row| {
6597                row.get::<_, Option<String>>(0)
6598            })
6599            .optional()
6600            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6601            .flatten()
6602            .filter(|key| !key.is_empty());
6603        let Some(key) = key else {
6604            return Ok(None);
6605        };
6606        let mut fallback: Row = vec![None; table.columns.len()];
6607        fallback[index] = Some(ColumnValue::String(key));
6608        Ok(Some(fallback))
6609    }
6610
6611    /// §5.11/§10.3 author-time encode check: a structural failure (a
6612    /// non-nullable NULL, a value the codec rejects) is an author-time
6613    /// error; a key-selection or unknown-key failure is deferred to the push
6614    /// seam, where it becomes a durable `client.encrypt_failed` rejection.
6615    fn validate_author_encode(
6616        &self,
6617        table: &TableSchema,
6618        row_id: &str,
6619        values: &Map<String, Value>,
6620    ) -> Result<(), String> {
6621        match encode_sparse_row_json(table, row_id, values, &self.encryption, None) {
6622            Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => Ok(()),
6623            result => result.map(|_| ()),
6624        }
6625    }
6626
6627    /// §5.11/§10.3: drop every pending commit whose push encode fails with
6628    /// `client.encrypt_failed` (an unresolvable key id or an unknown key) and
6629    /// raise one durable rejection per commit. `sync()` never aborts for an
6630    /// encode failure. Mirrors §7.4.4's `drop_incompatible_outbox`, including
6631    /// undoing the dropped commit's purely-optimistic rows.
6632    /// §7.1/§7.4.4: drop pending commits whose values the current codec refuses
6633    /// (an envelope or a type an earlier version accepted). `with_encryption`
6634    /// additionally drops commits whose §5.11 encryption cannot resolve a key;
6635    /// the startup boundary leaves those to the send seam, where hosts configure
6636    /// keys after open.
6637    /// Recovery runs as one observation. An enclosing observation (the guarded
6638    /// schema reset) passes its `batch`, so the rejection, outcome, and table
6639    /// domains join that change event instead of publishing a second one.
6640    fn drop_unencodable_outbox(
6641        &mut self,
6642        with_encryption: bool,
6643        batch: Option<&mut ChangeAccumulator>,
6644    ) -> Result<bool, String> {
6645        let mut failures = Vec::new();
6646        for commit in self.outbox.iter() {
6647            for op in &commit.ops {
6648                let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6649                    continue;
6650                };
6651                // An insert lacking a non-nullable column is left to
6652                // `drop_incompatible_outbox` (§7.4.4).
6653                let Some(values) = op.presented_values(table) else {
6654                    continue;
6655                };
6656                let fallback = self.stored_key_fallback(table, &op.row_id)?;
6657                let failure = match encode_sparse_row_json(
6658                    table,
6659                    &op.row_id,
6660                    &values,
6661                    &self.encryption,
6662                    fallback.as_ref(),
6663                ) {
6664                    Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => {
6665                        with_encryption.then_some((error, ENCRYPT_FAILED_CODE))
6666                    }
6667                    // §7.1/§7.4.4: a value the current codec refuses was
6668                    // persisted by a version that accepted it; it leaves
6669                    // through the incompatible-outbox path, so the FIFO
6670                    // queue never wedges.
6671                    Err(error) if error.starts_with(INVALID_REQUEST_CODE) => Some((
6672                        LEGACY_VALUE_REFUSAL_MESSAGE.to_owned(),
6673                        OUTBOX_INCOMPATIBLE_CODE,
6674                    )),
6675                    _ => None,
6676                };
6677                if let Some((error, code)) = failure {
6678                    failures.push((commit.clone(), error, code));
6679                    break;
6680                }
6681            }
6682        }
6683        if failures.is_empty() {
6684            return Ok(false);
6685        }
6686        self.reject_outbox_commits(
6687            failures
6688                .into_iter()
6689                .map(|(commit, message, code)| {
6690                    let details = (code == OUTBOX_INCOMPATIBLE_CODE).then(|| RejectionDetails {
6691                        field_paths: None,
6692                        reason: Some(INVALID_STORED_VALUES_REASON.to_owned()),
6693                        required_action: None,
6694                        references: None,
6695                    });
6696                    (commit, message, code, details)
6697                })
6698                .collect(),
6699            batch,
6700        )?;
6701        Ok(true)
6702    }
6703
6704    /// §7.4.4 client-local terminal drop of pending commits, each journaled as a
6705    /// rejection with `code` and `details`. Every code except
6706    /// `sync.outbox_incompatible` keeps the retained intent.
6707    #[allow(clippy::type_complexity)]
6708    fn reject_outbox_commits(
6709        &mut self,
6710        failures: Vec<(
6711            Arc<OutboxCommit>,
6712            String,
6713            &'static str,
6714            Option<RejectionDetails>,
6715        )>,
6716        batch: Option<&mut ChangeAccumulator>,
6717    ) -> Result<(), String> {
6718        // §7.4.4: one observation covers the durable outcome writes, the outbox
6719        // removal, the in-memory drop, and the overlay rebuild, so a storage fault
6720        // leaves the replica and the client unchanged, a successful recovery
6721        // publishes one batch with the rejection, outcome, and table domains, and
6722        // an ordinary open with nothing to recover publishes nothing.
6723        let rollback = self.capture();
6724        let owns_observation = batch.is_none();
6725        let owns_transaction = self.conn.is_autocommit();
6726        let mut domains = ChangeAccumulator::default();
6727        if owns_observation {
6728            self.begin_observation("syncular_value_recovery")?;
6729        }
6730        let dropped = (|| -> Result<(), String> {
6731            for (commit, message, code, details) in failures {
6732                if self.retain_failed_commits && code != OUTBOX_INCOMPATIBLE_CODE {
6733                    self.retain_failed_commit(&commit.client_commit_id, &commit.ops)?;
6734                }
6735                let representable = commit.ops.iter().all(Self::outbox_op_is_journalable);
6736                let rejection = RejectionRecord {
6737                    client_commit_id: commit.client_commit_id.clone(),
6738                    op_index: 0,
6739                    code: code.to_owned(),
6740                    message,
6741                    retryable: false,
6742                    details,
6743                    operation: representable
6744                        .then(|| commit.ops.first())
6745                        .flatten()
6746                        .map(CommitOperation::from),
6747                };
6748                self.persist_commit_outcome(
6749                    &commit.client_commit_id,
6750                    CommitOutcomeStatus::Rejected,
6751                    &[CommitOperationOutcome::Error {
6752                        rejection: rejection.clone(),
6753                    }],
6754                    representable.then_some(commit.ops.as_slice()),
6755                )?;
6756                self.delete_outbox_persisted(&commit.client_commit_id)?;
6757                self.outbox
6758                    .retain(|candidate| candidate.client_commit_id != commit.client_commit_id);
6759                self.rejections.push(rejection);
6760                for operation in &commit.ops {
6761                    domains.table(operation.table.as_str());
6762                }
6763            }
6764            domains.status = true;
6765            domains.rejections = true;
6766            domains.outcomes = true;
6767            self.prune_commit_outcomes()?;
6768            // The visible projection is re-derived from the surviving base + outbox.
6769            self.overlay_dirty.set(true);
6770            self.rebuild_overlay()?;
6771            Ok(())
6772        })();
6773        let result = match batch {
6774            Some(batch) => {
6775                if dropped.is_ok() {
6776                    for table in domains.tables.keys() {
6777                        batch.table(table.as_str());
6778                    }
6779                    batch.status |= domains.status;
6780                    batch.rejections |= domains.rejections;
6781                    batch.outcomes |= domains.outcomes;
6782                }
6783                dropped
6784            }
6785            None => {
6786                dropped.and_then(|()| self.finish_observation("syncular_value_recovery", domains))
6787            }
6788        };
6789        if let Err(error) = result {
6790            if owns_observation {
6791                if owns_transaction {
6792                    if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
6793                        let mut failure = self.storage_failure.borrow_mut();
6794                        let failure =
6795                            failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
6796                        failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
6797                    }
6798                } else {
6799                    self.rollback_observation("syncular_value_recovery");
6800                }
6801            }
6802            self.restore(rollback);
6803            return Err(error);
6804        }
6805        Ok(())
6806    }
6807
6808    pub fn pending_commit_ids(&self) -> Vec<String> {
6809        self.outbox
6810            .iter()
6811            .map(|c| c.client_commit_id.clone())
6812            .collect()
6813    }
6814
6815    /// §7.1: every pending commit in FIFO order, as the TypeScript client's
6816    /// `pendingCommits()` returns it.
6817    pub fn pending_commits(&self) -> Result<Vec<PendingCommit>, String> {
6818        let mut stmt = self
6819            .conn
6820            .prepare_cached(
6821                "SELECT seq, commit_id, created_at_ms, ops_json FROM _syncular_outbox ORDER BY seq",
6822            )
6823            .map_err(|error| error.to_string())?;
6824        let rows = stmt
6825            .query_map([], |row| {
6826                Ok((
6827                    row.get(0)?,
6828                    row.get(1)?,
6829                    row.get(2)?,
6830                    row.get::<_, String>(3)?,
6831                ))
6832            })
6833            .map_err(|error| error.to_string())?;
6834        rows.map(|row| {
6835            let (seq, client_commit_id, created_at_ms, raw) =
6836                row.map_err(|error| error.to_string())?;
6837            let operations = serde_json::from_str(&raw).map_err(|error| {
6838                format!("invalid persisted outbox {client_commit_id:?}: {error}")
6839            })?;
6840            Ok(PendingCommit {
6841                seq,
6842                client_commit_id,
6843                created_at_ms,
6844                operations,
6845            })
6846        })
6847        .collect()
6848    }
6849
6850    /// §6.1: the sparse push payload bytes of every pending upsert operation,
6851    /// FIFO — exactly what the next push round would put on the wire. Used by
6852    /// conformance B.21(h) to pin cross-core byte identity.
6853    pub fn pending_payloads(&self) -> Result<Vec<Vec<u8>>, String> {
6854        let mut payloads = Vec::new();
6855        for commit in self.outbox.iter() {
6856            for op in &commit.ops {
6857                let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6858                    continue;
6859                };
6860                let Some(values) = op.presented_values(table) else {
6861                    continue;
6862                };
6863                let fallback = self.stored_key_fallback(table, &op.row_id)?;
6864                if let Ok(payload) = encode_sparse_row_json(
6865                    table,
6866                    &op.row_id,
6867                    &values,
6868                    &self.encryption,
6869                    fallback.as_ref(),
6870                ) {
6871                    payloads.push(payload);
6872                }
6873            }
6874        }
6875        Ok(payloads)
6876    }
6877
6878    pub fn conflicts(&self) -> &[ConflictRecord] {
6879        &self.conflicts
6880    }
6881
6882    pub fn rejections(&self) -> &[RejectionRecord] {
6883        &self.rejections
6884    }
6885
6886    pub fn resolve_commit_outcome(
6887        &mut self,
6888        input: ResolveCommitOutcomeInput,
6889    ) -> Result<CommitOutcome, String> {
6890        let current = self
6891            .commit_outcome(&input.client_commit_id)?
6892            .ok_or_else(|| {
6893                format!(
6894                    "sync.outcome_not_found: no durable outcome exists for {:?}",
6895                    input.client_commit_id
6896                )
6897            })?;
6898        if current.resolution != CommitOutcomeResolution::Active {
6899            return Ok(current);
6900        }
6901        if current.replacement_client_commit_id.is_some() {
6902            return Err(REPLACEMENT_PENDING.to_owned());
6903        }
6904        if input.resolution == CommitOutcomeResolution::Active {
6905            return Err("sync.invalid_request: resolution must leave active state".to_owned());
6906        }
6907        match input.resolution {
6908            CommitOutcomeResolution::Superseded => {
6909                let replacement = input
6910                    .replacement_client_commit_id
6911                    .as_deref()
6912                    .filter(|value| !value.is_empty() && *value != input.client_commit_id)
6913                    .ok_or_else(|| {
6914                        "sync.invalid_request: superseded outcomes require a distinct replacementClientCommitId"
6915                            .to_owned()
6916                    })?;
6917                let _ = replacement;
6918            }
6919            _ if input.replacement_client_commit_id.is_some() => {
6920                return Err(
6921                    "sync.invalid_request: replacementClientCommitId is valid only for superseded outcomes"
6922                        .to_owned(),
6923                );
6924            }
6925            _ => {}
6926        }
6927        let allowed = match current.status {
6928            CommitOutcomeStatus::Conflict => matches!(
6929                input.resolution,
6930                CommitOutcomeResolution::ResolvedKeepServer | CommitOutcomeResolution::Superseded
6931            ),
6932            CommitOutcomeStatus::Rejected => {
6933                matches!(
6934                    input.resolution,
6935                    CommitOutcomeResolution::Superseded
6936                        | CommitOutcomeResolution::ResolvedKeepServer
6937                )
6938            }
6939            CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => {
6940                input.resolution == CommitOutcomeResolution::Dismissed
6941            }
6942        };
6943        if !allowed {
6944            return Err(format!(
6945                "sync.invalid_request: resolution {:?} is invalid for {:?} outcome",
6946                input.resolution, current.status
6947            ));
6948        }
6949
6950        let rollback = self.capture();
6951        self.begin_observation("syncular_outcome_resolution")?;
6952        let mut batch = ChangeAccumulator::default();
6953        let result = self
6954            .release_outcome(
6955                &current,
6956                input.resolution,
6957                input.replacement_client_commit_id.as_deref(),
6958                &mut batch,
6959            )
6960            .and_then(|()| self.rebuild_overlay_if_dirty())
6961            .and_then(|()| self.finish_observation("syncular_outcome_resolution", batch));
6962        if let Err(error) = result {
6963            self.rollback_observation("syncular_outcome_resolution");
6964            self.restore(rollback);
6965            return Err(error);
6966        }
6967        self.commit_outcome(&current.client_commit_id)?
6968            .ok_or_else(|| "sync.outcome_not_found: outcome disappeared".to_owned())
6969    }
6970
6971    /// §7.2.2: record a decision against an active conflict or rejection as a
6972    /// held replacement commit and return its client commit id. Without
6973    /// `replacement` the retained envelope is kept ("keep mine"); every
6974    /// operation on a retained row takes that row's base version.
6975    pub fn replace_commit_outcome(
6976        &mut self,
6977        client_commit_id: &str,
6978        sequence: i64,
6979        replacement: Option<Vec<Mutation>>,
6980    ) -> Result<String, ClientError> {
6981        let prior = self.storage_failure.borrow_mut().take();
6982        let outcome = (|| -> Result<String, ClientError> {
6983            let Some(current) = self.commit_outcome(client_commit_id)? else {
6984                return Err(ClientError {
6985                    code: "sync.outcome_not_found".to_owned(),
6986                    message: "no durable outcome exists for the commit".to_owned(),
6987                    details: Some(json!({ "clientCommitId": client_commit_id })),
6988                    retryable: false,
6989                });
6990            };
6991            if current.resolution == CommitOutcomeResolution::Active
6992                && current.replacement_client_commit_id.is_some()
6993            {
6994                return Err(ClientError {
6995                    code: "client.replacement_pending".to_owned(),
6996                    message: "the outcome has a pending replacement".to_owned(),
6997                    details: Some(json!({ "clientCommitId": client_commit_id })),
6998                    retryable: false,
6999                });
7000            }
7001            let (Some(envelope), Some(rows)) = (current.operations, current.retained_rows) else {
7002                return Err(invalid_authoring(
7003                    "the outcome cannot be replaced",
7004                    json!({ "clientCommitId": client_commit_id }),
7005                ));
7006            };
7007            if current.sequence != sequence
7008                || current.resolution != CommitOutcomeResolution::Active
7009                || !matches!(
7010                    current.status,
7011                    CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
7012                )
7013                || rows.is_empty()
7014                || envelope.len() != rows.len()
7015            {
7016                return Err(invalid_authoring(
7017                    "the outcome cannot be replaced",
7018                    json!({ "clientCommitId": client_commit_id }),
7019                ));
7020            }
7021            let ops = match replacement {
7022                None => envelope
7023                    .into_iter()
7024                    .zip(&rows)
7025                    .map(|(operation, row)| OutboxOp {
7026                        base_version: Some(row.server_version.unwrap_or(0)),
7027                        ..OutboxOp::from(operation)
7028                    })
7029                    .collect(),
7030                Some(mutations) => {
7031                    let mut ops = self.prepare_mutations(mutations)?;
7032                    for op in &mut ops {
7033                        let Some(row) = rows
7034                            .iter()
7035                            .find(|row| row.table == op.table && row.row_id == op.row_id)
7036                        else {
7037                            continue;
7038                        };
7039                        if op.base_version.is_some() {
7040                            return Err(invalid_authoring(
7041                                "an operation on a retained row takes its base version",
7042                                json!({ "table": op.table }),
7043                            ));
7044                        }
7045                        op.base_version = Some(row.server_version.unwrap_or(0));
7046                    }
7047                    ops
7048                }
7049            };
7050            Ok(self.record_outbox_commit(ops, None, Some(client_commit_id))?)
7051        })();
7052        self.finish_authoring(prior, outcome)
7053    }
7054
7055    /// Internal host step at the start of an idle drive (§7.2.2): capture
7056    /// every pending decision with the units and epochs of this drive.
7057    #[doc(hidden)]
7058    pub fn prepare_replacements(&self) -> Result<Vec<CurrentBasePreparation>, String> {
7059        let mut stmt = self
7060            .conn
7061            .prepare_cached(
7062                "SELECT client_commit_id, seq, replacement_client_commit_id
7063                   FROM _syncular_commit_outcomes
7064                  WHERE resolution = 'active' AND replacement_client_commit_id IS NOT NULL
7065                  ORDER BY seq ASC",
7066            )
7067            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7068        let decisions = stmt
7069            .query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))
7070            .and_then(|rows| rows.collect::<Result<Vec<(String, i64, String)>, _>>())
7071            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7072        if decisions.is_empty() {
7073            return Ok(Vec::new());
7074        }
7075        let units = self.stored(load_units(&self.conn))?;
7076        Ok(decisions
7077            .into_iter()
7078            .map(
7079                |(client_commit_id, sequence, replacement)| CurrentBasePreparation {
7080                    client_commit_id,
7081                    sequence,
7082                    replacement: Some(replacement),
7083                    units: units.clone(),
7084                    transport_epoch: self.transport_epoch,
7085                    registration_epoch: self.registration_epoch,
7086                    security_epoch: self.security_epoch,
7087                },
7088            )
7089            .collect())
7090    }
7091
7092    /// Internal host step when an idle drive reaches idle (§7.2.2): write,
7093    /// refuse, or keep each decision captured at the drive's start. Returns
7094    /// whether a decision was written, so the drive runs another round.
7095    #[doc(hidden)]
7096    pub fn settle_replacements(
7097        &mut self,
7098        decisions: &[CurrentBasePreparation],
7099        drive: &SyncOutcome,
7100    ) -> Result<bool, String> {
7101        if !self.transport_enabled {
7102            return Ok(false);
7103        }
7104        let mut written = false;
7105        for decision in decisions {
7106            // A registration change during the drive says nothing about the
7107            // base; the decision waits for the next drive.
7108            if decision.registration_epoch != self.registration_epoch {
7109                continue;
7110            }
7111            let Some(replacement) = decision.replacement.as_deref() else {
7112                continue;
7113            };
7114            let Some(current) =
7115                self.commit_outcome(&decision.client_commit_id)?
7116                    .filter(|current| {
7117                        current.resolution == CommitOutcomeResolution::Active
7118                            && current.replacement_client_commit_id.as_deref() == Some(replacement)
7119                    })
7120            else {
7121                continue;
7122            };
7123            let held = self
7124                .outbox
7125                .iter()
7126                .find(|commit| commit.client_commit_id == replacement)
7127                .cloned();
7128            let refused = match &held {
7129                // A revocation drop (§3.3) or a crash already ended the
7130                // replacement; its own journal entry records what happened.
7131                None => None,
7132                Some(commit) => match self.finish_current_base(decision.clone(), drive.clone()) {
7133                    CurrentBaseProof {
7134                        rows: Some(rows), ..
7135                    } => {
7136                        let proven = commit.ops.iter().all(|op| {
7137                            rows.iter()
7138                                .find(|row| row.table == op.table && row.row_id == op.row_id)
7139                                .is_none_or(|row| {
7140                                    op.base_version == Some(row.server_version.unwrap_or(0))
7141                                })
7142                        });
7143                        written |= proven;
7144                        (!proven).then(|| "base_moved".to_owned())
7145                    }
7146                    CurrentBaseProof {
7147                        reason:
7148                            Some(
7149                                reason @ (CurrentBaseProofReason::SchemaFloor
7150                                | CurrentBaseProofReason::MissingCoverage
7151                                | CurrentBaseProofReason::Revoked
7152                                | CurrentBaseProofReason::OutcomeUnavailable),
7153                            ),
7154                        ..
7155                    } => Some(
7156                        serde_json::to_value(reason)
7157                            .ok()
7158                            .and_then(|reason| reason.as_str().map(str::to_owned))
7159                            .ok_or("sync.local_corrupt")?,
7160                    ),
7161                    _ => continue,
7162                },
7163            };
7164            // One transaction: the original outcome is superseded first, so
7165            // the refused replacement retains its intent over the restored
7166            // server base.
7167            let rollback = self.capture();
7168            self.begin_observation("syncular_replacement")?;
7169            let mut batch = ChangeAccumulator::default();
7170            let result = self
7171                .release_outcome(
7172                    &current,
7173                    CommitOutcomeResolution::Superseded,
7174                    Some(replacement),
7175                    &mut batch,
7176                )
7177                .and_then(|()| self.rebuild_overlay_if_dirty())
7178                .and_then(|()| match (refused, held) {
7179                    (Some(reason), Some(commit)) => self.reject_outbox_commits(
7180                        vec![(
7181                            commit,
7182                            "the replacement could not be written on a proven base".to_owned(),
7183                            REPLACEMENT_REFUSED_CODE,
7184                            Some(RejectionDetails {
7185                                field_paths: None,
7186                                reason: Some(reason),
7187                                required_action: None,
7188                                references: None,
7189                            }),
7190                        )],
7191                        Some(&mut batch),
7192                    ),
7193                    _ => Ok(()),
7194                })
7195                .and_then(|()| self.finish_observation("syncular_replacement", batch));
7196            if let Err(error) = result {
7197                self.rollback_observation("syncular_replacement");
7198                self.restore(rollback);
7199                return Err(error);
7200            }
7201        }
7202        if written {
7203            self.set_sync_needed(true, true);
7204        }
7205        Ok(written)
7206    }
7207
7208    /// §7.2.1 explicit resolution inside the caller's observation: record the
7209    /// resolution, release the retained aggregate and mark its tables for the
7210    /// overlay rebuild, which restores the server base and replays what
7211    /// remains over it.
7212    fn release_outcome(
7213        &mut self,
7214        current: &CommitOutcome,
7215        resolution: CommitOutcomeResolution,
7216        replacement: Option<&str>,
7217        batch: &mut ChangeAccumulator,
7218    ) -> Result<(), String> {
7219        self.conn
7220            .execute(
7221                "UPDATE _syncular_commit_outcomes
7222                    SET resolution = ?1, resolved_at_ms = ?2,
7223                        replacement_client_commit_id = ?3
7224                  WHERE client_commit_id = ?4 AND resolution = 'active'",
7225                rusqlite::params![
7226                    Self::outcome_resolution_name(resolution),
7227                    self.clock_now_ms(),
7228                    replacement,
7229                    current.client_commit_id
7230                ],
7231            )
7232            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7233        self.conn
7234            .execute(
7235                "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
7236                rusqlite::params![current.client_commit_id],
7237            )
7238            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7239        for (commit, _) in self.failed_commits.iter() {
7240            if commit.client_commit_id == current.client_commit_id {
7241                for operation in &commit.ops {
7242                    self.overlay_dirty.table(&operation.table);
7243                }
7244            }
7245        }
7246        self.failed_commits
7247            .retain(|(commit, _)| commit.client_commit_id != current.client_commit_id);
7248        self.prune_commit_outcomes()?;
7249        self.conflicts
7250            .retain(|record| record.client_commit_id != current.client_commit_id);
7251        self.rejections
7252            .retain(|record| record.client_commit_id != current.client_commit_id);
7253        batch.conflicts |= current.status == CommitOutcomeStatus::Conflict;
7254        batch.rejections |= current.status == CommitOutcomeStatus::Rejected;
7255        batch.outcomes = true;
7256        for operation in current.operations.iter().flatten() {
7257            batch.table(&operation.table);
7258        }
7259        Ok(())
7260    }
7261
7262    pub fn schema_floor(&self) -> Option<&SchemaFloor> {
7263        self.schema_floor.as_ref()
7264    }
7265
7266    /// §7.3.5: the client's opaque auth-lease state, if any.
7267    pub fn lease_state(&self) -> Option<&LeaseState> {
7268        self.lease_state.as_ref()
7269    }
7270
7271    /// §7.3.5: record a request-level lease error (stop-and-surface). Only
7272    /// the two lease codes set it; other errors leave leaseState untouched.
7273    fn record_lease_error(&mut self, code: &str) -> Result<(), String> {
7274        if code != "sync.auth_lease_required" && code != "sync.auth_lease_revoked" {
7275            return Ok(());
7276        }
7277        let mut next = self.lease_state.clone().unwrap_or_default();
7278        next.error_code = Some(code.to_owned());
7279        self.set_lease_state(Some(next))
7280    }
7281
7282    fn set_lease_state(&mut self, next: Option<LeaseState>) -> Result<(), String> {
7283        if self.lease_state == next {
7284            return Ok(());
7285        }
7286        self.begin_observation("syncular_lease")?;
7287        let rollback = self.capture();
7288        self.lease_state = next;
7289        let persisted = match &self.lease_state {
7290            Some(lease) => serde_json::to_string(lease)
7291                .map_err(|error| error.to_string())
7292                .and_then(|json| self.set_meta(LEASE_STATE_KEY, &json)),
7293            None => self.delete_meta(LEASE_STATE_KEY),
7294        };
7295        let batch = ChangeAccumulator {
7296            status: true,
7297            ..ChangeAccumulator::default()
7298        };
7299        if let Err(error) =
7300            persisted.and_then(|()| self.finish_observation("syncular_lease", batch))
7301        {
7302            self.rollback_observation("syncular_lease");
7303            self.restore(rollback);
7304            return Err(error);
7305        }
7306        Ok(())
7307    }
7308
7309    fn set_schema_floor(&mut self, next: Option<SchemaFloor>) -> Result<(), String> {
7310        if self.schema_floor == next {
7311            return Ok(());
7312        }
7313        self.begin_observation("syncular_schema_floor")?;
7314        let rollback = self.capture();
7315        self.stopped = next.is_some();
7316        self.schema_floor = next;
7317        let persisted = match &self.schema_floor {
7318            Some(floor) => serde_json::to_string(floor)
7319                .map_err(|error| error.to_string())
7320                .and_then(|json| self.set_meta(SCHEMA_FLOOR_KEY, &json)),
7321            None => self.delete_meta(SCHEMA_FLOOR_KEY),
7322        };
7323        let batch = ChangeAccumulator {
7324            status: true,
7325            ..ChangeAccumulator::default()
7326        };
7327        if let Err(error) =
7328            persisted.and_then(|()| self.finish_observation("syncular_schema_floor", batch))
7329        {
7330            self.rollback_observation("syncular_schema_floor");
7331            self.restore(rollback);
7332            return Err(error);
7333        }
7334        Ok(())
7335    }
7336
7337    fn set_upgrading(&mut self, value: bool) {
7338        if self.upgrading == value {
7339            return;
7340        }
7341        if self.begin_observation("syncular_upgrading").is_err() {
7342            return;
7343        }
7344        self.upgrading = value;
7345        let batch = ChangeAccumulator {
7346            status: true,
7347            ..ChangeAccumulator::default()
7348        };
7349        if self
7350            .finish_observation("syncular_upgrading", batch)
7351            .is_err()
7352        {
7353            self.rollback_observation("syncular_upgrading");
7354        }
7355    }
7356
7357    pub fn sync_needed(&self) -> bool {
7358        self.sync_needed
7359    }
7360
7361    pub fn read_rows(&self, table: &str) -> Result<Vec<RowState>, String> {
7362        let schema_table = self
7363            .schema
7364            .table(table)
7365            .ok_or_else(|| format!("unknown table {table:?}"))?;
7366        let sql = format!(
7367            "SELECT * FROM {} ORDER BY {} ASC",
7368            visible_table(table),
7369            quote_ident(&schema_table.primary_key)
7370        );
7371        let mut stmt = self
7372            .conn
7373            .prepare(&sql)
7374            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7375        let mut rows = stmt
7376            .query([])
7377            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7378        let mut out = Vec::new();
7379        while let Some(row) = rows
7380            .next()
7381            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
7382        {
7383            let mut values = Map::new();
7384            for (i, column) in schema_table.columns.iter().enumerate() {
7385                let value = row
7386                    .get_ref(i)
7387                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7388                values.insert(column.name.clone(), sql_ref_to_json(column, value));
7389            }
7390            let version: i64 = row
7391                .get(schema_table.columns.len())
7392                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7393            let row_id = match values.get(&schema_table.primary_key) {
7394                Some(Value::String(s)) => s.clone(),
7395                Some(Value::Number(n)) => n.to_string(),
7396                Some(Value::Bool(b)) => b.to_string(),
7397                other => format!("{}", other.cloned().unwrap_or(Value::Null)),
7398            };
7399            let sealed_key = if schema_table.has_encrypted_columns() {
7400                row.get(schema_table.columns.len() + 1)
7401                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
7402            } else {
7403                None
7404            };
7405            out.push(RowState {
7406                row_id,
7407                version,
7408                values,
7409                sealed_key,
7410            });
7411        }
7412        Ok(out)
7413    }
7414
7415    // -- §5.10.5 native CRDT (the `crdt-yjs` feature) --------------------------
7416    //
7417    // The Rust face of the §5.10.4 client model: a local crdt edit loads the
7418    // current stored (server-merged ⊕ pending-overlay) column bytes, applies
7419    // the op with `yrs`, re-encodes the whole doc state, and records a
7420    // baseVersion-less sparse upsert carrying only the primary key and the
7421    // crdt column (§5.10.3, §6.6). No local merge — merging is server-side;
7422    // the overlay re-materializes the edit immediately (optimistic apply,
7423    // §7.1) and the server-merged bytes arrive on the next pull, idempotently.
7424    // Byte-compatible with `@syncular/crdt-yjs`.
7425
7426    /// The current stored value of a `crdt` column for one row — the visible
7427    /// (optimistic) bytes, or `None` when the row is absent or the column is
7428    /// NULL (the empty document, §5.10.1). Errors if the column is not a
7429    /// `crdt` column (guards the app against a typo'd column name).
7430    #[cfg(feature = "crdt-yjs")]
7431    fn crdt_column_bytes(
7432        &self,
7433        table: &str,
7434        row_id: &str,
7435        column: &str,
7436    ) -> Result<Option<Vec<u8>>, String> {
7437        let schema_table = self
7438            .schema
7439            .table(table)
7440            .ok_or_else(|| format!("unknown table {table:?}"))?;
7441        let col = schema_table
7442            .columns
7443            .iter()
7444            .find(|c| c.name == column)
7445            .ok_or_else(|| format!("table {table:?} has no column {column:?}"))?;
7446        if col.ty != ColumnType::Crdt {
7447            return Err(format!("column {column:?} is not a crdt column (§5.10.1)"));
7448        }
7449        let sql = format!(
7450            "SELECT {} FROM {} WHERE {}",
7451            quote_ident(column),
7452            visible_table(table),
7453            row_id_predicate(schema_table)
7454        );
7455        let bytes: Option<Vec<u8>> = self
7456            .conn
7457            .prepare_cached(&sql)
7458            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
7459            .query_row(rusqlite::params![row_id], |row| {
7460                row.get::<_, Option<Vec<u8>>>(0)
7461            })
7462            .map_err(|e| match e {
7463                rusqlite::Error::QueryReturnedNoRows => "no such row".to_owned(),
7464                other => Self::sqlite_failure(&self.storage_failure, other),
7465            })?;
7466        Ok(bytes)
7467    }
7468
7469    /// §5.10.4 materialize: the collaborative text of a `crdt` column, decoded
7470    /// from the stored bytes with `yrs` — `YjsColumn.text(name).toString()`.
7471    /// An absent row / NULL column is the empty document (empty string).
7472    #[cfg(feature = "crdt-yjs")]
7473    pub fn crdt_text(
7474        &self,
7475        table: &str,
7476        row_id: &str,
7477        column: &str,
7478        name: &str,
7479    ) -> Result<String, String> {
7480        let bytes = self
7481            .crdt_column_bytes(table, row_id, column)?
7482            .unwrap_or_default();
7483        crate::crdt::text(&bytes, name)
7484    }
7485
7486    /// §5.10.4 push-an-update: apply a text insert to a `crdt` column and
7487    /// record the resulting crdt-only sparse operation. Returns the enqueued
7488    /// `clientCommitId`.
7489    #[cfg(feature = "crdt-yjs")]
7490    pub fn crdt_insert_text(
7491        &mut self,
7492        table: &str,
7493        row_id: &str,
7494        column: &str,
7495        name: &str,
7496        index: u32,
7497        value: &str,
7498    ) -> Result<String, ClientError> {
7499        let prior = self.storage_failure.borrow_mut().take();
7500        let outcome = (|| -> Result<String, ClientError> {
7501            let current = self
7502                .crdt_column_bytes(table, row_id, column)?
7503                .unwrap_or_default();
7504            let update = crate::crdt::insert_text(&current, name, index, value)?;
7505            self.perform_crdt_push_update(table, row_id, column, &update)
7506        })();
7507        self.finish_authoring(prior, outcome)
7508    }
7509
7510    /// §5.10.4 push-an-update: apply a text delete to a `crdt` column and
7511    /// record the resulting crdt-only sparse operation. Returns the enqueued
7512    /// `clientCommitId`.
7513    #[cfg(feature = "crdt-yjs")]
7514    pub fn crdt_delete_text(
7515        &mut self,
7516        table: &str,
7517        row_id: &str,
7518        column: &str,
7519        name: &str,
7520        index: u32,
7521        len: u32,
7522    ) -> Result<String, ClientError> {
7523        let prior = self.storage_failure.borrow_mut().take();
7524        let outcome = (|| -> Result<String, ClientError> {
7525            let current = self
7526                .crdt_column_bytes(table, row_id, column)?
7527                .unwrap_or_default();
7528            let update = crate::crdt::delete_text(&current, name, index, len)?;
7529            self.perform_crdt_push_update(table, row_id, column, &update)
7530        })();
7531        self.finish_authoring(prior, outcome)
7532    }
7533
7534    /// §5.10.4 generic escape hatch: apply an arbitrary Yjs update onto a
7535    /// `crdt` column's current state and record the resulting crdt-only sparse
7536    /// operation. The app authored the update with its own `yrs` model.
7537    /// Returns the enqueued `clientCommitId`.
7538    #[cfg(feature = "crdt-yjs")]
7539    pub fn crdt_apply_update(
7540        &mut self,
7541        table: &str,
7542        row_id: &str,
7543        column: &str,
7544        update: &[u8],
7545    ) -> Result<String, ClientError> {
7546        let prior = self.storage_failure.borrow_mut().take();
7547        let outcome = (|| -> Result<String, ClientError> {
7548            let current = self
7549                .crdt_column_bytes(table, row_id, column)?
7550                .unwrap_or_default();
7551            let next = crate::crdt::apply_update(&current, update)?;
7552            self.perform_crdt_push_update(table, row_id, column, &next)
7553        })();
7554        self.finish_authoring(prior, outcome)
7555    }
7556
7557    /// Shared tail of the crdt edit methods: record a §6.1 sparse crdt-only
7558    /// upsert — the primary key plus the crdt column, no `baseVersion` — and
7559    /// enqueue it. The server merges the crdt column and leaves every other
7560    /// column untouched (§5.10.3), so a baseVersion-less crdt edit cannot
7561    /// clobber a concurrent edit to another column. A locally absent row
7562    /// records the same partial operation; the server answers per §6.2.
7563    #[cfg(feature = "crdt-yjs")]
7564    fn perform_crdt_push_update(
7565        &mut self,
7566        table: &str,
7567        row_id: &str,
7568        column: &str,
7569        crdt_bytes: &[u8],
7570    ) -> Result<String, ClientError> {
7571        let mut bytes_obj = Map::new();
7572        bytes_obj.insert("$bytes".to_owned(), Value::from(bytes_to_hex(crdt_bytes)));
7573        let mut partial = Map::new();
7574        partial.insert(column.to_owned(), Value::Object(bytes_obj));
7575        self.perform_patch(table, row_id, partial, None)
7576    }
7577
7578    /// Run an arbitrary read-only SQL query against the local database and
7579    /// return each row as a `column-name → JSON value` map. This is the seam
7580    /// the React `useSyncQuery` live-query API needs (it takes app-authored
7581    /// SQL over the visible tables/views, not a fixed table read like
7582    /// [`read_rows`]).
7583    ///
7584    /// Bound `params` are the driver value forms: JSON strings/numbers/bools/
7585    /// null bind directly; a `{"$bytes": hex}` object binds as a BLOB — the
7586    /// same envelope the command surface uses everywhere else. Output BLOB
7587    /// columns come back as `{"$bytes": hex}` to round-trip cleanly.
7588    ///
7589    /// The result column typing is dynamic (SQLite's stored affinity), because
7590    /// arbitrary SQL can alias, join, and compute — there is no schema column
7591    /// to consult per output cell, unlike [`read_rows`].
7592    pub fn query(&self, sql: &str, params: &[QueryValue]) -> Result<Vec<QueryRow>, String> {
7593        query_connection(&self.conn, sql, params).map_err(|failure| failure.to_string())
7594    }
7595
7596    /// Repository benchmark and conformance access, present only with `bench-internals`.
7597    #[cfg(feature = "bench-internals")]
7598    #[doc(hidden)]
7599    pub fn benchmark_connection(&mut self) -> &mut Connection {
7600        &mut self.conn
7601    }
7602
7603    /// Private benchmark intervals; absent from ordinary builds and diagnostics.
7604    #[cfg(feature = "bench-internals")]
7605    #[doc(hidden)]
7606    pub fn benchmark_phases(
7607        &self,
7608        enabled: Option<bool>,
7609        reset: bool,
7610    ) -> Result<Option<Value>, String> {
7611        self.benchmark_phases.configure(enabled, reset)?;
7612        Ok(self.benchmark_phases.snapshot())
7613    }
7614
7615    /// One serialized, read-only authority observation, including durable coverage.
7616    pub fn authority_snapshot(&self) -> Result<Value, String> {
7617        validate_authority_reads(&self.schema, &self.limits.authority_reads)?;
7618        if self.limits.authority_reads.is_empty() {
7619            return Err("client.authority_read_forbidden: no authority reads were declared at client creation".into());
7620        }
7621        self.conn
7622            .execute_batch("SAVEPOINT authority_snapshot")
7623            .map_err(|e| e.to_string())?;
7624        let result = (|| {
7625            let revision = self
7626                .get_meta(LOCAL_REVISION_KEY)?
7627                .ok_or("sync.local_corrupt: authority revision is missing")?;
7628            let parsed_revision = revision
7629                .parse::<u64>()
7630                .map_err(|_| "sync.local_corrupt: authority revision is invalid")?;
7631            if parsed_revision.to_string() != revision {
7632                return Err("sync.local_corrupt: authority revision is invalid".into());
7633            }
7634            let mut tables = Vec::new();
7635            for read in &self.limits.authority_reads {
7636                let table = self
7637                    .schema
7638                    .table(&read.table)
7639                    .ok_or("client.authority_read_forbidden: authority table is not declared")?;
7640                let scalar = |column: &str, value: &Value| -> Result<String, String> {
7641                    let ty = table
7642                        .columns
7643                        .iter()
7644                        .find(|c| c.name == column)
7645                        .expect("validated authority column")
7646                        .ty;
7647                    if ty == ColumnType::Boolean {
7648                        if let Some(value) = value.as_bool() {
7649                            return Ok(value.to_string());
7650                        }
7651                        return match value.as_i64() {
7652                            Some(0) => Ok("false".into()),
7653                            Some(1) => Ok("true".into()),
7654                            _ => Err("sync.local_corrupt: authority boolean is invalid".into()),
7655                        };
7656                    }
7657                    match value {
7658                        Value::String(s) => Ok(s.clone()),
7659                        Value::Number(n) => Ok(n.to_string()),
7660                        Value::Object(o) if ty == ColumnType::Integer && o.len() == 1 => o
7661                            .get("$bigint")
7662                            .and_then(Value::as_str)
7663                            .map(str::to_owned)
7664                            .ok_or("sync.local_corrupt: authority integer is invalid".into()),
7665                        _ => {
7666                            Err("sync.local_corrupt: authority scalar is missing or invalid".into())
7667                        }
7668                    }
7669                };
7670                let matches = |row: &QueryRow| -> Result<bool, String> {
7671                    for (variable, values) in &read.scopes {
7672                        let column = table
7673                            .scope_column(variable)
7674                            .expect("validated authority scope");
7675                        let value = row
7676                            .get(column)
7677                            .ok_or("sync.local_corrupt: authority scope column is missing")?;
7678                        if value.is_null() || !values.contains(&scalar(column, value)?) {
7679                            return Ok(false);
7680                        }
7681                    }
7682                    Ok(true)
7683                };
7684                let selected = read
7685                    .columns
7686                    .iter()
7687                    .map(|c| quote_ident(c))
7688                    .collect::<Vec<_>>()
7689                    .join(",");
7690                let mut intent = BTreeSet::new();
7691                let mut relevant = BTreeSet::new();
7692                for row in query_connection(&self.conn,
7693                    "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=?",
7694                    &[Value::String(read.table.clone())]).map_err(|e| e.to_string())? {
7695                    let id = row.get("id").and_then(Value::as_str).ok_or("sync.local_corrupt: authority intent id is invalid")?.to_owned();
7696                    intent.insert(id.clone());
7697                    if let Some(raw) = row.get("values_json").and_then(Value::as_str) {
7698                        let values: QueryRow = serde_json::from_str(raw).map_err(|_| "sync.local_corrupt: authority intent values are invalid")?;
7699                        if read.scopes.keys().all(|v| values.contains_key(table.scope_column(v).expect("validated scope"))) && matches(&values)? {relevant.insert(id);}
7700                    }
7701                }
7702                let mut rows = BTreeMap::new();
7703                for full in [base_table(&read.table), visible_table(&read.table)] {
7704                    for mut values in query_connection(
7705                        &self.conn,
7706                        &format!(
7707                            "SELECT {selected},_syncular_version AS authority_version FROM {full}"
7708                        ),
7709                        &[],
7710                    )
7711                    .map_err(|e| e.to_string())?
7712                    {
7713                        if !matches(&values)? {
7714                            continue;
7715                        }
7716                        let id = scalar(
7717                            &table.primary_key,
7718                            values
7719                                .get(&table.primary_key)
7720                                .expect("selected primary key"),
7721                        )?;
7722                        relevant.insert(id.clone());
7723                        if full == base_table(&read.table) {
7724                            let version = values
7725                                .remove("authority_version")
7726                                .expect("selected version");
7727                            let version = version
7728                                .as_i64()
7729                                .ok_or("sync.local_corrupt: authority server version is invalid")?;
7730                            if version >= 0 {
7731                                rows.insert(id.clone(), json!({"values": values, "version": version, "hasLocalIntent": intent.contains(&id)}));
7732                            }
7733                        }
7734                    }
7735                }
7736                intent.retain(|id| relevant.contains(id));
7737                let rows = rows.into_values().collect::<Vec<_>>();
7738                // Every unit covering the table, as its (unit, table) pair (§4.4).
7739                let replica = self.stored(replica_cursor(&self.conn))?;
7740                let persisted = self
7741                    .stored(load_units(&self.conn))?
7742                    .into_iter()
7743                    .filter(|unit| covers(table, &unit.scopes))
7744                    .map(|unit| {
7745                        let effective = unit.echo.as_deref().and_then(|echo| {
7746                            pair_scopes(&unit.scopes, &read.table, Some(echo))
7747                        });
7748                        let requested = read
7749                            .scopes
7750                            .keys()
7751                            .map(|v| (v.clone(), json!(unit.scopes.get(v).into_iter().collect::<Vec<_>>())))
7752                            .collect::<Map<_, _>>();
7753                        let complete = effective
7754                            .as_ref()
7755                            .is_some_and(|scopes| scopes.len() == read.scopes.len())
7756                            && unit.status == UnitStatus::Active
7757                            && !unit.bootstrapping();
7758                        let exposed = effective.map(|scopes| {
7759                            read.scopes
7760                                .keys()
7761                                .map(|v| {
7762                                    let held = scopes.iter().find(|(variable, _)| variable == v);
7763                                    (v.clone(), json!(held.map_or(&Vec::new(), |(_, values)| values)))
7764                                })
7765                                .collect::<Map<_, _>>()
7766                        });
7767                        json!({"requestedScopes": requested, "status": unit.status, "cursor": unit.cursor.unwrap_or(replica), "effectiveScopes": exposed, "complete": complete})
7768                    })
7769                    .collect::<Vec<_>>();
7770                fn covered(selectors: &[(&String, &Vec<String>)], candidates: &[&Value]) -> bool {
7771                    match selectors.split_first() {
7772                        None => !candidates.is_empty(),
7773                        Some(((variable, values), rest)) => values.iter().all(|value| {
7774                            covered(
7775                                rest,
7776                                &candidates
7777                                    .iter()
7778                                    .copied()
7779                                    .filter(|p| {
7780                                        p["effectiveScopes"][variable.as_str()]
7781                                            .as_array()
7782                                            .is_some_and(|held| {
7783                                                held.contains(&Value::String(value.clone()))
7784                                                    || held.contains(&Value::String("*".into()))
7785                                            })
7786                                    })
7787                                    .collect::<Vec<_>>(),
7788                            )
7789                        }),
7790                    }
7791                }
7792                let coverage = if covered(
7793                    &read.scopes.iter().collect::<Vec<_>>(),
7794                    &persisted
7795                        .iter()
7796                        .filter(|p| p["complete"] == true)
7797                        .collect::<Vec<_>>(),
7798                ) {
7799                    "complete"
7800                } else if persisted.iter().any(|p| {
7801                    p["status"] == "active"
7802                        && read.scopes.iter().all(|(v, values)| {
7803                            values.iter().any(|value| {
7804                                p["requestedScopes"][v].as_array().is_some_and(|held| {
7805                                    held.contains(&Value::String(value.clone()))
7806                                })
7807                            })
7808                        })
7809                }) {
7810                    "pending"
7811                } else {
7812                    "missing"
7813                };
7814                tables.push(json!({"table": read.table, "rows": rows, "localIntentRowIds": intent, "scopes": read.scopes, "coverage": coverage, "persisted": persisted}));
7815            }
7816            Ok(
7817                json!({"revision": revision, "complete": tables.iter().all(|t| t["coverage"] == "complete"), "tables": tables}),
7818            )
7819        })();
7820        match result {
7821            Ok(snapshot) => {
7822                self.conn
7823                    .execute_batch("RELEASE authority_snapshot")
7824                    .map_err(|e| e.to_string())?;
7825                Ok(snapshot)
7826            }
7827            Err(error) => {
7828                self.conn
7829                    .execute_batch("ROLLBACK TO authority_snapshot; RELEASE authority_snapshot")
7830                    .map_err(|e| format!("{error}; rollback failed: {e}"))?;
7831                Err(error)
7832            }
7833        }
7834    }
7835
7836    /// Rows, coverage, and local revision from one SQLite read snapshot.
7837    /// §7.5 atomic snapshot read. An `owner` records a failure in
7838    /// `diagnostics_snapshot().query_failures` until its next successful read.
7839    pub fn query_snapshot(
7840        &mut self,
7841        sql: &str,
7842        params: &[QueryValue],
7843        coverage: &[WindowCoverage],
7844        owner: Option<QueryOwner<'_>>,
7845    ) -> Result<QuerySnapshot, String> {
7846        let result = snapshot_connection(&self.conn, sql, params, coverage);
7847        if let Some(owner) = owner {
7848            self.record_query_read(owner, result.as_ref().err());
7849        }
7850        result.map_err(|failure| failure.to_string())
7851    }
7852
7853    /// §7.6: record the outcome of one owned snapshot read, including reads a
7854    /// host ran on a separate connection. A success removes the owner's entry;
7855    /// an identical failure leaves it unchanged; a changed failure moves last.
7856    pub fn record_query_read(&mut self, owner: QueryOwner<'_>, failure: Option<&QueryReadFailure>) {
7857        let position = self
7858            .query_failures
7859            .iter()
7860            .position(|entry| entry.id == owner.id);
7861        let Some(failure) = failure else {
7862            if let Some(index) = position {
7863                self.query_failures.remove(index);
7864            }
7865            return;
7866        };
7867        let tables: Vec<String> = BTreeSet::from_iter(owner.tables.iter().copied())
7868            .into_iter()
7869            .map(str::to_owned)
7870            .collect();
7871        let code = failure.code.unwrap_or("client.query_failed").to_owned();
7872        if position.is_some_and(|index| {
7873            let entry = &self.query_failures[index];
7874            entry.tables == tables && entry.code == code && entry.sqlite_code == failure.sqlite_code
7875        }) {
7876            return;
7877        }
7878        if let Some(index) = position {
7879            self.query_failures.remove(index);
7880        }
7881        self.query_failures.push(DiagnosticQueryFailure {
7882            id: owner.id.to_owned(),
7883            tables,
7884            code,
7885            sqlite_code: failure.sqlite_code,
7886            at_ms: self.clock_now_ms(),
7887        });
7888        if self.query_failures.len() > MAX_DIAGNOSTIC_QUERY_FAILURES {
7889            self.query_failures.remove(0);
7890        }
7891    }
7892
7893    // -- request building ---------------------------------------------------------
7894
7895    fn build_request(&self, url_capable: bool) -> Result<(Message, RequestMeta), Box<SyncOutcome>> {
7896        #[cfg(feature = "bench-internals")]
7897        let _phase = self.benchmark_phases.start(Phase::RequestPrepare);
7898        let log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7899            Box::new(SyncOutcome::Failed {
7900                error_code: "storage.failed".into(),
7901                message,
7902                details: None,
7903                recommended_action: None,
7904            })
7905        })?;
7906        let max_commits = self.limits.max_push_commits_per_request;
7907        let max_ops = self
7908            .limits
7909            .max_push_operations_per_request
7910            .unwrap_or(PUSH_OPS_PER_REQUEST);
7911        let byte_cap = self.limits.max_push_request_bytes;
7912        // §4.2/§5.4: bit 3 is advertised iff the transport can fetch a
7913        // bare URL — capability negotiation, decided per transport.
7914        let accept = self.limits.accept.unwrap_or(if url_capable {
7915            DEFAULT_ACCEPT | ACCEPT_SIGNED_URLS
7916        } else {
7917            DEFAULT_ACCEPT
7918        });
7919        let storage_failed = |message: String| {
7920            Box::new(SyncOutcome::Failed {
7921                error_code: "storage.failed".into(),
7922                message,
7923                details: None,
7924                recommended_action: None,
7925            })
7926        };
7927        let header = Frame::ReqHeader {
7928            client_id: self.client_id.clone(),
7929            schema_version: self.schema.version,
7930            log_epoch: log_epoch.clone(),
7931            outbox_id: self.get_meta(OUTBOX_ID_KEY).map_err(storage_failed)?,
7932        };
7933        // §1.5: the lead frames are REQ_HEADER plus the optional ROUND_FAILURE,
7934        // which stays ahead of every push, pull, unit and progress frame; the
7935        // byte-capacity probes below measure this exact sequence.
7936        let mut lead = vec![header];
7937        lead.extend(
7938            self.round_failure
7939                .iter()
7940                .map(|code| Frame::RoundFailure { code: code.clone() }),
7941        );
7942        // §2.1: a replica without an epoch holds nothing bound to one.
7943        if log_epoch.is_none() {
7944            lead.push(Frame::AdoptEpoch);
7945        }
7946        let registered: Vec<UnitRecord> = self
7947            .stored(load_units(&self.conn))
7948            .map_err(storage_failed)?
7949            .into_iter()
7950            .filter(|unit| unit.status == UnitStatus::Active)
7951            .collect();
7952        let registration_digest = ssp2::registration::registration_digest(
7953            registered
7954                .iter()
7955                .map(|unit| scope_pairs(&unit.scopes))
7956                .collect::<Vec<_>>()
7957                .iter()
7958                .map(Vec::as_slice),
7959        );
7960        let echo_digest = self
7961            .get_meta(ECHO_DIGEST_KEY)
7962            .map_err(storage_failed)?
7963            .filter(|hex| !hex.is_empty())
7964            .map(|hex| {
7965                crate::values::hex_to_bytes(&hex)
7966                    .ok()
7967                    .and_then(|bytes| <[u8; 32]>::try_from(bytes).ok())
7968                    .ok_or_else(|| {
7969                        "sync.local_corrupt: persisted echo digest is invalid".to_owned()
7970                    })
7971            })
7972            .transpose()
7973            .map_err(storage_failed)?;
7974        let pull = Frame::PullHeader {
7975            limit_commits: self.limits.limit_commits.unwrap_or(0),
7976            limit_snapshot_rows: self.limits.limit_snapshot_rows.unwrap_or(0),
7977            max_snapshot_pages: self.limits.max_snapshot_pages.unwrap_or(0),
7978            accept,
7979            cursor: self
7980                .stored(replica_cursor(&self.conn))
7981                .map_err(storage_failed)?,
7982            registration_digest,
7983            echo_digest,
7984        };
7985        let registration_digest = bytes_to_hex(&registration_digest);
7986        // §4.1: the list travels when it changed since the server stored it,
7987        // after `unregistered` and after a reset (both clear the stored digest).
7988        let travels = self
7989            .get_meta(REGISTERED_DIGEST_KEY)
7990            .map_err(storage_failed)?
7991            .as_deref()
7992            != Some(registration_digest.as_str());
7993        let mut sub_frames: Vec<Frame> = Vec::new();
7994        if travels {
7995            sub_frames.extend(registered.iter().map(|unit| Frame::Unit {
7996                scopes: scope_pairs(&unit.scopes),
7997            }));
7998        }
7999        // §4.3: one PROGRESS per catching-up unit, in registration order, each
8000        // followed by its RESTRICT while the unit holds a restriction.
8001        for unit in &registered {
8002            let Some(cursor) = unit.cursor else {
8003                continue;
8004            };
8005            sub_frames.push(Frame::Progress {
8006                id: unit.id.clone(),
8007                cursor,
8008                bootstrap_state: unit.bootstrap_state.clone().map(RawJson),
8009            });
8010            sub_frames.extend(
8011                unit.restriction
8012                    .as_ref()
8013                    .map(|restriction| Frame::Restrict {
8014                        cursor: restriction.cursor,
8015                        tables: restriction.tables.clone(),
8016                    }),
8017            );
8018        }
8019        // The fixed frames (order-independent size) and the header+pull probe
8020        // both encode canonically, so the byte budget is the exact wire size.
8021        let fixed_bytes = match byte_cap {
8022            Some(_) => {
8023                let mut frames = lead.clone();
8024                frames.push(pull.clone());
8025                frames.extend(sub_frames.iter().cloned());
8026                encode_message(&Message {
8027                    wire_version: WIRE_VERSION,
8028                    msg_kind: MsgKind::Request,
8029                    frames,
8030                })
8031                .len()
8032            }
8033            None => 0,
8034        };
8035        if let Some(cap) = byte_cap {
8036            if fixed_bytes > cap {
8037                return Err(Self::push_capacity_outcome("bytes", cap, fixed_bytes, None));
8038            }
8039        }
8040        let base_bytes = match byte_cap {
8041            Some(_) => {
8042                let mut frames = lead.clone();
8043                frames.push(pull.clone());
8044                encode_message(&Message {
8045                    wire_version: WIRE_VERSION,
8046                    msg_kind: MsgKind::Request,
8047                    frames,
8048                })
8049                .len()
8050            }
8051            None => 0,
8052        };
8053        let total_outbox = if log_epoch.is_some() {
8054            self.outbox.len()
8055        } else {
8056            0
8057        };
8058        let mut push_frames: Vec<Frame> = Vec::new();
8059        let mut pushed_ids = Vec::new();
8060        let mut ops_in_request = 0usize;
8061        let mut bytes_in_request = 0usize;
8062        // §2.1: an epoch-less request withholds the whole outbox until the
8063        // next, epoch-bound request.
8064        let mut deferred_commits = self.outbox.len() - total_outbox;
8065        // §7.2.2: a pending replacement is held; the push stops before it
8066        // without deferring work.
8067        let held: HashSet<String> = self
8068            .prepare_replacements()
8069            .map_err(storage_failed)?
8070            .into_iter()
8071            .filter_map(|decision| decision.replacement)
8072            .collect();
8073        #[cfg(feature = "bench-internals")]
8074        let outbox_phase = self.benchmark_phases.start(Phase::OutboxEncode);
8075        for (index, commit) in self.outbox.iter().take(total_outbox).enumerate() {
8076            if held.contains(&commit.client_commit_id) {
8077                break;
8078            }
8079            // §6.1/§7.1: the commit-count and operation caps are hard. A
8080            // first commit over the operation cap is a typed capacity error
8081            // and stays queued; a later one defers with the complete suffix.
8082            if max_commits.is_some_and(|cap| push_frames.len() >= cap) {
8083                deferred_commits = total_outbox - index;
8084                break;
8085            }
8086            if ops_in_request + commit.ops.len() > max_ops {
8087                if push_frames.is_empty() {
8088                    return Err(Self::push_capacity_outcome(
8089                        "operations",
8090                        max_ops,
8091                        commit.ops.len(),
8092                        Some(commit.client_commit_id.as_str()),
8093                    ));
8094                }
8095                deferred_commits = total_outbox - index;
8096                break;
8097            }
8098            // §7.1 chained base: the commit waits for the change of the commit
8099            // it chains on, which supplies its rebased version.
8100            if self.outbox[..index]
8101                .iter()
8102                .flat_map(|earlier| &earlier.ops)
8103                .any(|earlier| commit.ops.iter().any(|op| chains_on(earlier, op)))
8104            {
8105                deferred_commits = total_outbox - index;
8106                break;
8107            }
8108            let operations = commit
8109                .ops
8110                .iter()
8111                .map(|op| {
8112                    let payload = match self
8113                        .schema
8114                        .table(&op.table)
8115                        .and_then(|table| Some((table, op.presented_values(table)?)))
8116                    {
8117                        Some((table, values)) => {
8118                            // §0: outbox entries encode at send time with the
8119                            // current codec (validated at mutate()). §6.1: the
8120                            // values map's keys are the sparse presence set; an
8121                            // insert-intent operation presents every column (§7.1).
8122                            // §5.11: encrypted columns are encrypted here, with
8123                            // an absent key-id selector read from the stored row.
8124                            // `sync_inner` runs `drop_unencodable_outbox` first,
8125                            // so an encrypt failure cannot reach this encode; the
8126                            // author seam validated every other failure.
8127                            let fallback =
8128                                self.stored_key_fallback(table, &op.row_id)
8129                                    .map_err(|message| {
8130                                        Box::new(SyncOutcome::Failed {
8131                                            error_code: "storage.failed".into(),
8132                                            message,
8133                                            details: None,
8134                                            recommended_action: None,
8135                                        })
8136                                    })?;
8137                            encode_sparse_row_json(
8138                                table,
8139                                &op.row_id,
8140                                &values,
8141                                &self.encryption,
8142                                fallback.as_ref(),
8143                            )
8144                            .ok()
8145                        }
8146                        None => None,
8147                    };
8148                    Ok(ssp2::model::Operation {
8149                        table: op.table.clone(),
8150                        row_id: op.row_id.clone(),
8151                        op: if op.upsert { Op::Upsert } else { Op::Delete },
8152                        base_version: op.base_version,
8153                        payload,
8154                    })
8155                })
8156                .collect::<Result<Vec<_>, Box<SyncOutcome>>>()?;
8157            // §6.3.2, §7.1: the commit's outbox sequence.
8158            let client_seq = self
8159                .conn
8160                .prepare_cached("SELECT seq FROM _syncular_outbox WHERE commit_id = ?1")
8161                .and_then(|mut statement| {
8162                    statement.query_row([&commit.client_commit_id], |row| row.get(0))
8163                })
8164                .map_err(|error| {
8165                    storage_failed(Self::sqlite_failure(&self.storage_failure, error))
8166                })?;
8167            let frame = Frame::PushCommit {
8168                client_commit_id: commit.client_commit_id.clone(),
8169                client_seq,
8170                operations,
8171            };
8172            let frame_bytes = match byte_cap {
8173                Some(_) => {
8174                    let mut frames = lead.clone();
8175                    frames.push(frame.clone());
8176                    frames.push(pull.clone());
8177                    encode_message(&Message {
8178                        wire_version: WIRE_VERSION,
8179                        msg_kind: MsgKind::Request,
8180                        frames,
8181                    })
8182                    .len()
8183                        - base_bytes
8184                }
8185                None => 0,
8186            };
8187            // The head is always encoded so the caller can report the full
8188            // projected request size; a later commit defers once it no longer
8189            // fits.
8190            if let Some(cap) = byte_cap {
8191                if !push_frames.is_empty() && fixed_bytes + bytes_in_request + frame_bytes > cap {
8192                    deferred_commits = total_outbox - index;
8193                    break;
8194                }
8195            }
8196            push_frames.push(frame);
8197            pushed_ids.push(commit.client_commit_id.clone());
8198            ops_in_request += commit.ops.len();
8199            bytes_in_request += frame_bytes;
8200        }
8201        #[cfg(feature = "bench-internals")]
8202        drop(outbox_phase);
8203        if let Some(cap) = byte_cap {
8204            if fixed_bytes + bytes_in_request > cap {
8205                // The head alone does not fit this budget; the commit stays
8206                // queued and no transport round is attempted.
8207                let blocked = if push_frames.is_empty() {
8208                    None
8209                } else {
8210                    self.outbox.first().map(|c| c.client_commit_id.as_str())
8211                };
8212                return Err(Self::push_capacity_outcome(
8213                    "bytes",
8214                    cap,
8215                    fixed_bytes + bytes_in_request,
8216                    blocked,
8217                ));
8218            }
8219        }
8220        let mut frames = lead;
8221        frames.extend(push_frames);
8222        frames.push(pull);
8223        frames.extend(sub_frames);
8224        let message = Message {
8225            wire_version: WIRE_VERSION,
8226            msg_kind: MsgKind::Request,
8227            frames,
8228        };
8229        Ok((
8230            message,
8231            RequestMeta {
8232                pushed_ids,
8233                registration_digest,
8234                accept,
8235                deferred_commits,
8236                applied: BTreeMap::new(),
8237                deferred: BTreeSet::new(),
8238            },
8239        ))
8240    }
8241
8242    /// §7.1: a configured push capacity limit cannot carry this request.
8243    fn push_capacity_outcome(
8244        kind: &str,
8245        limit: usize,
8246        size: usize,
8247        client_commit_id: Option<&str>,
8248    ) -> Box<SyncOutcome> {
8249        let mut details = Map::new();
8250        details.insert("kind".to_owned(), Value::from(kind));
8251        details.insert("limit".to_owned(), Value::from(limit as u64));
8252        details.insert("size".to_owned(), Value::from(size as u64));
8253        if let Some(id) = client_commit_id {
8254            details.insert("clientCommitId".to_owned(), Value::from(id));
8255        }
8256        Box::new(SyncOutcome::Failed {
8257            error_code: "client.push_request_too_large".into(),
8258            message: "the push request exceeds a configured capacity limit".into(),
8259            details: Some(Value::Object(details)),
8260            recommended_action: None,
8261        })
8262    }
8263
8264    // -- sync -------------------------------------------------------------------
8265
8266    /// Cloneable observation handle; no client lock is needed to read it.
8267    pub fn progress(&self) -> ProgressObserver {
8268        self.progress.clone()
8269    }
8270
8271    pub fn sync(&mut self, transport: &mut dyn Transport) -> SyncOutcome {
8272        self.sync_bounded(transport, None)
8273    }
8274
8275    /// One round; `idle_bound` is the idle drive's round bound (§7.8).
8276    fn sync_bounded(
8277        &mut self,
8278        transport: &mut dyn Transport,
8279        idle_bound: Option<(u64, u32)>,
8280    ) -> SyncOutcome {
8281        let mut prepared = match self.prepare_sync_round(transport.supports_url_fetch()) {
8282            Ok(prepared) => prepared,
8283            Err(outcome) => return *outcome,
8284        };
8285        prepared.idle_bound = idle_bound;
8286        // The round's network deadline rides `PreparedSyncRound` and is scoped
8287        // to each exchange, so uploads, continuations, the main request, and
8288        // every segment fetch share one monotonic anchor without leaving
8289        // deadline state on a reused transport.
8290        let mut next = prepared;
8291        loop {
8292            match self.apply_sync_round(next.exchange(transport)) {
8293                crate::AppliedSyncRound::Continue(prepared) => next = prepared,
8294                crate::AppliedSyncRound::Complete {
8295                    outcome, controls, ..
8296                } => {
8297                    if self.transport_enabled {
8298                        for text in controls {
8299                            let _ = transport.realtime_send(&text);
8300                        }
8301                    } else {
8302                        self.disconnect_realtime(transport);
8303                    }
8304                    return outcome;
8305                }
8306            }
8307        }
8308    }
8309
8310    fn finish_sync_round(
8311        &mut self,
8312        started_at_ms: i64,
8313        attempt: u64,
8314        mut outcome: SyncOutcome,
8315    ) -> SyncOutcome {
8316        if let SyncOutcome::Failed {
8317            error_code,
8318            message,
8319            details,
8320            ..
8321        } = &mut outcome
8322        {
8323            if let Some((failure, code)) = self
8324                .storage_failure
8325                .borrow()
8326                .as_ref()
8327                .and_then(|failure| failure.code.map(|code| (failure, code)))
8328            {
8329                *error_code = code.to_owned();
8330                *message = match code {
8331                    "client.storage_busy" => "local SQLite storage is busy",
8332                    "client.storage_full" => "local SQLite storage is full",
8333                    "client.storage_io" => "local SQLite storage I/O failed",
8334                    "client.storage_corrupt" => "local SQLite storage is corrupt",
8335                    _ => unreachable!("unrecognized classified storage failure"),
8336                }
8337                .to_owned();
8338                *details = failure.details();
8339            }
8340        }
8341        let details = match &outcome {
8342            SyncOutcome::Failed { details, .. } => details.as_ref(),
8343            _ => None,
8344        };
8345        let cause_kind = details
8346            .and_then(|details| details.get("causeKind"))
8347            .and_then(Value::as_str)
8348            .and_then(|cause| match cause {
8349                "network" => Some(crate::TransportCauseKind::Network),
8350                "connect" => Some(crate::TransportCauseKind::Connect),
8351                "tls" => Some(crate::TransportCauseKind::Tls),
8352                "io" => Some(crate::TransportCauseKind::Io),
8353                "request" => Some(crate::TransportCauseKind::Request),
8354                "protocol" => Some(crate::TransportCauseKind::Protocol),
8355                "timeout" => Some(crate::TransportCauseKind::Timeout),
8356                "round_deadline" => Some(crate::TransportCauseKind::RoundDeadline),
8357                "aborted" => Some(crate::TransportCauseKind::Aborted),
8358                "body" => Some(crate::TransportCauseKind::Body),
8359                "status" => Some(crate::TransportCauseKind::Status),
8360                "redirect" => Some(crate::TransportCauseKind::Redirect),
8361                "unknown" => Some(crate::TransportCauseKind::Unknown),
8362                _ => None,
8363            });
8364        let http_status = if matches!(
8365            cause_kind,
8366            Some(
8367                crate::TransportCauseKind::Status
8368                    | crate::TransportCauseKind::Body
8369                    | crate::TransportCauseKind::Redirect
8370            )
8371        ) {
8372            details
8373                .and_then(|details| details.get("httpStatus"))
8374                .and_then(Value::as_f64)
8375                .filter(|status| status.fract() == 0.0 && (100.0..=599.0).contains(status))
8376                .map(|status| status as u16)
8377        } else {
8378            None
8379        };
8380        let retry_delay_ms = self.round_retry_delay_ms;
8381        self.progress.update(|p| match &outcome {
8382            SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report)
8383                if report.failed.is_empty() =>
8384            {
8385                p.state = ProgressState::Complete
8386            }
8387            SyncOutcome::Ok(_) | SyncOutcome::BudgetExhausted(_) => {
8388                p.state = ProgressState::Failed;
8389                p.error_code = Some("sync.scope_revoked".into());
8390            }
8391            SyncOutcome::Failed { error_code, .. } => {
8392                p.state = ProgressState::Failed;
8393                p.error_code = Some(Self::diagnostic_code(error_code));
8394                p.cause_kind = cause_kind;
8395                p.http_status = http_status;
8396                p.retry_delay_ms = retry_delay_ms;
8397            }
8398            SyncOutcome::RealtimeUnavailable { .. } => {
8399                p.state = ProgressState::Failed;
8400                p.error_code = Some(REALTIME_UNAVAILABLE_CODE.to_owned());
8401                p.retry_delay_ms = retry_delay_ms;
8402            }
8403        });
8404        let completed_at_ms = self.clock_now_ms();
8405        self.last_round = Some(match &outcome {
8406            SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report) => DiagnosticLastRound {
8407                epoch: self.epoch.clone(),
8408                attempt,
8409                status: "succeeded".to_owned(),
8410                started_at_ms,
8411                completed_at_ms,
8412                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
8413                counters: Some(DiagnosticRoundCounters {
8414                    pushed: report.pushed,
8415                    applied: report.applied.len(),
8416                    rejected: report.rejected.len(),
8417                    retryable: report.retryable.len(),
8418                    conflicts: report.conflicts,
8419                    commits_applied: report.commits_applied,
8420                    segment_rows_applied: report.segment_rows_applied,
8421                    bootstrapping: report.bootstrapping.len(),
8422                    resets: report.resets.len(),
8423                    revoked: report.revoked.len(),
8424                    failed: report.failed.len(),
8425                    deferred_commits: report.deferred_commits,
8426                }),
8427                error_code: None,
8428                cause_kind: None,
8429                http_status: None,
8430            },
8431            SyncOutcome::Failed { error_code, .. } => DiagnosticLastRound {
8432                epoch: self.epoch.clone(),
8433                attempt,
8434                status: "failed".to_owned(),
8435                started_at_ms,
8436                completed_at_ms,
8437                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
8438                counters: None,
8439                error_code: Some(Self::diagnostic_code(error_code)),
8440                cause_kind,
8441                http_status,
8442            },
8443            SyncOutcome::RealtimeUnavailable { .. } => DiagnosticLastRound {
8444                epoch: self.epoch.clone(),
8445                attempt,
8446                status: "failed".to_owned(),
8447                started_at_ms,
8448                completed_at_ms,
8449                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
8450                counters: None,
8451                error_code: Some(REALTIME_UNAVAILABLE_CODE.to_owned()),
8452                cause_kind: None,
8453                http_status: None,
8454            },
8455        });
8456        outcome
8457    }
8458
8459    /// Capture one request on the client owner. Mutations made after this
8460    /// call remain in the outbox for a later round; no network I/O occurs here.
8461    pub fn prepare_sync_round(
8462        &mut self,
8463        url_capable: bool,
8464    ) -> Result<crate::PreparedSyncRound, Box<SyncOutcome>> {
8465        if !self.transport_enabled {
8466            return Err(Box::new(SyncOutcome::Failed {
8467                error_code: "sync.offline".into(),
8468                message: "transport gate is closed".into(),
8469                details: None,
8470                recommended_action: None,
8471            }));
8472        }
8473        if self.active_round.is_some() {
8474            return Err(Box::new(SyncOutcome::Failed {
8475                error_code: "client.round_in_progress".into(),
8476                message: "a sync round is already in flight".into(),
8477                details: None,
8478                recommended_action: None,
8479            }));
8480        }
8481        self.storage_failure.borrow_mut().take();
8482        let attempt = self.progress.start(&self.epoch);
8483        self.round_retry_delay_ms = None;
8484        let started_at_ms = self.clock_now_ms();
8485        let prepared = (|| {
8486            if self.stopped {
8487                return Err(Box::new(SyncOutcome::Ok(SyncReport {
8488                    schema_floor: self.schema_floor.clone(),
8489                    ..SyncReport::default()
8490                })));
8491            }
8492            if self.security_preflight {
8493                return Err(Box::new(SyncOutcome::Failed {
8494                    error_code: SECURITY_PREFLIGHT_REQUIRED_CODE.into(),
8495                    message: "security preflight must complete before syncing".into(),
8496                    details: None,
8497                    recommended_action: None,
8498                }));
8499            }
8500            self.set_sync_needed(false, false);
8501            self.drain_pending_evictions()
8502                .and_then(|_| self.drop_incompatible_outbox())
8503                .and_then(|_| self.drop_unencodable_outbox(true, None))
8504                .map_err(|message| {
8505                    Box::new(SyncOutcome::Failed {
8506                        error_code: "storage.failed".into(),
8507                        message,
8508                        details: None,
8509                        recommended_action: None,
8510                    })
8511                })?;
8512            // §5.11: reveal rows sealed under a key the keyring gained since.
8513            self.reveal_sealed_rows().map_err(|error| {
8514                Box::new(SyncOutcome::Failed {
8515                    error_code: error.code,
8516                    message: error.message,
8517                    details: error.details,
8518                    recommended_action: None,
8519                })
8520            })?;
8521            let has_log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
8522                Box::new(SyncOutcome::Failed {
8523                    error_code: "storage.failed".into(),
8524                    message,
8525                    details: None,
8526                    recommended_action: None,
8527                })
8528            })?;
8529            let uploads = if has_log_epoch.is_some() && self.schema_has_blobs() {
8530                self.pending_blob_uploads().map_err(|e| {
8531                    Box::new(SyncOutcome::Failed {
8532                        error_code: e.code,
8533                        message: e.message,
8534                        details: e.details,
8535                        recommended_action: None,
8536                    })
8537                })?
8538            } else {
8539                Vec::new()
8540            };
8541            if self.realtime_state != RealtimeState::Connected
8542                && self.realtime_policy == RealtimePolicy::Required
8543            {
8544                let retry_delay_ms = self.schedule_background_retry();
8545                self.realtime_retry_delay_ms = Some(retry_delay_ms);
8546                return Err(Box::new(SyncOutcome::RealtimeUnavailable {
8547                    state: self.realtime_state,
8548                    reason_code: self.realtime_reason_code.clone(),
8549                    retry_delay_ms,
8550                }));
8551            }
8552            let (message, mut meta) = self.build_request(url_capable)?;
8553            let units = self.stored(load_units(&self.conn)).map_err(|message| {
8554                Box::new(SyncOutcome::Failed {
8555                    error_code: "storage.failed".into(),
8556                    message,
8557                    details: None,
8558                    recommended_action: None,
8559                })
8560            })?;
8561            for unit in &units {
8562                let applied =
8563                    self.stored(applied_rows(&self.conn, &unit.id))
8564                        .map_err(|message| {
8565                            Box::new(SyncOutcome::Failed {
8566                                error_code: "storage.failed".into(),
8567                                message,
8568                                details: None,
8569                                recommended_action: None,
8570                            })
8571                        })?;
8572                if !applied.is_empty() {
8573                    meta.applied.insert(unit.id.clone(), applied);
8574                }
8575            }
8576            let id = uuid::Uuid::new_v4();
8577            self.active_round = Some((id, started_at_ms, attempt));
8578            let phase = if uploads.is_empty() {
8579                crate::round::RoundPhase::Sync
8580            } else {
8581                crate::round::RoundPhase::UploadGrant
8582            };
8583            Ok(crate::PreparedSyncRound {
8584                id,
8585                started_at_ms,
8586                attempt,
8587                message,
8588                meta,
8589                uploads: uploads.into(),
8590                phase,
8591                encoded: None,
8592                continuation: None,
8593                completed: None,
8594                realtime: self.realtime_state == RealtimeState::Connected,
8595                // §5.5: the owning unit's scope map, each value a one-element list.
8596                scopes: units
8597                    .into_iter()
8598                    .map(|unit| {
8599                        (
8600                            unit.id,
8601                            canonical_scope_json(&unit_scope_lists(&unit.scopes)),
8602                        )
8603                    })
8604                    .collect(),
8605                #[cfg(feature = "bench-internals")]
8606                benchmark_phases: self.benchmark_phases.clone(),
8607                progress: self.progress.clone(),
8608                fixed_now: self
8609                    .now_ms
8610                    .as_ref()
8611                    .map(|clock| clock.load(std::sync::atomic::Ordering::Relaxed)),
8612                round_deadline_at: None,
8613                idle_bound: None,
8614            })
8615        })();
8616        prepared
8617            .map_err(|outcome| Box::new(self.finish_sync_round(started_at_ms, attempt, *outcome)))
8618    }
8619
8620    /// Discard the reply of an old authorization or registration context. Its
8621    /// submitted commits stay durable and can be retried with the same ids.
8622    /// §7.6: an abandoned in-flight round ends its attempt as failed.
8623    pub fn cancel_sync_round(&mut self) {
8624        if let Some((_, started_at_ms, attempt)) = self.active_round.take() {
8625            // A storage failure recorded since the round started is not its cause.
8626            self.storage_failure.borrow_mut().take();
8627            self.finish_sync_round(
8628                started_at_ms,
8629                attempt,
8630                SyncOutcome::Failed {
8631                    error_code: "client.round_cancelled".into(),
8632                    message: "sync round belongs to a released client context".into(),
8633                    details: None,
8634                    recommended_action: None,
8635                },
8636            );
8637        }
8638    }
8639
8640    /// Apply captured network results on the owner, preserving all normal
8641    /// version, schema, content-address and cursor checks. No network I/O.
8642    pub fn apply_sync_round(
8643        &mut self,
8644        completed: crate::CompletedSyncRound,
8645    ) -> crate::AppliedSyncRound {
8646        let mut prepared = completed.prepared;
8647        if self.active_round.map(|(id, ..)| id) != Some(prepared.id) || self.security_preflight {
8648            return crate::AppliedSyncRound::Complete {
8649                outcome: SyncOutcome::Failed {
8650                    error_code: "client.round_cancelled".into(),
8651                    message: "sync round belongs to a released client context".into(),
8652                    details: None,
8653                    recommended_action: None,
8654                },
8655                controls: Vec::new(),
8656                more: false,
8657                bootstrap_advanced: false,
8658            };
8659        }
8660        self.storage_failure.borrow_mut().take();
8661        let (response, mut downloads, transport_failed) = match completed.exchange {
8662            crate::round::ExchangeResult::Upload { id, result } => {
8663                let result = match result {
8664                    // §5.9.7: a non-retryable server refusal (`blob.too_large`)
8665                    // is the body's final outcome. The commits naming it take
8666                    // the incompatible-commit path with the server's code and
8667                    // leave this round's request; the round continues.
8668                    Err(error)
8669                        if error
8670                            .details
8671                            .as_ref()
8672                            .and_then(|details| details.get("retryable"))
8673                            == Some(&Value::Bool(false)) =>
8674                    {
8675                        self.conn
8676                            .prepare(
8677                                "SELECT commit_id FROM _syncular_blob_commit_refs WHERE blob_id = ?",
8678                            )
8679                            .and_then(|mut statement| {
8680                                statement
8681                                    .query_map(rusqlite::params![id], |row| row.get::<_, String>(0))?
8682                                    .collect::<Result<HashSet<_>, _>>()
8683                            })
8684                            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
8685                            .and_then(|refused| {
8686                                let commits = self
8687                                    .outbox
8688                                    .iter()
8689                                    .filter(|commit| refused.contains(&commit.client_commit_id))
8690                                    .cloned()
8691                                    .collect::<Vec<_>>();
8692                                if !commits.is_empty() {
8693                                    self.drop_outbox_commits(&commits, &error.code, &error.message)?;
8694                                }
8695                                prepared.message.frames.retain(|frame| {
8696                                    !matches!(frame, Frame::PushCommit { client_commit_id, .. }
8697                                        if refused.contains(client_commit_id))
8698                                });
8699                                prepared.meta.pushed_ids.retain(|id| !refused.contains(id));
8700                                prepared.continuation = Some(crate::round::RoundPhase::UploadGrant);
8701                                Ok(())
8702                            })
8703                            .map_err(|message| TransportError::new("client.failed", message))
8704                    }
8705                    result => result,
8706                };
8707                let result = result.and_then(|()| {
8708                    self.conn
8709                        .execute(
8710                            "DELETE FROM _syncular_blob_uploads WHERE blob_id = ?",
8711                            rusqlite::params![id],
8712                        )
8713                        .map(|_| ())
8714                        .map_err(|error| {
8715                            TransportError::new(
8716                                "client.failed",
8717                                Self::sqlite_failure(&self.storage_failure, error),
8718                            )
8719                        })
8720                });
8721                match result {
8722                    Ok(()) => return crate::AppliedSyncRound::Continue(prepared),
8723                    Err(TransportError {
8724                        code,
8725                        message,
8726                        details,
8727                    }) => {
8728                        self.active_round = None;
8729                        if Self::unreachable_transport(&details) {
8730                            // The round's work is still owed; the host's
8731                            // connectivity resume runs it.
8732                            self.set_sync_needed(true, false);
8733                        } else if Self::retryable_failure_code(&code) {
8734                            self.schedule_background_retry();
8735                        }
8736                        let recommended_action = recommended_action_of(&details);
8737                        let outcome = self.finish_sync_round(
8738                            prepared.started_at_ms,
8739                            prepared.attempt,
8740                            SyncOutcome::Failed {
8741                                error_code: code,
8742                                message,
8743                                details,
8744                                recommended_action,
8745                            },
8746                        );
8747                        return crate::AppliedSyncRound::Complete {
8748                            outcome,
8749                            controls: Vec::new(),
8750                            more: false,
8751                            bootstrap_advanced: false,
8752                        };
8753                    }
8754                }
8755            }
8756            crate::round::ExchangeResult::Reply {
8757                response,
8758                downloads,
8759                transport_failed,
8760            } => (response, downloads, transport_failed),
8761        };
8762        self.active_round = None;
8763        let before = self.resume_tokens();
8764        let outcome = (|| {
8765            let response = match response {
8766                Ok(response) => {
8767                    // §1.5: a complete, decodable response ends the report, an
8768                    // in-band ERROR included (the server already recorded it).
8769                    self.round_failure = None;
8770                    response
8771                }
8772                Err(TransportError {
8773                    code,
8774                    message,
8775                    details,
8776                }) => {
8777                    // §1.5: the server cannot see a round whose transport
8778                    // failed or whose response never decoded, so its code rides
8779                    // the following requests. A code the frame grammar rejects
8780                    // is not reportable, and the previous code stays; the
8781                    // client-local drive timeout never goes on the wire (§7.8).
8782                    if code != "sync.idle_timeout" && ssp2::model::valid_round_failure_code(&code) {
8783                        self.round_failure = Some(code.clone());
8784                    }
8785                    if transport_failed {
8786                        if prepared.realtime {
8787                            self.set_realtime_state(RealtimeState::Lost, Some(&code));
8788                        }
8789                        if let Err(message) = self.record_lease_error(&code) {
8790                            return SyncOutcome::Failed {
8791                                error_code: "storage.failed".to_owned(),
8792                                message,
8793                                details: None,
8794                                recommended_action: None,
8795                            };
8796                        }
8797                    }
8798                    if Self::retryable_failure_code(&code) && !Self::unreachable_transport(&details)
8799                    {
8800                        let delay = self.schedule_background_retry();
8801                        if prepared.realtime && transport_failed {
8802                            self.realtime_retry_delay_ms = Some(delay);
8803                        }
8804                    }
8805                    let recommended_action = recommended_action_of(&details);
8806                    return SyncOutcome::Failed {
8807                        error_code: code,
8808                        message,
8809                        details,
8810                        recommended_action,
8811                    };
8812                }
8813            };
8814            let mut outcome = self.process_response(&mut downloads, response, &prepared.meta);
8815            if let SyncOutcome::Ok(report) = &mut outcome {
8816                report.deferred_commits = prepared.meta.deferred_commits;
8817            }
8818            match &outcome {
8819                SyncOutcome::Ok(_) => self.reset_background_retry(),
8820                SyncOutcome::Failed {
8821                    error_code,
8822                    details,
8823                    ..
8824                } if Self::retryable_failure_code(error_code)
8825                    && !Self::unreachable_transport(details) =>
8826                {
8827                    self.schedule_background_retry();
8828                }
8829                _ => {}
8830            }
8831            if prepared.meta.deferred_commits > 0 {
8832                self.set_sync_needed(true, true);
8833            }
8834            self.previous_version_lifetime_check();
8835            outcome
8836        })();
8837        match &outcome {
8838            // §7.1: a unit still catching up needs another round, also when the
8839            // drive that started it ends early.
8840            SyncOutcome::Ok(report) if !report.bootstrapping.is_empty() => {
8841                self.set_sync_needed(true, false)
8842            }
8843            // The round's work is still owed; the host's connectivity resume
8844            // runs it.
8845            SyncOutcome::Failed { details, .. } if Self::unreachable_transport(details) => {
8846                self.set_sync_needed(true, false)
8847            }
8848            _ => {}
8849        }
8850        let more = self.transport_enabled
8851            && matches!(&outcome, SyncOutcome::Ok(report)
8852                if report.schema_floor.is_none()
8853                    && (!report.bootstrapping.is_empty()
8854                        || report.commits_applied > 0
8855                        || report.segment_rows_applied > 0
8856                        || !report.resets.is_empty()
8857                        || report.deferred_commits > 0
8858                        || self.sync_needed));
8859        let bootstrap_advanced = matches!(&outcome, SyncOutcome::Ok(report) if report.segment_rows_applied > 0 && !report.bootstrapping.is_empty())
8860            && before != self.resume_tokens();
8861        crate::AppliedSyncRound::Complete {
8862            outcome: self.finish_sync_round(prepared.started_at_ms, prepared.attempt, outcome),
8863            controls: if self.transport_enabled {
8864                downloads.controls
8865            } else {
8866                Vec::new()
8867            },
8868            more,
8869            bootstrap_advanced,
8870        }
8871    }
8872
8873    /// Every unit's resume token and applied-segment record: a bootstrap
8874    /// that advanced changes one (§4.7), also when it applied images of a
8875    /// section it deferred (§5.3, §5.6).
8876    #[allow(clippy::type_complexity)]
8877    fn resume_tokens(&self) -> Option<Vec<(String, Option<String>, Option<String>)>> {
8878        self.conn
8879            .prepare_cached(
8880                "SELECT id, bootstrap_state, applied FROM _syncular_units ORDER BY rowid",
8881            )
8882            .and_then(|mut stmt| {
8883                stmt.query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?
8884                    .collect()
8885            })
8886            .ok()
8887    }
8888
8889    /// §7.8: one idle drive's default total deadline, the TS client's value.
8890    pub const SYNC_IDLE_TIMEOUT_MS: u64 = 60_000;
8891
8892    pub fn sync_until_idle(
8893        &mut self,
8894        transport: &mut dyn Transport,
8895        max_rounds: Option<u32>,
8896    ) -> SyncOutcome {
8897        self.sync_until_idle_with_deadline(transport, max_rounds, Some(Self::SYNC_IDLE_TIMEOUT_MS))
8898    }
8899
8900    /// As [`SyncClient::sync_until_idle`], with an explicit total deadline in
8901    /// milliseconds (`None` disables it). The deadline is checked against the
8902    /// client clock between rounds: a drive past it after a completed round
8903    /// ends as `BudgetExhausted`. Each round is bounded by `timeout_ms` on its
8904    /// own, or the transport's tighter whole-round deadline (§1.8); a round
8905    /// that reaches the drive bound fails with `sync.idle_timeout`.
8906    pub fn sync_until_idle_with_deadline(
8907        &mut self,
8908        transport: &mut dyn Transport,
8909        max_rounds: Option<u32>,
8910        timeout_ms: Option<u64>,
8911    ) -> SyncOutcome {
8912        // §7.8: an explicit budget is a strict positive round count. Zero is a
8913        // caller error, not an exhaustion.
8914        if max_rounds == Some(0) {
8915            return SyncOutcome::Failed {
8916                details: None,
8917                error_code: "sync.invalid_request".into(),
8918                message: "maxRounds must be a positive integer".into(),
8919                recommended_action: None,
8920            };
8921        }
8922        if timeout_ms.is_some_and(|ms| ms == 0 || i64::try_from(ms).is_err()) {
8923            return SyncOutcome::Failed {
8924                details: None,
8925                error_code: "sync.invalid_request".into(),
8926                message: "timeoutMs must be a positive integer".into(),
8927                recommended_action: None,
8928            };
8929        }
8930        let started_at_ms = self.clock_now_ms();
8931        let rounds = max_rounds.unwrap_or(20);
8932        let mut aggregate = SyncReport::default();
8933        // §7.2.2: decisions pending at the drive's start are evaluated when it
8934        // reaches idle.
8935        let decisions = match self.prepare_replacements() {
8936            Ok(decisions) => decisions,
8937            Err(message) => {
8938                return SyncOutcome::Failed {
8939                    details: None,
8940                    error_code: "storage.failed".into(),
8941                    message,
8942                    recommended_action: None,
8943                }
8944            }
8945        };
8946        let mut spent = 0;
8947        let mut completed = false;
8948        while spent < rounds {
8949            // §7.8: a deadline that elapsed across completed rounds ends the
8950            // drive like an exhausted round budget; the next drive resumes.
8951            if completed
8952                && timeout_ms.is_some_and(|ms| {
8953                    self.clock_now_ms() >= started_at_ms.saturating_add(ms as i64)
8954                })
8955            {
8956                return SyncOutcome::BudgetExhausted(aggregate);
8957            }
8958            let idle_bound = timeout_ms.map(|ms| (ms, spent));
8959            spent += 1;
8960            let before = self.resume_tokens();
8961            match self.sync_bounded(transport, idle_bound) {
8962                SyncOutcome::Failed {
8963                    error_code,
8964                    message,
8965                    details,
8966                    recommended_action,
8967                } => {
8968                    return SyncOutcome::Failed {
8969                        details,
8970                        error_code,
8971                        message,
8972                        recommended_action,
8973                    };
8974                }
8975                outcome @ SyncOutcome::RealtimeUnavailable { .. } => return outcome,
8976                SyncOutcome::BudgetExhausted(_) => {
8977                    unreachable!("sync() never exhausts a round budget")
8978                }
8979                SyncOutcome::Ok(report) => {
8980                    completed = true;
8981                    if max_rounds.is_none()
8982                        && report.segment_rows_applied > 0
8983                        && !report.bootstrapping.is_empty()
8984                        && before != self.resume_tokens()
8985                    {
8986                        spent = 0;
8987                    }
8988                    // TS parity: a disabled transport or a schema floor ends
8989                    // the loop. The latest round still merges first.
8990                    let stop = !self.transport_enabled() || report.schema_floor.is_some();
8991                    aggregate.merge(&report);
8992                    // §4.5: pull again whenever the response contained
8993                    // commits or segments; resets re-bootstrap; a pending
8994                    // resume token continues paging (§4.7); deferred outbox
8995                    // commits and a raised sync-needed signal push on the next
8996                    // round.
8997                    let more = !stop
8998                        && (!report.bootstrapping.is_empty()
8999                            || report.commits_applied > 0
9000                            || report.segment_rows_applied > 0
9001                            || !report.resets.is_empty()
9002                            || report.deferred_commits > 0
9003                            || self.sync_needed);
9004                    if more {
9005                        continue;
9006                    }
9007                    // §7.2.2: a written decision runs another round, which
9008                    // pushes it.
9009                    match self.settle_replacements(&decisions, &SyncOutcome::Ok(aggregate.clone()))
9010                    {
9011                        Ok(true) if !stop => {}
9012                        Ok(_) => return SyncOutcome::Ok(aggregate),
9013                        Err(message) => {
9014                            return SyncOutcome::Failed {
9015                                details: None,
9016                                error_code: "storage.failed".into(),
9017                                message,
9018                                recommended_action: None,
9019                            }
9020                        }
9021                    }
9022                }
9023            }
9024        }
9025        // §7.8: partial success. The aggregate report is retained and the run
9026        // is explicitly not idle.
9027        SyncOutcome::BudgetExhausted(aggregate)
9028    }
9029
9030    fn process_response(
9031        &mut self,
9032        transport: &mut dyn Transport,
9033        response: Message,
9034        meta: &RequestMeta,
9035    ) -> SyncOutcome {
9036        #[cfg(feature = "bench-internals")]
9037        let _phase = self.benchmark_phases.start(Phase::ResponseApply);
9038        let mut report = SyncReport {
9039            pushed: meta.pushed_ids.len() as u32,
9040            ..SyncReport::default()
9041        };
9042        let mut rejection_details_by_commit: HashMap<String, BTreeMap<i32, RejectionDetails>> =
9043            HashMap::new();
9044        let pushed_ids = meta
9045            .pushed_ids
9046            .iter()
9047            .map(String::as_str)
9048            .collect::<HashSet<_>>();
9049        let mut last_final_push_result_id: Option<String> = None;
9050        for frame in &response.frames {
9051            match frame {
9052                Frame::PushResultDetails {
9053                    client_commit_id,
9054                    entries,
9055                } => {
9056                    let details = rejection_details_by_commit
9057                        .entry(client_commit_id.clone())
9058                        .or_default();
9059                    for entry in entries {
9060                        let parsed = match RejectionDetails::parse(&entry.details.0) {
9061                            Ok(value) => value,
9062                            Err(message) => {
9063                                return SyncOutcome::Failed {
9064                                    details: None,
9065                                    error_code: "sync.invalid_request".to_owned(),
9066                                    message,
9067                                    recommended_action: None,
9068                                };
9069                            }
9070                        };
9071                        details.insert(entry.op_index, parsed);
9072                    }
9073                }
9074                Frame::PushResult {
9075                    client_commit_id,
9076                    status,
9077                    results,
9078                    ..
9079                } if pushed_ids.contains(client_commit_id.as_str())
9080                    && Self::push_result_is_final(*status, results) =>
9081                {
9082                    last_final_push_result_id = Some(client_commit_id.clone());
9083                }
9084                _ => {}
9085            }
9086        }
9087        let mut frames = response.frames.into_iter().peekable();
9088        match frames.next() {
9089            Some(Frame::RespHeader {
9090                required_schema_version,
9091                latest_schema_version,
9092                log_epoch,
9093                reset_required,
9094            }) => {
9095                if let Some(required) = required_schema_version {
9096                    // §1.6 schema-floor response: nothing else is processed;
9097                    // stop syncing and surface the upgrade requirement.
9098                    let floor = SchemaFloor {
9099                        required_schema_version: Some(required),
9100                        latest_schema_version,
9101                    };
9102                    if let Err(message) = self.set_schema_floor(Some(floor.clone())) {
9103                        return SyncOutcome::Failed {
9104                            details: None,
9105                            error_code: "storage.failed".to_owned(),
9106                            message,
9107                            recommended_action: None,
9108                        };
9109                    }
9110                    report.schema_floor = Some(floor);
9111                    return SyncOutcome::Ok(report);
9112                }
9113                if reset_required {
9114                    if frames.next().is_some() {
9115                        return SyncOutcome::Failed {
9116                            details: None,
9117                            error_code: "client.invalid_host_response".to_owned(),
9118                            message: "log-epoch reset response contains body frames".to_owned(),
9119                            recommended_action: None,
9120                        };
9121                    }
9122                    match self.run_log_epoch_reset(&log_epoch) {
9123                        Ok(resets) => {
9124                            report.resets = resets;
9125                            return SyncOutcome::Ok(report);
9126                        }
9127                        Err(message) => {
9128                            return SyncOutcome::Failed {
9129                                details: None,
9130                                error_code: "sync.local_corrupt".to_owned(),
9131                                message,
9132                                recommended_action: None,
9133                            };
9134                        }
9135                    }
9136                }
9137                let stored_epoch = match self.get_meta(LOG_EPOCH_KEY) {
9138                    Ok(stored) => stored,
9139                    Err(message) => {
9140                        return SyncOutcome::Failed {
9141                            details: None,
9142                            error_code: "storage.failed".to_owned(),
9143                            message,
9144                            recommended_action: None,
9145                        };
9146                    }
9147                };
9148                // §2.1 adoption: the epoch is stored before any section applies.
9149                if stored_epoch.is_none() {
9150                    if let Err(message) = self.set_meta(LOG_EPOCH_KEY, &log_epoch) {
9151                        return SyncOutcome::Failed {
9152                            details: None,
9153                            error_code: "storage.failed".to_owned(),
9154                            message,
9155                            recommended_action: None,
9156                        };
9157                    }
9158                } else if stored_epoch.as_deref() != Some(log_epoch.as_str()) {
9159                    return SyncOutcome::Failed {
9160                        details: None,
9161                        error_code: "client.invalid_host_response".to_owned(),
9162                        message: "server changed logEpoch without requiring a reset".to_owned(),
9163                        recommended_action: None,
9164                    };
9165                }
9166            }
9167            _ => {
9168                return SyncOutcome::Failed {
9169                    details: None,
9170                    error_code: "sync.invalid_request".to_owned(),
9171                    message: "response does not start with RESP_HEADER".to_owned(),
9172                    recommended_action: None,
9173                };
9174            }
9175        }
9176
9177        if let Err(message) = self.begin_coalesced_apply() {
9178            return SyncOutcome::Failed {
9179                details: None,
9180                error_code: "storage.failed".into(),
9181                message,
9182                recommended_action: None,
9183            };
9184        }
9185        let mut failure: Option<(String, String, Option<String>, Option<Value>)> = None;
9186        // §4.5 client application: the units whose persisted echo a live
9187        // change must match, fixed at LIVE_START after every SUB_END persisted.
9188        let mut live: Option<(LiveStatus, String, Vec<UnitRecord>)> = None;
9189        let mut live_ended = false;
9190        while let Some(frame) = frames.next() {
9191            match frame {
9192                frame @ Frame::PushResult { .. } => {
9193                    let successful = matches!(
9194                        &frame,
9195                        Frame::PushResult {
9196                            status: PushStatus::Applied | PushStatus::Cached,
9197                            ..
9198                        }
9199                    );
9200                    let mut results = vec![frame];
9201                    if successful {
9202                        while matches!(
9203                            frames.peek(),
9204                            Some(Frame::PushResult {
9205                                status: PushStatus::Applied | PushStatus::Cached,
9206                                ..
9207                            })
9208                        ) {
9209                            if let Some(next) = frames.next() {
9210                                results.push(next);
9211                            }
9212                        }
9213                    }
9214                    if self
9215                        .handle_push_results(
9216                            &results,
9217                            &pushed_ids,
9218                            &rejection_details_by_commit,
9219                            &mut report,
9220                            last_final_push_result_id.as_deref(),
9221                        )
9222                        .is_err()
9223                    {
9224                        failure = Some((
9225                            "client.outcome_persistence_failed".to_owned(),
9226                            "local commit outcome could not be persisted".to_owned(),
9227                            None,
9228                            None,
9229                        ));
9230                        break;
9231                    }
9232                }
9233                Frame::PushResultDetails { .. } => {}
9234                Frame::SubStart {
9235                    id,
9236                    status,
9237                    reason_code,
9238                    bootstrap,
9239                    fenced,
9240                } => {
9241                    // §1.4 rule 5: an ERROR closes the section; its body still
9242                    // applied, its SUB_END values are never persisted.
9243                    let mut body = Vec::new();
9244                    let mut sub_end: Option<(i64, Option<String>)> = None;
9245                    let mut error: Option<Frame> = None;
9246                    for inner in frames.by_ref() {
9247                        match inner {
9248                            Frame::SubEnd {
9249                                next_cursor,
9250                                bootstrap_state,
9251                            } => {
9252                                sub_end = Some((next_cursor, bootstrap_state.map(|r| r.0)));
9253                                break;
9254                            }
9255                            inner @ Frame::Error { .. } => {
9256                                error = Some(inner);
9257                                break;
9258                            }
9259                            Frame::Unknown { .. } => {}
9260                            other => body.push(other),
9261                        }
9262                    }
9263                    let ended = sub_end.is_some();
9264                    let section = SectionStart {
9265                        id,
9266                        status,
9267                        reason_code,
9268                        bootstrap,
9269                        fenced,
9270                    };
9271                    let completed = match self.process_section(
9272                        transport,
9273                        &section,
9274                        body,
9275                        sub_end,
9276                        meta,
9277                        &mut report,
9278                    ) {
9279                        Err(SectionError::Abort(code, message)) => {
9280                            failure = Some((code, message, None, None));
9281                            break;
9282                        }
9283                        Err(SectionError::Transport(error)) => {
9284                            failure = Some((error.code, error.message, None, error.details));
9285                            break;
9286                        }
9287                        Ok(completed) => completed,
9288                        Err(_) => false,
9289                    };
9290                    if ended {
9291                        // The counters stay: `complete` and `failed` report them.
9292                        // §7.7: a completed bootstrap ends with the unit total
9293                        // equal to the rows processed.
9294                        self.progress.update(|p| {
9295                            p.unit_id = None;
9296                            p.table = None;
9297                            p.segment_id = None;
9298                            if completed && p.unit_rows_total.is_some() {
9299                                p.unit_rows_total = p.unit_rows_processed;
9300                            }
9301                        });
9302                    }
9303                    match error {
9304                        Some(Frame::Error {
9305                            code,
9306                            message,
9307                            recommended_action,
9308                            details,
9309                            ..
9310                        }) => {
9311                            failure = Some(Self::error_frame_failure(
9312                                code,
9313                                message,
9314                                recommended_action,
9315                                details,
9316                            ));
9317                            break;
9318                        }
9319                        Some(_) => unreachable!("only an ERROR closes a section early"),
9320                        None if !ended => {
9321                            failure = Some((
9322                                "sync.invalid_request".to_owned(),
9323                                "unit section without SUB_END".to_owned(),
9324                                None,
9325                                None,
9326                            ));
9327                            break;
9328                        }
9329                        None => {}
9330                    }
9331                }
9332                Frame::LiveStart {
9333                    status,
9334                    reason_code,
9335                } => {
9336                    let receivers = match self.stored(load_units(&self.conn)) {
9337                        Ok(units) => units
9338                            .into_iter()
9339                            .filter(|unit| {
9340                                unit.status == UnitStatus::Active
9341                                    && unit.echo.is_some()
9342                                    && !unit.bootstrapping()
9343                            })
9344                            .collect(),
9345                        Err(message) => {
9346                            failure = Some(("storage.failed".to_owned(), message, None, None));
9347                            break;
9348                        }
9349                    };
9350                    live = Some((status, reason_code, receivers));
9351                }
9352                Frame::Commit {
9353                    commit_seq,
9354                    tables,
9355                    changes,
9356                    ..
9357                } => {
9358                    let Some((LiveStatus::Active, _, receivers)) = &live else {
9359                        continue;
9360                    };
9361                    let receivers = receivers.clone();
9362                    match self.apply_live_commit(
9363                        &receivers,
9364                        &tables,
9365                        changes,
9366                        commit_seq,
9367                        AppliedServerCommitSource::Pull,
9368                    ) {
9369                        Ok(applied) => report.commits_applied += u32::from(applied),
9370                        Err(error) => {
9371                            failure = Some((error.code, error.message, None, error.details));
9372                            break;
9373                        }
9374                    }
9375                }
9376                Frame::LiveEnd {
9377                    through_seq,
9378                    echo_digest,
9379                } => {
9380                    let Some((status, reason_code, _)) = live.take() else {
9381                        continue;
9382                    };
9383                    live_ended = true;
9384                    live = Some((status, String::new(), Vec::new()));
9385                    if let Err(message) = self.finish_live_section(
9386                        status,
9387                        &reason_code,
9388                        through_seq,
9389                        echo_digest,
9390                        &meta.registration_digest,
9391                        &mut report,
9392                    ) {
9393                        failure = Some(("storage.failed".to_owned(), message, None, None));
9394                        break;
9395                    }
9396                }
9397                Frame::Lease {
9398                    lease_id,
9399                    expires_at_ms,
9400                } => {
9401                    // §7.3.5: persist the opaque lease; a fresh lease clears
9402                    // any prior lease error (the outage/revocation is over).
9403                    if let Err(message) = self.set_lease_state(Some(LeaseState {
9404                        lease_id: Some(lease_id),
9405                        expires_at_ms: Some(expires_at_ms),
9406                        error_code: None,
9407                    })) {
9408                        failure = Some(("storage.failed".to_owned(), message, None, None));
9409                        break;
9410                    }
9411                }
9412                Frame::Error {
9413                    code,
9414                    message,
9415                    recommended_action,
9416                    details,
9417                    ..
9418                } => {
9419                    // §1.6: the whole request failed; already-completed
9420                    // units keep their applied data and cursors.
9421                    failure = Some(Self::error_frame_failure(
9422                        code,
9423                        message,
9424                        recommended_action,
9425                        details,
9426                    ));
9427                    break;
9428                }
9429                Frame::Unknown { .. } => {}
9430                _ => {
9431                    failure = Some((
9432                        "sync.invalid_request".to_owned(),
9433                        "unexpected frame in response".to_owned(),
9434                        None,
9435                        None,
9436                    ));
9437                    break;
9438                }
9439            }
9440        }
9441
9442        let applied = match failure {
9443            Some(failure) => Err(failure),
9444            // Local apply boundaries already reconciled their affected overlay.
9445            // Refuse round success if any remaining dirty work fails to
9446            // reconcile. §4.8 E1: the push half may have drained commits that
9447            // pinned rows of a shrunk window unit, so retry deferred evictions.
9448            None => self
9449                .rebuild_overlay_if_dirty()
9450                .and_then(|()| self.drain_pending_evictions())
9451                .map_err(|message| ("storage.failed".to_owned(), message, None, None)),
9452        };
9453        // §1.4 rule 4: frames completed before a failure stay committed; a
9454        // failed COMMIT of the coalesced transaction fails the round.
9455        if let Err(message) = self.finish_coalesced_apply() {
9456            return SyncOutcome::Failed {
9457                details: None,
9458                error_code: "storage.failed".into(),
9459                message,
9460                recommended_action: None,
9461            };
9462        }
9463        if let Err((error_code, message, recommended_action, details)) = applied {
9464            return SyncOutcome::Failed {
9465                details,
9466                error_code,
9467                message,
9468                recommended_action,
9469            };
9470        }
9471        let catching_up = match self.stored(load_units(&self.conn)) {
9472            Ok(units) => units
9473                .into_iter()
9474                .filter(|unit| unit.status == UnitStatus::Active && unit.cursor.is_some())
9475                .map(|unit| unit.id)
9476                .collect::<Vec<_>>(),
9477            Err(message) => {
9478                return SyncOutcome::Failed {
9479                    details: None,
9480                    error_code: "storage.failed".into(),
9481                    message,
9482                    recommended_action: None,
9483                }
9484            }
9485        };
9486        // §7.1: a response without LIVE_END, one answered `unregistered` or
9487        // `reset`, or a unit still catching up leaves sync-needed raised;
9488        // after `unregistered` the next round starts at once.
9489        let status = live.map(|(status, _, _)| status);
9490        if !live_ended || status != Some(LiveStatus::Active) || !catching_up.is_empty() {
9491            self.set_sync_needed(true, status == Some(LiveStatus::Unregistered));
9492        }
9493        self.ack_after_pull(transport);
9494        // §7.4.5: the reset is over once the first post-reset pull round
9495        // leaves no unit catching up: the tables are rebuilt and current.
9496        if self.upgrading && catching_up.is_empty() {
9497            self.set_upgrading(false);
9498        }
9499        report.bootstrapping = catching_up;
9500        SyncOutcome::Ok(report)
9501    }
9502
9503    /// §1.6 / §10.1: the failure an in-band `ERROR` frame reports.
9504    fn error_frame_failure(
9505        code: String,
9506        message: String,
9507        recommended_action: String,
9508        details: Option<RawJson>,
9509    ) -> (String, String, Option<String>, Option<Value>) {
9510        let recommended_action = (!recommended_action.is_empty()).then_some(recommended_action);
9511        let details = details
9512            .and_then(|details| serde_json::from_str::<Value>(&details.0).ok())
9513            .filter(Value::is_object);
9514        (code, message, recommended_action, details)
9515    }
9516
9517    /// §4.5 at `LIVE_END` of a pull: join rule J for an `active` section, the
9518    /// §4.6 replica reset for `reset`, nothing for `unregistered`; then the
9519    /// replica cursor, the echo digest and the digest of the list the server
9520    /// now stores.
9521    fn finish_live_section(
9522        &mut self,
9523        status: LiveStatus,
9524        reason_code: &str,
9525        through_seq: i64,
9526        echo_digest: Option<[u8; 32]>,
9527        registration_digest: &str,
9528        report: &mut SyncReport,
9529    ) -> Result<(), String> {
9530        let rollback = self.capture();
9531        let resets = report.resets.len();
9532        self.begin_observation("syncular_live_end")?;
9533        let finished = (|| {
9534            let mut batch = ChangeAccumulator::default();
9535            let before = self.stored(replica_cursor(&self.conn))?;
9536            let mut cursor = if status == LiveStatus::Unregistered {
9537                before
9538            } else {
9539                -1
9540            };
9541            let joined = before.max(through_seq);
9542            for unit in self.stored(load_units(&self.conn))? {
9543                if unit.status != UnitStatus::Active || unit.bootstrapping() {
9544                    continue;
9545                }
9546                match status {
9547                    // §4.6 replica reset: every live unit bootstraps again;
9548                    // post-bootstrap units keep their cursors.
9549                    LiveStatus::Reset if unit.cursor.is_none() => {
9550                        for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9551                            batch.window(&base_key, &value);
9552                        }
9553                        report.resets.push(unit.id.clone());
9554                        self.stored(save_unit(
9555                            &self.conn,
9556                            &UnitRecord {
9557                                reason_code: Some(reason_code.to_owned()),
9558                                cursor: Some(-1),
9559                                seeded: Vec::new(),
9560                                ..unit
9561                            },
9562                        ))?;
9563                    }
9564                    // §4.5 join rule J.
9565                    LiveStatus::Active => {
9566                        let next = unit.cursor.unwrap_or(joined).max(through_seq);
9567                        if next >= joined {
9568                            cursor = joined;
9569                        }
9570                        if unit.cursor.is_some() {
9571                            self.stored(save_unit(
9572                                &self.conn,
9573                                &UnitRecord {
9574                                    cursor: (next < joined).then_some(next),
9575                                    ..unit
9576                                },
9577                            ))?;
9578                        }
9579                    }
9580                    _ => {}
9581                }
9582            }
9583            self.set_meta(REPLICA_CURSOR_KEY, &cursor.to_string())?;
9584            self.set_meta(
9585                ECHO_DIGEST_KEY,
9586                &echo_digest
9587                    .map(|digest| bytes_to_hex(&digest))
9588                    .unwrap_or_default(),
9589            )?;
9590            if status == LiveStatus::Unregistered {
9591                self.delete_meta(REGISTERED_DIGEST_KEY)?;
9592            } else {
9593                self.set_meta(REGISTERED_DIGEST_KEY, registration_digest)?;
9594            }
9595            self.finish_observation("syncular_live_end", batch)
9596        })();
9597        if finished.is_err() {
9598            self.rollback_observation("syncular_live_end");
9599            self.restore(rollback);
9600            report.resets.truncate(resets);
9601        }
9602        finished
9603    }
9604
9605    // -- push results (§6.3, §7.2) ------------------------------------------------
9606
9607    fn handle_push_results(
9608        &mut self,
9609        frames: &[Frame],
9610        pushed_ids: &HashSet<&str>,
9611        rejection_details_by_commit: &HashMap<String, BTreeMap<i32, RejectionDetails>>,
9612        report: &mut SyncReport,
9613        last_final_push_result_id: Option<&str>,
9614    ) -> Result<(), String> {
9615        self.begin_observation("syncular_push_results")?;
9616        let rollback = self.capture();
9617        let conflict_count = self.conflicts.len();
9618        let applied_count = report.applied.len();
9619        let rejected_count = report.rejected.len();
9620        let retryable_count = report.retryable.len();
9621        let mut drained = Vec::new();
9622        let mut batch = ChangeAccumulator::default();
9623        let persisted = (|| {
9624            for frame in frames {
9625                let Frame::PushResult {
9626                    client_commit_id,
9627                    status,
9628                    results,
9629                    commit_seq,
9630                } = frame
9631                else {
9632                    return Err("unexpected acknowledgement frame".to_owned());
9633                };
9634                if !pushed_ids.contains(client_commit_id.as_str()) {
9635                    continue;
9636                }
9637                let Some(index) = self
9638                    .outbox
9639                    .iter()
9640                    .position(|commit| commit.client_commit_id == *client_commit_id)
9641                else {
9642                    continue;
9643                };
9644                let status = *status;
9645                let rejection_details = rejection_details_by_commit.get(client_commit_id);
9646                let operations = self.outbox[index].ops.clone();
9647                match status {
9648                    PushStatus::Applied | PushStatus::Cached => {
9649                        // §7.2: a lost ack replays as `cached` — proceed as if the
9650                        // ack had arrived.
9651                        let sequence =
9652                            commit_seq.ok_or_else(|| "ACK lacks a commit sequence".to_owned())?;
9653                        let affected: HashSet<_> = operations
9654                            .iter()
9655                            .map(|op| (op.table.as_str(), op.row_id.as_str()))
9656                            .collect();
9657                        let prior = self.acknowledged_operations(Some(&affected), None)?;
9658                        for (op_index, operation) in operations.iter().enumerate() {
9659                            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))
9660                                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9661                            if delivered {
9662                                continue;
9663                            }
9664                            let table = self
9665                                .schema
9666                                .table(&operation.table)
9667                                .ok_or_else(|| "sync.unknown_table".to_owned())?;
9668                            let mut intended: Map<String, Value> = self
9669                                .stored_row(table, &operation.row_id, true)?
9670                                .map(|(row, _)| {
9671                                    table
9672                                        .columns
9673                                        .iter()
9674                                        .zip(&row)
9675                                        .map(|(column, value)| {
9676                                            (column.name.clone(), column_value_to_json(value))
9677                                        })
9678                                        .collect()
9679                                })
9680                                .unwrap_or_default();
9681                            let mut scope_image = intended.clone();
9682                            for op in prior
9683                                .iter()
9684                                .chain(
9685                                    self.failed_commits
9686                                        .iter()
9687                                        .flat_map(|(commit, _)| &commit.ops),
9688                                )
9689                                .chain(
9690                                    self.outbox
9691                                        .iter()
9692                                        .take(index)
9693                                        .flat_map(|commit| &commit.ops),
9694                                )
9695                                .chain(operations.iter().take(op_index + 1))
9696                            {
9697                                if op.table != operation.table || op.row_id != operation.row_id {
9698                                    continue;
9699                                }
9700                                if let Some(values) = &op.values {
9701                                    intended.extend(values.clone());
9702                                } else {
9703                                    scope_image = intended.clone();
9704                                    intended.clear();
9705                                }
9706                            }
9707                            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)",
9708                                rusqlite::params![client_commit_id, op_index as i64, operation.table, operation.row_id, sequence,
9709                                    serde_json::to_string(&CommitOperation::from(operation)).map_err(|_| "sync.local_corrupt".to_owned())?,
9710                                    serde_json::to_string(if operation.upsert { &intended } else { &scope_image }).map_err(|_| "sync.local_corrupt".to_owned())?])
9711                                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9712                        }
9713                        let journal_results = results
9714                            .iter()
9715                            .map(|result| {
9716                                let op_index = match result {
9717                                    OpResult::Applied { op_index }
9718                                    | OpResult::Conflict { op_index, .. }
9719                                    | OpResult::Error { op_index, .. } => *op_index,
9720                                };
9721                                CommitOperationOutcome::Applied { op_index }
9722                            })
9723                            .collect::<Vec<_>>();
9724                        let outcome_status = if status == PushStatus::Applied {
9725                            CommitOutcomeStatus::Applied
9726                        } else {
9727                            CommitOutcomeStatus::Cached
9728                        };
9729                        let persisted = self
9730                            .persist_commit_outcome(
9731                                client_commit_id,
9732                                outcome_status,
9733                                &journal_results,
9734                                None,
9735                            )
9736                            .and_then(|()| self.delete_outbox_persisted(client_commit_id));
9737                        persisted?;
9738                        self.sync_needed = true;
9739                        batch.status = true;
9740                        batch.outcomes = true;
9741                    }
9742                    PushStatus::Rejected => {
9743                        if results.iter().any(|result| {
9744                            matches!(
9745                                result,
9746                                OpResult::Error {
9747                                    code,
9748                                    retryable: true,
9749                                    ..
9750                                } if code == "sync.idempotency_cache_miss"
9751                            )
9752                        }) {
9753                            // §6.3/§7.2: a serving failure, not an outcome — keep the
9754                            // exact commit queued for an identical retry.
9755                            report.retryable.push(client_commit_id.to_owned());
9756                            continue;
9757                        }
9758
9759                        let mut journal_results = Vec::with_capacity(results.len());
9760                        let mut conflicts = Vec::new();
9761                        let mut rejections = Vec::new();
9762                        for result in results {
9763                            match result {
9764                                OpResult::Applied { op_index } => {
9765                                    journal_results.push(CommitOperationOutcome::Applied {
9766                                        op_index: *op_index,
9767                                    });
9768                                }
9769                                OpResult::Conflict {
9770                                    op_index,
9771                                    code,
9772                                    message,
9773                                    server_version,
9774                                    server_row,
9775                                    conflict_columns: conflict_columns_bitmap,
9776                                } => {
9777                                    let operation = operations
9778                                        .get(*op_index as usize)
9779                                        .map(CommitOperation::from);
9780                                    let (table, row_id) = operation
9781                                        .as_ref()
9782                                        .map(|op| (op.table.clone(), op.row_id.clone()))
9783                                        .unwrap_or_default();
9784                                    let server_row_json = self
9785                                        .schema
9786                                        .table(&table)
9787                                        .and_then(|t| {
9788                                            decode_row_bytes(t, server_row, &self.encryption)
9789                                                .ok()
9790                                                .map(|(row, _)| (t, row))
9791                                        })
9792                                        .map(|(t, row)| {
9793                                            let mut map = Map::new();
9794                                            for (i, column) in t.columns.iter().enumerate() {
9795                                                map.insert(
9796                                                    column.name.clone(),
9797                                                    column_value_to_json(
9798                                                        row.get(i).unwrap_or(&None),
9799                                                    ),
9800                                                );
9801                                            }
9802                                            map
9803                                        })
9804                                        .unwrap_or_default();
9805                                    // §6.3: decode the presence-layout bitmap
9806                                    // into the marked column names.
9807                                    let conflict_columns = self
9808                                        .schema
9809                                        .table(&table)
9810                                        .map(|t| {
9811                                            t.columns
9812                                                .iter()
9813                                                .enumerate()
9814                                                .filter(|(index, _)| {
9815                                                    conflict_columns_bitmap
9816                                                        .get(index / 8)
9817                                                        .is_some_and(|byte| {
9818                                                            byte & (1 << (index % 8)) != 0
9819                                                        })
9820                                                })
9821                                                .map(|(_, column)| column.name.clone())
9822                                                .collect::<Vec<_>>()
9823                                        })
9824                                        .unwrap_or_default();
9825                                    let conflict = ConflictRecord {
9826                                        client_commit_id: client_commit_id.to_owned(),
9827                                        op_index: *op_index,
9828                                        table,
9829                                        row_id,
9830                                        code: code.clone(),
9831                                        message: message.clone(),
9832                                        server_version: *server_version,
9833                                        server_row: server_row_json,
9834                                        conflict_columns,
9835                                        operation,
9836                                    };
9837                                    journal_results.push(CommitOperationOutcome::Conflict {
9838                                        conflict: conflict.clone(),
9839                                    });
9840                                    conflicts.push(conflict);
9841                                }
9842                                OpResult::Error {
9843                                    op_index,
9844                                    code,
9845                                    message,
9846                                    retryable,
9847                                } => {
9848                                    let rejection = RejectionRecord {
9849                                        client_commit_id: client_commit_id.to_owned(),
9850                                        op_index: *op_index,
9851                                        code: code.clone(),
9852                                        message: message.clone(),
9853                                        retryable: *retryable,
9854                                        details: rejection_details
9855                                            .and_then(|details| details.get(op_index))
9856                                            .cloned(),
9857                                        operation: operations
9858                                            .get(*op_index as usize)
9859                                            .map(CommitOperation::from),
9860                                    };
9861                                    journal_results.push(CommitOperationOutcome::Error {
9862                                        rejection: rejection.clone(),
9863                                    });
9864                                    rejections.push(rejection);
9865                                }
9866                            }
9867                        }
9868                        if self.retain_failed_commits {
9869                            self.retain_failed_commit(client_commit_id, &operations)?;
9870                        }
9871                        let outcome_status = if conflicts.is_empty() {
9872                            CommitOutcomeStatus::Rejected
9873                        } else {
9874                            CommitOutcomeStatus::Conflict
9875                        };
9876                        let persisted = self
9877                            .persist_commit_outcome(
9878                                client_commit_id,
9879                                outcome_status,
9880                                &journal_results,
9881                                Some(&operations),
9882                            )
9883                            .and_then(|()| self.delete_outbox_persisted(client_commit_id));
9884                        persisted?;
9885                        batch.conflicts = !conflicts.is_empty();
9886                        batch.rejections = !rejections.is_empty();
9887                        batch.status = true;
9888                        batch.outcomes = true;
9889                        self.conflicts.extend(conflicts);
9890                        self.rejections.extend(rejections);
9891                    }
9892                }
9893                drained.push(self.outbox.remove(index));
9894                if batch.status {
9895                    for operation in &operations {
9896                        if !self.record_row_scopes(
9897                            &mut batch,
9898                            &operation.table,
9899                            &operation.row_id,
9900                            false,
9901                        ) {
9902                            batch.table(&operation.table);
9903                        }
9904                    }
9905                }
9906                match status {
9907                    PushStatus::Applied | PushStatus::Cached => {
9908                        report.applied.push(client_commit_id.to_owned())
9909                    }
9910                    PushStatus::Rejected => report.rejected.push(client_commit_id.to_owned()),
9911                }
9912            }
9913            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)) {
9914                self.prune_commit_outcomes()?;
9915            }
9916            self.reconcile_rows(&drained)?;
9917            self.rebuild_overlay_if_dirty()?;
9918            self.finish_observation("syncular_push_results", batch)
9919        })();
9920        if let Err(error) = persisted {
9921            self.rollback_observation("syncular_push_results");
9922            self.restore(rollback);
9923            report.applied.truncate(applied_count);
9924            report.rejected.truncate(rejected_count);
9925            report.retryable.truncate(retryable_count);
9926            return Err(error);
9927        }
9928        if !rollback.sync_needed && self.sync_needed {
9929            self.sync_intent_queue.push_back(SyncIntent::Interactive);
9930        }
9931        report.conflicts += (self.conflicts.len() - conflict_count) as u32;
9932        Ok(())
9933    }
9934
9935    fn push_result_is_final(status: PushStatus, results: &[OpResult]) -> bool {
9936        status != PushStatus::Rejected
9937            || !results.iter().any(|result| {
9938                matches!(
9939                    result,
9940                    OpResult::Error {
9941                        code,
9942                        retryable: true,
9943                        ..
9944                    } if code == "sync.idempotency_cache_miss"
9945                )
9946            })
9947    }
9948
9949    // -- unit sections and the live section ------------------------------------------
9950
9951    /// One unit section (§4.4): apply its segments, then persist its
9952    /// `SUB_END` (§4.6 reset, §3.3 revocation and purge, the echo, cursor and
9953    /// resume token). A section of a unit the app released while the round was
9954    /// in flight is skipped; a fail-closed first page fails the unit and skips
9955    /// the rest of its section (§5.6). Returns whether its `SUB_END` completed
9956    /// a bootstrap (§7.7).
9957    fn process_section(
9958        &mut self,
9959        transport: &mut dyn Transport,
9960        start: &SectionStart,
9961        body: Vec<Frame>,
9962        sub_end: Option<(i64, Option<String>)>,
9963        meta: &RequestMeta,
9964        report: &mut SyncReport,
9965    ) -> Result<bool, SectionError> {
9966        let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
9967        let unit = self
9968            .stored(get_unit(&self.conn, &start.id))
9969            .map_err(storage)?
9970            .filter(|unit| unit.status == UnitStatus::Active);
9971        // §7.7: a section boundary ends the previous payload; the section's
9972        // UNIT_EXTENT starts the unit counters in the same snapshot.
9973        let extent = match (&unit, body.first()) {
9974            (
9975                Some(_),
9976                Some(Frame::UnitExtent {
9977                    rows_total,
9978                    rows_done,
9979                }),
9980            ) => u64::try_from(*rows_total)
9981                .ok()
9982                .zip(u64::try_from(*rows_done).ok()),
9983            _ => None,
9984        };
9985        self.progress.update(|p| {
9986            p.phase = ProgressPhase::Import;
9987            p.unit_id = unit.as_ref().map(|unit| unit.id.clone());
9988            p.unit_rows_total = extent.map(|(total, _)| total);
9989            p.unit_rows_processed = extent.map(|(_, done)| done);
9990            p.table = None;
9991            p.segment_id = None;
9992            p.bytes_received = 0;
9993            p.bytes_total = None;
9994            p.rows_processed = 0;
9995            p.rows_total = None;
9996            p.import_write_ms = None;
9997            p.import_commit_ms = None;
9998        });
9999        let Some(unit) = unit else {
10000            return Ok(false);
10001        };
10002        let echo: Vec<EchoRecord> = start
10003            .fenced
10004            .iter()
10005            .map(|record| EchoRecord {
10006                table: record.table.clone(),
10007                status: record.status.name().to_owned(),
10008                scopes: record.scopes.iter().cloned().collect(),
10009            })
10010            .collect();
10011        // §5.6: rows earlier attempts at this position applied.
10012        let applied_record = self
10013            .stored(applied_rows(&self.conn, &unit.id))
10014            .map_err(storage)?;
10015        // §5.6: a resumed bootstrap keeps the tables it already seeded.
10016        let mut seeded: BTreeSet<String> = if unit.bootstrap_state.is_none() {
10017            BTreeSet::new()
10018        } else {
10019            unit.seeded.iter().cloned().collect()
10020        };
10021        let applied = (|| {
10022            for frame in body {
10023                match frame {
10024                    Frame::SegmentInline { payload } => {
10025                        let segment = decode_rows_segment(&payload).map_err(|e| {
10026                            SectionError::Abort(e.code.as_str().to_owned(), e.detail)
10027                        })?;
10028                        self.progress.update(|p| {
10029                            p.phase = ProgressPhase::Import;
10030                            p.unit_id = Some(unit.id.clone());
10031                            p.table = Some(segment.table.clone());
10032                            p.segment_id = None;
10033                            p.bytes_received = payload.len() as u64;
10034                            p.bytes_total = Some(payload.len() as u64);
10035                            p.rows_processed = 0;
10036                            p.rows_total =
10037                                Some(segment.blocks.iter().map(|block| block.len() as u64).sum());
10038                            p.import_write_ms = None;
10039                            p.import_commit_ms = None;
10040                        });
10041                        let (pair, clear, effective) =
10042                            self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
10043                        report.segment_rows_applied +=
10044                            self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
10045                        seeded.insert(segment.table);
10046                    }
10047                    Frame::SegmentRef {
10048                        segment_id,
10049                        byte_length,
10050                        media_type,
10051                        table,
10052                        row_count,
10053                        as_of_commit_seq,
10054                        scope_digest,
10055                        row_cursor,
10056                        next_row_cursor,
10057                        url,
10058                        url_expires_at_ms,
10059                        ..
10060                    } => {
10061                        // §4.2: reject a descriptor whose mediaType was not
10062                        // advertised — never skip or guess.
10063                        let advertised = match media_type {
10064                            MediaType::Rows => {
10065                                meta.accept & ACCEPT_EXTERNAL_ROWS != 0
10066                                    || meta.accept & ACCEPT_INLINE_ROWS != 0
10067                            }
10068                            MediaType::Sqlite => meta.accept & ACCEPT_SQLITE != 0,
10069                        };
10070                        if !advertised {
10071                            return Err(SectionError::Abort(
10072                                "sync.invalid_request".to_owned(),
10073                                format!(
10074                                    "SEGMENT_REF mediaType {} was not advertised in accept (§4.2)",
10075                                    media_type.name()
10076                                ),
10077                            ));
10078                        }
10079                        // §5.6 applied-segment rule: a partly applied image
10080                        // already ran its table's first-page clear.
10081                        let resumed = applied_record.get(&segment_id).copied();
10082                        if resumed.is_some() {
10083                            seeded.insert(table.clone());
10084                        }
10085                        if resumed == Some(row_count) {
10086                            // §7.7: an earlier attempt imported this payload;
10087                            // its rows still count toward the unit.
10088                            self.progress.update(|p| {
10089                                p.phase = ProgressPhase::Import;
10090                                p.unit_id = Some(unit.id.clone());
10091                                p.table = Some(table.clone());
10092                                p.segment_id = Some(segment_id.clone());
10093                                p.bytes_received = 0;
10094                                p.bytes_total = None;
10095                                p.rows_processed = 0;
10096                                p.rows_total = u64::try_from(row_count).ok();
10097                                p.import_write_ms = None;
10098                                p.import_commit_ms = None;
10099                            });
10100                            self.progress.update(|p| {
10101                                p.rows_processed = u64::try_from(row_count).unwrap_or(0)
10102                            });
10103                            continue;
10104                        }
10105                        if meta
10106                            .deferred
10107                            .contains(&(unit.id.clone(), segment_id.clone()))
10108                        {
10109                            return Err(SectionError::Deferred);
10110                        }
10111                        self.progress.update(|p| {
10112                            p.phase = ProgressPhase::Download;
10113                            p.unit_id = Some(unit.id.clone());
10114                            p.table = Some(table.clone());
10115                            p.segment_id = Some(segment_id.clone());
10116                            p.bytes_received = 0;
10117                            p.bytes_total = u64::try_from(byte_length).ok();
10118                            p.rows_processed = 0;
10119                            p.rows_total = u64::try_from(row_count).ok();
10120                            p.import_write_ms = None;
10121                            p.import_commit_ms = None;
10122                        });
10123                        let observer = self.progress.clone();
10124                        let mut on_progress = |bytes| observer.update(|p| p.bytes_received = bytes);
10125                        let bytes = if let Some(url) = url {
10126                            // §5.4: a url-carrying descriptor MUST be fetched
10127                            // from that URL; failure invalidates the whole
10128                            // descriptor (no fall-through to §5.5 — re-pull
10129                            // recovers, §1.4 rule 5).
10130                            if meta.accept & ACCEPT_SIGNED_URLS == 0 {
10131                                return Err(SectionError::Abort(
10132                                    "sync.invalid_request".to_owned(),
10133                                    "SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)"
10134                                        .to_owned(),
10135                                ));
10136                            }
10137                            // §5.4: MUST NOT start a fetch at/past expiry.
10138                            if url_expires_at_ms.is_some_and(|exp| {
10139                                exp <= transport
10140                                    .segment_fetch_started_at(&url)
10141                                    .unwrap_or_else(|| self.clock_now_ms())
10142                            }) {
10143                                return Err(SectionError::Abort(
10144                                    "sync.segment_expired".to_owned(),
10145                                    format!(
10146                                        "signed URL for segment {segment_id} expired before fetch — re-pull mints fresh descriptors (§5.4)"
10147                                    ),
10148                                ));
10149                            }
10150                            transport
10151                                .fetch_url(
10152                                    &url,
10153                                    u64::try_from(byte_length).unwrap_or(0),
10154                                    &mut on_progress,
10155                                )
10156                                .map_err(|e| self.segment_fetch_failed(e))?
10157                        } else {
10158                            // §5.5: the owning unit's scope map, each value a one-element list.
10159                            let requested_scopes_json =
10160                                canonical_scope_json(&unit_scope_lists(&unit.scopes));
10161                            transport
10162                                .download_segment(
10163                                    &SegmentRequest {
10164                                        segment_id: segment_id.clone(),
10165                                        table: table.clone(),
10166                                        requested_scopes_json,
10167                                        byte_length: u64::try_from(byte_length).unwrap_or(0),
10168                                    },
10169                                    &mut on_progress,
10170                                )
10171                                .map_err(|e| {
10172                                    // §5.5: access changed since the response;
10173                                    // the next round's SUB_START settles the unit.
10174                                    if e.code == "sync.forbidden" {
10175                                        SectionError::Refused
10176                                    } else {
10177                                        self.segment_fetch_failed(e)
10178                                    }
10179                                })?
10180                        };
10181                        // §5.4: the descriptor's byteLength caps the body before
10182                        // §5.1 verifies the content address; the client discards
10183                        // the segment and re-pulls on either failure.
10184                        if bytes.len() as i64 > byte_length {
10185                            self.schedule_background_retry();
10186                            return Err(SectionError::Abort(
10187                                "sync.invalid_request".to_owned(),
10188                                "segment exceeds its byteLength".to_owned(),
10189                            ));
10190                        }
10191                        on_progress(bytes.len() as u64);
10192                        let digest = Sha256::digest(&bytes);
10193                        let expected = segment_id
10194                            .strip_prefix("sha256:")
10195                            .unwrap_or(segment_id.as_str());
10196                        if bytes_to_hex(&digest) != expected {
10197                            // §5.1: the client discards the segment and re-pulls.
10198                            self.schedule_background_retry();
10199                            return Err(SectionError::Abort(
10200                                "sync.invalid_request".to_owned(),
10201                                "segment bytes do not match the content address (§5.1)".to_owned(),
10202                            ));
10203                        }
10204                        self.progress.update(|p| p.phase = ProgressPhase::Import);
10205                        if media_type == MediaType::Sqlite {
10206                            // §5.3: a range image keeps its position in the resume
10207                            // token; a descriptor row cursor is invalid.
10208                            if row_cursor.is_some() || next_row_cursor.is_some() {
10209                                return Err(SectionError::Abort(
10210                                    "sync.invalid_request".to_owned(),
10211                                    "sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)"
10212                                        .to_owned(),
10213                                ));
10214                            }
10215                            let (pair, clear, effective) =
10216                                self.segment_pair(&unit, &echo, &seeded, &table)?;
10217                            report.segment_rows_applied += self.apply_sqlite_segment(
10218                                &pair,
10219                                &bytes,
10220                                clear,
10221                                &effective,
10222                                &unit.id,
10223                                &segment_id,
10224                                resumed.unwrap_or(0),
10225                                row_count,
10226                                as_of_commit_seq,
10227                                &scope_digest,
10228                            )?;
10229                            seeded.insert(table);
10230                        } else {
10231                            let segment = decode_rows_segment(&bytes).map_err(|e| {
10232                                SectionError::Abort(e.code.as_str().to_owned(), e.detail)
10233                            })?;
10234                            let (pair, clear, effective) =
10235                                self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
10236                            report.segment_rows_applied +=
10237                                self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
10238                            seeded.insert(segment.table);
10239                            // An image records its rows with each chunk.
10240                            self.stored(record_applied_rows(
10241                                &self.conn,
10242                                &unit.id,
10243                                &segment_id,
10244                                row_count,
10245                            ))
10246                            .map_err(storage)?;
10247                        }
10248                    }
10249                    Frame::UnitExtent { .. } => {}
10250                    _ => {
10251                        return Err(SectionError::Abort(
10252                            "sync.invalid_request".to_owned(),
10253                            "unexpected frame inside a unit section".to_owned(),
10254                        ));
10255                    }
10256                }
10257            }
10258            Ok(())
10259        })();
10260        match applied {
10261            Ok(()) => {}
10262            // The unit keeps catching up with its cursor unpersisted.
10263            Err(SectionError::Refused | SectionError::Deferred) => return Ok(false),
10264            Err(SectionError::FailClosed) => {
10265                // §5.6: the failure is unit-local; the rest of the response
10266                // still applies and the failed unit leaves the list.
10267                self.begin_observation("syncular_section_failure")
10268                    .map_err(storage)?;
10269                let failed = (|| {
10270                    let mut batch = ChangeAccumulator::default();
10271                    for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
10272                        batch.window(&base_key, &value);
10273                    }
10274                    batch.status = true;
10275                    self.stored(save_unit(
10276                        &self.conn,
10277                        &UnitRecord {
10278                            status: UnitStatus::Failed,
10279                            reason_code: Some("sync.scope_revoked".to_owned()),
10280                            restriction: None,
10281                            ..unit.clone()
10282                        },
10283                    ))?;
10284                    self.finish_observation("syncular_section_failure", batch)
10285                })();
10286                if let Err(message) = failed {
10287                    self.rollback_observation("syncular_section_failure");
10288                    return Err(storage(message));
10289                }
10290                report.failed.push(unit.id);
10291                return Ok(false);
10292            }
10293            Err(error) => return Err(error),
10294        }
10295        let Some((next_cursor, bootstrap_state)) = sub_end else {
10296            return Ok(false);
10297        };
10298        let completes = start.bootstrap && bootstrap_state.is_none();
10299        let rollback = self.capture();
10300        let counts = (
10301            report.resets.len(),
10302            report.revoked.len(),
10303            report.failed.len(),
10304        );
10305        self.begin_observation("syncular_sub_end")
10306            .map_err(storage)?;
10307        let finished = self
10308            .finish_section(start, echo, next_cursor, bootstrap_state, seeded, report)
10309            .and_then(|batch| {
10310                self.rebuild_overlay_if_dirty()?;
10311                self.finish_observation("syncular_sub_end", batch)
10312            });
10313        if let Err(message) = finished {
10314            self.rollback_observation("syncular_sub_end");
10315            self.restore(rollback);
10316            report.resets.truncate(counts.0);
10317            report.revoked.truncate(counts.1);
10318            report.failed.truncate(counts.2);
10319            return Err(storage(message));
10320        }
10321        Ok(completes)
10322    }
10323
10324    /// §5.6: the table, first-page flag and effective scopes of one segment
10325    /// of `unit`'s section. A first page outside the unit's restriction ends it.
10326    #[allow(clippy::type_complexity)]
10327    fn segment_pair(
10328        &self,
10329        unit: &UnitRecord,
10330        echo: &[EchoRecord],
10331        seeded: &BTreeSet<String>,
10332        name: &str,
10333    ) -> Result<(TableSchema, bool, Vec<(String, Vec<String>)>), SectionError> {
10334        let table = self.schema.table(name).cloned().ok_or_else(|| {
10335            SectionError::Abort(
10336                "sync.schema_mismatch".to_owned(),
10337                format!("segment table {name:?} is not in the client schema"),
10338            )
10339        })?;
10340        let effective = covers(&table, &unit.scopes)
10341            .then(|| pair_scopes(&unit.scopes, name, Some(echo)))
10342            .flatten()
10343            .ok_or_else(|| {
10344                SectionError::Abort(
10345                    "sync.invalid_request".to_owned(),
10346                    "a segment names no active pair of its unit".to_owned(),
10347                )
10348            })?;
10349        let first_page = !seeded.contains(name);
10350        // §5.6: a first page of a table outside the restriction is a whole
10351        // bootstrap from a server that predates RESTRICT; the restriction ends
10352        // before the clear runs.
10353        if first_page
10354            && unit
10355                .restriction
10356                .as_ref()
10357                .is_some_and(|restriction| !restriction.tables.iter().any(|t| t == name))
10358        {
10359            self.conn
10360                .execute(
10361                    "UPDATE _syncular_units SET restriction=NULL WHERE id=?1",
10362                    [&unit.id],
10363                )
10364                .map_err(|error| {
10365                    SectionError::Abort(
10366                        "storage.failed".to_owned(),
10367                        Self::sqlite_failure(&self.storage_failure, error),
10368                    )
10369                })?;
10370        }
10371        Ok((table, first_page, effective))
10372    }
10373
10374    /// §4.4 `SUB_END` of an active, revoked or reset section, inside the
10375    /// caller's observation: a reset discards cursor, resume token and
10376    /// first-page record and keeps the echo; a revoked pair purges by its last
10377    /// echo (§3.3); otherwise the echo replaces the persisted one, a revoked
10378    /// fenced record that turns active again re-bootstraps the unit, and a
10379    /// bootstrap section persists its pin, resume token and seeded tables.
10380    fn finish_section(
10381        &mut self,
10382        start: &SectionStart,
10383        echo: Vec<EchoRecord>,
10384        next_cursor: i64,
10385        bootstrap_state: Option<String>,
10386        seeded: BTreeSet<String>,
10387        report: &mut SyncReport,
10388    ) -> Result<ChangeAccumulator, String> {
10389        #[cfg(feature = "bench-internals")]
10390        let _phase = self.benchmark_phases.start(Phase::CursorPersist);
10391        let mut batch = ChangeAccumulator::default();
10392        // §4.4: SUB_END writes only into a unit that is still registered.
10393        let Some(unit) = self
10394            .stored(get_unit(&self.conn, &start.id))?
10395            .filter(|unit| unit.status == UnitStatus::Active)
10396        else {
10397            return Ok(batch);
10398        };
10399        for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
10400            batch.window(&base_key, &value);
10401        }
10402        if start.status == SubStatus::Reset {
10403            // §4.6: staleness, never a purge; the rows stay until the
10404            // bootstrap replaces them.
10405            report.resets.push(unit.id.clone());
10406            self.stored(save_unit(
10407                &self.conn,
10408                &UnitRecord {
10409                    reason_code: Some(start.reason_code.clone()),
10410                    cursor: Some(-1),
10411                    bootstrap_state: None,
10412                    seeded: Vec::new(),
10413                    restriction: None,
10414                    ..unit
10415                },
10416            ))?;
10417            return Ok(batch);
10418        }
10419        let revoked = start.status == SubStatus::Revoked;
10420        let mut units = None;
10421        let mut failed = false;
10422        let mut rearmed = false;
10423        for table in self.schema.tables.clone() {
10424            if !covers(&table, &unit.scopes) {
10425                continue;
10426            }
10427            let last = unit
10428                .echo
10429                .as_deref()
10430                .and_then(|last| pair_scopes(&unit.scopes, &table.name, Some(last)));
10431            let next = (!revoked)
10432                .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
10433                .flatten();
10434            // §3.3: a revoked fenced record that turns active again re-bootstraps.
10435            rearmed |= unit.echo.is_some() && last.is_none() && next.is_some();
10436            // §3.3: purge a pair the response revokes, keyed on the echo the
10437            // client persisted while the pair was active.
10438            if let (Some(last), None) = (&last, &next) {
10439                let units = match units {
10440                    Some(ref units) => units,
10441                    None => units.insert(self.stored(load_units(&self.conn))?),
10442                };
10443                let owners = unit_owners(units, &table, &unit.id);
10444                failed |= !self.purge_pair(&mut batch, &table, last, &owners)?;
10445            }
10446        }
10447        if revoked || failed {
10448            if revoked {
10449                report.revoked.push(unit.id.clone());
10450            }
10451            if failed {
10452                report.failed.push(unit.id.clone());
10453            }
10454            batch.status = true;
10455            self.stored(save_unit(
10456                &self.conn,
10457                &UnitRecord {
10458                    status: if failed {
10459                        UnitStatus::Failed
10460                    } else {
10461                        UnitStatus::Revoked
10462                    },
10463                    reason_code: Some(if failed {
10464                        "sync.scope_revoked".to_owned()
10465                    } else {
10466                        start.reason_code.clone()
10467                    }),
10468                    cursor: Some(-1),
10469                    bootstrap_state: None,
10470                    seeded: Vec::new(),
10471                    echo: None,
10472                    restriction: None,
10473                    ..unit
10474                },
10475            ))?;
10476            return Ok(batch);
10477        }
10478        let completed = start.bootstrap && !rearmed && bootstrap_state.is_none();
10479        let (cursor, bootstrap_state, seeded) = if rearmed {
10480            (Some(-1), None, Vec::new())
10481        } else if start.bootstrap {
10482            let seeded = if bootstrap_state.is_none() {
10483                Vec::new()
10484            } else {
10485                seeded.into_iter().collect()
10486            };
10487            (Some(next_cursor), bootstrap_state, seeded)
10488        } else {
10489            (
10490                unit.cursor,
10491                unit.bootstrap_state.clone(),
10492                unit.seeded.clone(),
10493            )
10494        };
10495        self.stored(save_unit(
10496            &self.conn,
10497            &UnitRecord {
10498                reason_code: None,
10499                echo: Some(echo.clone()),
10500                cursor,
10501                bootstrap_state,
10502                seeded,
10503                // §7.4.3: the restriction ends when the unit re-bootstraps or
10504                // completes its bootstrap.
10505                restriction: unit.restriction.clone().filter(|_| !rearmed && !completed),
10506                ..unit.clone()
10507            },
10508        ))?;
10509        if !completed {
10510            return Ok(batch);
10511        }
10512        // §7.1: a completed bootstrap covers acknowledged intent of its pairs
10513        // at or below its pin. The intent or the bootstrapped row proves the
10514        // pair: a patch omits its scope columns, and the base row it merged
10515        // over may be gone (a §7.4.4 reset before the ACK).
10516        for table in self.schema.tables.clone() {
10517            let Some(effective) = covers(&table, &unit.scopes)
10518                .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
10519                .flatten()
10520            else {
10521                continue;
10522            };
10523            let mut statement = self
10524                .conn
10525                .prepare("SELECT id,intent_json FROM _syncular_acked_rows WHERE tbl=?1 AND commit_seq<=?2")
10526                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10527            let rows = statement
10528                .query_map(rusqlite::params![table.name, next_cursor], |row| {
10529                    Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
10530                })
10531                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10532            let mut covered = HashSet::new();
10533            for row in rows {
10534                let (id, intent) =
10535                    row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10536                let values: Map<String, Value> =
10537                    serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
10538                let base = self.stored_row(&table, &id, true)?.map(|(row, _)| {
10539                    table
10540                        .columns
10541                        .iter()
10542                        .zip(&row)
10543                        .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
10544                        .collect()
10545                });
10546                if [Some(values), base]
10547                    .iter()
10548                    .flatten()
10549                    .any(|values| owns_local_row(&table, &effective, &[], values))
10550                {
10551                    covered.insert(id);
10552                }
10553            }
10554            drop(statement);
10555            for id in covered {
10556                self.conn
10557                    .execute(
10558                        "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3",
10559                        rusqlite::params![table.name, id, next_cursor],
10560                    )
10561                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10562                self.overlay_dirty.table(&table.name);
10563                batch.table(&table.name);
10564            }
10565        }
10566        Ok(batch)
10567    }
10568
10569    /// §3.3: purge one revoked pair inside the caller's observation: delete
10570    /// the rows matching its last effective scopes that no owner holds, drop
10571    /// the retained intent and every pending commit that provably writes into
10572    /// them, and delete now-unauthorized blob bodies. `Ok(false)` when the
10573    /// table has no local scope-column mapping (fail closed: nothing deleted).
10574    fn purge_pair(
10575        &mut self,
10576        batch: &mut ChangeAccumulator,
10577        table: &TableSchema,
10578        last: &[(String, Vec<String>)],
10579        owners: &[Vec<(String, Vec<String>)>],
10580    ) -> Result<bool, String> {
10581        if local_scope_predicate(table, last, owners).is_err() {
10582            return Ok(false);
10583        }
10584        for commit in self.drop_failed_commits(|name, values| {
10585            name == table.name && owns_local_row(table, last, owners, values)
10586        })? {
10587            batch.conflicts = true;
10588            batch.rejections = true;
10589            batch.outcomes = true;
10590            for operation in commit.ops {
10591                batch.table(&operation.table);
10592            }
10593        }
10594        if !self.purge_scope_rows(&table.name, last, owners)? {
10595            return Err("storage.failed: the revoked scope purge failed".to_owned());
10596        }
10597        self.record_scope_map(batch, &table.name, last);
10598        if self.drop_doomed_outbox(table, last, owners)? {
10599            batch.status = true;
10600            batch.rejections = true;
10601            batch.outcomes = true;
10602        }
10603        // §5.9.7 B2: revocation deletes now-unauthorized blob bodies.
10604        self.delete_unreferenced_cached_blobs()?;
10605        Ok(true)
10606    }
10607
10608    /// §4.5 client application: apply one live-section or delta `COMMIT`
10609    /// with only the changes that match the persisted echo of a receiving
10610    /// unit; every applied change then goes through the version guard.
10611    /// Returns whether any change of the frame applied.
10612    fn apply_live_commit(
10613        &mut self,
10614        receivers: &[UnitRecord],
10615        tables: &[String],
10616        changes: Vec<ssp2::model::Change>,
10617        commit_seq: i64,
10618        source: AppliedServerCommitSource,
10619    ) -> Result<bool, TransportError> {
10620        let changes: Vec<ssp2::model::Change> = changes
10621            .into_iter()
10622            .filter(|change| {
10623                // An unknown table fails loud in the apply below.
10624                let Some(table) = tables
10625                    .get(change.table_index as usize)
10626                    .and_then(|name| self.schema.table(name))
10627                else {
10628                    return true;
10629                };
10630                receivers.iter().any(|unit| {
10631                    covers(table, &unit.scopes)
10632                        && pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()).is_some_and(
10633                            |scopes| {
10634                                scopes.iter().all(|(variable, values)| {
10635                                    change
10636                                        .scopes
10637                                        .iter()
10638                                        .find(|(key, _)| key == variable)
10639                                        .is_some_and(|(_, value)| values.contains(value))
10640                                })
10641                            },
10642                        )
10643                })
10644            })
10645            .collect();
10646        if changes.is_empty() {
10647            return Ok(false);
10648        }
10649        let affected_tables = changes
10650            .iter()
10651            .filter_map(|change| tables.get(change.table_index as usize))
10652            .cloned()
10653            .collect::<BTreeSet<_>>();
10654        let previous_batches = self.change_queue.len();
10655        self.apply_commit_frame(tables, &changes, commit_seq)?;
10656        if self.change_queue.len() > previous_batches {
10657            if let Some(batch) = self.change_queue.back_mut() {
10658                batch
10659                    .applied_commits
10660                    .extend(
10661                        affected_tables
10662                            .into_iter()
10663                            .map(|table| AppliedServerCommit {
10664                                table,
10665                                commit_seq,
10666                                source,
10667                            }),
10668                    );
10669            }
10670        }
10671        Ok(true)
10672    }
10673
10674    // Both pull and realtime frames use the same durable observation boundary.
10675    fn apply_commit_frame(
10676        &mut self,
10677        tables: &[String],
10678        changes: &[ssp2::model::Change],
10679        sequence: i64,
10680    ) -> Result<(), TransportError> {
10681        #[cfg(feature = "bench-internals")]
10682        let _phase = self.benchmark_phases.start(Phase::CommitApply);
10683        let rollback = self.capture();
10684        self.coalesce_unit(changes.len())
10685            .and_then(|()| self.begin_observation("syncular_commit"))
10686            .map_err(|message| TransportError::new("storage.failed", message))?;
10687        let applied = (|| {
10688            let mut batch = ChangeAccumulator::default();
10689            self.record_commit_changes(&mut batch, tables, changes);
10690            // §7.1 chained base: a change names the version an acknowledged own
10691            // commit wrote; pending upserts chained on it move to that version.
10692            for change in changes {
10693                let Some(table) = tables.get(change.table_index as usize) else {
10694                    continue;
10695                };
10696                let acknowledged = self
10697                    .conn
10698                    .prepare_cached("SELECT op_json FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq=?3")
10699                    .and_then(|mut statement| {
10700                        statement
10701                            .query_map(rusqlite::params![table, change.row_id, sequence], |row| row.get::<_, String>(0))?
10702                            .collect::<Result<Vec<_>, _>>()
10703                    })
10704                    .map_err(|error| TransportError::new("storage.failed", Self::sqlite_failure(&self.storage_failure, error)))?
10705                    .iter()
10706                    .map(|op| serde_json::from_str::<CommitOperation>(op).map(OutboxOp::from))
10707                    .collect::<Result<Vec<_>, _>>()
10708                    .map_err(|_| TransportError::new("storage.failed", "sync.local_corrupt: invalid acknowledged operation".to_owned()))?;
10709                for index in 0..self.outbox.len() {
10710                    if !self.outbox[index]
10711                        .ops
10712                        .iter()
10713                        .any(|op| acknowledged.iter().any(|earlier| chains_on(earlier, op)))
10714                    {
10715                        continue;
10716                    }
10717                    let commit = Arc::make_mut(&mut self.outbox[index]);
10718                    for op in &mut commit.ops {
10719                        if acknowledged.iter().any(|earlier| chains_on(earlier, op)) {
10720                            op.base_version = Some(change.row_version);
10721                        }
10722                    }
10723                    let ops = serde_json::to_string(
10724                        &commit
10725                            .ops
10726                            .iter()
10727                            .map(CommitOperation::from)
10728                            .collect::<Vec<_>>(),
10729                    )
10730                    .map_err(|_| {
10731                        TransportError::new(
10732                            "storage.failed",
10733                            "sync.local_corrupt: unencodable outbox".to_owned(),
10734                        )
10735                    })?;
10736                    let id = commit.client_commit_id.clone();
10737                    self.conn
10738                        .execute(
10739                            "UPDATE _syncular_outbox SET ops_json=?1 WHERE commit_id=?2",
10740                            rusqlite::params![ops, id],
10741                        )
10742                        .map_err(|error| {
10743                            TransportError::new(
10744                                "storage.failed",
10745                                Self::sqlite_failure(&self.storage_failure, error),
10746                            )
10747                        })?;
10748                }
10749            }
10750            {
10751                let storage_failed = |error| {
10752                    TransportError::new(
10753                        "storage.failed",
10754                        Self::sqlite_failure(&self.storage_failure, error),
10755                    )
10756                };
10757                let pinned: HashSet<(&str, &str)> = self
10758                    .outbox
10759                    .iter()
10760                    .flat_map(|commit| &commit.ops)
10761                    .map(|op| (op.table.as_str(), op.row_id.as_str()))
10762                    .collect();
10763                for change in changes {
10764                    let table = tables.get(change.table_index as usize).ok_or_else(|| {
10765                        TransportError::new(
10766                            "sync.invalid_request",
10767                            "change tableIndex out of range".to_owned(),
10768                        )
10769                    })?;
10770                    if pinned.contains(&(table.as_str(), change.row_id.as_str())) {
10771                        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)")
10772                            .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
10773                            .map_err(storage_failed)?;
10774                    }
10775                    self.conn.prepare_cached("DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3")
10776                        .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
10777                        .map_err(storage_failed)?;
10778                }
10779            }
10780            self.apply_commit_changes(tables, changes)?;
10781            self.rebuild_overlay_if_dirty()
10782                .map_err(|message| TransportError::new("storage.failed", message))?;
10783            self.finish_observation("syncular_commit", batch)
10784                .map_err(|message| TransportError::new("storage.failed", message))
10785        })();
10786        if applied.is_err() {
10787            self.rollback_observation("syncular_commit");
10788            self.restore(rollback);
10789        }
10790        applied
10791    }
10792
10793    fn apply_commit_changes(
10794        &mut self,
10795        tables: &[String],
10796        changes: &[ssp2::model::Change],
10797    ) -> Result<(), TransportError> {
10798        // A clean overlay can reconcile changed primary keys independently
10799        // when their tables have no secondary unique constraints. Such a
10800        // constraint can change whether another row's write succeeds, so a
10801        // table with one and any local intent takes the table rebuild.
10802        let changed_tables: BTreeSet<&str> = changes
10803            .iter()
10804            .filter_map(|change| tables.get(change.table_index as usize))
10805            .map(String::as_str)
10806            .collect();
10807        let mut mirror_visible = !self.overlay_dirty.get();
10808        for name in &changed_tables {
10809            if mirror_visible
10810                && self
10811                    .schema
10812                    .table(name)
10813                    .is_some_and(|table| table.indexes.iter().any(|index| index.unique))
10814            {
10815                let (pending, protected) = self
10816                    .table_intent(name)
10817                    .map_err(|message| TransportError::new("storage.failed", message))?;
10818                mirror_visible = !pending && !protected;
10819            }
10820        }
10821        for change in changes {
10822            let table_name = tables.get(change.table_index as usize).ok_or_else(|| {
10823                TransportError::new(
10824                    "sync.invalid_request",
10825                    "change tableIndex out of range".to_owned(),
10826                )
10827            })?;
10828            let table = self.schema.table(table_name).ok_or_else(|| {
10829                TransportError::new(
10830                    "sync.schema_mismatch",
10831                    format!("change targets unknown table {table_name:?}"),
10832                )
10833            })?;
10834            let landed = match change.op {
10835                Op::Upsert => {
10836                    let payload = change.row.as_ref().ok_or_else(|| {
10837                        TransportError::new(
10838                            "sync.invalid_request",
10839                            "upsert change without row payload".to_owned(),
10840                        )
10841                    })?;
10842                    // §5.11: decrypt encrypted columns on apply, or seal the row.
10843                    let (row, sealed) = {
10844                        #[cfg(feature = "bench-internals")]
10845                        let _phase = self.benchmark_phases.start(Phase::RowDecode);
10846                        // §5.11: a decrypt failure keeps its own identity.
10847                        decode_row_bytes(table, payload, &self.encryption)?
10848                    };
10849                    let table_name = table.name.clone();
10850                    // §4.5 version guard: only a newer upsert lands.
10851                    let landed = self
10852                        .write_base_row(&table_name, &row, change.row_version, sealed.as_ref())
10853                        .map_err(|m| TransportError::new("sync.invalid_request", m))?;
10854                    if mirror_visible && landed {
10855                        self.write_row(
10856                            &visible_table(&table_name),
10857                            &table_name,
10858                            &row,
10859                            change.row_version,
10860                            sealed.as_ref(),
10861                        )
10862                        .map_err(|m| TransportError::new("sync.invalid_request", m))?;
10863                    }
10864                    landed
10865                }
10866                // §4.5 version guard: a delete at or below the local version
10867                // is skipped, a delete of an absent row is a no-op.
10868                Op::Delete => self
10869                    .delete_base_row(table_name, &change.row_id, change.row_version)
10870                    .map_err(|m| TransportError::new("sync.invalid_request", m))?,
10871            };
10872            // The change dropped the row's acknowledged intent either way
10873            // (§7.1), so the overlay of a skipped change rebuilds from the
10874            // unchanged base.
10875            self.overlay_dirty.table(table_name);
10876            if mirror_visible && !(landed && change.op == Op::Upsert) {
10877                let predicate = row_id_predicate(table);
10878                let visible = visible_table(table_name);
10879                let mut statements = vec![format!("DELETE FROM {visible} WHERE {predicate}")];
10880                if !landed {
10881                    statements.push(format!(
10882                        "INSERT INTO {visible} SELECT * FROM {} WHERE {predicate}",
10883                        base_table(table_name)
10884                    ));
10885                }
10886                for statement in &statements {
10887                    self.conn
10888                        .prepare_cached(statement)
10889                        .and_then(|mut statement| {
10890                            statement.execute(rusqlite::params![change.row_id])
10891                        })
10892                        .map_err(|error| {
10893                            TransportError::new("sync.invalid_request", error.to_string())
10894                        })?;
10895                }
10896            }
10897        }
10898        if mirror_visible {
10899            let changed_rows: HashSet<(&str, &str)> = changes
10900                .iter()
10901                .map(|change| {
10902                    (
10903                        tables[change.table_index as usize].as_str(),
10904                        change.row_id.as_str(),
10905                    )
10906                })
10907                .collect();
10908            self.replay_overlay(&changed_tables, Some(&changed_rows))
10909                .map_err(|message| TransportError::new("storage.failed", message))?;
10910            self.overlay_dirty.set(false);
10911        }
10912        Ok(())
10913    }
10914
10915    /// §5.6 segment application: validate against the generated schema,
10916    /// clear the pair's scope on the table's first page (fail closed
10917    /// without a mapping), then upsert each row with its segment-carried
10918    /// server version under the §4.5 version guard (§5.2).
10919    fn apply_segment(
10920        &mut self,
10921        table: &TableSchema,
10922        segment: &RowsSegment,
10923        first_page: bool,
10924        effective: &[(String, Vec<String>)],
10925        unit_id: &str,
10926    ) -> Result<u32, SectionError> {
10927        // §5.2: the column table validates against the generated schema —
10928        // order, names, types, nullability; mismatch is fatal. §5.11: the
10929        // server sends the WIRE types (bytes for an encrypted column), so
10930        // validate against wire_columns.
10931        let column = if segment.columns.len() != table.wire_columns.len() {
10932            Some(Value::from("count"))
10933        } else {
10934            segment
10935                .columns
10936                .iter()
10937                .zip(table.wire_columns.iter())
10938                .position(|(a, b)| a.name != b.name || a.ty != b.ty || a.nullable != b.nullable)
10939                .map(Value::from)
10940        };
10941        if segment.table != table.name
10942            || segment.schema_version != self.schema.version
10943            || column.is_some()
10944        {
10945            let mut details = Map::new();
10946            details.insert("table".to_owned(), Value::from(table.name.as_str()));
10947            if let Some(column) = column {
10948                details.insert("column".to_owned(), column);
10949            }
10950            return Err(SectionError::Transport(TransportError {
10951                code: "sync.schema_mismatch".to_owned(),
10952                message: "rows segment columns do not match the generated schema (§5.2)".to_owned(),
10953                details: Some(Value::Object(details)),
10954            }));
10955        }
10956        let mut applied = 0u32;
10957        let (mut write, mut commit) = (std::time::Duration::ZERO, std::time::Duration::ZERO);
10958        let empty = Vec::new();
10959        let blocks = if segment.blocks.is_empty() {
10960            std::slice::from_ref(&empty)
10961        } else {
10962            &segment.blocks
10963        };
10964        for (index, block) in blocks.iter().enumerate() {
10965            let clear = first_page && index == 0;
10966            if !clear && block.is_empty() {
10967                continue;
10968            }
10969            let rollback = self.capture();
10970            let (pending, protected) = self
10971                .table_intent(&table.name)
10972                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10973            let reconcile_pending =
10974                !protected && pending && table.indexes.iter().any(|index| index.unique);
10975            let mirror_visible = !protected && !reconcile_pending;
10976            self.coalesce_unit(block.len())
10977                .and_then(|()| self.begin_observation("syncular_segment_block"))
10978                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10979            let started = std::time::Instant::now();
10980            let outcome = (|| {
10981                self.rebuild_overlay_if_dirty()
10982                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10983                let mut changed_keys = Vec::new();
10984                let mut batch = ChangeAccumulator::default();
10985                if clear && self.clear_scope(table, effective, unit_id)? || !block.is_empty() {
10986                    batch.table(&table.name);
10987                }
10988                for (row_index, row) in block.iter().enumerate() {
10989                    let decrypted;
10990                    let mut sealed = None;
10991                    let values = if table.has_encrypted_columns() {
10992                        let mut values = row.values.clone();
10993                        sealed = crate::values::decrypt_segment_row(
10994                            table,
10995                            &mut values,
10996                            &self.encryption,
10997                        )
10998                        .map_err(SectionError::Transport)?;
10999                        decrypted = values;
11000                        &decrypted
11001                    } else {
11002                        &row.values
11003                    };
11004                    if !self
11005                        .write_base_row(&table.name, values, row.server_version, sealed.as_ref())
11006                        .map_err(|message| {
11007                            SectionError::Abort("sync.invalid_request".into(), message)
11008                        })?
11009                    {
11010                        continue;
11011                    }
11012                    if reconcile_pending {
11013                        changed_keys.push(
11014                            owned_sql_value(RowParam::Cell(&values[table.pk_index])).map_err(
11015                                |message| SectionError::Abort("storage.failed".into(), message),
11016                            )?,
11017                        );
11018                    }
11019                    if mirror_visible {
11020                        self.write_row(
11021                            &visible_table(&table.name),
11022                            &table.name,
11023                            values,
11024                            row.server_version,
11025                            sealed.as_ref(),
11026                        )
11027                        .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11028                    }
11029                    let processed = u64::from(applied) + row_index as u64 + 1;
11030                    if processed.is_multiple_of(1024) {
11031                        self.progress.update(|p| p.rows_processed = processed);
11032                    }
11033                }
11034                self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
11035                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11036                let written = std::time::Instant::now();
11037                self.finish_observation("syncular_segment_block", batch)
11038                    .map(|()| written)
11039                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))
11040            })();
11041            let written = match outcome {
11042                Ok(written) => written,
11043                Err(error) => {
11044                    self.rollback_observation("syncular_segment_block");
11045                    self.restore(rollback);
11046                    return Err(error);
11047                }
11048            };
11049            // §7.7: a payload reports its import cost.
11050            write += written - started;
11051            commit += written.elapsed();
11052            applied += block.len() as u32;
11053            self.progress.update(|p| {
11054                p.rows_processed = u64::from(applied);
11055                p.import_write_ms = u64::try_from(write.as_millis()).ok();
11056                p.import_commit_ms = u64::try_from(commit.as_millis()).ok();
11057            });
11058            std::thread::yield_now();
11059        }
11060        self.progress
11061            .update(|p| p.rows_processed = u64::from(applied));
11062        Ok(applied)
11063    }
11064
11065    /// §5.3 sqlite-image application: validate the in-file metadata
11066    /// against the descriptor, validate column names/order against the
11067    /// generated schema, run the §5.6 first-page clear when fresh, then
11068    /// replace-or-upsert every image row with its `_syncular_version`.
11069    /// Mechanics: the image lands in a temp file read through a second
11070    /// rusqlite connection, equivalent to ATTACH + INSERT…SELECT.
11071    /// Each image chunk commits its writes and revision before readers continue.
11072    #[allow(clippy::too_many_arguments)]
11073    fn apply_sqlite_segment(
11074        &mut self,
11075        table: &TableSchema,
11076        bytes: &[u8],
11077        first_page: bool,
11078        effective: &[(String, Vec<String>)],
11079        unit_id: &str,
11080        segment_id: &str,
11081        resumed: i64,
11082        row_count: i64,
11083        as_of_commit_seq: i64,
11084        scope_digest: &str,
11085    ) -> Result<u32, SectionError> {
11086        let invalid = |detail: &str| {
11087            SectionError::Abort(
11088                "sync.invalid_request".to_owned(),
11089                format!("sqlite segment rejected: {detail} (§5.3)"),
11090            )
11091        };
11092        // §5.11: an image bypasses the decrypt seam, so a server cannot serve
11093        // one for a table with encrypted columns.
11094        if table.has_encrypted_columns() {
11095            return Err(invalid("table has encrypted columns"));
11096        }
11097
11098        // The image lands beside the replica so it shares the replica's
11099        // directory permissions and volume; an in-memory replica has no
11100        // directory and uses the system temp dir. The file is owner-only.
11101        let directory = self
11102            .previous_version_replica_path()
11103            .and_then(|replica| std::path::Path::new(&replica).parent().map(Into::into))
11104            .unwrap_or_else(std::env::temp_dir);
11105        let path = directory.join(format!(".syncular-image-{}.tmp", uuid::Uuid::new_v4()));
11106        let outcome = (|| {
11107            let mut options = std::fs::OpenOptions::new();
11108            options.write(true).create_new(true);
11109            #[cfg(unix)]
11110            std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);
11111            std::io::Write::write_all(
11112                &mut options
11113                    .open(&path)
11114                    .map_err(|_| invalid("image temp file write failed"))?,
11115                bytes,
11116            )
11117            .map_err(|_| invalid("image temp file write failed"))?;
11118            let img = rusqlite::Connection::open_with_flags(
11119                &path,
11120                rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
11121            )
11122            .map_err(|_| invalid("bytes do not open as a SQLite database"))?;
11123            self.apply_sqlite_image(
11124                &img,
11125                table,
11126                first_page,
11127                effective,
11128                unit_id,
11129                segment_id,
11130                resumed,
11131                row_count,
11132                as_of_commit_seq,
11133                scope_digest,
11134            )
11135        })();
11136        let _ = std::fs::remove_file(&path);
11137        outcome
11138    }
11139
11140    #[allow(clippy::too_many_arguments)]
11141    fn apply_sqlite_image(
11142        &mut self,
11143        img: &rusqlite::Connection,
11144        table: &crate::schema::TableSchema,
11145        first_fresh_page: bool,
11146        effective: &[(String, Vec<String>)],
11147        unit_id: &str,
11148        segment_id: &str,
11149        resumed: i64,
11150        row_count: i64,
11151        as_of_commit_seq: i64,
11152        scope_digest: &str,
11153    ) -> Result<u32, SectionError> {
11154        let invalid = |detail: String| {
11155            SectionError::Abort(
11156                "sync.invalid_request".to_owned(),
11157                format!("sqlite segment rejected: {detail} (§5.3)"),
11158            )
11159        };
11160
11161        // 1. Metadata vs descriptor + client state (§5.3 rule 2; exactly
11162        //    one row).
11163        type MetaRow = (i64, String, i64, i64, String, i64, i64);
11164        let meta: MetaRow = img
11165            .query_row(
11166                "SELECT format, \"table\", \"schemaVersion\", \"asOfCommitSeq\",
11167                        \"scopeDigest\", \"rowCount\",
11168                        (SELECT count(*) FROM _syncular_segment)
11169                 FROM _syncular_segment",
11170                [],
11171                |row| {
11172                    Ok((
11173                        row.get(0)?,
11174                        row.get(1)?,
11175                        row.get(2)?,
11176                        row.get(3)?,
11177                        row.get(4)?,
11178                        row.get(5)?,
11179                        row.get(6)?,
11180                    ))
11181                },
11182            )
11183            .map_err(|_| invalid("missing or unreadable _syncular_segment metadata".to_owned()))?;
11184        let (format, meta_table, schema_version, pin, digest, meta_rows, meta_count) = meta;
11185        if meta_count != 1 {
11186            return Err(invalid(format!(
11187                "_syncular_segment must contain exactly one row, found {meta_count}"
11188            )));
11189        }
11190        if format != 1 {
11191            return Err(invalid(format!("format {format}")));
11192        }
11193        if meta_table != table.name {
11194            return Err(invalid(format!("image table {meta_table:?}")));
11195        }
11196        if schema_version != i64::from(self.schema.version) {
11197            return Err(invalid(format!("schemaVersion {schema_version}")));
11198        }
11199        if pin != as_of_commit_seq {
11200            return Err(invalid(format!("asOfCommitSeq {pin}")));
11201        }
11202        if digest != scope_digest {
11203            return Err(invalid("scopeDigest mismatch".to_owned()));
11204        }
11205        if meta_rows != row_count {
11206            return Err(invalid(format!("rowCount {meta_rows}")));
11207        }
11208
11209        // 2. Column names and order vs the generated schema (§5.3 rule 3).
11210        let mut names: Vec<String> = Vec::new();
11211        let mut primary_keys: Vec<String> = Vec::new();
11212        {
11213            let mut stmt = img
11214                .prepare(&format!("PRAGMA table_info({})", quote_ident(&table.name)))
11215                .map_err(|_| invalid("image data table missing".to_owned()))?;
11216            let mut rows = stmt
11217                .query([])
11218                .map_err(|_| invalid("image data table unreadable".to_owned()))?;
11219            while let Some(row) = rows
11220                .next()
11221                .map_err(|_| invalid("image data table unreadable".to_owned()))?
11222            {
11223                if row
11224                    .get::<_, i64>(5)
11225                    .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?
11226                    > 0
11227                {
11228                    primary_keys.push(row.get(1).map_err(|error| {
11229                        invalid(Self::sqlite_failure(&self.storage_failure, error))
11230                    })?);
11231                }
11232                names.push(
11233                    row.get::<_, String>(1)
11234                        .map_err(|_| invalid("image data table unreadable".to_owned()))?,
11235                );
11236            }
11237        }
11238        let mut expected: Vec<&str> = table.columns.iter().map(|c| c.name.as_str()).collect();
11239        expected.push("_syncular_version");
11240        if names.len() != expected.len() || names.iter().zip(expected.iter()).any(|(a, b)| a != b) {
11241            return Err(SectionError::Transport(TransportError {
11242                code: "sync.schema_mismatch".to_owned(),
11243                message: "sqlite segment columns do not match the generated schema (§5.3)"
11244                    .to_owned(),
11245                details: Some(serde_json::json!({ "table": table.name })),
11246            }));
11247        }
11248
11249        if primary_keys != vec![table.primary_key.clone()] {
11250            return Err(invalid(
11251                "image primary key does not match generated schema".into(),
11252            ));
11253        }
11254        let actual_count: i64 = img
11255            .query_row(
11256                &format!("SELECT count(*) FROM {}", quote_ident(&table.name)),
11257                [],
11258                |row| row.get(0),
11259            )
11260            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
11261        if actual_count != row_count {
11262            return Err(invalid("image row count does not match descriptor".into()));
11263        }
11264        let insert = self.insert_row_sql(&base_table(&table.name), table);
11265        let visible_insert = self.insert_row_sql(&visible_table(&table.name), table);
11266        let column_list = names
11267            .iter()
11268            .map(|n| quote_ident(n))
11269            .collect::<Vec<_>>()
11270            .join(", ");
11271        // §5.6: an earlier attempt at this position committed the first
11272        // `resumed` rows in primary-key order; the content address pins them.
11273        let mut stmt = img
11274            .prepare(&format!(
11275                "SELECT {column_list} FROM {} ORDER BY {} LIMIT -1 OFFSET ?1",
11276                quote_ident(&table.name),
11277                quote_ident(&table.primary_key)
11278            ))
11279            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
11280        let mut rows = stmt
11281            .query([resumed])
11282            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
11283        let resumed = u32::try_from(resumed)
11284            .ok()
11285            .filter(|rows| i64::from(*rows) <= actual_count)
11286            .ok_or_else(|| invalid("applied-segment record exceeds the image".into()))?;
11287        let mut applied = resumed;
11288        let mut limit = if first_fresh_page {
11289            1024
11290        } else {
11291            self.image_chunk_rows
11292                .get(&table.name)
11293                .copied()
11294                .unwrap_or(1024)
11295        };
11296        let (mut write, mut commit) = (std::time::Duration::ZERO, std::time::Duration::ZERO);
11297        loop {
11298            let clear = applied == 0 && first_fresh_page;
11299            let rollback = self.capture();
11300            let (pending, protected) = self
11301                .table_intent(&table.name)
11302                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11303            let reconcile_pending =
11304                !protected && pending && table.indexes.iter().any(|index| index.unique);
11305            let mirror_visible = !protected && !reconcile_pending;
11306            // §5.3: a table's first chunk holds 1,024 rows; a later range image
11307            // starts at the size its previous range reached. A later chunk holds at
11308            // least 1,024 rows, at most twice the rows of the one before, at
11309            // most 65,536, and at most the rows the one before applied per
11310            // 250 ms from its start to its COMMIT; a chunk that replays local
11311            // writes holds at most 1,024.
11312            let chunk = if pending || protected {
11313                limit.min(1024)
11314            } else {
11315                limit
11316            };
11317            self.coalesce_unit(chunk as usize)
11318                .and_then(|()| self.begin_observation("syncular_image_chunk"))
11319                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11320            let started = std::time::Instant::now();
11321            let result = (|| {
11322                self.rebuild_overlay_if_dirty()
11323                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11324                let mut changed_keys = Vec::new();
11325                let mut batch = ChangeAccumulator::default();
11326                if clear && self.clear_scope(table, effective, unit_id)? {
11327                    batch.table(&table.name);
11328                }
11329                let mut processed = 0u32;
11330                {
11331                    let mut ins = self.conn.prepare_cached(&insert).map_err(|error| {
11332                        invalid(Self::sqlite_failure(&self.storage_failure, error))
11333                    })?;
11334                    let mut mirror = if mirror_visible {
11335                        Some(self.conn.prepare_cached(&visible_insert).map_err(|error| {
11336                            invalid(Self::sqlite_failure(&self.storage_failure, error))
11337                        })?)
11338                    } else {
11339                        None
11340                    };
11341                    for _ in 0..chunk {
11342                        let Some(row) = rows.next().map_err(|error| {
11343                            invalid(Self::sqlite_failure(&self.storage_failure, error))
11344                        })?
11345                        else {
11346                            break;
11347                        };
11348                        for (i, column) in table.columns.iter().enumerate() {
11349                            let cell = row.get_ref(i).map_err(|error| {
11350                                invalid(Self::sqlite_failure(&self.storage_failure, error))
11351                            })?;
11352                            let param = image_cell_param(column, cell).map_err(invalid)?;
11353                            ins.raw_bind_parameter(i + 1, &param).map_err(|error| {
11354                                invalid(Self::sqlite_failure(&self.storage_failure, error))
11355                            })?;
11356                            if let Some(mirror) = &mut mirror {
11357                                mirror.raw_bind_parameter(i + 1, &param).map_err(|error| {
11358                                    invalid(Self::sqlite_failure(&self.storage_failure, error))
11359                                })?;
11360                            }
11361                        }
11362                        let version_index = table.columns.len();
11363                        let version: i64 = row.get(version_index).map_err(|error| {
11364                            invalid(Self::sqlite_failure(&self.storage_failure, error))
11365                        })?;
11366                        if version < 1 {
11367                            return Err(invalid("image row version must be positive".into()));
11368                        }
11369                        ins.raw_bind_parameter(version_index + 1, version)
11370                            .map_err(|error| {
11371                                invalid(Self::sqlite_failure(&self.storage_failure, error))
11372                            })?;
11373                        // §4.5 version guard: the base upsert decides.
11374                        let landed = ins.raw_execute().map_err(|error| {
11375                            invalid(Self::sqlite_failure(&self.storage_failure, error))
11376                        })? > 0;
11377                        processed += 1;
11378                        if processed.is_multiple_of(1024) && processed < chunk {
11379                            self.progress
11380                                .update(|p| p.rows_processed = u64::from(applied + processed));
11381                        }
11382                        if !landed {
11383                            continue;
11384                        }
11385                        if let Some(mirror) = &mut mirror {
11386                            mirror
11387                                .raw_bind_parameter(version_index + 1, version)
11388                                .map_err(|error| {
11389                                    invalid(Self::sqlite_failure(&self.storage_failure, error))
11390                                })?;
11391                            mirror.raw_execute().map_err(|error| {
11392                                invalid(Self::sqlite_failure(&self.storage_failure, error))
11393                            })?;
11394                        }
11395                        if reconcile_pending {
11396                            changed_keys.push(row.get::<_, SqlValue>(table.pk_index).map_err(
11397                                |error| invalid(Self::sqlite_failure(&self.storage_failure, error)),
11398                            )?);
11399                        }
11400                    }
11401                }
11402                if processed > 0 {
11403                    batch.table(&table.name);
11404                    self.overlay_dirty.table(&table.name);
11405                }
11406                self.stored(record_applied_rows(
11407                    &self.conn,
11408                    unit_id,
11409                    segment_id,
11410                    i64::from(applied + processed),
11411                ))
11412                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11413                self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
11414                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11415                let written = std::time::Instant::now();
11416                self.finish_observation("syncular_image_chunk", batch)
11417                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11418                Ok((processed, written))
11419            })();
11420            let (processed, written) = match result {
11421                Ok(done) => done,
11422                Err(error) => {
11423                    self.rollback_observation("syncular_image_chunk");
11424                    self.restore(rollback);
11425                    return Err(error);
11426                }
11427            };
11428            // The chunk commits before the yield, also inside a coalesced apply.
11429            let coalesced = self.coalesced.is_some();
11430            if coalesced {
11431                self.commit_coalesced_apply()
11432                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11433            }
11434            write += written - started;
11435            commit += written.elapsed();
11436            applied += processed;
11437            let last = processed < chunk || i64::from(applied) == actual_count;
11438            // A file replica's WAL keeps its high-water size until truncated.
11439            if last && self.conn.is_autocommit() {
11440                self.conn
11441                    .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
11442                    .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
11443            }
11444            if coalesced {
11445                self.begin_coalesced_apply()
11446                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11447            }
11448            self.progress.update(|p| {
11449                p.rows_processed = u64::from(applied);
11450                p.import_write_ms = u64::try_from(write.as_millis()).ok();
11451                p.import_commit_ms = u64::try_from(commit.as_millis()).ok();
11452            });
11453            let duration = started.elapsed().as_secs_f64() * 1000.0;
11454            #[cfg(test)]
11455            let duration = self.image_chunk_ms.get().unwrap_or(duration);
11456            std::thread::yield_now();
11457            if last {
11458                break;
11459            }
11460            // A zero duration saturates the cast and leaves the doubling.
11461            limit = (processed * 2)
11462                .min(65_536)
11463                .min((f64::from(processed) * 250.0 / duration) as u32)
11464                .max(1024);
11465            self.image_chunk_rows.insert(table.name.clone(), limit);
11466        }
11467        if i64::from(applied) != actual_count {
11468            return Err(invalid(format!(
11469                "image yielded {applied} rows, expected {actual_count}"
11470            )));
11471        }
11472        Ok(applied - resumed)
11473    }
11474
11475    /// §7.1 keyed reconciliation of the rows `drained` commits touch: restore
11476    /// them from the base and replay their remaining intent. A table with a
11477    /// secondary unique index restores and replays every row with intent,
11478    /// since one row's value can admit or defer another row's write.
11479    fn reconcile_rows(&self, drained: &[Arc<OutboxCommit>]) -> Result<(), String> {
11480        let names: BTreeSet<&str> = drained
11481            .iter()
11482            .flat_map(|commit| &commit.ops)
11483            .map(|op| op.table.as_str())
11484            .collect();
11485        for name in names {
11486            let Some(table) = self.schema.table(name) else {
11487                continue;
11488            };
11489            let ops = drained.iter().flat_map(|commit| &commit.ops);
11490            let tables = BTreeSet::from([name]);
11491            let rows: HashSet<_> = ops
11492                .clone()
11493                .map(|op| (op.table.as_str(), op.row_id.as_str()))
11494                .collect();
11495            let unique = table.indexes.iter().any(|index| index.unique);
11496            let acknowledged = if unique {
11497                self.acknowledged_operations(None, Some(&tables))?
11498            } else {
11499                Vec::new()
11500            };
11501            let peers = acknowledged
11502                .iter()
11503                .chain(
11504                    self.failed_commits
11505                        .iter()
11506                        .flat_map(|(commit, _)| &commit.ops),
11507                )
11508                .chain(self.outbox.iter().flat_map(|commit| &commit.ops))
11509                .filter(|_| unique);
11510            self.restore_base_rows(table, &mut Vec::new(), peers.chain(ops.clone()))?;
11511            self.replay_overlay(&tables, (!unique).then_some(&rows))?;
11512        }
11513        Ok(())
11514    }
11515
11516    /// Whether `table` has pending outbox intent, and whether it has protected
11517    /// (acknowledged or retained failed) intent.
11518    fn table_intent(&self, table: &str) -> Result<(bool, bool), String> {
11519        let touches = |op: &OutboxOp| op.table == table;
11520        Ok((
11521            self.outbox
11522                .iter()
11523                .flat_map(|commit| &commit.ops)
11524                .any(touches),
11525            self.failed_commits
11526                .iter()
11527                .flat_map(|(commit, _)| &commit.ops)
11528                .any(touches)
11529                || self
11530                    .conn
11531                    .query_row(
11532                        "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows WHERE tbl=?1)",
11533                        [table],
11534                        |row| row.get(0),
11535                    )
11536                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
11537        ))
11538    }
11539
11540    /// §7.1 reconciliation after an import block or chunk. Keyed replay covers
11541    /// only pending intent, so a table with protected intent rebuilds; a
11542    /// `restore` restores the imported `keys` and every pending row first.
11543    fn reconcile_import(
11544        &mut self,
11545        table: &TableSchema,
11546        keys: &mut Vec<SqlValue>,
11547        protected: bool,
11548        restore: bool,
11549    ) -> Result<(), String> {
11550        if protected {
11551            return self.rebuild_overlay_if_dirty();
11552        }
11553        let pending = self.outbox.iter().flat_map(|commit| &commit.ops);
11554        if restore {
11555            self.restore_base_rows(table, keys, pending.clone())?;
11556        }
11557        self.apply_outbox_ops(pending.filter(|op| op.table == table.name))?;
11558        self.overlay_dirty.set(false);
11559        Ok(())
11560    }
11561
11562    /// Restore the visible rows of `keys` and of the rows `ops` touch in
11563    /// `table` from the base before the caller replays their intent. The
11564    /// caller owns the transaction and publishes its revision after replay.
11565    fn restore_base_rows<'a>(
11566        &self,
11567        table: &TableSchema,
11568        keys: &mut Vec<SqlValue>,
11569        ops: impl IntoIterator<Item = &'a OutboxOp>,
11570    ) -> Result<(), String> {
11571        let visible = visible_table(&table.name);
11572        let base = base_table(&table.name);
11573        let pk = quote_ident(&table.primary_key);
11574        let predicate = row_id_predicate(table);
11575        let mut lookup = self.conn.prepare_cached(&format!(
11576            "SELECT {pk} FROM {base} WHERE {predicate} UNION SELECT {pk} FROM {visible} WHERE {predicate}"
11577        )).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11578        let mut deleted = HashSet::new();
11579        for op in ops.into_iter().filter(|op| op.table == table.name) {
11580            if op.upsert {
11581                if let Some(values) = &op.values {
11582                    let key = json_to_column_value(
11583                        &table.columns[table.pk_index],
11584                        values.get(&table.primary_key),
11585                    )?;
11586                    keys.push(owned_sql_value(RowParam::Cell(&key))?);
11587                }
11588            } else if deleted.insert(&op.row_id) {
11589                keys.extend(
11590                    lookup
11591                        .query_map([&op.row_id], |row| row.get::<_, SqlValue>(0))
11592                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11593                        .collect::<Result<Vec<_>, _>>()
11594                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
11595                );
11596            }
11597        }
11598        // Delete the complete affected set before restoring any base value, so
11599        // old optimistic unique values cannot collide with the new server rows.
11600        for chunk in keys.chunks(400) {
11601            let holes = vec!["?"; chunk.len()].join(",");
11602            self.conn
11603                .prepare_cached(&format!("DELETE FROM {visible} WHERE {pk} IN ({holes})"))
11604                .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
11605                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11606        }
11607        let updates = table
11608            .columns
11609            .iter()
11610            .map(|column| column.name.as_str())
11611            .chain(std::iter::once("_syncular_version"))
11612            .chain(table.sealed_columns().iter().copied())
11613            .filter(|name| *name != table.primary_key)
11614            .map(|name| {
11615                let name = quote_ident(name);
11616                format!("{name}=excluded.{name}")
11617            })
11618            .collect::<Vec<_>>()
11619            .join(",");
11620        for chunk in keys.chunks(400) {
11621            let holes = vec!["?"; chunk.len()].join(",");
11622            self.conn.prepare_cached(&format!("INSERT INTO {visible} SELECT * FROM {base} WHERE {pk} IN ({holes}) ON CONFLICT ({pk}) DO UPDATE SET {updates}"))
11623                .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
11624                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11625        }
11626        Ok(())
11627    }
11628
11629    // -- application-authorized local purge ---------------------------------------
11630
11631    fn compile_local_data_purge(
11632        &self,
11633        input: &LocalDataPurgeInput,
11634    ) -> Result<(Vec<CompiledLocalDataPurgeTarget>, String), String> {
11635        let invalid = |message: String| format!("sync.invalid_request: {message}");
11636        if input.purge_id.is_empty()
11637            || input.purge_id.len() > 128
11638            || !is_local_operation_code_like(&input.purge_id)
11639        {
11640            return Err(invalid(
11641                "local purge purgeId must be a 1–128 character code-like identifier".to_owned(),
11642            ));
11643        }
11644        if input.targets.is_empty() || input.targets.len() > MAX_LOCAL_PURGE_TARGETS {
11645            return Err(invalid(format!(
11646                "local purge needs between 1 and {MAX_LOCAL_PURGE_TARGETS} targets"
11647            )));
11648        }
11649
11650        let mut deduplicated: BTreeMap<
11651            String,
11652            (CompiledLocalDataPurgeTarget, LocalDataPurgeTarget),
11653        > = BTreeMap::new();
11654        for target in &input.targets {
11655            let table = self.schema.table(&target.table).ok_or_else(|| {
11656                invalid(format!(
11657                    "local purge names unknown table {:?}",
11658                    target.table
11659                ))
11660            })?;
11661            if target.selectors.is_empty() || target.selectors.len() > MAX_LOCAL_PURGE_SELECTORS {
11662                return Err(invalid(format!(
11663                    "local purge target {:?} needs between 1 and {MAX_LOCAL_PURGE_SELECTORS} selectors",
11664                    target.table
11665                )));
11666            }
11667            let mut selectors = Vec::with_capacity(target.selectors.len());
11668            let mut canonical_selectors = BTreeMap::new();
11669            for (column_name, raw_values) in &target.selectors {
11670                let Some((column_index, column)) = table
11671                    .columns
11672                    .iter()
11673                    .enumerate()
11674                    .find(|(_, column)| column.name == *column_name)
11675                else {
11676                    return Err(invalid(format!(
11677                        "local purge target {:?} names unknown column {:?}",
11678                        target.table, column_name
11679                    )));
11680                };
11681                let encrypted = table
11682                    .encrypted_columns
11683                    .iter()
11684                    .any(|candidate| candidate.index == column_index);
11685                if column.ty != ColumnType::String || encrypted {
11686                    return Err(invalid(format!(
11687                        "local purge selector {:?}.{:?} must be a plaintext string column",
11688                        target.table, column_name
11689                    )));
11690                }
11691                if raw_values.is_empty() || raw_values.len() > MAX_LOCAL_PURGE_VALUES {
11692                    return Err(invalid(format!(
11693                        "local purge selector {:?}.{:?} needs between 1 and {MAX_LOCAL_PURGE_VALUES} values",
11694                        target.table, column_name
11695                    )));
11696                }
11697                let mut values = raw_values.clone();
11698                values.sort();
11699                values.dedup();
11700                if values.iter().any(|value| {
11701                    value.is_empty()
11702                        || value.len() > MAX_LOCAL_PURGE_VALUE_LENGTH
11703                        || !is_local_operation_code_like(value)
11704                }) {
11705                    return Err(invalid(format!(
11706                        "local purge selector values must be 1–{MAX_LOCAL_PURGE_VALUE_LENGTH} character code-like identifiers"
11707                    )));
11708                }
11709                selectors.push((column_name.clone(), values.clone()));
11710                canonical_selectors.insert(column_name.clone(), values);
11711            }
11712            let canonical = LocalDataPurgeTarget {
11713                table: target.table.clone(),
11714                selectors: canonical_selectors,
11715            };
11716            let key = serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
11717            deduplicated.insert(
11718                key,
11719                (
11720                    CompiledLocalDataPurgeTarget {
11721                        table: target.table.clone(),
11722                        selectors,
11723                    },
11724                    canonical,
11725                ),
11726            );
11727        }
11728        let targets = deduplicated
11729            .values()
11730            .map(|(compiled, _)| compiled.clone())
11731            .collect::<Vec<_>>();
11732        let canonical = deduplicated
11733            .values()
11734            .map(|(_, target)| target.clone())
11735            .collect::<Vec<_>>();
11736        let canonical_plan =
11737            serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
11738        Ok((targets, canonical_plan))
11739    }
11740
11741    fn local_purge_base_row_ids(
11742        &self,
11743        targets: &[CompiledLocalDataPurgeTarget],
11744    ) -> Result<BTreeMap<String, BTreeSet<String>>, String> {
11745        let mut by_table: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
11746        for target in targets {
11747            let table = self
11748                .schema
11749                .table(&target.table)
11750                .ok_or_else(|| format!("sync.invalid_request: unknown table {:?}", target.table))?;
11751            let mut clauses = Vec::with_capacity(target.selectors.len());
11752            let mut params = Vec::new();
11753            for (column, values) in &target.selectors {
11754                clauses.push(format!(
11755                    "{} IN ({})",
11756                    quote_ident(column),
11757                    values.iter().map(|_| "?").collect::<Vec<_>>().join(", ")
11758                ));
11759                params.extend(values.iter().cloned().map(SqlValue::Text));
11760            }
11761            let sql = format!(
11762                "SELECT CAST({} AS TEXT) FROM {} WHERE {}",
11763                quote_ident(&table.primary_key),
11764                base_table(&target.table),
11765                clauses.join(" AND ")
11766            );
11767            let mut statement = self
11768                .conn
11769                .prepare(&sql)
11770                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11771            let rows = statement
11772                .query_map(rusqlite::params_from_iter(params), |row| {
11773                    let value = sql_ref_to_json(&table.columns[table.pk_index], row.get_ref(0)?);
11774                    render_row_id_json(Some(&value))
11775                        .map_err(|message| rusqlite::Error::ToSqlConversionFailure(message.into()))
11776                })
11777                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11778            let ids = by_table.entry(target.table.clone()).or_default();
11779            for row in rows {
11780                ids.insert(
11781                    row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
11782                );
11783            }
11784        }
11785        Ok(by_table)
11786    }
11787
11788    fn local_purge_values_match(
11789        target: &CompiledLocalDataPurgeTarget,
11790        values: &Map<String, Value>,
11791    ) -> bool {
11792        target.selectors.iter().all(|(column, allowed)| {
11793            values
11794                .get(column)
11795                .and_then(Value::as_str)
11796                .is_some_and(|value| allowed.iter().any(|candidate| candidate == value))
11797        })
11798    }
11799
11800    /// Apply one host-authorized local security purge. The host MUST gate the
11801    /// corresponding subscriptions first; this primitive owns local SQLite
11802    /// cleanup and never grants/revokes server authority by itself.
11803    pub fn purge_local_data(
11804        &mut self,
11805        input: &LocalDataPurgeInput,
11806    ) -> Result<LocalDataPurgeResult, String> {
11807        let (targets, canonical_plan) = self.compile_local_data_purge(input)?;
11808        let meta_key = format!("localPurge:{}", input.purge_id);
11809        let applied_plan = self
11810            .conn
11811            .query_row(
11812                "SELECT value FROM _syncular_meta WHERE key = ?1",
11813                rusqlite::params![meta_key],
11814                |row| row.get::<_, String>(0),
11815            )
11816            .optional()
11817            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11818        if let Some(applied_plan) = applied_plan {
11819            if applied_plan != canonical_plan {
11820                return Err(format!(
11821                    "sync.invalid_request: local purge id {:?} was already used with a different plan",
11822                    input.purge_id
11823                ));
11824            }
11825            // A retry after a failed rewrite finishes it.
11826            self.erase_purged_pages()?;
11827            return Ok(LocalDataPurgeResult {
11828                already_applied: true,
11829                purged_rows: 0,
11830                dropped_commits: 0,
11831            });
11832        }
11833
11834        // RFC 0005 D7: the container file cannot be a purge target (its name is
11835        // not in the running schema), so purge drops it as a fixed step, before
11836        // any mirror row is touched and unconditionally.
11837        let _ = self.drop_previous_version();
11838
11839        let rollback = self.capture();
11840        self.begin_observation("syncular_local_purge")?;
11841        let applied = (|| -> Result<(ChangeAccumulator, LocalDataPurgeResult), String> {
11842            let row_ids = self.local_purge_base_row_ids(&targets)?;
11843            let retained_dropped = self.drop_failed_commits(|table, values| {
11844                targets.iter().any(|target| {
11845                    target.table == table && Self::local_purge_values_match(target, values)
11846                })
11847            })?;
11848            let doomed = self
11849                .outbox
11850                .iter()
11851                .filter(|commit| {
11852                    commit.ops.iter().any(|operation| {
11853                        let matching_targets = targets
11854                            .iter()
11855                            .filter(|target| target.table == operation.table)
11856                            .collect::<Vec<_>>();
11857                        if matching_targets.is_empty() {
11858                            return false;
11859                        }
11860                        if row_ids
11861                            .get(&operation.table)
11862                            .is_some_and(|ids| ids.contains(&operation.row_id))
11863                        {
11864                            return true;
11865                        }
11866                        operation.values.as_ref().is_some_and(|values| {
11867                            matching_targets
11868                                .iter()
11869                                .any(|target| Self::local_purge_values_match(target, values))
11870                        })
11871                    })
11872                })
11873                .cloned()
11874                .collect::<Vec<_>>();
11875            let doomed_ids = doomed
11876                .iter()
11877                .map(|commit| commit.client_commit_id.clone())
11878                .collect::<BTreeSet<_>>();
11879            let mut batch = ChangeAccumulator::default();
11880            for commit in &retained_dropped {
11881                batch.conflicts = true;
11882                batch.rejections = true;
11883                batch.outcomes = true;
11884                for operation in &commit.ops {
11885                    batch.table(&operation.table);
11886                }
11887            }
11888            let mut rejections = Vec::new();
11889            // §5.11 purge erasure: the journal keeps a dropped commit's identity and
11890            // codes, never its operations, so no purged value survives in it.
11891            for commit in &doomed {
11892                for operation in &commit.ops {
11893                    batch.table(&operation.table);
11894                    self.overlay_dirty.table(&operation.table);
11895                }
11896                let results = (0..commit.ops.len())
11897                    .map(|op_index| {
11898                        let rejection = RejectionRecord {
11899                            client_commit_id: commit.client_commit_id.clone(),
11900                            op_index: op_index as i32,
11901                            code: "client.local_data_purged".to_owned(),
11902                            message: "the commit was dropped by an application-authorized local data purge".to_owned(),
11903                            retryable: false,
11904                            details: None,
11905                            operation: None,
11906                        };
11907                        rejections.push(rejection.clone());
11908                        CommitOperationOutcome::Error { rejection }
11909                    })
11910                    .collect::<Vec<_>>();
11911                self.persist_commit_outcome(
11912                    &commit.client_commit_id,
11913                    CommitOutcomeStatus::Rejected,
11914                    &results,
11915                    None,
11916                )?;
11917                self.delete_outbox_persisted(&commit.client_commit_id)?;
11918            }
11919            if !doomed.is_empty() {
11920                self.outbox
11921                    .retain(|commit| !doomed_ids.contains(&commit.client_commit_id));
11922                self.rejections.extend(rejections);
11923                self.prune_commit_outcomes()?;
11924                batch.status = true;
11925                batch.rejections = true;
11926                batch.outcomes = true;
11927            }
11928
11929            let mut purged_rows = 0usize;
11930            for (table, ids) in &row_ids {
11931                if ids.is_empty() {
11932                    continue;
11933                }
11934                batch.table(table);
11935                self.overlay_dirty.table(table);
11936                for row_id in ids {
11937                    self.delete_base_row(table, row_id, i64::MAX)?;
11938                    purged_rows += 1;
11939                }
11940            }
11941            // §5.11 purge erasure: a journaled outcome with an operation or
11942            // conflict row the purge reaches keeps its identity, status, ids
11943            // and codes only.
11944            let touches = |table: &str, row_id: &str, values: Option<&Map<String, Value>>| {
11945                targets.iter().any(|target| {
11946                    target.table == table
11947                        && (row_ids.get(table).is_some_and(|ids| ids.contains(row_id))
11948                            || values.is_some_and(|values| {
11949                                Self::local_purge_values_match(target, values)
11950                            }))
11951                })
11952            };
11953            let entries = self
11954                .conn
11955                .prepare("SELECT client_commit_id, results_json, operations_json FROM _syncular_commit_outcomes")
11956                .and_then(|mut statement| {
11957                    statement
11958                        .query_map([], |row| {
11959                            Ok((
11960                                row.get::<_, String>(0)?,
11961                                row.get::<_, String>(1)?,
11962                                row.get::<_, Option<String>>(2)?,
11963                            ))
11964                        })?
11965                        .collect::<Result<Vec<_>, _>>()
11966                })
11967                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11968            for (client_commit_id, results_json, operations_json) in entries {
11969                let corrupt = |_| "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
11970                let mut results: Vec<CommitOperationOutcome> =
11971                    serde_json::from_str(&results_json).map_err(corrupt)?;
11972                let operations: Vec<CommitOperation> = operations_json
11973                    .map(|json| serde_json::from_str(&json))
11974                    .transpose()
11975                    .map_err(corrupt)?
11976                    .unwrap_or_default();
11977                let named = operations
11978                    .iter()
11979                    .chain(results.iter().filter_map(|result| match result {
11980                        CommitOperationOutcome::Conflict { conflict } => conflict.operation.as_ref(),
11981                        CommitOperationOutcome::Error { rejection } => rejection.operation.as_ref(),
11982                        CommitOperationOutcome::Applied { .. } => None,
11983                    }))
11984                    .any(|operation| touches(&operation.table, &operation.row_id, operation.values.as_ref()))
11985                    || results.iter().any(|result| {
11986                        matches!(result, CommitOperationOutcome::Conflict { conflict }
11987                            if touches(&conflict.table, &conflict.row_id, Some(&conflict.server_row)))
11988                    });
11989                if !named {
11990                    continue;
11991                }
11992                for result in &mut results {
11993                    match result {
11994                        CommitOperationOutcome::Conflict { conflict } => {
11995                            conflict.server_row = Map::new();
11996                            conflict.conflict_columns.clear();
11997                            conflict.operation = None;
11998                        }
11999                        CommitOperationOutcome::Error { rejection } => {
12000                            rejection.details = None;
12001                            rejection.operation = None;
12002                        }
12003                        CommitOperationOutcome::Applied { .. } => {}
12004                    }
12005                }
12006                let results_json = serde_json::to_string(&results).map_err(|error| error.to_string())?;
12007                self.conn
12008                    .execute(
12009                        "UPDATE _syncular_commit_outcomes SET results_json = ?1, operations_json = NULL WHERE client_commit_id = ?2",
12010                        rusqlite::params![results_json, client_commit_id],
12011                    )
12012                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12013                batch.outcomes = true;
12014            }
12015            self.rebuild_overlay_if_dirty()?;
12016            self.delete_unreferenced_cached_blobs()?;
12017            self.conn
12018                .execute(
12019                    "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
12020                    rusqlite::params![meta_key, canonical_plan],
12021                )
12022                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12023            Ok((
12024                batch,
12025                LocalDataPurgeResult {
12026                    already_applied: false,
12027                    purged_rows,
12028                    dropped_commits: doomed.len(),
12029                },
12030            ))
12031        })()
12032        .and_then(|(batch, result)| {
12033            self.finish_observation("syncular_local_purge", batch)
12034                .map(|()| result)
12035        });
12036        let result = match applied {
12037            Ok(result) => result,
12038            Err(error) => {
12039                self.rollback_observation("syncular_local_purge");
12040                self.restore(rollback);
12041                return Err(error);
12042            }
12043        };
12044        self.cancel_sync_round();
12045        self.erase_purged_pages()?;
12046        Ok(result)
12047    }
12048
12049    /// §5.11 purge erasure: SQLite leaves a deleted value in the freed pages of the
12050    /// database file, and the WAL keeps the frames written before the purge,
12051    /// until either is rewritten. VACUUM rebuilds the file from the remaining
12052    /// rows, and the checkpoint truncates the WAL.
12053    fn erase_purged_pages(&self) -> Result<(), String> {
12054        let erased = self
12055            .conn
12056            .execute_batch("PRAGMA secure_delete = ON; VACUUM;")
12057            .and_then(|()| {
12058                self.conn
12059                    .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
12060            });
12061        let reset = self.conn.execute_batch("PRAGMA secure_delete = OFF");
12062        erased
12063            .and(reset)
12064            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
12065    }
12066
12067    /// Application-authorized recovery of the replicated projection. Unlike a
12068    /// local security purge, this retains the entire outbox, device identity,
12069    /// lease, outcomes, unit registrations, and protected bookkeeping.
12070    /// The projection reset, unit rewind, optimistic replay, and
12071    /// idempotency marker share one savepoint for interruption safety.
12072    pub fn rebootstrap_local_data(
12073        &mut self,
12074        input: &LocalDataRebootstrapInput,
12075    ) -> Result<LocalDataRebootstrapResult, String> {
12076        if input.rebootstrap_id.is_empty()
12077            || input.rebootstrap_id.len() > 128
12078            || !is_local_operation_code_like(&input.rebootstrap_id)
12079        {
12080            return Err(
12081                "sync.invalid_request: local rebootstrap rebootstrapId must be a 1–128 character code-like identifier"
12082                    .to_owned(),
12083            );
12084        }
12085        let meta_key = format!("localRebootstrap:{}", input.rebootstrap_id);
12086        if let Some(persisted) = meta_get(&self.conn, &meta_key).map_err(|_| {
12087            "sync.local_corrupt: persisted local rebootstrap receipt is unreadable".to_owned()
12088        })? {
12089            let (retained_commits, reset_subscriptions) =
12090                decode_local_rebootstrap_receipt(&persisted)?;
12091            return Ok(LocalDataRebootstrapResult {
12092                already_applied: true,
12093                retained_commits,
12094                reset_subscriptions,
12095            });
12096        }
12097        if self.stopped || self.schema_floor.is_some() {
12098            return Err(
12099                "sync.invalid_request: local rebootstrap cannot bypass an active schema-floor stop; update the application first"
12100                    .to_owned(),
12101            );
12102        }
12103
12104        let retained_commits = self.outbox.len();
12105        let reset_subscriptions = self.stored(load_units(&self.conn))?.len();
12106        let receipt = encode_local_rebootstrap_receipt(retained_commits, reset_subscriptions)?;
12107        let rollback = self.capture();
12108        self.begin_observation("syncular_local_rebootstrap")?;
12109        let mut batch = ChangeAccumulator::default();
12110        let applied = (|| -> Result<(), String> {
12111            self.run_schema_reset_observed(&mut batch, false)?;
12112            self.conn
12113                .execute(
12114                    "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
12115                    rusqlite::params![meta_key, receipt],
12116                )
12117                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12118            self.sync_needed = true;
12119            self.sync_intent_queue.push_back(SyncIntent::Interactive);
12120            batch.status = true;
12121            Ok(())
12122        })()
12123        .and_then(|()| self.finish_observation("syncular_local_rebootstrap", batch));
12124        if let Err(error) = applied {
12125            self.rollback_observation("syncular_local_rebootstrap");
12126            self.restore(rollback);
12127            return Err(error);
12128        }
12129        self.cancel_sync_round();
12130
12131        Ok(LocalDataRebootstrapResult {
12132            already_applied: false,
12133            retained_commits,
12134            reset_subscriptions,
12135        })
12136    }
12137
12138    // -- scope purge + doomed outbox (§3.3) ----------------------------------------
12139
12140    /// Delete base and visible rows owned by the effective scopes
12141    /// ([`local_scope_predicate`]); `Ok(false)` = no local scope-column
12142    /// mapping for a key (the fail-closed case). A SQLite failure is an error.
12143    fn purge_scope_rows(
12144        &mut self,
12145        table_name: &str,
12146        effective: &[(String, Vec<String>)],
12147        owners: &[Vec<(String, Vec<String>)>],
12148    ) -> Result<bool, String> {
12149        let Some(table) = self.schema.table(table_name) else {
12150            return Ok(false);
12151        };
12152        let Ok(predicate) = local_scope_predicate(table, effective, owners) else {
12153            return Ok(false);
12154        };
12155        let Some((predicate, params)) = predicate else {
12156            return Ok(true);
12157        };
12158        self.overlay_dirty.table(table_name);
12159        for source in [base_table(table_name), visible_table(table_name)] {
12160            self.conn
12161                .execute(
12162                    &format!("DELETE FROM {source} WHERE {predicate}"),
12163                    rusqlite::params_from_iter(&params),
12164                )
12165                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12166        }
12167        Ok(true)
12168    }
12169
12170    /// §3.3: drop pending commits whose upserts provably land in the
12171    /// revoked effective scopes and no other owner covers (row ownership)
12172    /// — whole-commit, never per-operation.
12173    fn drop_doomed_outbox(
12174        &mut self,
12175        table: &TableSchema,
12176        effective: &[(String, Vec<String>)],
12177        owners: &[Vec<(String, Vec<String>)>],
12178    ) -> Result<bool, String> {
12179        let doomed: Vec<_> =
12180            self.outbox
12181                .iter()
12182                .filter(|commit| {
12183                    commit.ops.iter().any(|op| {
12184                        op.upsert
12185                            && op.table == table.name
12186                            && op.values.as_ref().is_some_and(|values| {
12187                                owns_local_row(table, effective, owners, values)
12188                            })
12189                    })
12190                })
12191                .cloned()
12192                .collect();
12193        if doomed.is_empty() {
12194            return Ok(false);
12195        }
12196        let mut rejections = Vec::new();
12197        for commit in &doomed {
12198            let results = commit
12199                .ops
12200                .iter()
12201                .enumerate()
12202                .map(|(op_index, operation)| {
12203                    self.overlay_dirty.table(&operation.table);
12204                    let rejection = RejectionRecord {
12205                        client_commit_id: commit.client_commit_id.clone(),
12206                        op_index: op_index as i32,
12207                        code: "sync.scope_revoked".to_owned(),
12208                        message: "the commit was dropped because its effective scope was revoked"
12209                            .to_owned(),
12210                        retryable: false,
12211                        details: None,
12212                        operation: Some(CommitOperation::from(operation)),
12213                    };
12214                    rejections.push(rejection.clone());
12215                    CommitOperationOutcome::Error { rejection }
12216                })
12217                .collect::<Vec<_>>();
12218            self.persist_commit_outcome(
12219                &commit.client_commit_id,
12220                CommitOutcomeStatus::Rejected,
12221                &results,
12222                Some(&commit.ops),
12223            )?;
12224            self.delete_outbox_persisted(&commit.client_commit_id)?;
12225        }
12226        self.prune_commit_outcomes()?;
12227        let doomed_ids = doomed
12228            .iter()
12229            .map(|commit| commit.client_commit_id.as_str())
12230            .collect::<BTreeSet<_>>();
12231        self.outbox
12232            .retain(|commit| !doomed_ids.contains(commit.client_commit_id.as_str()));
12233        self.rejections.extend(rejections);
12234        Ok(true)
12235    }
12236
12237    // -- blobs (§5.9) ----------------------------------------------------------------
12238
12239    /// §5.9.7: hash bytes into the content address, cache them, queue the
12240    /// upload (flushed before the next push, B4). Returns the canonical
12241    /// BlobRef JSON `{blobId, byteLength, mediaType?}` for a `blob_ref`
12242    /// column value.
12243    pub fn upload_blob(
12244        &mut self,
12245        bytes: &[u8],
12246        media_type: Option<String>,
12247        name: Option<String>,
12248    ) -> Result<Value, String> {
12249        let blob_id = blob_id_for(bytes);
12250        let now = self.clock_now_ms();
12251        let tx = self
12252            .conn
12253            .transaction()
12254            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12255        tx.execute(
12256            "INSERT INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,?,?)
12257             ON CONFLICT(blob_id) DO NOTHING",
12258            rusqlite::params![blob_id, bytes, bytes.len() as i64, media_type, now],
12259        )
12260        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12261        tx.execute(
12262            "INSERT OR IGNORE INTO _syncular_blob_uploads(blob_id, media_type, created_at_ms) VALUES (?,?,?)",
12263            rusqlite::params![blob_id, media_type, now],
12264        )
12265        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12266        tx.commit()
12267            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12268        self.enforce_blob_cache_cap();
12269        let mut obj = Map::new();
12270        obj.insert("blobId".to_owned(), Value::from(blob_id));
12271        obj.insert("byteLength".to_owned(), Value::from(bytes.len() as i64));
12272        if let Some(mt) = media_type {
12273            obj.insert("mediaType".to_owned(), Value::from(mt));
12274        }
12275        if let Some(n) = name {
12276            obj.insert("name".to_owned(), Value::from(n));
12277        }
12278        Ok(Value::Object(obj))
12279    }
12280
12281    /// §5.9.7: resolve an owned blob body without driver encoding. A
12282    /// content-addressed cache hit serves with no fetch (B1); a miss downloads
12283    /// (§5.9.5), verifies the address, caches the bytes, and returns them.
12284    pub fn fetch_blob_bytes(
12285        &mut self,
12286        transport: &mut dyn Transport,
12287        blob_id_or_ref: &str,
12288    ) -> Result<FetchedBlob, (String, String)> {
12289        let simple = |m: String| ("client.failed".to_owned(), m);
12290        // A BlobRef declares the size that caps the download (§5.9.5); a bare
12291        // blobId declares none.
12292        let (blob_id, byte_length) = if blob_id_or_ref.starts_with("sha256:") {
12293            (blob_id_or_ref.to_owned(), None)
12294        } else {
12295            let value: Value = serde_json::from_str(blob_id_or_ref)
12296                .map_err(|_| simple("blob ref is not JSON".to_owned()))?;
12297            (
12298                value
12299                    .get("blobId")
12300                    .and_then(Value::as_str)
12301                    .ok_or_else(|| simple("blob ref has no blobId".to_owned()))?
12302                    .to_owned(),
12303                value.get("byteLength").and_then(Value::as_u64),
12304            )
12305        };
12306        if let Some(cached) = self.get_cached_blob_bytes(&blob_id).map_err(simple)? {
12307            return Ok(cached);
12308        }
12309        if !self.transport_enabled {
12310            return Err(("sync.offline".into(), "transport gate is closed".into()));
12311        }
12312        // §5.9.5: propagate the server's blob.* code (blob.forbidden /
12313        // blob.not_found) verbatim so the harness can assert on it. The
12314        // authorized endpoint serves bytes inline OR (always-issue, presign
12315        // configured) a signed url the client fetches directly — no host auth,
12316        // no fall-through: failure => re-request (the caller's next fetch_blob_bytes).
12317        #[cfg(feature = "bench-internals")]
12318        let download_phase = self.benchmark_phases.start(Phase::BlobDownload);
12319        let bytes = match transport
12320            .blob_download(&blob_id, byte_length)
12321            .map_err(|e| (e.code, e.message))?
12322        {
12323            BlobDownload::Bytes(bytes) => bytes,
12324            BlobDownload::Url {
12325                url,
12326                url_expires_at_ms,
12327            } => {
12328                // §5.9.5: MUST NOT start a fetch at/past expiry.
12329                if url_expires_at_ms.is_some_and(|exp| exp <= self.clock_now_ms()) {
12330                    return Err((
12331                        "sync.segment_expired".to_owned(),
12332                        format!(
12333                            "blob url for {blob_id} expired before fetch — re-request mints a fresh url (§5.9.5)"
12334                        ),
12335                    ));
12336                }
12337                transport
12338                    .fetch_blob_url(&url, byte_length)
12339                    .map_err(|e| (e.code, e.message))?
12340            }
12341        };
12342        #[cfg(feature = "bench-internals")]
12343        drop(download_phase);
12344        #[cfg(feature = "bench-internals")]
12345        let validate_phase = self.benchmark_phases.start(Phase::BlobValidate);
12346        // §5.9.5 inherits §5.1: the declared size caps the body before the
12347        // content address is verified.
12348        if byte_length.is_some_and(|cap| bytes.len() as u64 > cap) {
12349            return Err((
12350                "sync.invalid_request".to_owned(),
12351                "blob exceeds its byteLength".to_owned(),
12352            ));
12353        }
12354        if blob_id_for(&bytes) != blob_id {
12355            return Err(simple(format!(
12356                "blob content address mismatch for {blob_id}"
12357            )));
12358        }
12359        #[cfg(feature = "bench-internals")]
12360        drop(validate_phase);
12361        #[cfg(feature = "bench-internals")]
12362        let insert_phase = self.benchmark_phases.start(Phase::BlobCacheInsert);
12363        let now = self.clock_now_ms();
12364        self.conn
12365            .execute(
12366                "INSERT OR IGNORE INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,NULL,?)",
12367                rusqlite::params![blob_id, bytes, bytes.len() as i64, now],
12368            )
12369            .map_err(|e| simple(e.to_string()))?;
12370        self.conn
12371            .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
12372            .map_err(|e| simple(e.to_string()))?;
12373        self.enforce_blob_cache_cap();
12374        #[cfg(feature = "bench-internals")]
12375        drop(insert_phase);
12376        self.get_cached_blob_bytes(&blob_id)
12377            .map_err(simple)?
12378            .ok_or_else(|| simple("blob cache write failed".to_owned()))
12379    }
12380
12381    fn get_cached_blob_bytes(&self, blob_id: &str) -> Result<Option<FetchedBlob>, String> {
12382        #[cfg(feature = "bench-internals")]
12383        let _phase = self.benchmark_phases.start(Phase::BlobCacheRead);
12384        let mut stmt = self
12385            .conn
12386            .prepare("SELECT bytes, byte_length, media_type FROM _syncular_blobs WHERE blob_id = ?")
12387            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12388        let mut rows = stmt
12389            .query(rusqlite::params![blob_id])
12390            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12391        if let Some(row) = rows
12392            .next()
12393            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
12394        {
12395            let bytes: Vec<u8> = row
12396                .get(0)
12397                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12398            let byte_length: i64 = row
12399                .get(1)
12400                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12401            let media_type: Option<String> = row
12402                .get(2)
12403                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12404            return Ok(Some(FetchedBlob {
12405                blob_id: blob_id.to_owned(),
12406                byte_length,
12407                bytes,
12408                media_type,
12409            }));
12410        }
12411        Ok(None)
12412    }
12413
12414    /// §5.9.7 B4: upload every queued blob before push.
12415    fn pending_blob_uploads(&self) -> Result<Vec<crate::round::PendingUpload>, TransportError> {
12416        let pending: Vec<(String, Option<String>)> = {
12417            let mut stmt = self
12418                .conn
12419                .prepare(
12420                    "SELECT blob_id, media_type FROM (
12421                      SELECT blob_id, media_type, created_at_ms FROM _syncular_blob_uploads
12422                      UNION ALL
12423                      SELECT DISTINCT r.blob_id, b.media_type, 9223372036854775807 AS created_at_ms
12424                      FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id = r.blob_id
12425                      WHERE NOT EXISTS (SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id = r.blob_id)
12426                    ) ORDER BY created_at_ms, blob_id",
12427                )
12428                .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
12429            let rows = stmt
12430                .query_map([], |row| {
12431                    Ok((row.get::<_, String>(0)?, row.get::<_, Option<String>>(1)?))
12432                })
12433                .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
12434            rows.collect::<Result<_, _>>()
12435                .map_err(|error| match error {
12436                    rusqlite::Error::InvalidColumnType(..)
12437                    | rusqlite::Error::FromSqlConversionFailure(..) => TransportError::new(
12438                        "sync.local_corrupt",
12439                        "Pending blob upload metadata is invalid",
12440                    ),
12441                    _ => TransportError::new("client.failed", error.to_string()),
12442                })?
12443        };
12444        let mut uploads = Vec::new();
12445        for (blob_id, media_type) in pending {
12446            let bytes = (|| {
12447                let stored: Option<(SqlValue, SqlValue)> = self
12448                    .conn
12449                    .query_row(
12450                        "SELECT bytes, byte_length FROM _syncular_blobs WHERE blob_id = ?",
12451                        rusqlite::params![blob_id],
12452                        |row| Ok((row.get(0)?, row.get(1)?)),
12453                    )
12454                    .optional()
12455                    .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
12456                let Some((SqlValue::Blob(bytes), SqlValue::Integer(byte_length))) = stored else {
12457                    return Err(TransportError::new(
12458                        "sync.local_corrupt",
12459                        "Pending blob upload body is missing or corrupt",
12460                    ));
12461                };
12462                if byte_length != bytes.len() as i64 || blob_id_for(&bytes) != blob_id {
12463                    return Err(TransportError::new(
12464                        "sync.local_corrupt",
12465                        "Pending blob upload body is missing or corrupt",
12466                    ));
12467                }
12468                Ok(bytes)
12469            })();
12470            let failed = bytes.is_err();
12471            uploads.push(crate::round::PendingUpload {
12472                id: blob_id,
12473                bytes,
12474                media_type,
12475            });
12476            if failed {
12477                break;
12478            }
12479        }
12480        Ok(uploads)
12481    }
12482
12483    fn visible_blob_ids_sql(&self) -> String {
12484        let mut selects = Vec::new();
12485        for table in &self.schema.tables {
12486            for column in table
12487                .columns
12488                .iter()
12489                .filter(|column| column.ty == ColumnType::BlobRef)
12490            {
12491                let identifier = quote_ident(&column.name);
12492                selects.push(format!(
12493                    "SELECT json_extract({identifier}, '$.blobId') AS blob_id FROM {} \
12494                     WHERE typeof({identifier}) = 'text' AND json_valid({identifier}) \
12495                     AND json_type({identifier}, '$.blobId') = 'text'",
12496                    quote_ident(&table.name),
12497                ));
12498            }
12499        }
12500        if selects.is_empty() {
12501            "SELECT NULL AS blob_id WHERE 0".to_owned()
12502        } else {
12503            selects.join(" UNION ")
12504        }
12505    }
12506
12507    /// §5.9.7 B1 size cap. Visible rows, pending commits, and
12508    /// staged uploads pin bodies directly; no derived refcount is stored.
12509    fn enforce_blob_cache_cap(&self) {
12510        let Some(max_bytes) = self.limits.blob_cache_max_bytes else {
12511            return;
12512        };
12513        let mut total: i64 = self
12514            .conn
12515            .query_row(
12516                "SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs",
12517                [],
12518                |row| row.get(0),
12519            )
12520            .unwrap_or(0);
12521        if total <= max_bytes {
12522            return;
12523        }
12524        let query = format!(
12525            "SELECT blob_id, byte_length FROM _syncular_blobs
12526             WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
12527               AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
12528               AND blob_id NOT IN ({})
12529             ORDER BY created_at_ms ASC, blob_id ASC",
12530            self.visible_blob_ids_sql(),
12531        );
12532        let candidates: Vec<(String, i64)> = {
12533            let Ok(mut stmt) = self.conn.prepare(&query) else {
12534                return;
12535            };
12536            let Ok(rows) = stmt.query_map([], |row| {
12537                Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
12538            }) else {
12539                return;
12540            };
12541            rows.filter_map(Result::ok).collect()
12542        };
12543        for (blob_id, byte_length) in candidates {
12544            if total <= max_bytes {
12545                break;
12546            }
12547            let _ = self.conn.execute(
12548                "DELETE FROM _syncular_blobs WHERE blob_id = ?",
12549                rusqlite::params![blob_id],
12550            );
12551            total -= byte_length;
12552        }
12553    }
12554
12555    fn delete_unreferenced_cached_blobs(&mut self) -> Result<(), String> {
12556        #[cfg(feature = "bench-internals")]
12557        let _phase = self.benchmark_phases.start(Phase::BlobRetention);
12558        if !self.schema_has_blobs() {
12559            return Ok(());
12560        }
12561        self.rebuild_overlay_if_dirty()?;
12562        self.conn
12563            .execute(
12564                &format!(
12565                    "DELETE FROM _syncular_blobs
12566                 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
12567                   AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
12568                   AND blob_id NOT IN ({})",
12569                    self.visible_blob_ids_sql(),
12570                ),
12571                [],
12572            )
12573            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12574        Ok(())
12575    }
12576
12577    // -- local row storage ----------------------------------------------------------
12578
12579    /// The cached per-table primary-key upsert SQL for `full_table` (see
12580    /// the `insert_sql` field: built once, reused per row).
12581    fn insert_row_sql(&self, full_table: &str, table: &crate::schema::TableSchema) -> String {
12582        if let Some(sql) = self.insert_sql.borrow().get(full_table) {
12583            return sql.clone();
12584        }
12585        let mut columns: Vec<String> = table.columns.iter().map(|c| quote_ident(&c.name)).collect();
12586        columns.push(quote_ident("_syncular_version"));
12587        columns.extend(table.sealed_columns().iter().map(|name| quote_ident(name)));
12588        let placeholders: Vec<&str> = columns.iter().map(|_| "?").collect();
12589        let primary_key = quote_ident(&table.primary_key);
12590        let updates = columns
12591            .iter()
12592            .filter(|column| **column != primary_key)
12593            .map(|column| format!("{column}=excluded.{column}"))
12594            .collect::<Vec<_>>()
12595            .join(", ");
12596        // §4.5 version guard: server state lands in the base table only above
12597        // the stored version; the visible overlay takes every write.
12598        let guard = if full_table == base_table(&table.name) {
12599            format!(" WHERE excluded._syncular_version > {full_table}._syncular_version")
12600        } else {
12601            String::new()
12602        };
12603        let sql = format!(
12604            "INSERT INTO {full_table} ({}) VALUES ({}) ON CONFLICT ({primary_key}) DO UPDATE SET {updates}{guard}",
12605            columns.join(", "),
12606            placeholders.join(", ")
12607        );
12608        self.insert_sql
12609            .borrow_mut()
12610            .insert(full_table.to_owned(), sql.clone());
12611        sql
12612    }
12613
12614    /// §4.5: write a server row under the version guard; returns whether it
12615    /// landed. `sealed` is its §5.11 sealed state, `None` for an unsealed row.
12616    fn write_base_row(
12617        &self,
12618        table_name: &str,
12619        row: &Row,
12620        version: i64,
12621        sealed: Option<&SealedRow>,
12622    ) -> Result<bool, String> {
12623        let landed = self.write_row(&base_table(table_name), table_name, row, version, sealed)?;
12624        if landed {
12625            self.overlay_dirty.table(table_name);
12626        }
12627        Ok(landed)
12628    }
12629
12630    fn write_row(
12631        &self,
12632        full_table: &str,
12633        table_name: &str,
12634        row: &Row,
12635        version: i64,
12636        sealed: Option<&SealedRow>,
12637    ) -> Result<bool, String> {
12638        #[cfg(feature = "bench-internals")]
12639        let _phase = self.benchmark_phases.start(Phase::RowWrite);
12640        let table = self
12641            .schema
12642            .table(table_name)
12643            .ok_or_else(|| format!("unknown table {table_name:?}"))?;
12644        let sql = self.insert_row_sql(full_table, table);
12645        let mut stmt = self
12646            .conn
12647            .prepare_cached(&sql)
12648            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12649        let params = row
12650            .iter()
12651            .map(RowParam::Cell)
12652            .chain(std::iter::once(RowParam::Version(version)))
12653            .chain(
12654                [
12655                    sealed.map(|sealed| sealed.key_id.as_str()),
12656                    sealed.map(|sealed| sealed.envelopes.as_str()),
12657                ]
12658                .into_iter()
12659                .take(table.sealed_columns().len())
12660                .map(RowParam::Text),
12661            );
12662        stmt.execute(rusqlite::params_from_iter(params))
12663            .map(|changed| changed > 0)
12664            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
12665    }
12666
12667    /// §4.5: delete a server row whose stored version lies below `version`;
12668    /// returns whether a row left.
12669    fn delete_base_row(
12670        &self,
12671        table_name: &str,
12672        row_id: &str,
12673        version: i64,
12674    ) -> Result<bool, String> {
12675        let table = self
12676            .schema
12677            .table(table_name)
12678            .ok_or_else(|| format!("unknown table {table_name:?}"))?;
12679        let sql = format!(
12680            "DELETE FROM {} WHERE {} AND _syncular_version < ?2",
12681            base_table(table_name),
12682            row_id_predicate(table)
12683        );
12684        let mut stmt = self
12685            .conn
12686            .prepare_cached(&sql)
12687            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12688        let landed = stmt
12689            .execute(rusqlite::params![row_id, version])
12690            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
12691            > 0;
12692        if landed {
12693            self.overlay_dirty.table(table_name);
12694        }
12695        Ok(landed)
12696    }
12697
12698    fn has_acknowledged_rows(&self) -> Result<bool, String> {
12699        self.conn
12700            .query_row(
12701                "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows)",
12702                [],
12703                |row| row.get(0),
12704            )
12705            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
12706    }
12707
12708    fn acknowledged_operations(
12709        &self,
12710        rows: Option<&HashSet<(&str, &str)>>,
12711        tables: Option<&BTreeSet<&str>>,
12712    ) -> Result<Vec<OutboxOp>, String> {
12713        let keys = rows.map(|rows| serde_json::to_string(&rows).expect("row keys"));
12714        let mut statement = self
12715            .conn
12716            .prepare_cached(if keys.is_some() {
12717                ACKED_ROWS_BY_ROW
12718            } else {
12719                "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"
12720            })
12721            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12722        let rows = statement
12723            .query_map(
12724                rusqlite::params![
12725                    keys,
12726                    tables.map(|tables| serde_json::to_string(tables).expect("table keys"))
12727                ],
12728                |row| {
12729                    #[cfg(test)]
12730                    self.acknowledged_replay_count
12731                        .set(self.acknowledged_replay_count.get() + 1);
12732                    Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
12733                },
12734            )
12735            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12736        rows.map(|row| {
12737            let (op, intent) =
12738                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12739            let op: CommitOperation =
12740                serde_json::from_str(&op).map_err(|_| "sync.local_corrupt".to_owned())?;
12741            let table = self
12742                .schema
12743                .table(&op.table)
12744                .ok_or_else(|| "sync.unknown_table".to_owned())?;
12745            let values = if op.op == "upsert" && self.visible_row(table, &op.row_id)?.is_none() {
12746                Some(serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?)
12747            } else {
12748                op.values.clone()
12749            };
12750            Ok(OutboxOp {
12751                values,
12752                ..op.into()
12753            })
12754        })
12755        .collect()
12756    }
12757
12758    fn drop_acknowledged_rows(
12759        &self,
12760        matches: impl Fn(&str, &Map<String, Value>) -> bool,
12761    ) -> Result<Vec<OutboxCommit>, String> {
12762        let mut statement = self
12763            .conn
12764            .prepare("SELECT commit_id,tbl,intent_json,id FROM _syncular_acked_rows")
12765            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12766        let rows = statement
12767            .query_map([], |row| {
12768                Ok((
12769                    row.get::<_, String>(0)?,
12770                    row.get::<_, String>(1)?,
12771                    row.get::<_, String>(2)?,
12772                    row.get::<_, String>(3)?,
12773                ))
12774            })
12775            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12776        let mut doomed = HashSet::new();
12777        for row in rows {
12778            let (id, table, intent, row_id) =
12779                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12780            let values =
12781                serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
12782            let base_matches = self
12783                .schema
12784                .table(&table)
12785                .map(|schema| self.stored_row(schema, &row_id, true))
12786                .transpose()?
12787                .flatten()
12788                .is_some_and(|(base, _)| {
12789                    let schema = self.schema.table(&table).expect("acknowledged table");
12790                    let values = schema
12791                        .columns
12792                        .iter()
12793                        .zip(base.iter())
12794                        .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
12795                        .collect();
12796                    matches(&table, &values)
12797                });
12798            if matches(&table, &values) || base_matches {
12799                doomed.insert(id);
12800            }
12801        }
12802        let mut dropped = Vec::new();
12803        for id in doomed {
12804            let mut statement = self
12805                .conn
12806                .prepare("SELECT op_json FROM _syncular_acked_rows WHERE commit_id=?1 ORDER BY idx")
12807                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12808            let operations = statement
12809                .query_map([&id], |row| row.get::<_, String>(0))
12810                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12811            let mut ops = Vec::new();
12812            for operation in operations {
12813                let json = operation
12814                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12815                let op: CommitOperation =
12816                    serde_json::from_str(&json).map_err(|_| "sync.local_corrupt".to_owned())?;
12817                self.overlay_dirty.table(&op.table);
12818                ops.push(OutboxOp {
12819                    table: op.table,
12820                    row_id: op.row_id,
12821                    upsert: op.op == "upsert",
12822                    base_version: op.base_version,
12823                    values: op.values,
12824                    insert: op.insert,
12825                });
12826            }
12827            dropped.push(OutboxCommit {
12828                client_commit_id: id.clone(),
12829                ops,
12830            });
12831            self.conn
12832                .execute("DELETE FROM _syncular_acked_rows WHERE commit_id=?1", [id])
12833                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12834        }
12835        Ok(dropped)
12836    }
12837
12838    /// [`Self::rebuild_overlay`], skipped when neither the base tables nor
12839    /// the outbox changed since the last rebuild (the no-op sync round).
12840    fn rebuild_overlay_if_dirty(&mut self) -> Result<(), String> {
12841        if self.overlay_dirty.get() {
12842            self.rebuild_overlay()?;
12843        }
12844        Ok(())
12845    }
12846
12847    /// §7.1: local reads see outbox state applied optimistically — rebuild
12848    /// every visible table as (base server state) + (pending outbox replay
12849    /// on top). Optimistic rows carry version `-1`.
12850    fn rebuild_overlay(&mut self) -> Result<(), String> {
12851        #[cfg(feature = "bench-internals")]
12852        let _phase = self.benchmark_phases.start(Phase::OverlayRebuild);
12853        #[cfg(test)]
12854        self.overlay_rebuild_count
12855            .set(self.overlay_rebuild_count.get() + 1);
12856        let dirty = self.overlay_dirty.snapshot();
12857        let tables: Vec<_> = self
12858            .schema
12859            .tables
12860            .iter()
12861            .filter(|table| {
12862                dirty
12863                    .as_ref()
12864                    .is_none_or(|names| names.is_empty() || names.contains(&table.name))
12865            })
12866            .cloned()
12867            .collect();
12868        let names: BTreeSet<_> = tables.iter().map(|table| table.name.as_str()).collect();
12869        self.begin_observation("syncular_overlay")?;
12870        let rebuilt = (|| {
12871            for table in &tables {
12872                for index in &table.fts_indexes {
12873                    self.drop_fts_triggers(index)?;
12874                }
12875                let visible = visible_table(&table.name);
12876                let base = base_table(&table.name);
12877                self.conn
12878                    .execute_batch(&format!(
12879                        "DELETE FROM {visible}; INSERT INTO {visible} SELECT * FROM {base}"
12880                    ))
12881                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12882            }
12883            self.replay_overlay(&names, None)?;
12884            for table in &tables {
12885                for index in &table.fts_indexes {
12886                    self.rebuild_fts_projection(table, index)?;
12887                    self.create_fts_triggers(table, index)?;
12888                }
12889            }
12890            self.conn
12891                .execute_batch("RELEASE syncular_overlay")
12892                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12893            Ok(())
12894        })();
12895        if rebuilt.is_err() {
12896            self.conn
12897                .execute_batch("ROLLBACK TO syncular_overlay; RELEASE syncular_overlay")
12898                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12899        } else {
12900            self.overlay_dirty.set(false);
12901        }
12902        rebuilt
12903    }
12904
12905    /// §7.1 replay of acknowledged, retained failed and pending intent, in
12906    /// that order, for the operations of `tables` on `rows` (every row for
12907    /// `None`) over their current visible state.
12908    fn replay_overlay(
12909        &self,
12910        tables: &BTreeSet<&str>,
12911        rows: Option<&HashSet<(&str, &str)>>,
12912    ) -> Result<(), String> {
12913        let replays = |op: &&OutboxOp| {
12914            tables.contains(op.table.as_str())
12915                && rows.is_none_or(|rows| rows.contains(&(op.table.as_str(), op.row_id.as_str())))
12916        };
12917        self.apply_outbox_ops(&self.acknowledged_operations(rows, Some(tables))?)?;
12918        for (commit, initial) in self.failed_commits.iter() {
12919            for operation in commit.ops.iter().filter(replays) {
12920                let Some(table) = self.schema.table(&operation.table) else {
12921                    continue;
12922                };
12923                if operation.upsert
12924                    && self.visible_row(table, &operation.row_id)?.is_none()
12925                    && operation.presented_values(table).is_some_and(|values| {
12926                        table
12927                            .columns
12928                            .iter()
12929                            .all(|column| values.contains_key(&column.name))
12930                    })
12931                {
12932                    let key = serde_json::to_string(&(&operation.table, &operation.row_id))
12933                        .expect("row key serialization");
12934                    if let Some(Value::Object(values)) = initial.get(&key) {
12935                        self.apply_outbox_ops(&[OutboxOp {
12936                            values: Some(values.clone()),
12937                            ..operation.clone()
12938                        }])?;
12939                    }
12940                }
12941            }
12942            self.apply_outbox_ops(commit.ops.iter().filter(replays))?;
12943        }
12944        self.apply_outbox_ops(
12945            self.outbox
12946                .iter()
12947                .flat_map(|commit| &commit.ops)
12948                .filter(replays),
12949        )
12950    }
12951
12952    /// §7.1 replay: every operation is applied over the current visible
12953    /// state. An operation that no longer applies (a server row now holds its
12954    /// unique value) stays pending and invisible until a later replay admits
12955    /// it or the server answers its push.
12956    fn apply_outbox_ops<'a>(
12957        &self,
12958        ops: impl IntoIterator<Item = &'a OutboxOp>,
12959    ) -> Result<(), String> {
12960        #[cfg(feature = "bench-internals")]
12961        let mut phase = self.benchmark_phases.start(Phase::PendingReplay);
12962        for op in ops {
12963            #[cfg(feature = "bench-internals")]
12964            if let Some(phase) = &mut phase {
12965                phase.unit();
12966            }
12967            if op.upsert {
12968                if let Some((table, values)) = self
12969                    .schema
12970                    .table(&op.table)
12971                    .filter(|table| table.indexes.iter().any(|index| index.unique))
12972                    .and_then(|table| Some((table, op.presented_values(table)?)))
12973                {
12974                    let mut intended: Map<String, Value> = self
12975                        .visible_row(table, &op.row_id)?
12976                        .map(|(row, _)| {
12977                            table
12978                                .columns
12979                                .iter()
12980                                .zip(&row)
12981                                .map(|(column, value)| {
12982                                    (column.name.clone(), column_value_to_json(value))
12983                                })
12984                                .collect()
12985                        })
12986                        .unwrap_or_default();
12987                    intended.extend(values.into_owned());
12988                    if !self.unique_conflicts(table, &intended, false)?.is_empty() {
12989                        continue;
12990                    }
12991                }
12992            }
12993            self.apply_outbox_op(op)?;
12994        }
12995        Ok(())
12996    }
12997
12998    fn apply_outbox_op(&self, op: &OutboxOp) -> Result<(), String> {
12999        let Some(table) = self.schema.table(&op.table) else {
13000            return Ok(());
13001        };
13002        let visible = visible_table(&table.name);
13003        if !op.upsert {
13004            let sql = format!("DELETE FROM {visible} WHERE {}", row_id_predicate(table));
13005            self.conn
13006                .prepare_cached(&sql)
13007                .and_then(|mut statement| statement.execute(rusqlite::params![op.row_id]))
13008                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13009            return Ok(());
13010        }
13011        // §7.1: an insert-intent operation that lacks a non-nullable column
13012        // cannot encode; it stays invisible until the send-time prepass drops
13013        // it as sync.outbox_incompatible (§7.4.4).
13014        let Some(values) = op.presented_values(table) else {
13015            return Ok(());
13016        };
13017        // §7.1: the overlay applies the operation's PRESENT columns
13018        // over the current local row. A partial operation over an
13019        // absent local row leaves it absent — the server answers it
13020        // with sync.row_deleted or sync.row_missing (§6.2). An
13021        // insert-intent operation presents every column.
13022        let full = table
13023            .columns
13024            .iter()
13025            .all(|column| values.contains_key(&column.name));
13026        let local = self.visible_row(table, &op.row_id)?;
13027        if local.is_none() && !full {
13028            return Ok(());
13029        }
13030        let mut row: Row = Vec::with_capacity(table.columns.len());
13031        for (index, column) in table.columns.iter().enumerate() {
13032            let incoming = match values.get(&column.name) {
13033                Some(raw) => json_to_column_value(
13034                    if raw.get("$bytes").is_some()
13035                        && table
13036                            .encrypted_columns
13037                            .iter()
13038                            .any(|encrypted| encrypted.index == index)
13039                    {
13040                        &table.wire_columns[index]
13041                    } else {
13042                        column
13043                    },
13044                    Some(raw),
13045                ),
13046                None => Ok(local
13047                    .as_ref()
13048                    .and_then(|(values, _)| values.get(index).cloned())
13049                    .flatten()),
13050            };
13051            row.push(incoming.map_err(|_| {
13052                "sync.local_corrupt: persisted optimistic row value is invalid".to_owned()
13053            })?);
13054        }
13055        let version = local.as_ref().map_or(-1, |(_, version)| *version);
13056        self.write_row(&visible, &table.name, &row, version, None)
13057            .map(|_| ())
13058            .map_err(|error| {
13059                if error.starts_with("UNIQUE constraint failed:") {
13060                    "sync.constraint_violation: local write violates a unique constraint".to_owned()
13061                } else {
13062                    error
13063                }
13064            })
13065    }
13066
13067    /// Whether the row is present in the overlay. Existence reads only the
13068    /// key: locked encrypted values stay opaque, and decoding the complete row
13069    /// would reject a valid plain write.
13070    fn visible_row_exists(&self, table: &TableSchema, row_id: &str) -> Result<bool, String> {
13071        self.conn
13072            .query_row(
13073                &format!(
13074                    "SELECT EXISTS(SELECT 1 FROM {} WHERE {})",
13075                    visible_table(&table.name),
13076                    row_id_predicate(table)
13077                ),
13078                rusqlite::params![row_id],
13079                |row| row.get(0),
13080            )
13081            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
13082    }
13083
13084    /// §5.11: a sealed row is read-only; a write could otherwise send NULL
13085    /// over ciphertext this device cannot see.
13086    fn refuse_sealed_row(&self, table: &TableSchema, row_id: &str) -> Result<(), ClientError> {
13087        if !table.has_encrypted_columns() {
13088            return Ok(());
13089        }
13090        let key_id: Option<String> = self
13091            .conn
13092            .query_row(
13093                &format!(
13094                    "SELECT \"_sync_sealed_key\" FROM {} WHERE {}",
13095                    visible_table(&table.name),
13096                    row_id_predicate(table)
13097                ),
13098                rusqlite::params![row_id],
13099                |row| row.get(0),
13100            )
13101            .optional()
13102            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
13103            .flatten();
13104        match key_id {
13105            None => Ok(()),
13106            Some(key_id) => Err(ClientError {
13107                code: "client.encryption_key_missing".to_owned(),
13108                message: "the row is sealed under a key this device does not hold".to_owned(),
13109                details: Some(json!({ "table": table.name, "keyId": key_id })),
13110                retryable: false,
13111            }),
13112        }
13113    }
13114
13115    /// §5.11 reveal: decrypt every sealed base row whose envelope keys the
13116    /// keyring now holds into its columns and clear both reserved columns,
13117    /// one change batch per table. `client.decrypt_failed` fails the caller.
13118    fn reveal_sealed_rows(&mut self) -> Result<(), TransportError> {
13119        let storage = |message: String| TransportError::new("storage.failed", message);
13120        let tables: Vec<TableSchema> = self
13121            .schema
13122            .tables
13123            .iter()
13124            .filter(|table| table.has_encrypted_columns())
13125            .cloned()
13126            .collect();
13127        for table in &tables {
13128            let base = base_table(&table.name);
13129            let pk = quote_ident(&table.primary_key);
13130            let sealed: Vec<(SqlValue, i64, String)> = self
13131                .conn
13132                .prepare_cached(&format!(
13133                    "SELECT {pk}, \"_syncular_version\", \"_sync_sealed\" FROM {base} WHERE \"_sync_sealed_key\" IS NOT NULL"
13134                ))
13135                .and_then(|mut statement| {
13136                    statement
13137                        .query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?
13138                        .collect()
13139                })
13140                .map_err(|error| storage(Self::sqlite_failure(&self.storage_failure, error)))?;
13141            let mut revealed = Vec::new();
13142            for (key, version, envelopes) in sealed {
13143                if let Some(row) =
13144                    crate::values::reveal_sealed_row(table, &envelopes, &self.encryption)?
13145                {
13146                    revealed.push((key, version, row));
13147                }
13148            }
13149            if revealed.is_empty() {
13150                continue;
13151            }
13152            self.begin_observation("syncular_reveal").map_err(storage)?;
13153            let outcome = (|| {
13154                let assignments = table
13155                    .encrypted_columns
13156                    .iter()
13157                    .map(|enc| format!("{}=?", quote_ident(&table.columns[enc.index].name)))
13158                    .collect::<Vec<_>>()
13159                    .join(",");
13160                let mut statement = self
13161                    .conn
13162                    .prepare_cached(&format!(
13163                        "UPDATE {base} SET {assignments},\"_sync_sealed_key\"=NULL,\"_sync_sealed\"=NULL WHERE {pk}=? AND \"_syncular_version\"=?"
13164                    ))
13165                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13166                for (key, version, row) in &revealed {
13167                    let mut params = table
13168                        .encrypted_columns
13169                        .iter()
13170                        .map(|enc| owned_sql_value(RowParam::Cell(&row[enc.index])))
13171                        .collect::<Result<Vec<_>, _>>()?;
13172                    params.push(key.clone());
13173                    params.push(SqlValue::Integer(*version));
13174                    statement
13175                        .execute(rusqlite::params_from_iter(params))
13176                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13177                }
13178                drop(statement);
13179                self.overlay_dirty.table(&table.name);
13180                self.rebuild_overlay()?;
13181                let mut batch = ChangeAccumulator::default();
13182                batch.table(&table.name);
13183                self.finish_observation("syncular_reveal", batch)
13184            })();
13185            if outcome.is_err() {
13186                self.rollback_observation("syncular_reveal");
13187            }
13188            outcome.map_err(storage)?;
13189        }
13190        Ok(())
13191    }
13192
13193    /// The visible (optimistic) row's values plus version, or `None` when the
13194    /// row is absent from the overlay.
13195    fn visible_row(&self, table: &TableSchema, row_id: &str) -> Result<Option<(Row, i64)>, String> {
13196        self.stored_row(table, row_id, false)
13197    }
13198
13199    fn stored_row(
13200        &self,
13201        table: &TableSchema,
13202        row_id: &str,
13203        base: bool,
13204    ) -> Result<Option<(Row, i64)>, String> {
13205        let sql = format!(
13206            "SELECT * FROM {} WHERE {}",
13207            if base {
13208                base_table(&table.name)
13209            } else {
13210                visible_table(&table.name)
13211            },
13212            row_id_predicate(table)
13213        );
13214        let mut stmt = self
13215            .conn
13216            .prepare_cached(&sql)
13217            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13218        let mut rows = stmt
13219            .query(rusqlite::params![row_id])
13220            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13221        let Some(row) = rows
13222            .next()
13223            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
13224        else {
13225            return Ok(None);
13226        };
13227        let mut values = Vec::with_capacity(table.columns.len());
13228        for (index, column) in table.columns.iter().enumerate() {
13229            let raw = row
13230                .get_ref(index)
13231                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13232            if let rusqlite::types::ValueRef::Blob(bytes) = raw {
13233                if table
13234                    .encrypted_columns
13235                    .iter()
13236                    .any(|encrypted| encrypted.index == index)
13237                {
13238                    values.push(Some(ColumnValue::Bytes(bytes.to_vec())));
13239                    continue;
13240                }
13241            }
13242            let json = sql_ref_to_json(column, raw);
13243            values.push(json_to_column_value(column, Some(&json)).map_err(|_| {
13244                "sync.local_corrupt: persisted local row value is invalid".to_owned()
13245            })?);
13246        }
13247        let version: i64 = row
13248            .get(table.columns.len())
13249            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13250        Ok(Some((values, version)))
13251    }
13252
13253    // -- realtime (§8) ---------------------------------------------------------------
13254
13255    /// §8.8: the configured realtime policy.
13256    #[must_use]
13257    pub fn realtime_policy(&self) -> RealtimePolicy {
13258        self.realtime_policy
13259    }
13260
13261    /// §8.8: the explicit realtime availability state.
13262    #[must_use]
13263    pub fn realtime_state(&self) -> RealtimeState {
13264        self.realtime_state
13265    }
13266
13267    /// §8.8: set the realtime policy. Refused while the socket is connected:
13268    /// a policy change never silently re-routes an ownership state.
13269    pub fn set_realtime_policy(&mut self, policy: RealtimePolicy) -> Result<(), String> {
13270        if self.realtime_state == RealtimeState::Connected && policy != self.realtime_policy {
13271            return Err(
13272                "sync.invalid_request: disconnect realtime before changing the realtime policy"
13273                    .to_owned(),
13274            );
13275        }
13276        self.realtime_policy = policy;
13277        match policy {
13278            RealtimePolicy::Off => self.set_realtime_state(RealtimeState::Disabled, None),
13279            RealtimePolicy::Required | RealtimePolicy::Optional
13280                if self.realtime_state == RealtimeState::Disabled =>
13281            {
13282                self.set_realtime_state(RealtimeState::Disconnected, None);
13283            }
13284            RealtimePolicy::Required | RealtimePolicy::Optional => {}
13285        }
13286        Ok(())
13287    }
13288
13289    /// Record an availability transition, keeping the reason code bounded and
13290    /// code-like (§7.6) and clearing it where it cannot apply.
13291    fn set_realtime_state(&mut self, state: RealtimeState, reason_code: Option<&str>) {
13292        self.realtime_state = state;
13293        self.realtime_reason_code = reason_code.map(Self::diagnostic_code);
13294        if matches!(state, RealtimeState::Connected | RealtimeState::Disabled) {
13295            self.realtime_reason_code = None;
13296            self.realtime_retry_delay_ms = None;
13297        }
13298    }
13299
13300    #[must_use]
13301    fn realtime_connected(&self) -> bool {
13302        self.realtime_state == RealtimeState::Connected
13303    }
13304
13305    pub fn connect_realtime(&mut self, transport: &mut dyn Transport) -> Result<(), String> {
13306        if !self.transport_enabled {
13307            return Err("sync.offline: transport gate is closed".into());
13308        }
13309        if self.realtime_policy == RealtimePolicy::Off {
13310            return Err(
13311                "sync.invalid_request: realtime is off; realtime connect is refused".to_owned(),
13312            );
13313        }
13314        if self.realtime_connected() {
13315            return Ok(());
13316        }
13317        self.realtime_state = RealtimeState::Connecting;
13318        match transport.realtime_connect(&self.client_id) {
13319            Ok(()) => {
13320                self.set_realtime_state(RealtimeState::Connected, None);
13321                Ok(())
13322            }
13323            Err(error) => {
13324                self.set_realtime_state(RealtimeState::Refused, Some(&error.code));
13325                Err(format!("{}: {}", error.code, error.message))
13326            }
13327        }
13328    }
13329
13330    pub fn disconnect_realtime(&mut self, transport: &mut dyn Transport) {
13331        self.cancel_sync_round();
13332        // A deliberately disconnected or policy-disabled client has nothing
13333        // to release; a `lost` socket still does (the host owns the handle).
13334        if self.realtime_state == RealtimeState::Disconnected
13335            || self.realtime_state == RealtimeState::Disabled
13336        {
13337            return;
13338        }
13339        let _ = transport.realtime_close();
13340        self.set_realtime_state(
13341            if self.realtime_policy == RealtimePolicy::Off {
13342                RealtimeState::Disabled
13343            } else {
13344                RealtimeState::Disconnected
13345            },
13346            None,
13347        );
13348        self.presence.clear(); // §8.6.1: presence is per-connection
13349    }
13350
13351    /// §8.8: the host observed the socket end without disconnecting it (a
13352    /// peer close, an I/O error, a failed send; the native transport reports
13353    /// these as `Inbound::Disconnected`). Releases the transport, moves a
13354    /// `Connected` state to `Lost` with the transport's code as the reason, and schedules
13355    /// one background retry intent so the host reconnects and catches up.
13356    pub fn realtime_lost(&mut self, transport: &mut dyn Transport, error: &TransportError) {
13357        if self.realtime_state != RealtimeState::Connected {
13358            return;
13359        }
13360        self.cancel_sync_round();
13361        let _ = transport.realtime_close();
13362        self.set_realtime_state(RealtimeState::Lost, Some(&error.code));
13363        self.realtime_retry_delay_ms = Some(self.schedule_background_retry());
13364        self.presence.clear();
13365    }
13366
13367    /// §8.6.2: publish (or clear, `doc: None`) this client's presence
13368    /// document for `scope_key`. Requires a live socket; the document is
13369    /// ephemeral (lost on disconnect). Authorization is the connection's
13370    /// registration (§8.6.3) — an unheld key is rejected loudly by the
13371    /// server with `presence.forbidden`.
13372    pub fn set_presence(
13373        &mut self,
13374        transport: &mut dyn Transport,
13375        scope_key: &str,
13376        doc: Option<&Value>,
13377    ) -> Result<(), String> {
13378        if !self.transport_enabled {
13379            return Err("sync.offline: transport gate is closed".into());
13380        }
13381        if !self.realtime_connected() {
13382            return Err("setPresence requires a connected realtime socket (§8.6)".to_string());
13383        }
13384        let text = encode_presence_publish(scope_key, doc);
13385        transport
13386            .realtime_send(&text)
13387            .map_err(|e| format!("{}: {}", e.code, e.message))
13388    }
13389
13390    /// §8.6: the peers currently present on a scope key (ephemeral).
13391    pub fn presence(&self, scope_key: &str) -> Vec<PresencePeer> {
13392        self.presence
13393            .get(scope_key)
13394            .map(|peers| peers.values().cloned().collect())
13395            .unwrap_or_default()
13396    }
13397
13398    /// §8.6 apply an inbound presence fanout to the local map.
13399    fn apply_presence(
13400        &mut self,
13401        scope_key: String,
13402        kind: Option<PresenceKind>,
13403        actor_id: Option<String>,
13404        client_id: Option<String>,
13405        doc: Option<Value>,
13406        error: Option<String>,
13407    ) {
13408        // A refused publish (§8.6.2) changes no peer; the native host surfaces
13409        // it as a `presence` event carrying the server's `error` code.
13410        if error.is_some() {
13411            return;
13412        }
13413        let (Some(kind), Some(actor_id), Some(client_id)) = (kind, actor_id, client_id) else {
13414            return;
13415        };
13416        let peer_key = format!("{actor_id} {client_id}");
13417        match kind {
13418            PresenceKind::Leave => {
13419                if let Some(peers) = self.presence.get_mut(&scope_key) {
13420                    peers.remove(&peer_key);
13421                    if peers.is_empty() {
13422                        self.presence.remove(&scope_key);
13423                    }
13424                }
13425            }
13426            _ => {
13427                let doc = match doc {
13428                    Some(Value::Object(_)) => doc.unwrap(),
13429                    _ => return,
13430                };
13431                self.presence.entry(scope_key).or_default().insert(
13432                    peer_key,
13433                    PresencePeer {
13434                        actor_id,
13435                        client_id,
13436                        doc,
13437                    },
13438                );
13439            }
13440        }
13441    }
13442
13443    /// Inbound JSON control message (§8.1). Unknown events are tolerated.
13444    pub fn on_realtime_text(&mut self, text: &str) {
13445        if self.stopped || !self.transport_enabled || self.security_preflight {
13446            return;
13447        }
13448        match parse_control(text) {
13449            Ok(ControlMessage::Hello { requires_sync, .. }) => {
13450                if requires_sync {
13451                    // §8.1: pull before trusting the socket for continuity.
13452                    self.set_sync_needed(true, true);
13453                }
13454            }
13455            Ok(ControlMessage::Presence {
13456                scope_key,
13457                kind,
13458                actor_id,
13459                client_id,
13460                doc,
13461                error,
13462                ..
13463            }) => {
13464                self.apply_presence(scope_key, kind, actor_id, client_id, doc, error);
13465            }
13466            Ok(ControlMessage::Wake { .. }) => {
13467                // §8.3: any wake-up means "run a pull soon", never data.
13468                self.set_sync_needed(true, true);
13469            }
13470            Ok(ControlMessage::Scopes { .. }) => {
13471                // §8.7: surfaced to the app; no sync-needed, no round.
13472                self.scopes_changed += 1;
13473            }
13474            _ => {}
13475        }
13476    }
13477
13478    /// Inbound binary delta: a complete SSP2 response (§8.2), applied like
13479    /// a pull response per section; an unapplied delta is a wake-up.
13480    /// Mailbox hosts send durable acknowledgements on their I/O executor.
13481    pub fn on_realtime_binary_queued(&mut self, bytes: &[u8]) -> Vec<String> {
13482        let mut transport = crate::round::DownloadResults::default();
13483        self.on_realtime_binary(&mut transport, bytes);
13484        transport.controls
13485    }
13486
13487    /// §8.2: a delta applies exactly like a live section and sets the replica
13488    /// cursor to its `throughSeq`; one at or below the replica cursor is a
13489    /// duplicate. A delta the client does not apply (no live unit, a status
13490    /// other than `active`, a decode or apply failure) is a drop and raises
13491    /// sync-needed.
13492    pub fn on_realtime_binary(&mut self, transport: &mut dyn Transport, bytes: &[u8]) {
13493        if self.stopped || !self.transport_enabled || self.security_preflight {
13494            return;
13495        }
13496        #[cfg(feature = "bench-internals")]
13497        let decode_phase = self.benchmark_phases.start(Phase::ResponseDecode);
13498        let message = match decode_message(bytes) {
13499            Ok(m) if m.msg_kind == MsgKind::Response => m,
13500            _ => {
13501                self.set_sync_needed(true, true);
13502                return;
13503            }
13504        };
13505        #[cfg(feature = "bench-internals")]
13506        drop(decode_phase);
13507        // §8.2: a delta's header means what a pull response's header means. A
13508        // schema floor (§1.6) is recorded, stops syncing and applies nothing.
13509        if let Some(Frame::RespHeader {
13510            required_schema_version: Some(required),
13511            latest_schema_version,
13512            ..
13513        }) = message.frames.first()
13514        {
13515            let floor = SchemaFloor {
13516                required_schema_version: Some(*required),
13517                latest_schema_version: *latest_schema_version,
13518            };
13519            if self.set_schema_floor(Some(floor)).is_err() {
13520                self.set_sync_needed(true, true);
13521            }
13522            return;
13523        }
13524        let through = message.frames.iter().find_map(|frame| match frame {
13525            Frame::LiveEnd { through_seq, .. } => Some(*through_seq),
13526            _ => None,
13527        });
13528        let epoch = self.get_meta(LOG_EPOCH_KEY).ok().flatten();
13529        let mut dropped = !matches!(message.frames.first(), Some(Frame::RespHeader {
13530                reset_required: false,
13531                log_epoch,
13532                ..
13533            }) if Some(log_epoch) == epoch.as_ref());
13534        let mut applied: Option<i64> = None;
13535        dropped |= self.begin_coalesced_apply().is_err();
13536        let mut receivers: Option<Vec<UnitRecord>> = None;
13537        for frame in message.frames {
13538            if dropped {
13539                break;
13540            }
13541            match frame {
13542                Frame::LiveStart { status, .. } => {
13543                    let Ok(cursor) = self.stored(replica_cursor(&self.conn)) else {
13544                        dropped = true;
13545                        break;
13546                    };
13547                    if status != LiveStatus::Active || cursor < 0 {
13548                        dropped = true;
13549                    } else if !through.is_some_and(|through| through <= cursor) {
13550                        // A catching-up unit receives no delta (§8.2).
13551                        receivers = self.stored(load_units(&self.conn)).ok().map(|units| {
13552                            units
13553                                .into_iter()
13554                                .filter(|unit| {
13555                                    unit.status == UnitStatus::Active
13556                                        && unit.echo.is_some()
13557                                        && unit.cursor.is_none()
13558                                })
13559                                .collect()
13560                        });
13561                        dropped = receivers.is_none();
13562                    }
13563                }
13564                Frame::Commit {
13565                    commit_seq,
13566                    tables,
13567                    changes,
13568                    ..
13569                } => {
13570                    let Some(receivers) = receivers.clone() else {
13571                        continue;
13572                    };
13573                    dropped = self
13574                        .apply_live_commit(
13575                            &receivers,
13576                            &tables,
13577                            changes,
13578                            commit_seq,
13579                            AppliedServerCommitSource::Delta,
13580                        )
13581                        .is_err();
13582                }
13583                Frame::LiveEnd { through_seq, .. } if receivers.is_some() => {
13584                    dropped = self
13585                        .set_meta(REPLICA_CURSOR_KEY, &through_seq.to_string())
13586                        .is_err();
13587                    applied = Some(through_seq);
13588                }
13589                Frame::Error { .. } => dropped = true,
13590                _ => {}
13591            }
13592        }
13593        // §1.4 rule 4: the ack follows the COMMIT. A failed COMMIT restored
13594        // the replica cursor, so the delta counts as a drop.
13595        if self.finish_coalesced_apply().is_err() || dropped {
13596            applied = None;
13597            dropped = true;
13598        }
13599        if let Some(cursor) = applied {
13600            // §8.2 ack point: the delta's throughSeq.
13601            let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
13602            let _ = transport.realtime_send(&ack);
13603        }
13604        if dropped {
13605            self.set_sync_needed(true, true);
13606        }
13607    }
13608
13609    /// §8.2 ack point after a pull round on a live connection: the replica
13610    /// cursor while it is at least `0`.
13611    fn ack_after_pull(&mut self, transport: &mut dyn Transport) {
13612        if !self.realtime_connected() {
13613            return;
13614        }
13615        if let Ok(cursor @ 0..) = self.stored(replica_cursor(&self.conn)) {
13616            let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
13617            let _ = transport.realtime_send(&ack);
13618        }
13619    }
13620}
13621
13622#[cfg(test)]
13623mod previous_version_wiring_tests;
13624
13625#[cfg(test)]
13626mod identity_tests;
13627
13628#[cfg(test)]
13629mod insert_intent_tests;
13630
13631#[cfg(test)]
13632mod robustness_tests;
13633
13634#[cfg(test)]
13635mod range_image_tests;