Skip to main content

syncular_client/
client.rs

1//! The Syncular v2 Rust client core (SPEC.md client-behavior contract):
2//! rusqlite local storage, §3.2/§3.3 effective-scope persistence + purge,
3//! §4 pull/cursor/bootstrap (§4.7 resume, §5.6 segment application), §6
4//! push with outbox order, §7 optimistic apply / rollback / replay-on-top,
5//! §2.3 clientCommitId idempotency, §8 realtime client rules, §10 errors.
6//!
7//! Built from `SPEC.md` and the committed `ssp2` codec alone — no
8//! reference to the v1 Rust tree or the v2 TypeScript client.
9
10use crate::{ProgressObserver, ProgressPhase, ProgressState};
11use ssp2::encode_message;
12use std::borrow::Cow;
13#[cfg(test)]
14use std::cell::Cell;
15use std::cell::RefCell;
16use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet, VecDeque};
17use std::sync::Arc;
18
19use rusqlite::types::{ToSqlOutput, Value as SqlValue, ValueRef};
20use rusqlite::{Connection, OpenFlags, OptionalExtension};
21use serde::{Deserialize, Serialize};
22use serde_json::{json, Map, Value};
23use sha2::{Digest, Sha256};
24use ssp2::decode::WIRE_VERSION;
25use ssp2::model::{
26    FencedRecord, Frame, LiveStatus, MediaType, Message, MsgKind, Op, OpResult, PushStatus,
27    SubStatus,
28};
29use ssp2::primitives::RawJson;
30use ssp2::registration::canonical_scope_json;
31use ssp2::segment::{decode_rows_segment, Column, ColumnType, ColumnValue, Row, RowsSegment};
32use ssp2::{decode_message, encode_presence_publish, parse_control, ControlMessage, PresenceKind};
33
34use crate::api::{
35    AppliedServerCommit, AppliedServerCommitSource, ClientChangeBatch, ClientDiagnosticsHost,
36    ClientDiagnosticsLease, ClientDiagnosticsReplica, ClientDiagnosticsSchema,
37    ClientDiagnosticsSnapshot, ClientDiagnosticsStorage, ClientError, ClientLimits, CommandEffects,
38    CommitDelivery, CommitOperation, CommitOperationOutcome, CommitOutcome, CommitOutcomeQuery,
39    CommitOutcomeResolution, CommitOutcomeStatus, ConflictRecord, CoverageSnapshot,
40    CurrentBaseProof, CurrentBaseProofReason, DiagnosticLastChange, DiagnosticLastRound,
41    DiagnosticQueryFailure, DiagnosticRoundCounters, DiagnosticUnits, EchoRecord, FetchedBlob,
42    LeaseState, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataPurgeTarget,
43    LocalDataRebootstrapInput, LocalDataRebootstrapResult, Mutation, PresencePeer,
44    PreviousVersionStatus, QueryOwner, QueryReadFailure, QueryRow, QuerySnapshot, QueryValue,
45    RejectionDetails, RejectionRecord, ResolveCommitOutcomeInput, RetainedCommitRow,
46    RetainedUniqueConflict, RowState, SchemaFloor, SnapshotRead, SyncIntent, SyncOutcome,
47    SyncReport, SyncStatusSnapshot, TableChange, UnitCatchup, UnitRecord, UnitScopes, UnitStatus,
48    WindowBase, WindowChange, WindowCoverage, WindowState, WindowUnitRef,
49    CLIENT_DIAGNOSTICS_VERSION, MAX_DIAGNOSTIC_QUERY_FAILURES,
50};
51use crate::api::{RealtimePolicy, RealtimeState, REALTIME_UNAVAILABLE_CODE};
52#[cfg(feature = "bench-internals")]
53use crate::bench::{Phase, Recorder};
54use crate::previous_version::{
55    capture_previous_version_from_replica, first_incompatibility,
56    reconcile_previous_version_at_boot, set_local_schema_descriptor,
57    sweep_previous_version_container, PendingCommitAudit, PreviousVersionContextConfig,
58    PreviousVersionLifecycle, PreviousVersionReadSpec, PreviousVersionSnapshot,
59};
60use crate::schema::{parse_schema_json, ClientSchema, FtsIndexSchema, TableSchema};
61use crate::transport::{BlobDownload, SegmentRequest, Transport, TransportError};
62use crate::values::{
63    bytes_to_hex, column_value_to_json, decode_row_bytes, encode_sparse_row_json, full_row_values,
64    is_canonical_bytes_envelope, json_to_column_value, json_to_scope_map, normalize_values_casing,
65    render_row_id_json, scope_map_to_json,
66};
67
68/// §4.2 default: rows and SQLite images, both applied in committed chunks.
69/// Bit 3 (signed URLs, §5.4) is
70/// added per transport capability at request-build time.
71const DEFAULT_ACCEPT: u8 = 0b0111;
72const ACCEPT_INLINE_ROWS: u8 = 1 << 0;
73const ACCEPT_EXTERNAL_ROWS: u8 = 1 << 1;
74const ACCEPT_SQLITE: u8 = 1 << 2;
75const ACCEPT_SIGNED_URLS: u8 = 1 << 3;
76const MAX_DIAGNOSTIC_DOMAINS: usize = 256;
77
78/// §10.1 `recommendedAction` carried by a server HTTP error body.
79fn recommended_action_of(details: &Option<Value>) -> Option<String> {
80    details
81        .as_ref()?
82        .get("recommendedAction")?
83        .as_str()
84        .map(str::to_owned)
85}
86
87/// §7.4.1 persisted local schema-version marker (`_syncular_meta` key).
88pub(crate) const LOCAL_SCHEMA_VERSION_KEY: &str = "localSchemaVersion";
89const LOCAL_REVISION_KEY: &str = "localRevision";
90/// §4.5 replica cursor; absent means `-1`.
91const REPLICA_CURSOR_KEY: &str = "replicaCursor";
92/// Hex of the last pull `LIVE_END.echoDigest` (§4.2); absent means empty.
93const ECHO_DIGEST_KEY: &str = "echoDigest";
94/// Hex of the registration digest of the list the server stores (§4.1).
95const REGISTERED_DIGEST_KEY: &str = "registrationDigest";
96/// §7.1: the identity of the outbox sequence.
97const OUTBOX_ID_KEY: &str = "outboxId";
98const CLIENT_ID_KEY: &str = "clientId";
99const LEASE_STATE_KEY: &str = "leaseState";
100const SCHEMA_FLOOR_KEY: &str = "schemaFloor";
101pub(crate) const LOG_EPOCH_KEY: &str = "logEpoch";
102/// Persisted fail-closed quarantine marker: present while a security preflight
103/// is pending and `activateSecurity` has yet to run. Storing it in the replica
104/// keeps the gate with the data it protects, so a rebuilt host handle reopening
105/// the same file returns in preflight even though its in-memory state is fresh.
106const SECURITY_PREFLIGHT_PENDING_KEY: &str = "securityPreflightPending";
107const LOCAL_REBOOTSTRAP_RECEIPT_VERSION: u8 = 2;
108const MAX_JS_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
109/// §7.4.4 client-local code: a pending outbox commit cannot re-encode under
110/// the new schema after a bump. Never a wire code (§10.3).
111const OUTBOX_INCOMPATIBLE_CODE: &str = "sync.outbox_incompatible";
112/// §5.11 client-local code: an encode at the push seam resolved no usable key
113/// id or named an unknown key. Never a wire code (§10.3).
114const ENCRYPT_FAILED_CODE: &str = "client.encrypt_failed";
115const INVALID_REQUEST_CODE: &str = "sync.invalid_request:";
116/// §7.4.4: static text for a persisted commit the current codec refuses.
117const LEGACY_VALUE_REFUSAL_MESSAGE: &str =
118    "the persisted commit carries values the current codec refuses";
119/// §7.4.4: bounded reason on every intrinsic value drop.
120const INVALID_STORED_VALUES_REASON: &str = "invalid_stored_values";
121
122#[derive(Debug, Serialize, Deserialize)]
123#[serde(rename_all = "camelCase", deny_unknown_fields)]
124struct PersistedLocalDataRebootstrapReceipt {
125    version: u8,
126    retained_commits: u64,
127    reset_subscriptions: u64,
128}
129
130fn invalid_local_rebootstrap_receipt() -> String {
131    "sync.local_corrupt: persisted local rebootstrap receipt is invalid".to_owned()
132}
133
134fn encode_local_rebootstrap_receipt(
135    retained_commits: usize,
136    reset_subscriptions: usize,
137) -> Result<String, String> {
138    let retained_commits =
139        u64::try_from(retained_commits).map_err(|_| invalid_local_rebootstrap_receipt())?;
140    let reset_subscriptions =
141        u64::try_from(reset_subscriptions).map_err(|_| invalid_local_rebootstrap_receipt())?;
142    if retained_commits > MAX_JS_SAFE_INTEGER || reset_subscriptions > MAX_JS_SAFE_INTEGER {
143        return Err(invalid_local_rebootstrap_receipt());
144    }
145    serde_json::to_string(&PersistedLocalDataRebootstrapReceipt {
146        version: LOCAL_REBOOTSTRAP_RECEIPT_VERSION,
147        retained_commits,
148        reset_subscriptions,
149    })
150    .map_err(|_| invalid_local_rebootstrap_receipt())
151}
152
153fn decode_local_rebootstrap_receipt(value: &str) -> Result<(usize, usize), String> {
154    // Pre-0.15.36 markers proved application but did not retain the receipt.
155    if value == "v1" {
156        return Ok((0, 0));
157    }
158    let receipt: PersistedLocalDataRebootstrapReceipt =
159        serde_json::from_str(value).map_err(|_| invalid_local_rebootstrap_receipt())?;
160    if receipt.version != LOCAL_REBOOTSTRAP_RECEIPT_VERSION
161        || receipt.retained_commits > MAX_JS_SAFE_INTEGER
162        || receipt.reset_subscriptions > MAX_JS_SAFE_INTEGER
163    {
164        return Err(invalid_local_rebootstrap_receipt());
165    }
166    Ok((
167        usize::try_from(receipt.retained_commits)
168            .map_err(|_| invalid_local_rebootstrap_receipt())?,
169        usize::try_from(receipt.reset_subscriptions)
170            .map_err(|_| invalid_local_rebootstrap_receipt())?,
171    ))
172}
173
174#[cfg(test)]
175mod observation_tests;
176
177/// Internal state for hosts that perform network I/O outside the client owner.
178#[doc(hidden)]
179pub struct CurrentBasePreparation {
180    client_commit_id: String,
181    sequence: i64,
182    units: Vec<UnitRecord>,
183    transport_epoch: u64,
184    registration_epoch: u64,
185    security_epoch: u64,
186}
187
188#[cfg(test)]
189mod units_tests;
190
191#[derive(Debug, Clone)]
192struct OutboxOp {
193    upsert: bool,
194    table: String,
195    row_id: String,
196    base_version: Option<i64>,
197    /// Schema-agnostic local form (§0): driver JSON values, encoded with
198    /// the current codec at send time. A key's presence IS the §6.1 sparse
199    /// presence set — both the overlay and the wire payload derive from it.
200    values: Option<Map<String, Value>>,
201    /// §7.1 insert intent: `mutate` recorded this upsert while the row was
202    /// absent from the visible replica. Replay and send-time encoding present
203    /// every current-schema column; a column `values` lacks is NULL.
204    insert: bool,
205}
206
207impl OutboxOp {
208    /// The values this upsert presents under the current `table` (§7.1). An
209    /// insert-intent operation presents every column, a missing one as NULL;
210    /// `None` when a missing column is non-nullable, which leaves the commit
211    /// unencodable (§7.4.4), or when the operation carries no values.
212    fn presented_values(&self, table: &TableSchema) -> Option<Cow<'_, Map<String, Value>>> {
213        let values = self.values.as_ref()?;
214        if !self.insert || table.columns.iter().all(|c| values.contains_key(&c.name)) {
215            return Some(Cow::Borrowed(values));
216        }
217        full_row_values(table, values.clone()).ok().map(Cow::Owned)
218    }
219}
220
221impl From<CommitOperation> for OutboxOp {
222    fn from(operation: CommitOperation) -> Self {
223        Self {
224            upsert: operation.op == "upsert",
225            table: operation.table,
226            row_id: operation.row_id,
227            base_version: operation.base_version,
228            values: operation.values,
229            insert: operation.insert,
230        }
231    }
232}
233
234/// §7.5 static authoring refusal; the table and column travel in details.
235fn invalid_authoring(message: &str, details: Value) -> ClientError {
236    ClientError {
237        code: "sync.invalid_request".to_owned(),
238        message: message.to_owned(),
239        details: Some(details),
240        retryable: false,
241    }
242}
243
244/// §7.1 chained base: `later` repeats `earlier`'s positive base on the same
245/// row and presents only columns `earlier` presents.
246fn chains_on(earlier: &OutboxOp, later: &OutboxOp) -> bool {
247    // Only an upsert carries values, and it always carries its primary key.
248    earlier.row_id == later.row_id
249        && earlier.table == later.table
250        && later.base_version.is_some_and(|base| base > 0)
251        && earlier.base_version == later.base_version
252        && later.values.as_ref().is_some_and(|values| {
253            values.keys().all(|column| {
254                earlier
255                    .values
256                    .as_ref()
257                    .is_some_and(|earlier| earlier.contains_key(column))
258            })
259        })
260}
261
262impl From<&OutboxOp> for CommitOperation {
263    fn from(operation: &OutboxOp) -> Self {
264        Self {
265            table: operation.table.clone(),
266            row_id: operation.row_id.clone(),
267            op: if operation.upsert { "upsert" } else { "delete" }.to_owned(),
268            base_version: operation.base_version,
269            values: operation.values.clone(),
270            insert: operation.insert,
271        }
272    }
273}
274
275#[derive(Debug, Clone)]
276struct OutboxCommit {
277    client_commit_id: String,
278    ops: Vec<OutboxOp>,
279}
280
281/// One commit's `(table, value keys, insert intent)` per upsert operation — the classification
282/// shape the §7.4.4 send-time drop and the RFC 0005 D6 audit share, so the two
283/// can never disagree about which commits cannot re-encode.
284fn commit_audit_operations(commit: &OutboxCommit) -> Vec<(&str, Vec<&str>, bool)> {
285    commit
286        .ops
287        .iter()
288        .filter(|operation| operation.upsert)
289        .map(|operation| {
290            (
291                operation.table.as_str(),
292                operation
293                    .values
294                    .as_ref()
295                    .map(|values| values.keys().map(String::as_str).collect())
296                    .unwrap_or_default(),
297                operation.insert,
298            )
299        })
300        .collect()
301}
302
303type FailedCommit = (OutboxCommit, Map<String, Value>);
304
305#[derive(Debug, Clone)]
306struct CompiledLocalDataPurgeTarget {
307    table: String,
308    selectors: Vec<(String, Vec<String>)>,
309}
310
311struct StoredCommitOutcomeRow {
312    sequence: i64,
313    client_commit_id: String,
314    status: String,
315    recorded_at_ms: i64,
316    results_json: String,
317    operations_json: Option<String>,
318    resolution: String,
319    resolved_at_ms: Option<i64>,
320    replacement_client_commit_id: Option<String>,
321}
322
323impl StoredCommitOutcomeRow {
324    fn from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<Self> {
325        Ok(Self {
326            sequence: row.get(0)?,
327            client_commit_id: row.get(1)?,
328            status: row.get(2)?,
329            recorded_at_ms: row.get(3)?,
330            results_json: row.get(4)?,
331            operations_json: row.get(5)?,
332            resolution: row.get(6)?,
333            resolved_at_ms: row.get(7)?,
334            replacement_client_commit_id: row.get(8)?,
335        })
336    }
337}
338
339/// Section outcome distinguishing the §5.6 unit-local fail-closed
340/// path from a round-aborting failure (§1.4 rule 5).
341/// §4.4 a unit section's `SUB_START`.
342struct SectionStart {
343    id: String,
344    status: SubStatus,
345    reason_code: String,
346    bootstrap: bool,
347    fenced: Vec<FencedRecord>,
348}
349
350enum SectionError {
351    FailClosed,
352    Abort(String, String),
353    Transport(TransportError),
354}
355
356#[derive(Debug)]
357pub(crate) struct RequestMeta {
358    pushed_ids: Vec<String>,
359    /// Hex of the registration digest this pull carried; the server stores
360    /// that list once the round completes (§4.1).
361    registration_digest: String,
362    pub(crate) accept: u8,
363    /// §6.1 splitBatch: outbox commits held back from THIS request because
364    /// the running operation count reached the push cap — the next round
365    /// pushes them (`sync_needed` stays set while any remain).
366    deferred_commits: usize,
367}
368
369#[derive(Default)]
370struct ChangeAccumulator {
371    /// None means table-wide; Some is the exact scoped domain.
372    tables: BTreeMap<String, Option<BTreeSet<String>>>,
373    windows: BTreeMap<String, BTreeSet<String>>,
374    status: bool,
375    conflicts: bool,
376    rejections: bool,
377    outcomes: bool,
378}
379
380impl ChangeAccumulator {
381    fn table(&mut self, table: &str) {
382        self.tables.insert(table.to_owned(), None);
383    }
384
385    fn scope(&mut self, table: &str, key: String) {
386        match self.tables.get_mut(table) {
387            Some(None) => {}
388            Some(Some(keys)) => {
389                keys.insert(key);
390            }
391            None => {
392                self.tables
393                    .insert(table.to_owned(), Some(BTreeSet::from([key])));
394            }
395        }
396    }
397
398    fn window(&mut self, base_key: &str, value: &str) {
399        self.windows
400            .entry(base_key.to_owned())
401            .or_default()
402            .insert(value.to_owned());
403    }
404
405    fn touched(&self) -> bool {
406        !self.tables.is_empty()
407            || !self.windows.is_empty()
408            || self.status
409            || self.conflicts
410            || self.rejections
411            || self.outcomes
412    }
413}
414
415/// §6.1: the server caps total operations per request (reference default
416/// 500) and rejects the whole batch with `sync.too_many_operations`; the
417/// client "splits and retries". Splitting happens at build time: commits are
418/// included IN ORDER until the operation budget is spent, the rest wait for
419/// the next round.
420const PUSH_OPS_PER_REQUEST: usize = 500;
421const MAX_LOCAL_PURGE_TARGETS: usize = 64;
422const MAX_LOCAL_PURGE_SELECTORS: usize = 8;
423const MAX_LOCAL_PURGE_VALUES: usize = 128;
424const MAX_LOCAL_PURGE_VALUE_LENGTH: usize = 256;
425pub const SECURITY_PREFLIGHT_REQUIRED_CODE: &str = "client.security_preflight_required";
426
427/// Dirty visible tables; `None` means a whole-replica recovery/reset.
428struct OverlayDirty(RefCell<Option<BTreeSet<String>>>);
429
430impl OverlayDirty {
431    fn clean() -> Self {
432        Self(RefCell::new(Some(BTreeSet::new())))
433    }
434    fn get(&self) -> bool {
435        self.0
436            .borrow()
437            .as_ref()
438            .is_none_or(|tables| !tables.is_empty())
439    }
440    fn set(&self, dirty: bool) {
441        *self.0.borrow_mut() = if dirty { None } else { Some(BTreeSet::new()) };
442    }
443    fn table(&self, table: &str) {
444        if let Some(tables) = self.0.borrow_mut().as_mut() {
445            tables.insert(table.to_owned());
446        }
447    }
448    fn snapshot(&self) -> Option<BTreeSet<String>> {
449        self.0.borrow().clone()
450    }
451    fn restore(&self, tables: Option<BTreeSet<String>>) {
452        *self.0.borrow_mut() = tables;
453    }
454}
455
456/// A copy-on-write in-memory mirror: a [`Rollback`] shares it, and the first
457/// write after a capture copies it once.
458#[derive(Debug, Clone, Default)]
459struct Shared<T>(Arc<T>);
460
461impl<T> std::ops::Deref for Shared<T> {
462    type Target = T;
463    fn deref(&self) -> &T {
464        &self.0
465    }
466}
467
468impl<T: Clone> std::ops::DerefMut for Shared<T> {
469    fn deref_mut(&mut self) -> &mut T {
470        Arc::make_mut(&mut self.0)
471    }
472}
473
474impl<T> From<T> for Shared<T> {
475    fn from(value: T) -> Self {
476        Self(Arc::new(value))
477    }
478}
479
480/// The in-memory mirrors of durable state, captured before a local
481/// transaction and restored when it rolls back. Queues only grow inside a
482/// transaction, so their lengths suffice.
483#[derive(Debug, Clone)]
484struct Rollback {
485    outbox: Shared<Vec<Arc<OutboxCommit>>>,
486    failed_commits: Shared<Vec<FailedCommit>>,
487    conflicts: Shared<Vec<ConflictRecord>>,
488    rejections: Shared<Vec<RejectionRecord>>,
489    schema_floor: Option<SchemaFloor>,
490    lease_state: Option<LeaseState>,
491    stopped: bool,
492    upgrading: bool,
493    sync_needed: bool,
494    active_round: Option<uuid::Uuid>,
495    overlay_dirty: Option<BTreeSet<String>>,
496    change_queue: usize,
497    sync_intent_queue: usize,
498    last_change: Option<DiagnosticLastChange>,
499}
500
501pub struct SyncClient {
502    #[cfg(feature = "bench-internals")]
503    benchmark_phases: Recorder,
504    conn: Connection,
505    schema: ClientSchema,
506    client_id: String,
507    limits: ClientLimits,
508    outbox: Shared<Vec<Arc<OutboxCommit>>>,
509    failed_commits: Shared<Vec<FailedCommit>>,
510    retain_failed_commits: bool,
511    conflicts: Shared<Vec<ConflictRecord>>,
512    rejections: Shared<Vec<RejectionRecord>>,
513    schema_floor: Option<SchemaFloor>,
514    /// §7.3.5: the opaque auth-lease state (from LEASE frames + lease errors).
515    lease_state: Option<LeaseState>,
516    /// §1.6: the schema-floor response stops syncing until an upgrade.
517    stopped: bool,
518    /// §7.4.5: true while a schema-bump reset + first re-bootstrap is in flight.
519    upgrading: bool,
520    /// §8.4 coalesced sync-needed signal.
521    sync_needed: bool,
522    /// §8.8: how sync rounds treat the realtime binding, and its exact
523    /// availability state with the evidence behind a lost or refused one.
524    realtime_policy: RealtimePolicy,
525    realtime_state: RealtimeState,
526    realtime_reason_code: Option<String>,
527    realtime_retry_delay_ms: Option<u64>,
528    /// §8.6 presence: scopeKey → (`actorId clientId` peer key → peer).
529    presence: HashMap<String, HashMap<String, PresencePeer>>,
530    /// Client clock (epoch ms) for the §5.4 `urlExpiresAtMs` check; the
531    /// host may pin it (conformance runs on a virtual clock).
532    now_ms: Option<i64>,
533    /// §5.11 client-side encryption keys (`keyId → key bytes`). Empty ⇒ E2EE
534    /// off. The encrypt/decrypt seam (`values.rs`) is compiled only under the
535    /// `e2ee` feature; without it, a schema with encrypted columns fails loud.
536    encryption: crate::values::EncryptionConfig,
537    /// Fail-closed host bootstrap gate. While set, command hosts permit only
538    /// status/lifecycle inspection and an exact authorized local purge.
539    security_preflight: bool,
540    security_epoch: u64,
541    transport_enabled: bool,
542    transport_epoch: u64,
543    /// Raised by every registration change; a current-base proof spanning
544    /// one reports missing coverage.
545    registration_epoch: u64,
546    /// RFC 0005 D2/D8: the previous-version capture config. `None` (default)
547    /// means the feature is off; the descriptor write and the container orphan
548    /// sweep still happen.
549    previous_version: Option<PreviousVersionContextConfig>,
550    /// Per-table primary-key upsert SQL, built once per (full table name) —
551    /// the row write path runs per row during bootstrap (§5.6), so the SQL
552    /// string (and, via `prepare_cached`, its compiled statement) is reused
553    /// instead of being rebuilt and re-prepared per row. Cleared on a §7.4.3
554    /// schema reset (the column lists may have changed).
555    insert_sql: RefCell<HashMap<String, String>>,
556    /// §7.1: reconcile only tables whose base/outbox changed. Whole-replica
557    /// reset and restart explicitly invalidate every table.
558    overlay_dirty: OverlayDirty,
559    // First SQLite failure of the current operation, before savepoint cleanup.
560    storage_failure: RefCell<Option<QueryReadFailure>>,
561    /// Test-only structural performance signal: response processing must not
562    /// turn a batch of acknowledgements into one full overlay rebuild each.
563    #[cfg(test)]
564    overlay_rebuild_count: Cell<usize>,
565    #[cfg(test)]
566    acknowledged_replay_count: Cell<usize>,
567    /// Test-only structural performance signal: outcome retention is enforced
568    /// once per response rather than once per acknowledgement.
569    #[cfg(test)]
570    outcome_prune_count: Cell<usize>,
571    /// Exact observer-transaction output drained by command/FFI hosts.
572    progress: ProgressObserver,
573    change_queue: VecDeque<ClientChangeBatch>,
574    sync_intent_queue: VecDeque<SyncIntent>,
575    /// Explicit exponential retry policy for transient transport failures.
576    retry_delay_ms: u64,
577    /// §7.7: the background retry the current round scheduled, if any.
578    round_retry_delay_ms: Option<u64>,
579    /// A round whose response never completed (§1.5): the client keeps its
580    /// code and reports it on every following request until a round receives a
581    /// complete, decodable response. The server already recorded the round, so
582    /// nothing else can tell it the round failed on this side.
583    round_failure: Option<String>,
584    active_round: Option<uuid::Uuid>,
585    last_round: Option<DiagnosticLastRound>,
586    last_change: Option<DiagnosticLastChange>,
587    /// §7.6: latest failed owned snapshot read per owner id, oldest first.
588    query_failures: Vec<DiagnosticQueryFailure>,
589    /// SPEC §1.4 rule 4: the open coalesced apply transaction of a response.
590    coalesced: Option<CoalescedApply>,
591    /// A coalesced apply transaction of the current response failed; every
592    /// later observation of that response fails until it ends.
593    coalesced_failure: Option<String>,
594}
595
596/// SPEC §1.4 rule 4: the frames and blocks of one response share one local
597/// write transaction of at most `COALESCED_APPLY_ROWS` rows. The in-memory
598/// state captured at its `BEGIN` is restored when its `COMMIT` fails.
599struct CoalescedApply {
600    rows: usize,
601    rollback: Rollback,
602}
603
604const COALESCED_APPLY_ROWS: usize = 1024;
605
606pub(crate) fn quote_ident(name: &str) -> String {
607    format!("\"{}\"", name.replace('"', "\"\""))
608}
609/// §7.4.1 `_syncular_meta` helpers. Free functions so RFC 0005's
610/// previous-version module reads and writes the SAME records as the client
611/// instead of growing a parallel meta layer.
612pub(crate) fn meta_get(conn: &Connection, key: &str) -> rusqlite::Result<Option<String>> {
613    conn.query_row(
614        "SELECT value FROM _syncular_meta WHERE key = ?1",
615        rusqlite::params![key],
616        |row| row.get::<_, String>(0),
617    )
618    .optional()
619}
620
621pub(crate) fn meta_set(conn: &Connection, key: &str, value: &str) -> rusqlite::Result<()> {
622    conn.execute(
623        "INSERT OR REPLACE INTO _syncular_meta (key, value) VALUES (?1, ?2)",
624        rusqlite::params![key, value],
625    )
626    .map(|_| ())
627}
628
629pub(crate) fn meta_delete(conn: &Connection, key: &str) -> rusqlite::Result<()> {
630    conn.execute(
631        "DELETE FROM _syncular_meta WHERE key = ?1",
632        rusqlite::params![key],
633    )
634    .map(|_| ())
635}
636
637/// Seek by the existing key while retaining the exact legacy text match.
638fn row_id_predicate(table: &TableSchema) -> String {
639    let key = quote_ident(&table.primary_key);
640    let text_match = format!("CAST({key} AS TEXT) = ?1");
641    match table.columns[table.pk_index].ty {
642        ColumnType::String | ColumnType::Json => {
643            format!("{key} = ?1 AND {text_match}")
644        }
645        // Native columns have no declared SQLite affinity. Match the stored
646        // integer bind type explicitly. Unary + removes expression affinity so
647        // SQLite can seek the typeless key; the text check preserves exact IDs.
648        ColumnType::Integer | ColumnType::Boolean => {
649            format!("{key} = +CAST(?1 AS INTEGER) AND {text_match}")
650        }
651        // REAL-to-text conversion can round distinct values to the same text.
652        // Narrowing those matches by numeric equality would change behavior.
653        _ => text_match,
654    }
655}
656
657/// §3.3/§4.8/§5.6 row ownership: rows whose local scope columns match
658/// `effective` and that no entry of `owners` matches. `owners` holds the
659/// pair scopes of every owner of the table (§3.3 row ownership); a scoped delete never removes a row one of them still covers.
660/// Scope values bind by the column's declared type, as `row_id_predicate`
661/// does. `Ok(None)` matches nothing (an empty map or value list); `Err(())`
662/// is a missing local scope-column mapping (the fail-closed case).
663fn local_scope_predicate(
664    table: &TableSchema,
665    effective: &[(String, Vec<String>)],
666    owners: &[Vec<(String, Vec<String>)>],
667) -> Result<Option<(String, Vec<SqlValue>)>, ()> {
668    if effective.is_empty() || effective.iter().any(|(_, values)| values.is_empty()) {
669        return Ok(None);
670    }
671    let column = |variable: &str| {
672        let name = table.scope_column(variable).ok_or(())?;
673        let column = table
674            .columns
675            .iter()
676            .find(|column| column.name == name)
677            .ok_or(())?;
678        Ok((quote_ident(name), column.ty == ColumnType::Integer))
679    };
680    let mut clauses = Vec::new();
681    let mut params = Vec::new();
682    for (variable, values) in effective {
683        let (key, integer) = column(variable)?;
684        let holes = vec!["?"; values.len()].join(", ");
685        clauses.push(if integer {
686            params.extend(values.iter().cloned().map(SqlValue::Text));
687            let seek = vec!["+CAST(? AS INTEGER)"; values.len()].join(", ");
688            format!("{key} IN ({seek}) AND CAST({key} AS TEXT) IN ({holes})")
689        } else {
690            format!("{key} IN ({holes})")
691        });
692        params.extend(values.iter().cloned().map(SqlValue::Text));
693    }
694    // Owners bind as one JSON parameter per variable set, so the statement
695    // keeps its size at any owner count; owners of one variable bind the
696    // union of their values. An owner holding other values of a variable
697    // `effective` names owns none of its rows and drops out. Values compare
698    // as text, the exact semantics of the effective clauses.
699    let mut groups: BTreeMap<Vec<&str>, Vec<Vec<&[String]>>> = BTreeMap::new();
700    for owner in owners {
701        if owner.is_empty()
702            || owner.iter().any(|(variable, values)| {
703                values.is_empty()
704                    || effective.iter().any(|(name, wanted)| {
705                        name == variable && wanted.iter().all(|value| !values.contains(value))
706                    })
707            })
708        {
709            continue;
710        }
711        let mut owner: Vec<_> = owner.iter().collect();
712        owner.sort_by(|a, b| a.0.cmp(&b.0));
713        groups
714            .entry(
715                owner
716                    .iter()
717                    .map(|(variable, _)| variable.as_str())
718                    .collect(),
719            )
720            .or_default()
721            .push(owner.iter().map(|(_, values)| values.as_slice()).collect());
722    }
723    let within = |variable: &str, list: &str| {
724        let (key, integer) = column(variable)?;
725        let key = if integer {
726            format!("CAST({key} AS TEXT)")
727        } else {
728            key
729        };
730        Ok(format!("{key} IN (SELECT value FROM json_each({list}))"))
731    };
732    for (variables, tuples) in groups {
733        if let [variable] = variables[..] {
734            let values: BTreeSet<&String> = tuples.iter().flatten().copied().flatten().collect();
735            params.push(SqlValue::Text(
736                Value::from_iter(values.into_iter().cloned()).to_string(),
737            ));
738            clauses.push(format!("NOT {}", within(variable, "?")?));
739        } else {
740            params.push(SqlValue::Text(
741                serde_json::to_string(&tuples).expect("owner tuples serialize"),
742            ));
743            let matches = variables
744                .iter()
745                .enumerate()
746                .map(|(index, variable)| within(variable, &format!("o.value,'$[{index}]'")))
747                .collect::<Result<Vec<_>, ()>>()?;
748            clauses.push(format!(
749                "NOT EXISTS (SELECT 1 FROM json_each(?) o WHERE {})",
750                matches.join(" AND ")
751            ));
752        }
753    }
754    Ok(Some((clauses.join(" AND "), params)))
755}
756
757/// [`local_scope_predicate`] over decoded row values (retained rows).
758fn owns_local_row(
759    table: &TableSchema,
760    effective: &[(String, Vec<String>)],
761    owners: &[Vec<(String, Vec<String>)>],
762    values: &Map<String, Value>,
763) -> bool {
764    let matches = |scopes: &[(String, Vec<String>)]| {
765        !scopes.is_empty()
766            && scopes.iter().all(|(variable, allowed)| {
767                table
768                    .scope_column(variable)
769                    .and_then(|column| values.get(column))
770                    .filter(|value| !value.is_null())
771                    .is_some_and(|value| {
772                        allowed.contains(
773                            &value
774                                .as_str()
775                                .map_or_else(|| value.to_string(), str::to_owned),
776                        )
777                    })
778            })
779    };
780    matches(effective) && !owners.iter().any(|owner| matches(owner))
781}
782
783fn is_local_operation_code_like(value: &str) -> bool {
784    let bytes = value.as_bytes();
785    bytes.first().is_some_and(u8::is_ascii_alphanumeric)
786        && bytes
787            .iter()
788            .all(|byte| byte.is_ascii_alphanumeric() || matches!(*byte, b'.' | b'_' | b':' | b'-'))
789}
790
791fn base_table(name: &str) -> String {
792    quote_ident(&format!("_syncular_base_{name}"))
793}
794
795/// §4.8 deferred eviction record: (unit id, table, effective scope map).
796type PendingEvict = (String, String, Vec<(String, Vec<String>)>);
797
798/// §4.8: a stable key for a window base: variable + canonical fixed scopes.
799fn window_base_key(base: &WindowBase) -> String {
800    format!(
801        "{}\0{}",
802        base.variable,
803        ssp2::registration::canonical_unit_json(&scope_pairs(&base.fixed_scopes))
804    )
805}
806
807/// The unit of one window value: the fixed scopes plus the value.
808fn window_unit_scopes(base: &WindowBase, value: &str) -> UnitScopes {
809    let mut scopes = base.fixed_scopes.clone();
810    scopes.insert(base.variable.clone(), value.to_owned());
811    scopes
812}
813
814/// A unit's scope map as the codec and the digests take it.
815fn scope_pairs(scopes: &UnitScopes) -> Vec<(String, String)> {
816    let mut pairs: Vec<(String, String)> = scopes
817        .iter()
818        .map(|(variable, value)| (variable.clone(), value.clone()))
819        .collect();
820    pairs.sort_by(|a, b| a.0.encode_utf16().cmp(b.0.encode_utf16()));
821    pairs
822}
823
824/// §4.1: the unit covers every table declaring all of its variables.
825fn covers(table: &TableSchema, scopes: &UnitScopes) -> bool {
826    scopes
827        .keys()
828        .all(|variable| table.scope_column(variable).is_some())
829}
830
831/// §4.4: the effective scopes of the (unit, table) pair under `echo`: the
832/// scope map as one-element lists plus the fenced lists. `None` when the
833/// fence revoked the pair.
834fn pair_scopes(
835    scopes: &UnitScopes,
836    table: &str,
837    echo: Option<&[EchoRecord]>,
838) -> Option<Vec<(String, Vec<String>)>> {
839    let fenced = echo.and_then(|echo| echo.iter().find(|record| record.table == table));
840    if fenced.is_some_and(|record| record.status == "revoked") {
841        return None;
842    }
843    let mut effective: BTreeMap<String, Vec<String>> = fenced
844        .map(|record| record.scopes.clone())
845        .unwrap_or_default();
846    for (variable, value) in scopes {
847        effective.insert(variable.clone(), vec![value.clone()]);
848    }
849    Some(effective.into_iter().collect())
850}
851
852/// §3.3 row ownership: the pair scopes of every owner of `table` except
853/// `except_id`. An owner is active with a persisted echo and live or
854/// post-bootstrap, or bootstrapping with a segment of the table in its
855/// current bootstrap.
856fn unit_owners(
857    units: &[UnitRecord],
858    table: &TableSchema,
859    except_id: &str,
860) -> Vec<Vec<(String, Vec<String>)>> {
861    units
862        .iter()
863        .filter(|unit| {
864            unit.id != except_id
865                && unit.status == UnitStatus::Active
866                && unit.echo.is_some()
867                && (!unit.bootstrapping() || unit.seeded.contains(&table.name))
868                && covers(table, &unit.scopes)
869        })
870        .filter_map(|unit| pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()))
871        .collect()
872}
873
874/// §5.5 / §5.6: the unit's scope map, each value a one-element list.
875fn unit_scope_lists(scopes: &UnitScopes) -> Vec<(String, Vec<String>)> {
876    scopes
877        .iter()
878        .map(|(variable, value)| (variable.clone(), vec![value.clone()]))
879        .collect()
880}
881
882/// §7.1 acknowledged intent of the rows `?1` names (`[[table, id], ...]`).
883/// It joins through the (tbl, id) index: a scan per acknowledgement would
884/// make draining a batch quadratic.
885const 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";
886
887const UNIT_COLUMNS: &str =
888    "id, scopes, explicit, status, reason_code, cursor, bootstrap_state, seeded, echo";
889
890/// A unit row; a field that does not parse is a conversion failure, which
891/// both read paths classify as `sync.local_corrupt`.
892fn unit_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<UnitRecord> {
893    fn json<T: serde::de::DeserializeOwned>(index: usize, raw: &str) -> rusqlite::Result<T> {
894        serde_json::from_str(raw).map_err(|error| {
895            rusqlite::Error::FromSqlConversionFailure(
896                index,
897                rusqlite::types::Type::Text,
898                Box::new(error),
899            )
900        })
901    }
902    Ok(UnitRecord {
903        id: row.get(0)?,
904        scopes: json(1, &row.get::<_, String>(1)?)?,
905        explicit: row.get::<_, i64>(2)? == 1,
906        status: json(
907            3,
908            &serde_json::to_string(&row.get::<_, String>(3)?).expect("text"),
909        )?,
910        reason_code: row.get(4)?,
911        cursor: row.get(5)?,
912        bootstrap_state: row.get(6)?,
913        seeded: json(7, &row.get::<_, String>(7)?)?,
914        echo: row
915            .get::<_, Option<String>>(8)?
916            .map(|echo| json::<Vec<EchoRecord>>(8, &echo))
917            .transpose()?
918            .map(|echo| {
919                if echo
920                    .iter()
921                    .all(|record| record.status == "active" || record.status == "revoked")
922                {
923                    Ok(echo)
924                } else {
925                    Err(rusqlite::Error::FromSqlConversionFailure(
926                        8,
927                        rusqlite::types::Type::Text,
928                        "echo status is neither active nor revoked".into(),
929                    ))
930                }
931            })
932            .transpose()?,
933    })
934}
935
936/// Every unit in registration order (§4.1).
937fn load_units(conn: &Connection) -> rusqlite::Result<Vec<UnitRecord>> {
938    conn.prepare_cached(&format!(
939        "SELECT {UNIT_COLUMNS} FROM _syncular_units ORDER BY rowid"
940    ))?
941    .query_map([], unit_from_row)?
942    .collect()
943}
944
945fn get_unit(conn: &Connection, id: &str) -> rusqlite::Result<Option<UnitRecord>> {
946    conn.query_row(
947        &format!("SELECT {UNIT_COLUMNS} FROM _syncular_units WHERE id = ?1"),
948        [id],
949        unit_from_row,
950    )
951    .optional()
952}
953
954/// Insert or update in place: an update keeps the registration order.
955fn save_unit(conn: &Connection, unit: &UnitRecord) -> rusqlite::Result<()> {
956    conn.prepare_cached(&format!(
957        "INSERT INTO _syncular_units({UNIT_COLUMNS}) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9)
958         ON CONFLICT(id) DO UPDATE SET explicit=excluded.explicit, status=excluded.status,
959           reason_code=excluded.reason_code, cursor=excluded.cursor,
960           bootstrap_state=excluded.bootstrap_state, seeded=excluded.seeded, echo=excluded.echo"
961    ))?
962    .execute(rusqlite::params![
963        unit.id,
964        serde_json::to_string(&unit.scopes).expect("scope map serializes"),
965        i64::from(unit.explicit),
966        unit.status.name(),
967        unit.reason_code,
968        unit.cursor,
969        unit.bootstrap_state,
970        serde_json::to_string(&unit.seeded).expect("table list serializes"),
971        unit.echo
972            .as_ref()
973            .map(|echo| serde_json::to_string(echo).expect("echo serializes")),
974    ])
975    .map(|_| ())
976}
977
978/// §4.1 references: every window registry entry `(base, value)` holding a unit.
979fn window_refs(conn: &Connection, unit_id: &str) -> rusqlite::Result<Vec<(String, String)>> {
980    conn.prepare_cached("SELECT base, unit FROM _syncular_windows WHERE sub_id = ?1")?
981        .query_map([unit_id], |row| Ok((row.get(0)?, row.get(1)?)))?
982        .collect()
983}
984
985/// §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
986/// registrations and discard every synced state, so the next round sends the
987/// list and fresh-bootstraps every unit. The caller owns the transaction.
988fn reset_units(conn: &Connection) -> rusqlite::Result<()> {
989    conn.execute_batch(
990        "UPDATE _syncular_units SET status='active', reason_code=NULL, cursor=-1,
991           bootstrap_state=NULL, seeded='[]', echo=NULL;
992         DELETE FROM _syncular_meta WHERE key IN ('replicaCursor','echoDigest','registrationDigest');",
993    )
994}
995
996/// §4.5: the replica cursor, `-1` while no unit is live.
997fn replica_cursor(conn: &Connection) -> rusqlite::Result<i64> {
998    meta_get(conn, REPLICA_CURSOR_KEY)?.map_or(Ok(-1), |raw| {
999        raw.parse().map_err(|error| {
1000            rusqlite::Error::FromSqlConversionFailure(
1001                0,
1002                rusqlite::types::Type::Text,
1003                Box::new(error),
1004            )
1005        })
1006    })
1007}
1008
1009fn visible_table(name: &str) -> String {
1010    quote_ident(name)
1011}
1012
1013const FTS_SOURCE_ID_COLUMN: &str = "_syncular_source_id";
1014
1015/// §7.4.3: is a `sqlite_master` table name a synced table (visible or base),
1016/// i.e. NOT one of the durable bookkeeping tables the reset preserves?
1017fn is_synced_table_name(name: &str) -> bool {
1018    if name.starts_with("sqlite_") {
1019        return false;
1020    }
1021    if name.starts_with("_syncular_base_") {
1022        return true; // the base half of a synced table pair
1023    }
1024    // Bookkeeping: outbox, units, meta, blob cache/uploads.
1025    !name.starts_with("_syncular_")
1026}
1027
1028/// `"sha256:" + hex` of the bytes — the content address (§5.9.1).
1029fn blob_id_for(bytes: &[u8]) -> String {
1030    let digest = Sha256::digest(bytes);
1031    format!("sha256:{}", bytes_to_hex(&digest))
1032}
1033
1034/// One [`SyncClient::write_row`] bind parameter, borrowing the row-codec
1035/// value it wraps — strings/JSON/bytes bind as borrowed TEXT/BLOB (no copy
1036/// per row on the §5.6 bootstrap path), scalars bind owned.
1037enum RowParam<'a> {
1038    Cell(&'a Option<ColumnValue>),
1039    Version(i64),
1040}
1041
1042impl rusqlite::ToSql for RowParam<'_> {
1043    fn to_sql(&self) -> rusqlite::Result<ToSqlOutput<'_>> {
1044        Ok(match self {
1045            RowParam::Version(v) => ToSqlOutput::Owned(SqlValue::Integer(*v)),
1046            RowParam::Cell(cell) => match cell {
1047                None => ToSqlOutput::Owned(SqlValue::Null),
1048                Some(ColumnValue::String(s)) => ToSqlOutput::Borrowed(ValueRef::Text(s.as_bytes())),
1049                Some(ColumnValue::Integer(i)) => ToSqlOutput::Owned(SqlValue::Integer(*i)),
1050                Some(ColumnValue::Float(f)) => ToSqlOutput::Owned(SqlValue::Real(*f)),
1051                Some(ColumnValue::Boolean(b)) => {
1052                    ToSqlOutput::Owned(SqlValue::Integer(i64::from(*b)))
1053                }
1054                Some(ColumnValue::Json(raw)) | Some(ColumnValue::BlobRef(raw)) => {
1055                    ToSqlOutput::Borrowed(ValueRef::Text(raw.0.as_bytes()))
1056                }
1057                // §5.10: crdt bytes store as BLOB, like bytes.
1058                Some(ColumnValue::Bytes(b)) | Some(ColumnValue::Crdt(b)) => {
1059                    ToSqlOutput::Borrowed(ValueRef::Blob(b))
1060                }
1061            },
1062        })
1063    }
1064}
1065
1066// Retain a typed primary key across the current import chunk without copying row payloads.
1067fn owned_sql_value(param: impl rusqlite::ToSql) -> Result<SqlValue, String> {
1068    match param.to_sql().map_err(|error| error.to_string())? {
1069        ToSqlOutput::Owned(value) => Ok(value),
1070        ToSqlOutput::Borrowed(value) => {
1071            SqlValue::try_from(value).map_err(|error| error.to_string())
1072        }
1073        _ => Err("sync.invalid_request: unsupported SQLite key parameter".into()),
1074    }
1075}
1076
1077/// §5.3 image cell → bind parameter, strict per the declared column type
1078/// (`boolean` from INTEGER 0/1, `json` from its raw TEXT, NULL only when
1079/// nullable). Mismatches are image-producer violations. Returns the cell
1080/// borrowed when the stored representation already matches what the row
1081/// codec would write, or the normalized scalar (boolean → 0/1, float from
1082/// INTEGER → REAL) otherwise — the local write is byte-identical to the
1083/// old convert-then-insert path without allocating per cell.
1084fn image_cell_param<'a>(column: &Column, value: ValueRef<'a>) -> Result<ToSqlOutput<'a>, String> {
1085    use ssp2::segment::ColumnType;
1086    let mismatch = || {
1087        Err(format!(
1088            "image column {:?} holds a value of the wrong type",
1089            column.name
1090        ))
1091    };
1092    match value {
1093        ValueRef::Null => {
1094            if !column.nullable {
1095                return Err(format!(
1096                    "image column {:?} is NULL but not nullable",
1097                    column.name
1098                ));
1099            }
1100            Ok(ToSqlOutput::Owned(SqlValue::Null))
1101        }
1102        ValueRef::Integer(i) => match column.ty {
1103            ColumnType::Integer => Ok(ToSqlOutput::Borrowed(value)),
1104            ColumnType::Boolean => Ok(ToSqlOutput::Owned(SqlValue::Integer(i64::from(i != 0)))),
1105            ColumnType::Float => Ok(ToSqlOutput::Owned(SqlValue::Real(i as f64))),
1106            _ => mismatch(),
1107        },
1108        ValueRef::Real(_) => match column.ty {
1109            ColumnType::Float => Ok(ToSqlOutput::Borrowed(value)),
1110            _ => mismatch(),
1111        },
1112        ValueRef::Text(t) => {
1113            std::str::from_utf8(t)
1114                .map_err(|_| format!("image column {:?} is not UTF-8", column.name))?;
1115            match column.ty {
1116                ColumnType::String | ColumnType::Json | ColumnType::BlobRef => {
1117                    Ok(ToSqlOutput::Borrowed(value))
1118                }
1119                _ => mismatch(),
1120            }
1121        }
1122        ValueRef::Blob(_) => match column.ty {
1123            // §5.10: a crdt column stores its opaque bytes as BLOB, like bytes.
1124            ColumnType::Bytes | ColumnType::Crdt => Ok(ToSqlOutput::Borrowed(value)),
1125            _ => mismatch(),
1126        },
1127    }
1128}
1129
1130pub(crate) fn sql_ref_to_json(column: &Column, value: rusqlite::types::ValueRef<'_>) -> Value {
1131    use rusqlite::types::ValueRef;
1132    match value {
1133        ValueRef::Null => Value::Null,
1134        ValueRef::Integer(i) => match column.ty {
1135            ssp2::segment::ColumnType::Boolean => Value::Bool(i != 0),
1136            ssp2::segment::ColumnType::Float => {
1137                serde_json::Number::from_f64(i as f64).map_or(Value::Null, Value::Number)
1138            }
1139            _ => Value::from(i),
1140        },
1141        ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1142        ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1143        ValueRef::Blob(b) => {
1144            let mut map = Map::new();
1145            map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1146            Value::Object(map)
1147        }
1148    }
1149}
1150
1151/// Bind a driver JSON value form as a rusqlite parameter for [`SyncClient::query`].
1152/// Objects are accepted in lossless `{"$bytes": hex}` and
1153/// `{"$bigint": decimal}` envelope forms.
1154fn json_param_to_sql(value: &Value) -> Result<SqlValue, String> {
1155    Ok(match value {
1156        Value::Null => SqlValue::Null,
1157        Value::Bool(b) => SqlValue::Integer(i64::from(*b)),
1158        Value::Number(n) => {
1159            if let Some(i) = n.as_i64() {
1160                SqlValue::Integer(i)
1161            } else if let Some(f) = n.as_f64() {
1162                SqlValue::Real(f)
1163            } else {
1164                return Err(format!("query param number {n} is out of range"));
1165            }
1166        }
1167        Value::String(s) => SqlValue::Text(s.clone()),
1168        Value::Object(_) => {
1169            if let Some(hex) = value.get("$bytes").and_then(Value::as_str) {
1170                SqlValue::Blob(crate::values::hex_to_bytes(hex)?)
1171            } else if let Some(decimal) = value.get("$bigint").and_then(Value::as_str) {
1172                SqlValue::Integer(decimal.parse::<i64>().map_err(|_| {
1173                    format!("query bigint param {decimal:?} is outside SQLite's i64 range")
1174                })?)
1175            } else {
1176                return Err(
1177                    "query object param must be a {$bytes: hex} or {$bigint: decimal} value"
1178                        .to_owned(),
1179                );
1180            }
1181        }
1182        Value::Array(_) => return Err("query array params are not supported".to_owned()),
1183    })
1184}
1185
1186/// Map a rusqlite value with no schema column to consult (arbitrary query
1187/// output): integers/reals/text pass through by stored affinity, blobs ride
1188/// as `{"$bytes": hex}`. Distinct from [`sql_ref_to_json`], which uses the
1189/// schema column type to recover booleans/floats/json.
1190fn sql_ref_to_json_dynamic(value: rusqlite::types::ValueRef<'_>) -> Value {
1191    use rusqlite::types::ValueRef;
1192    match value {
1193        ValueRef::Null => Value::Null,
1194        ValueRef::Integer(i) => {
1195            // JSON/Tauri IPC cannot represent every SQLite i64 exactly. Keep
1196            // ordinary UI-sized integers ergonomic and envelope only values
1197            // beyond JavaScript's safe range.
1198            const MAX_SAFE_INTEGER: i64 = 9_007_199_254_740_991;
1199            if (-MAX_SAFE_INTEGER..=MAX_SAFE_INTEGER).contains(&i) {
1200                Value::from(i)
1201            } else {
1202                let mut map = Map::new();
1203                map.insert("$bigint".to_owned(), Value::from(i.to_string()));
1204                Value::Object(map)
1205            }
1206        }
1207        ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1208        ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1209        ValueRef::Blob(b) => {
1210            let mut map = Map::new();
1211            map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1212            Value::Object(map)
1213        }
1214    }
1215}
1216
1217/// §7.5: SQLite failures classify by result code into [`QueryReadFailure`].
1218fn query_connection(
1219    conn: &Connection,
1220    sql: &str,
1221    params: &[QueryValue],
1222) -> Result<Vec<QueryRow>, QueryReadFailure> {
1223    let lowered_sql = crate::query_guard::lower_public_query_sql(sql);
1224    let mut stmt = crate::query_guard::prepare_read_only(conn, &lowered_sql)?;
1225    let bound: Vec<SqlValue> = params
1226        .iter()
1227        .map(json_param_to_sql)
1228        .collect::<Result<_, _>>()?;
1229    // §2.4: an unaliased physical version column stays engine-internal, so a
1230    // `SELECT *` row feeds straight back into mutation values. An explicit
1231    // alias (`_sync_version AS v`) returns it as ordinary query data.
1232    let columns: Vec<(usize, String)> = stmt
1233        .column_names()
1234        .enumerate()
1235        .filter(|(_, name)| *name != "_syncular_version")
1236        .map(|(i, name)| (i, name.to_owned()))
1237        .collect();
1238    let bound_refs: Vec<&dyn rusqlite::ToSql> =
1239        bound.iter().map(|v| v as &dyn rusqlite::ToSql).collect();
1240    let mut sql_rows = stmt.query(bound_refs.as_slice())?;
1241    let mut out = Vec::new();
1242    while let Some(row) = sql_rows.next()? {
1243        let mut record = Map::new();
1244        for (i, name) in &columns {
1245            let value = row.get_ref(*i)?;
1246            record.insert(name.clone(), sql_ref_to_json_dynamic(value));
1247        }
1248        out.push(record);
1249    }
1250    Ok(out)
1251}
1252
1253fn persisted_window_state(
1254    conn: &Connection,
1255    base: &WindowBase,
1256) -> Result<WindowState, QueryReadFailure> {
1257    let mut stmt = conn.prepare(
1258        "SELECT windows.unit, units.status, units.cursor, units.bootstrap_state
1259           FROM _syncular_windows AS windows
1260           LEFT JOIN _syncular_units AS units ON units.id = windows.sub_id
1261          WHERE windows.base = ?1
1262          ORDER BY windows.unit ASC",
1263    )?;
1264    let rows = stmt.query_map(rusqlite::params![window_base_key(base)], |row| {
1265        Ok((
1266            row.get::<_, String>(0)?,
1267            row.get::<_, Option<String>>(1)?,
1268            row.get::<_, Option<i64>>(2)?,
1269            row.get::<_, Option<String>>(3)?,
1270        ))
1271    })?;
1272    let mut units = Vec::new();
1273    let mut pending = Vec::new();
1274    for row in rows {
1275        let (unit, status, cursor, bootstrap_state) = row?;
1276        // §4.8: complete iff registered, active and not bootstrapping.
1277        if status.as_deref() != Some("active")
1278            || cursor.is_some_and(|cursor| cursor < 0 || bootstrap_state.is_some())
1279        {
1280            pending.push(unit.clone());
1281        }
1282        units.push(unit);
1283    }
1284    Ok(WindowState { units, pending })
1285}
1286
1287/// One read-only statement in a §7.5 snapshot read.
1288#[derive(Debug, Clone, Copy)]
1289pub struct SnapshotStatement<'a> {
1290    pub sql: &'a str,
1291    pub params: &'a [Value],
1292}
1293
1294/// A §7.5 atomic read request: read-only statements, window coverage, unit
1295/// catch-up states, and commit deliveries, all resolved from one SQLite read
1296/// transaction and one revision.
1297#[derive(Debug, Clone, Default)]
1298pub struct SnapshotReadRequest<'a> {
1299    pub statements: Vec<SnapshotStatement<'a>>,
1300    pub coverage: &'a [WindowCoverage],
1301    pub units: Vec<String>,
1302    pub commit_ids: Vec<String>,
1303}
1304
1305#[cfg(test)]
1306thread_local! {
1307    /// Test-only rendezvous that runs between the statements of one snapshot
1308    /// read. A test uses it to commit on another connection mid-read and prove
1309    /// the read transaction's snapshot and revision stay stable.
1310    static SNAPSHOT_READ_HOOK: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
1311        std::cell::RefCell::new(None);
1312}
1313
1314#[cfg(test)]
1315fn run_snapshot_read_hook() {
1316    SNAPSHOT_READ_HOOK.with(|slot| {
1317        if let Some(hook) = slot.borrow_mut().take() {
1318            hook();
1319        }
1320    });
1321}
1322
1323/// §7.5: resolve a request over one SQLite read transaction. The revision,
1324/// every statement's rows, coverage, catch-up states, and deliveries are
1325/// captured under one `SAVEPOINT`; any statement's failure rolls the whole
1326/// read back and releases the connection.
1327fn snapshot_read_connection(
1328    conn: &Connection,
1329    request: &SnapshotReadRequest<'_>,
1330) -> Result<SnapshotRead, QueryReadFailure> {
1331    conn.execute_batch("SAVEPOINT syncular_snapshot_read")?;
1332    let corrupt = |message: &str| QueryReadFailure {
1333        code: Some("sync.local_corrupt"),
1334        sqlite_code: None,
1335        sqlite_message: None,
1336        rollback_failure: None,
1337        message: message.to_owned(),
1338    };
1339    let stored_failure = |error: rusqlite::Error, message: &str| match error {
1340        rusqlite::Error::Utf8Error(..)
1341        | rusqlite::Error::InvalidColumnType(..)
1342        | rusqlite::Error::FromSqlConversionFailure(..)
1343        | rusqlite::Error::IntegralValueOutOfRange(..) => corrupt(message),
1344        _ => QueryReadFailure::from(error),
1345    };
1346    let result: Result<SnapshotRead, QueryReadFailure> = (|| {
1347        // The durable revision as a canonical decimal `u64`; a missing marker
1348        // is the legacy zero, and any other non-canonical value is corrupt.
1349        let revision: Option<String> = conn
1350            .query_row(
1351                "SELECT value FROM _syncular_meta WHERE key = ?1",
1352                rusqlite::params![LOCAL_REVISION_KEY],
1353                |row| row.get(0),
1354            )
1355            .optional()
1356            .map_err(|error| stored_failure(error, "persisted local revision is invalid"))?;
1357        let revision = match revision {
1358            None => "0".to_owned(),
1359            Some(value)
1360                if value == "0"
1361                    || (matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1362                        && value.bytes().all(|b| b.is_ascii_digit())
1363                        && value.parse::<u64>().is_ok()) =>
1364            {
1365                value
1366            }
1367            Some(_) => return Err(corrupt("persisted local revision is invalid")),
1368        };
1369        let mut queries = Vec::with_capacity(request.statements.len());
1370        for statement in &request.statements {
1371            queries.push(query_connection(conn, statement.sql, statement.params)?);
1372            #[cfg(test)]
1373            run_snapshot_read_hook();
1374        }
1375        let mut pending = Vec::new();
1376        let mut missing = Vec::new();
1377        for requested in request.coverage {
1378            let base_key = window_base_key(&requested.base);
1379            let state = persisted_window_state(conn, &requested.base)?;
1380            for unit in BTreeSet::from_iter(requested.units.iter().cloned()) {
1381                let reference = WindowUnitRef {
1382                    base_key: base_key.clone(),
1383                    unit: unit.clone(),
1384                };
1385                if !state.units.iter().any(|held| held == &unit) {
1386                    missing.push(reference);
1387                } else if state.pending.iter().any(|held| held == &unit) {
1388                    pending.push(reference);
1389                }
1390            }
1391        }
1392        let mut units = Vec::with_capacity(request.units.len());
1393        for id in &request.units {
1394            let exists: bool = conn.query_row(
1395                "SELECT EXISTS(SELECT 1 FROM _syncular_units WHERE id = ?1)",
1396                [id],
1397                |row| row.get(0),
1398            )?;
1399            if !exists {
1400                units.push(UnitCatchup::Unknown { id: id.clone() });
1401                continue;
1402            }
1403            // Every persisted field is required to be well typed; a corrupt
1404            // record fails typed instead of inventing a state.
1405            let unit = get_unit(conn, id)
1406                .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?
1407                .ok_or_else(|| corrupt("persisted unit state is invalid"))?;
1408            let cursor = match unit.cursor {
1409                Some(cursor) => cursor,
1410                None => replica_cursor(conn)
1411                    .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?,
1412            };
1413            if cursor.unsigned_abs() > MAX_JS_SAFE_INTEGER {
1414                return Err(corrupt("persisted unit state is invalid"));
1415            }
1416            let active = unit.status == UnitStatus::Active;
1417            let pending = unit.bootstrapping();
1418            units.push(UnitCatchup::Known {
1419                id: id.clone(),
1420                status: unit.status,
1421                live: unit.cursor.is_none(),
1422                cursor,
1423                has_resume_token: unit.bootstrap_state.is_some(),
1424                bootstrap_complete: active && !pending,
1425                known_pending_pages: active && pending,
1426                reason_code: unit.reason_code,
1427            });
1428        }
1429        let mut deliveries = Vec::with_capacity(request.commit_ids.len());
1430        for id in &request.commit_ids {
1431            let pending: bool = conn.query_row(
1432                "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id = ?1)",
1433                rusqlite::params![id],
1434                |row| row.get(0),
1435            )?;
1436            if pending {
1437                deliveries.push(CommitDelivery::Pending {
1438                    client_commit_id: id.clone(),
1439                });
1440                continue;
1441            }
1442            let row = conn
1443                .query_row(
1444                    "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
1445                            resolution, resolved_at_ms, replacement_client_commit_id
1446                       FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
1447                    rusqlite::params![id],
1448                    StoredCommitOutcomeRow::from_row,
1449                )
1450                .optional()
1451                .map_err(|error| stored_failure(error, "persisted commit outcome is invalid"))?;
1452            deliveries.push(match row {
1453                Some(row) => CommitDelivery::Known {
1454                    client_commit_id: id.clone(),
1455                    outcome: SyncClient::outcome_from_row(row)
1456                        .map_err(|_| corrupt("persisted commit outcome is invalid"))?,
1457                },
1458                None => CommitDelivery::Unknown {
1459                    client_commit_id: id.clone(),
1460                },
1461            });
1462        }
1463        Ok(SnapshotRead {
1464            revision,
1465            queries,
1466            coverage: CoverageSnapshot {
1467                complete: pending.is_empty() && missing.is_empty(),
1468                pending,
1469                missing,
1470            },
1471            units,
1472            deliveries,
1473        })
1474    })();
1475    match result {
1476        Ok(read) => {
1477            conn.execute_batch("RELEASE syncular_snapshot_read")?;
1478            Ok(read)
1479        }
1480        Err(mut error) => {
1481            if let Err(rollback) = conn
1482                .execute_batch("ROLLBACK TO syncular_snapshot_read; RELEASE syncular_snapshot_read")
1483            {
1484                error.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
1485            }
1486            Err(error)
1487        }
1488    }
1489}
1490
1491fn snapshot_connection(
1492    conn: &Connection,
1493    sql: &str,
1494    params: &[Value],
1495    coverage: &[WindowCoverage],
1496) -> Result<QuerySnapshot, QueryReadFailure> {
1497    let read = snapshot_read_connection(
1498        conn,
1499        &SnapshotReadRequest {
1500            statements: vec![SnapshotStatement { sql, params }],
1501            coverage,
1502            units: Vec::new(),
1503            commit_ids: Vec::new(),
1504        },
1505    )?;
1506    Ok(QuerySnapshot {
1507        revision: read.revision,
1508        rows: read
1509            .queries
1510            .into_iter()
1511            .next()
1512            .expect("single-query snapshot returns one result"),
1513        coverage: read.coverage,
1514    })
1515}
1516
1517/// A long-lived read-only SQLite sidecar for latency-critical native views.
1518/// Network rounds stay serialized on the mutable core owner, while atomic
1519/// query snapshots use this independent connection and therefore never queue
1520/// behind HTTP/WebSocket latency.
1521pub struct FileQuerySnapshotReader {
1522    path: String,
1523    conn: Option<Connection>,
1524}
1525
1526impl FileQuerySnapshotReader {
1527    #[must_use]
1528    pub fn new(path: impl Into<String>) -> Self {
1529        Self {
1530            path: path.into(),
1531            conn: None,
1532        }
1533    }
1534
1535    fn connection(&mut self) -> Result<&Connection, QueryReadFailure> {
1536        if self.conn.is_none() {
1537            let conn = Connection::open_with_flags(
1538                &self.path,
1539                OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
1540            )
1541            .map_err(QueryReadFailure::from)?;
1542            conn.busy_timeout(std::time::Duration::from_millis(250))
1543                .map_err(QueryReadFailure::from)?;
1544            self.conn = Some(conn);
1545        }
1546        self.conn
1547            .as_ref()
1548            .ok_or_else(|| QueryReadFailure::from("read sidecar connection missing".to_owned()))
1549    }
1550
1551    /// One atomic read over the shared primitive: every statement, coverage,
1552    /// catch-up, and delivery under one `SAVEPOINT` and one revision.
1553    pub fn snapshot_read(
1554        &mut self,
1555        request: &SnapshotReadRequest<'_>,
1556    ) -> Result<SnapshotRead, QueryReadFailure> {
1557        snapshot_read_connection(self.connection()?, request)
1558    }
1559
1560    /// The current durable local revision. A host can skip a read when it is
1561    /// unchanged; a corrupt or unreadable marker fails typed.
1562    pub fn local_revision(&mut self) -> Result<String, QueryReadFailure> {
1563        Ok(self
1564            .snapshot_read(&SnapshotReadRequest::default())?
1565            .revision)
1566    }
1567
1568    /// One unit's persisted catch-up state (see the §7.5 contract).
1569    pub fn unit_catchup(&mut self, id: &str) -> Result<UnitCatchup, QueryReadFailure> {
1570        let read = self.snapshot_read(&SnapshotReadRequest {
1571            units: vec![id.to_owned()],
1572            ..Default::default()
1573        })?;
1574        Ok(read
1575            .units
1576            .into_iter()
1577            .next()
1578            .expect("one requested catch-up"))
1579    }
1580
1581    /// One client commit's delivery status: pending, its retained outcome, or
1582    /// an explicit unknown (never held, or pruned by retention).
1583    pub fn commit_delivery(&mut self, id: &str) -> Result<CommitDelivery, QueryReadFailure> {
1584        let read = self.snapshot_read(&SnapshotReadRequest {
1585            commit_ids: vec![id.to_owned()],
1586            ..Default::default()
1587        })?;
1588        Ok(read
1589            .deliveries
1590            .into_iter()
1591            .next()
1592            .expect("one requested delivery"))
1593    }
1594
1595    /// Hosts report an owned failure, and the first success after it, to the
1596    /// owning core through [`SyncClient::record_query_read`] (§7.6).
1597    pub fn query_snapshot(
1598        &mut self,
1599        sql: &str,
1600        params: &[Value],
1601        coverage: &[WindowCoverage],
1602    ) -> Result<QuerySnapshot, QueryReadFailure> {
1603        snapshot_connection(self.connection()?, sql, params, coverage)
1604    }
1605}
1606
1607fn validate_authority_reads(
1608    schema: &ClientSchema,
1609    declarations: &[crate::api::AuthorityReadDeclaration],
1610) -> Result<(), String> {
1611    let mut seen = BTreeSet::new();
1612    for read in declarations {
1613        let table = schema
1614            .table(&read.table)
1615            .ok_or("client.authority_read_forbidden: authority table is not declared")?;
1616        let plain = |name: &str| {
1617            table.columns.iter().enumerate().any(|(i, c)| {
1618                c.name == name
1619                    && name != "authority_version"
1620                    && !name.starts_with("_sync")
1621                    && !table.encrypted_columns.iter().any(|e| e.index == i)
1622                    && matches!(
1623                        c.ty,
1624                        ssp2::segment::ColumnType::String
1625                            | ssp2::segment::ColumnType::Integer
1626                            | ssp2::segment::ColumnType::Float
1627                            | ssp2::segment::ColumnType::Boolean
1628                            | ssp2::segment::ColumnType::Json
1629                    )
1630            })
1631        };
1632        if !seen.insert(&read.table)
1633            || read.columns.is_empty()
1634            || read.columns.iter().collect::<BTreeSet<_>>().len() != read.columns.len()
1635            || !read.columns.contains(&table.primary_key)
1636            || !read.columns.iter().all(|c| plain(c))
1637            || read.scopes.is_empty()
1638            || !read.scopes.iter().all(|(v, values)| {
1639                table
1640                    .scope_column(v)
1641                    .is_some_and(|c| read.columns.iter().any(|column| column == c) && plain(c))
1642                    && !values.is_empty()
1643                    && values.iter().all(|v| !v.is_empty() && v != "*")
1644            })
1645        {
1646            return Err("client.authority_read_forbidden: authority reads require plain columns, a primary key and nonempty plain scope selectors".into());
1647        }
1648    }
1649    Ok(())
1650}
1651
1652// §7.4.2: every open and recreation checks before any persistent writes.
1653/// A marker read that hit a recognized SQLite storage failure keeps that
1654/// classification (BUSY/LOCKED stay retryable); only an unclassified read
1655/// failure is the invalid-marker `sync.local_corrupt`.
1656fn schema_marker_read_failure(error: rusqlite::Error) -> String {
1657    let failure = QueryReadFailure::from(error);
1658    if failure.code.is_some() {
1659        failure.to_string()
1660    } else {
1661        "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned()
1662    }
1663}
1664
1665/// §7.1: reject an invalid configured client limit before any storage is
1666/// opened or written. Zero would wedge the push queue and an out-of-range
1667/// value would differ per target; the TS core enforces the same bounds.
1668fn validate_client_limits(limits: &crate::api::ClientLimits) -> Result<(), String> {
1669    if limits.outcome_retention_max_entries == Some(0) {
1670        return Err("sync.invalid_request: outcomeRetentionMaxEntries must be positive".to_owned());
1671    }
1672    if [
1673        limits.max_push_commits_per_request,
1674        limits.max_push_operations_per_request,
1675        limits.max_push_request_bytes,
1676    ]
1677    .into_iter()
1678    .flatten()
1679    .any(|value| value == 0 || value > u32::MAX as usize)
1680    {
1681        return Err(
1682            "sync.invalid_request: push limit must be an integer in 1..=4294967295".to_owned(),
1683        );
1684    }
1685    Ok(())
1686}
1687
1688fn read_local_schema_version(conn: &Connection, requested: i32) -> Result<Option<i32>, String> {
1689    let corrupt =
1690        || "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned();
1691    let table_type: Option<String> = conn
1692        .query_row(
1693            "SELECT type FROM sqlite_master WHERE name = '_syncular_meta'",
1694            [],
1695            |row| row.get(0),
1696        )
1697        .optional()
1698        .map_err(schema_marker_read_failure)?;
1699    let Some(table_type) = table_type else {
1700        return Ok(None);
1701    };
1702    if table_type != "table" {
1703        return Err(corrupt());
1704    }
1705    // §7.4.2: a duplicated marker cannot be resolved. `query_row` would take
1706    // whichever row SQLite returns first, and an older one would drive a
1707    // destructive reset over a newer replica.
1708    let mut statement = conn
1709        .prepare("SELECT value FROM _syncular_meta WHERE key = ?1")
1710        .map_err(schema_marker_read_failure)?;
1711    let mut rows = statement
1712        .query([LOCAL_SCHEMA_VERSION_KEY])
1713        .map_err(schema_marker_read_failure)?;
1714    let value: Option<String> = rows
1715        .next()
1716        .map_err(schema_marker_read_failure)?
1717        .map(|row| row.get(0))
1718        .transpose()
1719        .map_err(schema_marker_read_failure)?;
1720    if rows.next().map_err(schema_marker_read_failure)?.is_some() {
1721        return Err(corrupt());
1722    }
1723    let Some(value) = value else {
1724        let has_descriptor = conn
1725            .query_row(
1726                "SELECT 1 FROM _syncular_meta WHERE key = ?1 LIMIT 1",
1727                [crate::previous_version::LOCAL_SCHEMA_DESCRIPTOR_KEY],
1728                |_| Ok(()),
1729            )
1730            .optional()
1731            .map_err(schema_marker_read_failure)?
1732            .is_some();
1733        if has_descriptor {
1734            return Err(corrupt());
1735        }
1736        return Ok(None);
1737    };
1738    if !matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1739        || !value.bytes().all(|b| b.is_ascii_digit())
1740    {
1741        return Err(corrupt());
1742    }
1743    let version = value.parse::<i32>().map_err(|_| corrupt())?;
1744    if version > requested {
1745        return Err(
1746            "client.schema_downgrade: persisted local schema is newer than the requested schema"
1747                .to_owned(),
1748        );
1749    }
1750    Ok(Some(version))
1751}
1752
1753/// A file replica on a browser worker must recover a hot journal before any
1754/// statement reads it. `wasm_vfs` replaces the installed OPFS VFS's reserved
1755/// lock callback, so install it before the connection opens its file.
1756#[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
1757fn prepare_wasm_replica(path: &str) -> Result<(), String> {
1758    if path.is_empty() || path == ":memory:" {
1759        return Ok(());
1760    }
1761    crate::wasm_vfs::disable_foreign_lock_check()
1762}
1763
1764#[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
1765fn prepare_wasm_replica(_path: &str) -> Result<(), String> {
1766    Ok(())
1767}
1768
1769impl SyncClient {
1770    pub fn new_with_identity(
1771        client_id: Option<String>,
1772        schema_json: &Value,
1773        limits: ClientLimits,
1774    ) -> Result<Self, String> {
1775        let resolved = client_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
1776        let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1777        Self::with_connection(resolved, schema_json, limits, conn)
1778    }
1779
1780    pub fn new(
1781        client_id: String,
1782        schema_json: &Value,
1783        limits: ClientLimits,
1784    ) -> Result<Self, String> {
1785        let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1786        Self::with_connection(client_id, schema_json, limits, conn)
1787    }
1788
1789    /// Build a client backed by an on-disk SQLite database at `path` — the
1790    /// seam a native host (Tauri plugin, FFI file-DB variant) uses to persist
1791    /// across process restarts. `create_tables` runs `IF NOT EXISTS`, so
1792    /// re-opening the same file reuses the persisted rows. Keeps rusqlite out
1793    /// of the command router's dependency set (the router only holds a path).
1794    pub fn open_path(
1795        client_id: String,
1796        schema_json: &Value,
1797        limits: ClientLimits,
1798        path: &str,
1799    ) -> Result<Self, String> {
1800        validate_client_limits(&limits)?;
1801        parse_schema_json(schema_json)?;
1802        prepare_wasm_replica(path)?;
1803        let conn = Connection::open(path).map_err(|e| format!("open db {path:?}: {e}"))?;
1804        Self::with_connection(client_id, schema_json, limits, conn)
1805    }
1806
1807    /// Open a file replica and resolve its client id. Native targets require
1808    /// WAL for the independent snapshot reader; `wasm32-unknown-unknown`
1809    /// accepts the sqlite-wasm worker journal instead.
1810    pub fn open_path_with_identity(
1811        client_id: Option<String>,
1812        schema_json: &Value,
1813        limits: ClientLimits,
1814        path: &str,
1815    ) -> Result<Self, String> {
1816        Self::open_path_with_identity_journal(
1817            client_id,
1818            schema_json,
1819            limits,
1820            path,
1821            !cfg!(all(target_arch = "wasm32", target_os = "unknown")),
1822        )
1823    }
1824
1825    fn open_path_with_identity_journal(
1826        client_id: Option<String>,
1827        schema_json: &Value,
1828        limits: ClientLimits,
1829        path: &str,
1830        require_wal: bool,
1831    ) -> Result<Self, String> {
1832        validate_client_limits(&limits)?;
1833        // §7.4.2: an invalid requested version is refused before the replica is
1834        // even created, so a rejected constructor leaves no file behind.
1835        parse_schema_json(schema_json)?;
1836        prepare_wasm_replica(path)?;
1837        let conn = Connection::open(path).map_err(|e| format!("open db {path:?}: {e}"))?;
1838        // A file-backed native client uses an independent read connection for
1839        // latency-critical snapshots. WAL is SQLite's intended reader/writer
1840        // concurrency mode: a view read never holds a rollback-journal lock
1841        // that delays the client's next commit. The busy timeout must precede
1842        // this replica's own startup transaction; WAL is applied only after
1843        // startup succeeded, because a refused open must leave the replica's
1844        // journal mode and contents untouched (§7.4.2).
1845        conn.busy_timeout(std::time::Duration::from_millis(250))
1846            .map_err(|error| format!("configure db {path:?} busy timeout: {error}"))?;
1847        // Durability is the caller's contract here, not the VFS default: a
1848        // rollback-journal commit needs FULL before it writes the database
1849        // pages, or a killed worker can leave a half-written image behind.
1850        // WAL below inherits the same setting.
1851        conn.pragma_update(None, "synchronous", "FULL")
1852            .map_err(|error| format!("configure db {path:?} synchronous: {error}"))?;
1853        let client = Self::with_connection_identity(client_id, schema_json, limits, conn)?;
1854        // A browser worker's sqlite-wasm VFS has no WAL mode, and the wasm
1855        // host has no independent snapshot reader. The WAL requirement exists
1856        // for native file replicas, where it is the reader/writer boundary.
1857        if require_wal {
1858            let journal_mode: String = client
1859                .conn
1860                .pragma_update_and_check(None, "journal_mode", "WAL", |row| row.get(0))
1861                .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
1862            if journal_mode != "wal" {
1863                return Err(
1864                    "sync.invalid_request: file-backed client requires WAL journal mode".to_owned(),
1865                );
1866            }
1867        }
1868        Ok(client)
1869    }
1870
1871    /// Delete a file replica at `path`, including its `-journal`, `-wal`, and
1872    /// `-shm` sidecars, through the VFS that owns it. Use this after
1873    /// `client.storage_corrupt`: an OPFS SAH pool stores those files under
1874    /// opaque names, so deleting the pool directory behind SQLite bypasses the
1875    /// pool's slot accounting.
1876    ///
1877    /// Close the client and every [`FileQuerySnapshotReader`] on `path` first;
1878    /// a VFS cannot delete a file another handle still owns. A file that does
1879    /// not exist counts as deleted, so a cleanly closed replica without
1880    /// sidecars resets. The next open
1881    /// creates a fresh replica (new client id) and re-bootstraps from the
1882    /// server. A memory replica has nothing to delete and fails with
1883    /// `sync.invalid_request`.
1884    pub fn reset_replica(path: &str) -> Result<(), String> {
1885        if path.is_empty() || path == ":memory:" {
1886            return Err("sync.invalid_request: a memory replica has nothing to reset".to_owned());
1887        }
1888        // SAFETY: a null VFS name asks SQLite for its process-wide default VFS,
1889        // the same one `Connection::open(path)` above selects. `xDelete` is
1890        // that VFS's own function pointer, and `c_name` outlives the call.
1891        let vfs = unsafe { rusqlite::ffi::sqlite3_vfs_find(std::ptr::null()) };
1892        if vfs.is_null() {
1893            return Err("client.storage_io: no SQLite VFS is registered".to_owned());
1894        }
1895        let delete = unsafe { (*vfs).xDelete }
1896            .ok_or_else(|| "client.storage_io: the SQLite VFS cannot delete files".to_owned())?;
1897        for suffix in ["-wal", "-shm", "-journal", ""] {
1898            let file_name = format!("{path}{suffix}");
1899            let c_name = std::ffi::CString::new(file_name.as_str()).map_err(|_| {
1900                format!("sync.invalid_request: replica path {file_name:?} contains a NUL byte")
1901            })?;
1902            // SAFETY: `vfs` and its `xDelete` pointer come from the live
1903            // SQLite library; `c_name` is a valid NUL-terminated path.
1904            let code = unsafe { delete(vfs, c_name.as_ptr(), 1) };
1905            // A cleanly closed WAL replica has no sidecars; a missing file is
1906            // already deleted.
1907            if code != rusqlite::ffi::SQLITE_OK && code != rusqlite::ffi::SQLITE_IOERR_DELETE_NOENT
1908            {
1909                return Err(format!(
1910                    "client.storage_io: deleting replica file {file_name:?} failed with SQLite code {code}"
1911                ));
1912            }
1913        }
1914        Ok(())
1915    }
1916
1917    #[must_use]
1918    pub fn client_id(&self) -> &str {
1919        &self.client_id
1920    }
1921
1922    /// Rotate the caller's client id (§1.5) and return the new one. Use it
1923    /// after a `sync.invalid_client_id` refusal (`recommendedAction:
1924    /// resetClientId`): the next round carries the new id. A live realtime
1925    /// socket is closed so the next connection registers with the new id.
1926    /// The replica and its outbox stay in place; wipe them yourself when the
1927    /// stored data belongs to the account that signed out.
1928    pub fn reset_client_id(&mut self, transport: &mut dyn Transport) -> Result<String, String> {
1929        self.disconnect_realtime(transport);
1930        let client_id = uuid::Uuid::new_v4().to_string();
1931        self.set_meta(CLIENT_ID_KEY, &client_id)?;
1932        self.client_id.clone_from(&client_id);
1933        self.round_failure = None;
1934        Ok(client_id)
1935    }
1936
1937    /// Build a client over a caller-supplied rusqlite connection — the seam a
1938    /// native host (Tauri plugin, FFI file-DB variant) uses to back the core
1939    /// with an on-disk database (`Connection::open(path)`) rather than the
1940    /// default `:memory:`. The connection MUST be fresh (no pre-existing
1941    /// syncular tables); `create_tables` runs `IF NOT EXISTS`, so re-opening
1942    /// the same file across process restarts reuses the persisted rows.
1943    pub fn with_connection(
1944        client_id: String,
1945        schema_json: &Value,
1946        limits: ClientLimits,
1947        conn: Connection,
1948    ) -> Result<Self, String> {
1949        Self::with_connection_identity(Some(client_id), schema_json, limits, conn)
1950    }
1951
1952    /// [`Self::with_connection`] for `open_path_with_identity`: no requested id
1953    /// means a durable replica's persisted `clientId` wins over a fresh one.
1954    fn with_connection_identity(
1955        client_id: Option<String>,
1956        schema_json: &Value,
1957        limits: ClientLimits,
1958        conn: Connection,
1959    ) -> Result<Self, String> {
1960        validate_client_limits(&limits)?;
1961        let schema = parse_schema_json(schema_json)?;
1962        validate_authority_reads(&schema, &limits.authority_reads)?;
1963        // RFC 0005 D8: resolve the previous-version config before the opening
1964        // reset runs — the capture happens inside it. Bad bounds fail loud.
1965        let previous_version = match limits.previous_version_context {
1966            Some(config) => {
1967                config.validate()?;
1968                Some(config)
1969            }
1970            None => None,
1971        };
1972        let mut client = SyncClient {
1973            #[cfg(feature = "bench-internals")]
1974            benchmark_phases: Recorder::default(),
1975            conn,
1976            schema,
1977            client_id: client_id
1978                .clone()
1979                .unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
1980            limits,
1981            outbox: Shared::default(),
1982            failed_commits: Shared::default(),
1983            retain_failed_commits: false,
1984            conflicts: Shared::default(),
1985            rejections: Shared::default(),
1986            schema_floor: None,
1987            lease_state: None,
1988            stopped: false,
1989            upgrading: false,
1990            sync_needed: false,
1991            realtime_policy: RealtimePolicy::Optional,
1992            realtime_state: RealtimeState::Disconnected,
1993            realtime_reason_code: None,
1994            realtime_retry_delay_ms: None,
1995            presence: HashMap::new(),
1996            now_ms: None,
1997            encryption: crate::values::EncryptionConfig::default(),
1998            security_preflight: false,
1999            security_epoch: 0,
2000            transport_enabled: true,
2001            transport_epoch: 0,
2002            registration_epoch: 0,
2003            previous_version,
2004            insert_sql: RefCell::new(HashMap::new()),
2005            overlay_dirty: OverlayDirty::clean(),
2006            storage_failure: RefCell::new(None),
2007            #[cfg(test)]
2008            overlay_rebuild_count: Cell::new(0),
2009            #[cfg(test)]
2010            acknowledged_replay_count: Cell::new(0),
2011            #[cfg(test)]
2012            outcome_prune_count: Cell::new(0),
2013            progress: ProgressObserver::default(),
2014            change_queue: VecDeque::new(),
2015            sync_intent_queue: VecDeque::new(),
2016            retry_delay_ms: 250,
2017            round_retry_delay_ms: None,
2018            round_failure: None,
2019            active_round: None,
2020            last_round: None,
2021            last_change: None,
2022            query_failures: Vec::new(),
2023            coalesced: None,
2024            coalesced_failure: None,
2025        };
2026        // The row write path leans on the prepared-statement cache (two
2027        // insert statements per synced table, plus the bookkeeping
2028        // statements); size it so a multi-table schema never thrashes.
2029        client
2030            .conn
2031            .set_prepared_statement_cache_capacity(64.max(client.schema.tables.len() * 4));
2032        // §7.4.2: one write transaction (SQLite `BEGIN IMMEDIATE`, a reserved
2033        // writer) covers the marker read, the identity check, and every
2034        // bookkeeping/schema write, so a concurrent open that upgraded the
2035        // replica cannot interleave between the guard and the writes, and a
2036        // refusal leaves the replica unchanged.
2037        client
2038            .conn
2039            .execute_batch("BEGIN IMMEDIATE")
2040            .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2041        let startup = (|| -> Result<(), String> {
2042            // The marker guard runs inside the write transaction, so the version
2043            // it validates is the version every write below commits under.
2044            let marker = read_local_schema_version(&client.conn, client.schema.version)?;
2045            // New app indexes may reference columns that only exist after a
2046            // version-bump reset.
2047            client.create_bookkeeping_tables()?;
2048            match client.get_meta(CLIENT_ID_KEY)? {
2049                Some(existing) => match client_id {
2050                    Some(requested) if existing != requested => {
2051                        return Err(format!(
2052                            "client.identity_mismatch: this database belongs to {existing:?}; refusing to rebind it to {requested:?}"
2053                        ))
2054                    }
2055                    _ => client.client_id = existing,
2056                },
2057                None => client.set_meta(CLIENT_ID_KEY, &client.client_id)?,
2058            }
2059            client.restore_persisted_state()?;
2060            client.failed_commits = client.load_failed_commits()?.into();
2061            match marker {
2062                None => {
2063                    client.create_synced_tables()?;
2064                    client.persist_schema_version()?;
2065                    client.save_unit_scope_schema()?;
2066                }
2067                Some(version) if version == client.schema.version => {
2068                    client.create_synced_tables()?;
2069                    // RFC 0005 D1: the same-version open backfills the descriptor
2070                    // for a database first opened by an unaware binary, so the
2071                    // NEXT bump can capture without needing a schema bump first.
2072                    set_local_schema_descriptor(&client.conn, &client.schema)
2073                        .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2074                    client.save_unit_scope_schema()?;
2075                }
2076                Some(_) => client.run_schema_reset()?,
2077            }
2078            // RFC 0005 D9: the reset sweep cannot see a container whose capture
2079            // committed in its OWN file while the replica's savepoint never
2080            // released — a crash at that seam leaves a container beside a matching
2081            // OLD marker, and the next open at that version runs no reset. Discard
2082            // it before anything can read it. No-op when no container exists.
2083            client.reconcile_previous_version_at_boot()?;
2084            client.clear_satisfied_persisted_schema_floor()?;
2085            client.prune_unknown_units(false)?;
2086            // §7.1/§7.4.4: recover intrinsically codec-invalid persisted values at
2087            // the full startup/reset reconciliation boundary, inside this open
2088            // transaction and after the schema and identity guards, so a commit
2089            // an earlier version accepted is dropped with durable rejection
2090            // evidence before any replay. A table the current schema removed
2091            // keeps the §7.4.4 send-time classification, and an unresolved
2092            // encryption key stays with the send seam because hosts configure
2093            // keys after open.
2094            client.drop_unencodable_outbox(false, None)?;
2095            if marker == Some(client.schema.version)
2096                && (!client.outbox.is_empty()
2097                    || !client.failed_commits.is_empty()
2098                    || client.has_acknowledged_rows()?)
2099            {
2100                // Reconstruct the visible optimistic overlay from the durable
2101                // base plus outbox instead of trusting a process-interrupted
2102                // mirror.
2103                client.overlay_dirty.set(true);
2104                client.rebuild_overlay()?;
2105            }
2106            // Every persisted active unit needs one catch-up pull on
2107            // open: realtime only covers changes after connection, while an
2108            // idempotent setWindow correctly creates no fresh command effect.
2109            // Pending outbox work has the same restart requirement. The core
2110            // owns this intent so native hosts never poll or require an
2111            // application-issued sync().
2112            client.enqueue_startup_sync_if_needed()?;
2113            Ok(())
2114        })();
2115        match startup {
2116            Ok(()) => match client.conn.execute_batch("COMMIT") {
2117                // §4.8: an eviction a crash interrupted finishes before any
2118                // read, with or without a transport; a replica reopened in
2119                // preflight finishes it at activation.
2120                Ok(()) => {
2121                    if !client.security_preflight {
2122                        client.drain_pending_evictions()?;
2123                    }
2124                    Ok(client)
2125                }
2126                Err(error) => {
2127                    let failure = Self::sqlite_failure(&client.storage_failure, error);
2128                    if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2129                        // Keep a failed rollback's typed storage classification.
2130                        let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2131                    }
2132                    Err(failure)
2133                }
2134            },
2135            Err(error) => {
2136                if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2137                    // Keep a failed rollback's typed storage classification.
2138                    let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2139                }
2140                Err(error)
2141            }
2142        }
2143    }
2144
2145    /// Pin the client clock (epoch ms) — the §5.4 expiry check runs
2146    /// against this instead of system time (conformance virtual clock).
2147    pub fn set_now_ms(&mut self, now_ms: i64) {
2148        self.now_ms = Some(now_ms);
2149    }
2150
2151    /// §5.11: install the client-side encryption keys (`keyId → key bytes`).
2152    /// The command router parses these from the `create` command's
2153    /// `encryption` config (keys as `{$bytes: hex}`).
2154    pub fn set_encryption(&mut self, encryption: crate::values::EncryptionConfig) {
2155        self.encryption = encryption;
2156    }
2157
2158    #[must_use]
2159    pub fn security_lifecycle(&self) -> &'static str {
2160        if self.security_preflight {
2161            "preflight"
2162        } else {
2163            "active"
2164        }
2165    }
2166
2167    #[must_use]
2168    pub fn security_preflight(&self) -> bool {
2169        self.security_preflight
2170    }
2171
2172    /// Host-owned, non-persisted network gate. Local operations remain available.
2173    pub fn set_transport_enabled(&mut self, transport: &mut dyn Transport, enabled: bool) {
2174        if self.transport_enabled != enabled {
2175            self.transport_enabled = enabled;
2176            self.transport_epoch = self.transport_epoch.wrapping_add(1);
2177            self.sync_intent_queue.clear();
2178            self.sync_intent_queue
2179                .push_back(if enabled && !self.security_preflight {
2180                    SyncIntent::Interactive
2181                } else {
2182                    SyncIntent::None
2183                });
2184        }
2185        // A captured reply keeps its normal apply/revocation semantics.
2186        if !enabled && self.active_round.is_none() {
2187            self.disconnect_realtime(transport);
2188        }
2189    }
2190
2191    pub fn transport_enabled(&self) -> bool {
2192        self.transport_enabled
2193    }
2194
2195    /// Quarantine this replica: enter the fail-closed gate, release all
2196    /// core-owned key material, and record the gate in the database so
2197    /// reopening re-enters preflight until `activate_security` clears it.
2198    ///
2199    /// Use [`SyncClient::seal_security_on_teardown`] for the shutdown barrier,
2200    /// which must NOT leave that durable mark.
2201    pub fn begin_security_preflight(&mut self) -> Result<(), String> {
2202        self.seal_security_on_teardown();
2203        // Persist the quarantine so it survives handle teardown and restart:
2204        // reopening this replica re-enters preflight until activation clears it.
2205        self.set_meta(SECURITY_PREFLIGHT_PENDING_KEY, "1")
2206    }
2207
2208    /// Release core-owned key material as a host tears the client down,
2209    /// WITHOUT recording a quarantine.
2210    ///
2211    /// Shutting an activated client down is not a quarantine event. Persisting
2212    /// the gate here marks every cleanly closed replica as pending, and the
2213    /// next plain `create` is then refused permanently: the reopen path
2214    /// restores the flag from the marker and the create guard rejects it. The
2215    /// in-memory flag still closes the gate for anything still holding this
2216    /// instance, which is all a teardown barrier needs.
2217    pub fn seal_security_on_teardown(&mut self) {
2218        self.cancel_sync_round();
2219        self.security_preflight = true;
2220        self.security_epoch = self.security_epoch.wrapping_add(1);
2221        self.encryption = crate::values::EncryptionConfig::default();
2222        self.sync_intent_queue.clear();
2223    }
2224
2225    /// Install the post-authentication keyring and release the host loop.
2226    pub fn activate_security(
2227        &mut self,
2228        encryption: crate::values::EncryptionConfig,
2229    ) -> Result<(), String> {
2230        if !self.security_preflight {
2231            return Err(
2232                "sync.invalid_request: activateSecurity requires security preflight".to_owned(),
2233            );
2234        }
2235        // §4.8: an interrupted eviction finishes before protected reads open.
2236        self.drain_pending_evictions()?;
2237        self.enqueue_startup_sync_if_needed()?;
2238        self.delete_meta(SECURITY_PREFLIGHT_PENDING_KEY)?;
2239        self.encryption = encryption;
2240        self.security_preflight = false;
2241        Ok(())
2242    }
2243
2244    fn clock_now_ms(&self) -> i64 {
2245        self.now_ms.unwrap_or_else(crate::wall_clock_ms)
2246    }
2247
2248    fn create_bookkeeping_tables(&self) -> Result<(), String> {
2249        let exists = |name: &str| {
2250            self.conn
2251                .query_row(
2252                    "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1)",
2253                    [name],
2254                    |row| row.get::<_, bool>(0),
2255                )
2256                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2257        };
2258        let outbox_existed = exists("_syncular_outbox")?;
2259        // Durable client bookkeeping (outbox + units + meta).
2260        self.conn
2261            .execute_batch(
2262                "CREATE TABLE IF NOT EXISTS _syncular_outbox (
2263                   seq INTEGER PRIMARY KEY AUTOINCREMENT,
2264                   commit_id TEXT NOT NULL UNIQUE, ops_json TEXT NOT NULL);
2265                 CREATE TABLE IF NOT EXISTS _syncular_row_deliveries (
2266                   tbl TEXT NOT NULL, id TEXT NOT NULL, commit_seq INTEGER NOT NULL, PRIMARY KEY(tbl,id));
2267                 CREATE TABLE IF NOT EXISTS _syncular_acked_rows (
2268                   commit_id TEXT NOT NULL, idx INTEGER NOT NULL, tbl TEXT NOT NULL, id TEXT NOT NULL,
2269                   commit_seq INTEGER NOT NULL, op_json TEXT NOT NULL, intent_json TEXT,
2270                   PRIMARY KEY(commit_id, idx));
2271                 CREATE INDEX IF NOT EXISTS _syncular_acked_rows_row
2272                   ON _syncular_acked_rows(tbl, id);
2273                 CREATE TABLE IF NOT EXISTS _syncular_failed_commits (
2274                   seq INTEGER PRIMARY KEY AUTOINCREMENT, client_commit_id TEXT NOT NULL UNIQUE,
2275                   operations_json TEXT NOT NULL, initial_json TEXT NOT NULL);
2276                 CREATE TABLE IF NOT EXISTS _syncular_commit_outcomes (
2277                   seq INTEGER PRIMARY KEY AUTOINCREMENT,
2278                   client_commit_id TEXT NOT NULL UNIQUE,
2279                   status TEXT NOT NULL CHECK(status IN ('applied', 'cached', 'conflict', 'rejected')),
2280                   recorded_at_ms INTEGER NOT NULL,
2281                   results_json TEXT NOT NULL,
2282                   operations_json TEXT,
2283                   resolution TEXT NOT NULL DEFAULT 'active'
2284                     CHECK(resolution IN ('active', 'resolved_keep_server', 'superseded', 'dismissed')),
2285                   resolved_at_ms INTEGER,
2286                   replacement_client_commit_id TEXT);
2287                 CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq
2288                   ON _syncular_commit_outcomes(resolution, seq);
2289                 CREATE TABLE IF NOT EXISTS _syncular_units (
2290                   id TEXT PRIMARY KEY, scopes TEXT NOT NULL,
2291                   explicit INTEGER NOT NULL DEFAULT 0,
2292                   status TEXT NOT NULL DEFAULT 'active', reason_code TEXT,
2293                   cursor INTEGER DEFAULT -1, bootstrap_state TEXT,
2294                   seeded TEXT NOT NULL DEFAULT '[]', echo TEXT);
2295                 CREATE TABLE IF NOT EXISTS _syncular_meta (
2296                   key TEXT PRIMARY KEY, value TEXT NOT NULL);
2297                 CREATE TABLE IF NOT EXISTS _syncular_windows (
2298                   base TEXT NOT NULL, unit TEXT NOT NULL, sub_id TEXT NOT NULL,
2299                   PRIMARY KEY (base, unit));
2300                 CREATE INDEX IF NOT EXISTS _syncular_windows_unit ON _syncular_windows(sub_id);
2301                 CREATE TABLE IF NOT EXISTS _syncular_pending_evictions (
2302                   unit_id TEXT NOT NULL, tbl TEXT NOT NULL,
2303                   effective_scopes TEXT NOT NULL, PRIMARY KEY (unit_id, tbl));
2304                 CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
2305                   commit_id TEXT NOT NULL, blob_id TEXT NOT NULL,
2306                   PRIMARY KEY(commit_id, blob_id));
2307                 CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body
2308                   ON _syncular_blob_commit_refs(blob_id);",
2309            )
2310            .map_err(|e| e.to_string())?;
2311        // Migrate an outcome journal created before failed aggregate
2312        // envelopes were retained. Historical rows intentionally stay NULL.
2313        let _ = self
2314            .conn
2315            .execute_batch("ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations_json TEXT");
2316        if self.get_meta(LOCAL_REVISION_KEY)?.is_none() {
2317            self.set_meta(LOCAL_REVISION_KEY, "0")?;
2318        }
2319        // §7.1: `outboxId` names the outbox sequence. A new outbox table starts
2320        // a new sequence, so it replaces the id in the same transaction.
2321        if !outbox_existed || self.get_meta(OUTBOX_ID_KEY)?.is_none() {
2322            self.set_meta(OUTBOX_ID_KEY, &uuid::Uuid::new_v4().to_string())?;
2323        }
2324        // §9: a replica written under wire version 3 keeps its outbox, journal,
2325        // rows and pending evictions and registers its units fresh. Its
2326        // subscriptions, cursors, echoes, resume tokens and window entries go;
2327        // units left from an earlier version 4 life restart.
2328        if exists("_syncular_window_pending_evict")? {
2329            let invalid: bool = self
2330                .conn
2331                .query_row(
2332                    "SELECT EXISTS(SELECT 1 FROM _syncular_window_pending_evict
2333                       WHERE NOT json_valid(effective_scopes)
2334                          OR json_type(effective_scopes) <> 'object'
2335                          OR EXISTS(SELECT 1 FROM json_each(effective_scopes)
2336                               WHERE type <> 'array'
2337                                  OR EXISTS(SELECT 1 FROM json_each(value) AS v
2338                                       WHERE v.type <> 'text')))",
2339                    [],
2340                    |row| row.get(0),
2341                )
2342                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2343            if invalid {
2344                return Err(
2345                    "sync.local_corrupt: a version 3 pending eviction cannot be upgraded"
2346                        .to_owned(),
2347                );
2348            }
2349            self.conn
2350                .execute_batch(
2351                    "INSERT OR REPLACE INTO _syncular_pending_evictions
2352                       SELECT sub_id, tbl, effective_scopes FROM _syncular_window_pending_evict;
2353                     DROP TABLE _syncular_window_pending_evict;
2354                     DROP TABLE IF EXISTS _syncular_subscriptions;
2355                     DELETE FROM _syncular_windows;",
2356                )
2357                .and_then(|()| reset_units(&self.conn))
2358                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2359        }
2360        // §5.9.7 blob cache. Mutable upload state stays off the body row so
2361        // completing a large upload does not rewrite its BLOB record.
2362        if self.schema_has_blobs() {
2363            if exists("_syncular_blobs")? {
2364                let mut statement = self
2365                    .conn
2366                    .prepare("PRAGMA table_info(_syncular_blobs)")
2367                    .map_err(|e| e.to_string())?;
2368                let mut columns = statement
2369                    .query_map([], |row| row.get::<_, String>(1))
2370                    .map_err(|e| e.to_string())?
2371                    .collect::<Result<Vec<_>, _>>()
2372                    .map_err(|e| e.to_string())?;
2373                columns.sort();
2374                let mut expected = vec![
2375                    "blob_id",
2376                    "byte_length",
2377                    "bytes",
2378                    "created_at_ms",
2379                    "media_type",
2380                ];
2381                expected.sort_unstable();
2382                if columns != expected {
2383                    return Err(
2384                        "sync.schema_mismatch: Local blob schema is incompatible".to_owned()
2385                    );
2386                }
2387            } else {
2388                self.conn
2389                    .execute_batch(
2390                        "CREATE TABLE _syncular_blobs(
2391                           blob_id TEXT PRIMARY KEY,
2392                           bytes BLOB NOT NULL,
2393                           byte_length INTEGER NOT NULL,
2394                           media_type TEXT,
2395                           created_at_ms INTEGER NOT NULL);",
2396                    )
2397                    .map_err(|e| e.to_string())?;
2398            }
2399            self.conn
2400                .execute_batch(
2401                    "CREATE TABLE IF NOT EXISTS _syncular_blob_uploads(
2402                       blob_id TEXT PRIMARY KEY,
2403                       media_type TEXT,
2404                       created_at_ms INTEGER NOT NULL);",
2405                )
2406                .map_err(|e| e.to_string())?;
2407        }
2408        Ok(())
2409    }
2410
2411    /// True iff any synced table declares a `blob_ref` column (§5.9).
2412    fn schema_has_blobs(&self) -> bool {
2413        self.schema
2414            .tables
2415            .iter()
2416            .any(|t| t.columns.iter().any(|c| c.ty == ColumnType::BlobRef))
2417    }
2418
2419    // -- meta (§7.4.1 marker, bookkeeping) ------------------------------------
2420
2421    fn get_meta(&self, key: &str) -> Result<Option<String>, String> {
2422        meta_get(&self.conn, key)
2423            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2424    }
2425
2426    // The caller holds the startup/reset transaction. Either both schema
2427    // records persist or the enclosing operation fails and rolls back.
2428    fn persist_schema_version(&self) -> Result<(), String> {
2429        self.conn
2430            .execute(
2431                "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
2432                rusqlite::params![LOCAL_SCHEMA_VERSION_KEY, self.schema.version.to_string()],
2433            )
2434            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2435        set_local_schema_descriptor(&self.conn, &self.schema)
2436            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2437    }
2438
2439    pub(crate) fn set_meta(&self, key: &str, value: &str) -> Result<(), String> {
2440        meta_set(&self.conn, key, value)
2441            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2442    }
2443
2444    fn delete_meta(&self, key: &str) -> Result<(), String> {
2445        meta_delete(&self.conn, key)
2446            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2447    }
2448
2449    /// §7.1: the durable outbox in FIFO order, in schema-agnostic local form.
2450    fn load_outbox(&self) -> Result<Vec<Arc<OutboxCommit>>, String> {
2451        let mut stmt = self
2452            .conn
2453            .prepare("SELECT commit_id, ops_json FROM _syncular_outbox ORDER BY seq ASC")
2454            .map_err(|error| error.to_string())?;
2455        let rows = stmt
2456            .query_map([], |row| {
2457                Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
2458            })
2459            .map_err(|error| error.to_string())?;
2460        let mut commits = Vec::new();
2461        for row in rows {
2462            let (client_commit_id, raw) = row.map_err(|error| error.to_string())?;
2463            let entries: Vec<Value> = serde_json::from_str(&raw).map_err(|error| {
2464                format!("invalid persisted outbox {client_commit_id:?}: {error}")
2465            })?;
2466            let mut ops = Vec::with_capacity(entries.len());
2467            for entry in entries {
2468                let op = entry.get("op").and_then(Value::as_str).unwrap_or("delete");
2469                ops.push(OutboxOp {
2470                    upsert: op == "upsert",
2471                    table: entry
2472                        .get("table")
2473                        .and_then(Value::as_str)
2474                        .ok_or_else(|| "persisted outbox operation missing table".to_owned())?
2475                        .to_owned(),
2476                    row_id: entry
2477                        .get("rowId")
2478                        .and_then(Value::as_str)
2479                        .ok_or_else(|| "persisted outbox operation missing rowId".to_owned())?
2480                        .to_owned(),
2481                    base_version: entry.get("baseVersion").and_then(Value::as_i64),
2482                    // A legacy entry's `changedFields` key is ignored:
2483                    // the values map is the presence set (§6.1).
2484                    values: entry.get("values").and_then(Value::as_object).cloned(),
2485                    insert: entry.get("insert") == Some(&Value::Bool(true)),
2486                });
2487            }
2488            commits.push(Arc::new(OutboxCommit {
2489                client_commit_id,
2490                ops,
2491            }));
2492        }
2493        Ok(commits)
2494    }
2495
2496    fn restore_persisted_state(&mut self) -> Result<(), String> {
2497        self.outbox = self.load_outbox()?.into();
2498
2499        self.prune_commit_outcomes()?;
2500        let active = self.commit_outcomes(CommitOutcomeQuery {
2501            active_only: true,
2502            ..CommitOutcomeQuery::default()
2503        })?;
2504        self.conflicts = active
2505            .iter()
2506            .flat_map(|outcome| outcome.results.iter())
2507            .filter_map(|result| match result {
2508                CommitOperationOutcome::Conflict { conflict } => Some(conflict.clone()),
2509                _ => None,
2510            })
2511            .collect::<Vec<_>>()
2512            .into();
2513        self.rejections = active
2514            .iter()
2515            .flat_map(|outcome| outcome.results.iter())
2516            .filter_map(|result| match result {
2517                CommitOperationOutcome::Error { rejection } => Some(rejection.clone()),
2518                _ => None,
2519            })
2520            .collect::<Vec<_>>()
2521            .into();
2522
2523        self.lease_state = self
2524            .get_meta(LEASE_STATE_KEY)?
2525            .map(|raw| serde_json::from_str(&raw))
2526            .transpose()
2527            .map_err(|error| format!("invalid persisted lease state: {error}"))?;
2528        self.schema_floor = self
2529            .get_meta(SCHEMA_FLOOR_KEY)?
2530            .map(|raw| serde_json::from_str(&raw))
2531            .transpose()
2532            .map_err(|error| format!("invalid persisted schema floor: {error}"))?;
2533        self.stopped = self.schema_floor.is_some();
2534        // A replica left in unactivated preflight reopens gated: the quarantine
2535        // decision persists with the data across handle teardown and restart.
2536        if self.get_meta(SECURITY_PREFLIGHT_PENDING_KEY)?.as_deref() == Some("1") {
2537            self.security_preflight = true;
2538        }
2539        Ok(())
2540    }
2541
2542    fn save_unit_scope_schema(&self) -> Result<(), String> {
2543        let declarations: BTreeMap<_, BTreeMap<_, _>> = self
2544            .schema
2545            .tables
2546            .iter()
2547            .map(|table| {
2548                (
2549                    table.name.clone(),
2550                    table
2551                        .scope_variables
2552                        .iter()
2553                        .map(|scope| {
2554                            (
2555                                scope.variable.clone(),
2556                                [scope.prefix.clone(), scope.column.clone()],
2557                            )
2558                        })
2559                        .collect(),
2560                )
2561            })
2562            .collect();
2563        self.set_meta(
2564            "subscriptionScopeSchema",
2565            &serde_json::to_string(&declarations).expect("scope schema serialization"),
2566        )
2567    }
2568
2569    /// Drop units that cover no table of the running schema, with their window
2570    /// registry rows and pending evictions; never translate scopes. At a bump
2571    /// (§7.4.3) a unit also needs every variable unchanged in prefix and column
2572    /// on every table it covered before.
2573    fn prune_unknown_units(&mut self, bump: bool) -> Result<(), String> {
2574        let previous: Option<BTreeMap<String, BTreeMap<String, [String; 2]>>> = if bump {
2575            self.get_meta("subscriptionScopeSchema")?
2576                .map(|raw| serde_json::from_str(&raw))
2577                .transpose()
2578                .map_err(|_| "sync.local_corrupt: invalid persisted scope schema".to_owned())?
2579        } else {
2580            None
2581        };
2582        // A table keeps the variables' meaning when each has the same prefix
2583        // and column as before. An old binary stored no declaration evidence;
2584        // matching names cannot prove unchanged meaning, so the app registers
2585        // again.
2586        let unchanged = |name: &str, variables: &[&String]| {
2587            let (Some(old), Some(table)) = (
2588                previous.as_ref().and_then(|previous| previous.get(name)),
2589                self.schema.table(name),
2590            ) else {
2591                return false;
2592            };
2593            variables.iter().all(|variable| {
2594                table
2595                    .scope_variables
2596                    .iter()
2597                    .find(|scope| &scope.variable == *variable)
2598                    .is_some_and(|scope| {
2599                        old.get(*variable) == Some(&[scope.prefix.clone(), scope.column.clone()])
2600                    })
2601            })
2602        };
2603        let compatible = |scopes: &UnitScopes| {
2604            if !self.schema.tables.iter().any(|table| covers(table, scopes)) {
2605                return false;
2606            }
2607            if !bump {
2608                return true;
2609            }
2610            let Some(previous) = &previous else {
2611                return false;
2612            };
2613            previous.iter().all(|(name, old)| {
2614                !scopes.keys().all(|variable| old.contains_key(variable))
2615                    || unchanged(name, &scopes.keys().collect::<Vec<_>>())
2616            })
2617        };
2618        let mut stale: BTreeSet<String> = self
2619            .stored(load_units(&self.conn))?
2620            .into_iter()
2621            .filter(|unit| !compatible(&unit.scopes))
2622            .map(|unit| unit.id)
2623            .collect();
2624        // A shrunk window's deferred eviction outlives its unit row and keeps
2625        // its per-table scopes. A table the schema no longer has cannot be
2626        // evicted, and at a bump a table whose scope declarations changed must
2627        // not be evicted by the outdated rule.
2628        for (id, table, effective) in self.load_pending_evictions()? {
2629            if self.schema.table(&table).is_none()
2630                || (bump
2631                    && !unchanged(
2632                        &table,
2633                        &effective
2634                            .iter()
2635                            .map(|(variable, _)| variable)
2636                            .collect::<Vec<_>>(),
2637                    ))
2638            {
2639                stale.insert(id);
2640            }
2641        }
2642        for id in &stale {
2643            for sql in [
2644                "DELETE FROM _syncular_windows WHERE sub_id = ?1",
2645                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
2646                "DELETE FROM _syncular_units WHERE id = ?1",
2647            ] {
2648                self.conn
2649                    .execute(sql, rusqlite::params![id])
2650                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2651            }
2652        }
2653        Ok(())
2654    }
2655
2656    pub fn local_revision(&self) -> Result<u64, String> {
2657        Ok(self
2658            .get_meta(LOCAL_REVISION_KEY)?
2659            .and_then(|value| value.parse().ok())
2660            .unwrap_or(0))
2661    }
2662
2663    /// §7.5: resolve a snapshot read on the mutable owner connection through
2664    /// the same primitive the read-only sidecar uses, so the command surface
2665    /// and the file sidecar return one revision, rows, coverage, catch-up, and
2666    /// delivery shape. The structured [`QueryReadFailure`] is preserved; an
2667    /// `owner` records its failure (and its next success) in diagnostics.
2668    pub fn snapshot_read(
2669        &mut self,
2670        request: &SnapshotReadRequest<'_>,
2671        owner: Option<QueryOwner<'_>>,
2672    ) -> Result<SnapshotRead, QueryReadFailure> {
2673        let result = snapshot_read_connection(&self.conn, request);
2674        if let Some(owner) = owner {
2675            self.record_query_read(owner, result.as_ref().err());
2676        }
2677        result
2678    }
2679
2680    #[must_use]
2681    pub fn status_snapshot(&self) -> SyncStatusSnapshot {
2682        SyncStatusSnapshot {
2683            current_schema_version: self.schema.version,
2684            outbox: self.outbox.len(),
2685            upgrading: self.upgrading,
2686            lease_state: self.lease_state.clone(),
2687            schema_floor: self.schema_floor.clone(),
2688            sync_needed: self.sync_needed,
2689            previous_version_context: self.previous_version_status(),
2690        }
2691    }
2692
2693    /// RFC 0005 A2: container presence for a host that must act on it (Diego's
2694    /// rollback precondition), read without creating the file.
2695    fn previous_version_status(&self) -> PreviousVersionStatus {
2696        let Some(replica_path) = self.previous_version_replica_path() else {
2697            return PreviousVersionStatus {
2698                present: false,
2699                created_at_ms: None,
2700            };
2701        };
2702        match crate::previous_version::read_previous_version_record(&replica_path) {
2703            Ok(Some(record)) => PreviousVersionStatus {
2704                present: true,
2705                created_at_ms: Some(record.created_at_ms),
2706            },
2707            _ => PreviousVersionStatus {
2708                present: std::path::Path::new(
2709                    &crate::previous_version::previous_version_container_path(&replica_path),
2710                )
2711                .exists(),
2712                created_at_ms: None,
2713            },
2714        }
2715    }
2716
2717    /// RFC 0005 D7: read captured rows from the previous local schema. `state`
2718    /// is always `previousVersion`; the container never makes
2719    /// `query_snapshot()` coverage complete. Lease stop/expiry, scope
2720    /// revocation, coverage completion and the TTL DISCARD the container and
2721    /// close the read with their own reason.
2722    pub fn previous_version_snapshot(
2723        &self,
2724        spec: &PreviousVersionReadSpec,
2725    ) -> Result<PreviousVersionSnapshot, String> {
2726        let now_ms = self.clock_now_ms();
2727        crate::previous_version::previous_version_snapshot(
2728            &self.conn,
2729            self.previous_version_replica_path().as_deref(),
2730            self.previous_version.as_ref(),
2731            PreviousVersionLifecycle {
2732                lease_inactive: self.previous_version_lease_inactive(now_ms),
2733                scope_revoked: self
2734                    .stored(load_units(&self.conn))?
2735                    .iter()
2736                    .any(|unit| unit.status == UnitStatus::Revoked),
2737                coverage_complete: self.previous_version_coverage_complete()?,
2738            },
2739            now_ms,
2740            self.schema.version,
2741            spec,
2742        )
2743    }
2744
2745    /// RFC 0005 D6: the advisory pre-reset compatibility audit.
2746    pub fn previous_version_audit(
2747        &self,
2748    ) -> Result<Option<crate::previous_version::PreviousVersionAudit>, String> {
2749        crate::previous_version::stored_previous_version_audit(&self.conn)
2750            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2751    }
2752
2753    /// RFC 0005 A2/D9: the executable downgrade step. Drop the container file
2754    /// and both metadata records, and report whether anything was present.
2755    /// Idempotent: absence is a successful no-op.
2756    pub fn previous_version_discard(
2757        &self,
2758    ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2759        self.drop_previous_version()
2760    }
2761
2762    fn drop_previous_version(
2763        &self,
2764    ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2765        let Some(replica_path) = self.previous_version_replica_path() else {
2766            return Ok(crate::previous_version::PreviousVersionDiscardOutcome {
2767                present: false,
2768                discarded: false,
2769            });
2770        };
2771        crate::previous_version::discard_previous_version(&self.conn, &replica_path)
2772    }
2773
2774    /// RFC 0005 D7: `leaseState.errorCode` or an expired lease.
2775    fn previous_version_lease_inactive(&self, now_ms: i64) -> bool {
2776        let Some(lease) = &self.lease_state else {
2777            return false;
2778        };
2779        if lease.error_code.is_some() {
2780            return true;
2781        }
2782        lease.expires_at_ms.is_some_and(|expires| expires <= now_ms)
2783    }
2784
2785    /// RFC 0005 D7: §7.4.5 replacement coverage — no active unit is
2786    /// bootstrapping. An empty active set is not completion (mirrors the TS
2787    /// predicate exactly).
2788    fn previous_version_coverage_complete(&self) -> Result<bool, String> {
2789        let units = self.stored(load_units(&self.conn))?;
2790        let mut active = units
2791            .iter()
2792            .filter(|unit| unit.status == UnitStatus::Active)
2793            .peekable();
2794        Ok(active.peek().is_some() && !active.any(UnitRecord::bootstrapping))
2795    }
2796
2797    /// RFC 0005 D7: lifetime triggers evaluated once per sync round, after the
2798    /// apply. A container that no longer has a reason to exist is discarded so
2799    /// the rows do not outlive the window they were kept for.
2800    fn previous_version_lifetime_check(&self) {
2801        let Some(config) = self.previous_version.filter(|config| config.enabled) else {
2802            return;
2803        };
2804        let now_ms = self.clock_now_ms();
2805        if self.previous_version_lease_inactive(now_ms) {
2806            let _ = self.drop_previous_version();
2807            return;
2808        }
2809        let Some(replica_path) = self.previous_version_replica_path() else {
2810            return;
2811        };
2812        let Ok(Some(record)) = crate::previous_version::read_previous_version_record(&replica_path)
2813        else {
2814            return;
2815        };
2816        let Ok(units) = load_units(&self.conn) else {
2817            return;
2818        };
2819        if units.iter().any(|unit| unit.status == UnitStatus::Revoked) {
2820            let _ = self.drop_previous_version();
2821            return;
2822        }
2823        if now_ms - record.created_at_ms > config.max_age_ms {
2824            let _ = self.drop_previous_version();
2825            return;
2826        }
2827        if self.previous_version_coverage_complete() == Ok(true) {
2828            let _ = self.drop_previous_version();
2829        }
2830    }
2831
2832    pub fn diagnostics_snapshot(&self) -> Result<ClientDiagnosticsSnapshot, String> {
2833        let registered = self.stored(load_units(&self.conn))?;
2834        // Both meta values in one statement: the FFI host recomputes
2835        // diagnostics after every command.
2836        let (local_revision, replica_cursor): (Option<String>, Option<String>) = self.stored(
2837            self.conn
2838                .prepare_cached(
2839                    "SELECT (SELECT value FROM _syncular_meta WHERE key = ?1),
2840                            (SELECT value FROM _syncular_meta WHERE key = ?2)",
2841                )
2842                .and_then(|mut statement| {
2843                    statement.query_row([LOCAL_REVISION_KEY, REPLICA_CURSOR_KEY], |row| {
2844                        Ok((row.get(0)?, row.get(1)?))
2845                    })
2846                }),
2847        )?;
2848        let mut units = DiagnosticUnits::default();
2849        for unit in &registered {
2850            *match unit.status {
2851                UnitStatus::Revoked => &mut units.revoked,
2852                UnitStatus::Failed => &mut units.failed,
2853                UnitStatus::Active if !unit.bootstrapping() => &mut units.complete,
2854                UnitStatus::Active
2855                    if unit.reason_code.as_deref() == Some("sync.cursor_expired") =>
2856                {
2857                    &mut units.reset
2858                }
2859                UnitStatus::Active => &mut units.bootstrapping,
2860            } += 1;
2861        }
2862        units.reason_codes = registered
2863            .iter()
2864            .filter_map(|unit| unit.reason_code.as_deref().map(Self::diagnostic_code))
2865            .collect::<BTreeSet<_>>()
2866            .into_iter()
2867            .collect();
2868        let captured_at_ms = self.clock_now_ms();
2869        let lease = if let Some(error_code) = self
2870            .lease_state
2871            .as_ref()
2872            .and_then(|state| state.error_code.clone())
2873        {
2874            ClientDiagnosticsLease {
2875                state: "stopped".to_owned(),
2876                expires_at_ms: self
2877                    .lease_state
2878                    .as_ref()
2879                    .and_then(|state| state.expires_at_ms),
2880                error_code: Some(Self::diagnostic_code(&error_code)),
2881            }
2882        } else if let Some(expires_at_ms) = self
2883            .lease_state
2884            .as_ref()
2885            .and_then(|state| state.expires_at_ms)
2886        {
2887            ClientDiagnosticsLease {
2888                state: if expires_at_ms <= captured_at_ms {
2889                    "expired".to_owned()
2890                } else {
2891                    "active".to_owned()
2892                },
2893                expires_at_ms: Some(expires_at_ms),
2894                error_code: None,
2895            }
2896        } else {
2897            ClientDiagnosticsLease {
2898                state: "none".to_owned(),
2899                expires_at_ms: None,
2900                error_code: None,
2901            }
2902        };
2903        let connectivity = match self.last_round.as_ref() {
2904            _ if !self.transport_enabled && self.active_round.is_none() => "offline",
2905            Some(round) if round.status == "succeeded" => "online",
2906            Some(round)
2907                if round.status == "failed"
2908                    && matches!(
2909                        round.cause_kind,
2910                        Some(
2911                            crate::TransportCauseKind::Network | crate::TransportCauseKind::Connect
2912                        )
2913                    ) =>
2914            {
2915                "offline"
2916            }
2917            Some(round) if round.status == "failed" && round.http_status.is_some() => "online",
2918            _ => "unknown",
2919        };
2920        Ok(ClientDiagnosticsSnapshot {
2921            version: CLIENT_DIAGNOSTICS_VERSION,
2922            captured_at_ms,
2923            host: ClientDiagnosticsHost {
2924                kind: "direct".to_owned(),
2925                role: "single".to_owned(),
2926                connectivity: connectivity.to_owned(),
2927                realtime: self.realtime_state,
2928                realtime_policy: self.realtime_policy,
2929                realtime_reason_code: self.realtime_reason_code.clone(),
2930                realtime_retry_delay_ms: self.realtime_retry_delay_ms,
2931            },
2932            security_lifecycle: self.security_lifecycle().to_owned(),
2933            schema: ClientDiagnosticsSchema {
2934                current_version: self.schema.version,
2935                upgrading: self.upgrading,
2936                required_version: self
2937                    .schema_floor
2938                    .as_ref()
2939                    .and_then(|floor| floor.required_schema_version),
2940                latest_version: self
2941                    .schema_floor
2942                    .as_ref()
2943                    .and_then(|floor| floor.latest_schema_version),
2944            },
2945            replica: ClientDiagnosticsReplica {
2946                local_revision: local_revision
2947                    .and_then(|value| value.parse::<u64>().ok())
2948                    .unwrap_or(0)
2949                    .to_string(),
2950                sync_needed: self.sync_needed,
2951                pending_outbox: self.outbox.len(),
2952            },
2953            lease,
2954            active_units: registered
2955                .iter()
2956                .filter(|unit| unit.status == UnitStatus::Active)
2957                .count(),
2958            units,
2959            replica_cursor: replica_cursor.map_or(Ok(-1), |raw| {
2960                raw.parse()
2961                    .map_err(|_| "sync.local_corrupt: persisted unit state is invalid".to_owned())
2962            })?,
2963            last_round: self.last_round.clone(),
2964            last_change: self.last_change.clone(),
2965            storage: self.diagnostics_storage(),
2966            query_failures: self.query_failures.clone(),
2967        })
2968    }
2969
2970    fn diagnostics_storage(&self) -> ClientDiagnosticsStorage {
2971        let read = || -> Result<ClientDiagnosticsStorage, rusqlite::Error> {
2972            let page_count: i64 = self
2973                .conn
2974                .query_row("PRAGMA page_count", [], |row| row.get(0))?;
2975            let page_size: i64 = self
2976                .conn
2977                .query_row("PRAGMA page_size", [], |row| row.get(0))?;
2978            // One cached aggregate, since the FFI host recomputes diagnostics
2979            // after every command; every invocation still reads current storage.
2980            let (outbox_bytes, outcome_entries, outcome_bytes): (i64, i64, i64) = self
2981                .conn
2982                .prepare_cached(
2983                    "SELECT (SELECT COALESCE(SUM(LENGTH(ops_json)), 0) FROM _syncular_outbox),
2984                            COUNT(*), COALESCE(SUM(LENGTH(results_json) + COALESCE(LENGTH(operations_json), 0)), 0)
2985                       FROM _syncular_commit_outcomes",
2986                )?
2987                .query_row([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?;
2988            let blob_bytes = if self.schema_has_blobs() {
2989                self.conn
2990                    .prepare_cached("SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs")?
2991                    .query_row([], |row| row.get(0))?
2992            } else {
2993                0
2994            };
2995            let pressure = self
2996                .limits
2997                .blob_cache_max_bytes
2998                .is_some_and(|limit| blob_bytes > limit);
2999            Ok(ClientDiagnosticsStorage {
3000                status: if pressure { "pressure" } else { "healthy" }.to_owned(),
3001                database_bytes_approx: Some(page_count.saturating_mul(page_size).max(0)),
3002                pending_outbox_bytes_approx: Some(outbox_bytes.max(0)),
3003                retained_outcome_bytes_approx: Some(outcome_bytes.max(0)),
3004                retained_outcome_entries: Some(outcome_entries.max(0)),
3005                blob_cache_bytes_approx: Some(blob_bytes.max(0)),
3006                pressure_reason_code: pressure.then(|| "client.blob_cache_over_limit".to_owned()),
3007            })
3008        };
3009        read().unwrap_or_else(|_| ClientDiagnosticsStorage {
3010            status: "unreadable".to_owned(),
3011            database_bytes_approx: None,
3012            pending_outbox_bytes_approx: None,
3013            retained_outcome_bytes_approx: None,
3014            retained_outcome_entries: None,
3015            blob_cache_bytes_approx: None,
3016            pressure_reason_code: None,
3017        })
3018    }
3019
3020    pub fn drain_change_batches(&mut self) -> Vec<ClientChangeBatch> {
3021        self.change_queue.drain(..).collect()
3022    }
3023
3024    pub fn drain_sync_intents(&mut self) -> Vec<SyncIntent> {
3025        let intents = self.sync_intent_queue.drain(..).collect();
3026        if self.transport_enabled {
3027            intents
3028        } else {
3029            vec![SyncIntent::None]
3030        }
3031    }
3032
3033    fn schedule_background_retry(&mut self) -> u64 {
3034        let delay_ms = self.retry_delay_ms;
3035        self.sync_intent_queue
3036            .push_back(SyncIntent::Background { delay_ms });
3037        self.retry_delay_ms = (self.retry_delay_ms * 2).min(30_000);
3038        self.round_retry_delay_ms = Some(delay_ms);
3039        delay_ms
3040    }
3041
3042    fn reset_background_retry(&mut self) {
3043        self.retry_delay_ms = 250;
3044    }
3045
3046    fn retryable_transport_code(code: &str) -> bool {
3047        code == "transport.failed"
3048            || code == "transport.timeout"
3049            || code == "transport.unavailable"
3050            || code == "sync.transport_failed"
3051    }
3052
3053    /// §1.8: the transport reported a refused or unreachable endpoint. The
3054    /// native transport says `connect` (DNS failure, connection refused,
3055    /// reset, or aborted); a browser fetch transport says `network`. Repeating
3056    /// the request on a backoff repairs neither, so no retry is scheduled.
3057    fn unreachable_transport(details: &Option<serde_json::Value>) -> bool {
3058        matches!(
3059            details
3060                .as_ref()
3061                .and_then(|details| details.get("causeKind"))
3062                .and_then(serde_json::Value::as_str),
3063            Some("connect" | "network")
3064        )
3065    }
3066
3067    /// §1.5: a segment fetch that fails inside an otherwise complete round is
3068    /// invisible to the server (the round response arrived whole), so its code
3069    /// rides the following requests like a socket-round failure. A code the
3070    /// frame grammar rejects is not reportable and the previous code stays.
3071    fn segment_fetch_failed(&mut self, error: TransportError) -> SectionError {
3072        if ssp2::model::valid_round_failure_code(&error.code) {
3073            self.round_failure = Some(error.code.clone());
3074        }
3075        SectionError::Transport(error)
3076    }
3077
3078    /// A failed round worth a background retry: a transport failure, or a
3079    /// §10.2 code the catalog marks retryable (clients may hardcode the
3080    /// catalog metadata, §10.1). Matches the TypeScript core, which retries
3081    /// on the server's `retryable` flag.
3082    fn retryable_failure_code(code: &str) -> bool {
3083        Self::retryable_transport_code(code)
3084            || matches!(
3085                code,
3086                "sync.auth_required"
3087                    | "sync.auth_lease_required"
3088                    | "sync.auth_lease_revoked"
3089                    | "sync.internal_error"
3090                    | "sync.idempotency_cache_miss"
3091                    | "sync.schema_not_ready"
3092                    | "sync.segment_expired"
3093                    | "sync.rate_limited"
3094                    | "sync.websocket_connection_limit"
3095            )
3096    }
3097
3098    fn diagnostic_code(code: &str) -> String {
3099        let valid = !code.is_empty()
3100            && code.len() <= 96
3101            && code.contains('.')
3102            && code
3103                .bytes()
3104                .next()
3105                .is_some_and(|byte| byte.is_ascii_lowercase())
3106            && code.bytes().all(|byte| {
3107                byte.is_ascii_lowercase()
3108                    || byte.is_ascii_digit()
3109                    || matches!(byte, b'.' | b'_' | b'-')
3110            });
3111        if valid {
3112            code.to_owned()
3113        } else {
3114            "client.unknown_failure".to_owned()
3115        }
3116    }
3117
3118    fn set_sync_needed(&mut self, value: bool, interactive: bool) {
3119        if self.sync_needed != value {
3120            if self.begin_observation("syncular_status").is_ok() {
3121                self.sync_needed = value;
3122                let batch = ChangeAccumulator {
3123                    status: true,
3124                    ..ChangeAccumulator::default()
3125                };
3126                if self.finish_observation("syncular_status", batch).is_err() {
3127                    self.rollback_observation("syncular_status");
3128                }
3129            } else {
3130                self.sync_needed = value;
3131            }
3132        }
3133        if value && interactive {
3134            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3135        }
3136    }
3137
3138    /// A unit-store result: a row that does not parse is `sync.local_corrupt`;
3139    /// every other SQLite error keeps its storage classification.
3140    fn stored<T>(&self, result: rusqlite::Result<T>) -> Result<T, String> {
3141        result.map_err(|error| match error {
3142            rusqlite::Error::FromSqlConversionFailure(..) => {
3143                "sync.local_corrupt: persisted unit state is invalid".to_owned()
3144            }
3145            error => Self::sqlite_failure(&self.storage_failure, error),
3146        })
3147    }
3148
3149    fn sqlite_failure(
3150        storage_failure: &RefCell<Option<QueryReadFailure>>,
3151        error: rusqlite::Error,
3152    ) -> String {
3153        let message = error.to_string();
3154        let failure = QueryReadFailure::from(error);
3155        let code = failure.code;
3156        if code.is_some() && storage_failure.borrow().is_none() {
3157            *storage_failure.borrow_mut() = Some(failure);
3158        }
3159        match code {
3160            Some(code) => format!("{code}: {message}"),
3161            None => message,
3162        }
3163    }
3164
3165    fn begin_observation(&self, name: &str) -> Result<(), String> {
3166        if let Some(failure) = &self.coalesced_failure {
3167            return Err(failure.clone());
3168        }
3169        // SQLite rolls a whole transaction back on some I/O and capacity
3170        // errors; later frames must not commit on their own after that.
3171        if self.coalesced.is_some() && self.conn.is_autocommit() {
3172            return Err("the coalesced apply transaction was rolled back".to_owned());
3173        }
3174        self.conn
3175            .execute_batch(&format!("SAVEPOINT {name}"))
3176            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3177    }
3178
3179    /// SPEC §1.4 rule 4: open a coalesced apply transaction unless a caller
3180    /// already owns one.
3181    fn begin_coalesced_apply(&mut self) -> Result<(), String> {
3182        if self.coalesced.is_some() || !self.conn.is_autocommit() {
3183            return Ok(());
3184        }
3185        self.conn
3186            .execute_batch("BEGIN")
3187            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3188        self.coalesced = Some(CoalescedApply {
3189            rows: 0,
3190            rollback: self.capture(),
3191        });
3192        Ok(())
3193    }
3194
3195    fn capture(&self) -> Rollback {
3196        Rollback {
3197            outbox: self.outbox.clone(),
3198            failed_commits: self.failed_commits.clone(),
3199            conflicts: self.conflicts.clone(),
3200            rejections: self.rejections.clone(),
3201            schema_floor: self.schema_floor.clone(),
3202            lease_state: self.lease_state.clone(),
3203            stopped: self.stopped,
3204            upgrading: self.upgrading,
3205            sync_needed: self.sync_needed,
3206            active_round: self.active_round,
3207            overlay_dirty: self.overlay_dirty.snapshot(),
3208            change_queue: self.change_queue.len(),
3209            sync_intent_queue: self.sync_intent_queue.len(),
3210            last_change: self.last_change.clone(),
3211        }
3212    }
3213
3214    fn restore(&mut self, rollback: Rollback) {
3215        self.outbox = rollback.outbox;
3216        self.failed_commits = rollback.failed_commits;
3217        self.conflicts = rollback.conflicts;
3218        self.rejections = rollback.rejections;
3219        self.schema_floor = rollback.schema_floor;
3220        self.lease_state = rollback.lease_state;
3221        self.stopped = rollback.stopped;
3222        self.upgrading = rollback.upgrading;
3223        self.sync_needed = rollback.sync_needed;
3224        self.active_round = rollback.active_round;
3225        self.overlay_dirty.restore(rollback.overlay_dirty);
3226        self.change_queue.truncate(rollback.change_queue);
3227        self.sync_intent_queue.truncate(rollback.sync_intent_queue);
3228        self.last_change = rollback.last_change;
3229    }
3230
3231    /// Account the rows of the next frame or block. A unit that would take the
3232    /// coalesced transaction past the bound commits the earlier units first.
3233    fn coalesce_unit(&mut self, rows: usize) -> Result<(), String> {
3234        let Some(open) = &self.coalesced else {
3235            return Ok(());
3236        };
3237        if open.rows > 0 && open.rows + rows > COALESCED_APPLY_ROWS {
3238            self.commit_coalesced_apply()?;
3239            self.begin_coalesced_apply()?;
3240        }
3241        if let Some(open) = &mut self.coalesced {
3242            open.rows += rows;
3243        }
3244        Ok(())
3245    }
3246
3247    /// COMMIT the coalesced transaction. A failed COMMIT rolls every coalesced
3248    /// frame back, restores the in-memory state of its `BEGIN`, drops the
3249    /// change batches and sync intents queued since, and fails the rest of the
3250    /// response.
3251    fn commit_coalesced_apply(&mut self) -> Result<(), String> {
3252        let Some(open) = self.coalesced.take() else {
3253            return Ok(());
3254        };
3255        let committed = if self.conn.is_autocommit() {
3256            Err("the coalesced apply transaction was rolled back".to_owned())
3257        } else {
3258            self.conn
3259                .execute_batch("COMMIT")
3260                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3261        };
3262        let Err(error) = committed else {
3263            return Ok(());
3264        };
3265        if !self.conn.is_autocommit() {
3266            if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3267                let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3268            }
3269        }
3270        self.restore(open.rollback);
3271        self.coalesced_failure = Some(error.clone());
3272        Err(error)
3273    }
3274
3275    /// End the response's coalescing: COMMIT what is open and clear a failure.
3276    fn finish_coalesced_apply(&mut self) -> Result<(), String> {
3277        let committed = self.commit_coalesced_apply();
3278        match self.coalesced_failure.take() {
3279            Some(failure) => Err(failure),
3280            None => committed,
3281        }
3282    }
3283
3284    fn rollback_observation(&self, name: &str) {
3285        if let Err(error) = self
3286            .conn
3287            .execute_batch(&format!("ROLLBACK TO {name}; RELEASE {name}"))
3288        {
3289            if let Some(failure) = self.storage_failure.borrow_mut().as_mut() {
3290                if failure.rollback_failure.is_none() {
3291                    failure.rollback_failure = Some(Box::new(QueryReadFailure::from(error)));
3292                }
3293            }
3294        }
3295    }
3296
3297    fn finish_observation(
3298        &mut self,
3299        name: &str,
3300        mut batch: ChangeAccumulator,
3301    ) -> Result<(), String> {
3302        #[cfg(feature = "bench-internals")]
3303        let _phase = self.benchmark_phases.start(Phase::ObservationCommit);
3304        if self.failed_commits.iter().any(|(commit, _)| {
3305            commit
3306                .ops
3307                .iter()
3308                .any(|operation| batch.tables.contains_key(&operation.table))
3309        }) {
3310            batch.outcomes = true;
3311        }
3312        if !batch.touched() {
3313            self.conn
3314                .execute_batch(&format!("RELEASE {name}"))
3315                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3316            return Ok(());
3317        }
3318        let revision = self
3319            .local_revision()?
3320            .checked_add(1)
3321            .ok_or_else(|| "local revision exhausted u64".to_owned())?;
3322        self.conn
3323            .execute(
3324                "INSERT OR REPLACE INTO _syncular_meta(key, value) VALUES (?1, ?2)",
3325                rusqlite::params![LOCAL_REVISION_KEY, revision.to_string()],
3326            )
3327            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3328        let status = batch.status.then(|| self.status_snapshot());
3329        let event = ClientChangeBatch {
3330            revision: revision.to_string(),
3331            tables: batch
3332                .tables
3333                .into_iter()
3334                .map(|(table, scope_keys)| TableChange {
3335                    table,
3336                    scope_keys: scope_keys.map(|keys| keys.into_iter().collect()),
3337                })
3338                .collect(),
3339            windows: batch
3340                .windows
3341                .into_iter()
3342                .map(|(base_key, units)| WindowChange {
3343                    base_key,
3344                    units: units.into_iter().collect(),
3345                })
3346                .collect(),
3347            status,
3348            conflicts_changed: batch.conflicts,
3349            rejections_changed: batch.rejections,
3350            outcomes_changed: batch.outcomes,
3351            applied_commits: Vec::new(),
3352        };
3353        self.conn
3354            .execute_batch(&format!("RELEASE {name}"))
3355            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3356        let mut diagnostic_tables = event
3357            .tables
3358            .iter()
3359            .map(|entry| entry.table.clone())
3360            .collect::<BTreeSet<_>>()
3361            .into_iter()
3362            .collect::<Vec<_>>();
3363        // §7.6: the selected variables of the changed window bases.
3364        let mut diagnostic_windows = event
3365            .windows
3366            .iter()
3367            .map(|entry| {
3368                entry
3369                    .base_key
3370                    .split('\0')
3371                    .next()
3372                    .unwrap_or_default()
3373                    .to_owned()
3374            })
3375            .collect::<BTreeSet<_>>()
3376            .into_iter()
3377            .collect::<Vec<_>>();
3378        let domains_truncated = diagnostic_tables.len() > MAX_DIAGNOSTIC_DOMAINS
3379            || diagnostic_windows.len() > MAX_DIAGNOSTIC_DOMAINS;
3380        diagnostic_tables.truncate(MAX_DIAGNOSTIC_DOMAINS);
3381        diagnostic_windows.truncate(MAX_DIAGNOSTIC_DOMAINS);
3382        self.last_change = Some(DiagnosticLastChange {
3383            revision: event.revision.clone(),
3384            recorded_at_ms: self.clock_now_ms(),
3385            tables: diagnostic_tables,
3386            windows: diagnostic_windows,
3387            domains_truncated,
3388            status_changed: event.status.is_some(),
3389            conflicts_changed: event.conflicts_changed,
3390            rejections_changed: event.rejections_changed,
3391            outcomes_changed: event.outcomes_changed,
3392        });
3393        self.change_queue.push_back(event);
3394        Ok(())
3395    }
3396
3397    fn record_scope_map(
3398        &self,
3399        batch: &mut ChangeAccumulator,
3400        table_name: &str,
3401        scopes: &[(String, Vec<String>)],
3402    ) {
3403        let Some(table) = self.schema.table(table_name) else {
3404            return;
3405        };
3406        // A bulk scoped delete whose map leaves a declared variable unnamed
3407        // cannot list the deleted rows' keys for it: the change is table-wide.
3408        if table.scope_variables.iter().any(|scope| {
3409            !scopes
3410                .iter()
3411                .any(|(variable, _)| *variable == scope.variable)
3412        }) {
3413            batch.table(table_name);
3414            return;
3415        }
3416        for (variable, values) in scopes {
3417            let Some(scope) = table
3418                .scope_variables
3419                .iter()
3420                .find(|scope| &scope.variable == variable)
3421            else {
3422                continue;
3423            };
3424            for value in values {
3425                batch.scope(table_name, format!("{}:{value}", scope.prefix));
3426            }
3427        }
3428    }
3429
3430    /// Record a row's current scope keys from the base or visible table.
3431    fn record_row_scopes(
3432        &self,
3433        batch: &mut ChangeAccumulator,
3434        table_name: &str,
3435        row_id: &str,
3436        base: bool,
3437    ) -> bool {
3438        let Some(table) = self.schema.table(table_name) else {
3439            return false;
3440        };
3441        if table.scope_variables.is_empty() {
3442            return false;
3443        }
3444        let columns = table
3445            .scope_variables
3446            .iter()
3447            .map(|scope| quote_ident(&scope.column))
3448            .collect::<Vec<_>>()
3449            .join(", ");
3450        let full_table = if base {
3451            base_table(table_name)
3452        } else {
3453            visible_table(table_name)
3454        };
3455        let sql = format!(
3456            "SELECT {columns} FROM {full_table} WHERE {} LIMIT 1",
3457            row_id_predicate(table)
3458        );
3459        let Ok(mut stmt) = self.conn.prepare_cached(&sql) else {
3460            return false;
3461        };
3462        let values = stmt.query_row(rusqlite::params![row_id], |row| {
3463            let mut values = Vec::with_capacity(table.scope_variables.len());
3464            for index in 0..table.scope_variables.len() {
3465                values.push(row.get::<_, Option<String>>(index)?);
3466            }
3467            Ok(values)
3468        });
3469        let Ok(values) = values else {
3470            return false;
3471        };
3472        let mut recorded = false;
3473        for (scope, value) in table.scope_variables.iter().zip(values) {
3474            if let Some(value) = value {
3475                batch.scope(table_name, format!("{}:{value}", scope.prefix));
3476                recorded = true;
3477            }
3478        }
3479        recorded
3480    }
3481
3482    fn record_commit_changes(
3483        &self,
3484        batch: &mut ChangeAccumulator,
3485        tables: &[String],
3486        changes: &[ssp2::model::Change],
3487    ) {
3488        #[cfg(feature = "bench-internals")]
3489        let _phase = self.benchmark_phases.start(Phase::ObservationPrepare);
3490        for change in changes {
3491            let Some(table_name) = tables.get(change.table_index as usize) else {
3492                continue;
3493            };
3494            let mut precise = self.record_row_scopes(batch, table_name, &change.row_id, true);
3495            if let Some(table) = self.schema.table(table_name) {
3496                for (variable, value) in &change.scopes {
3497                    if let Some(scope) = table
3498                        .scope_variables
3499                        .iter()
3500                        .find(|scope| &scope.variable == variable)
3501                    {
3502                        batch.scope(table_name, format!("{}:{value}", scope.prefix));
3503                        precise = true;
3504                    }
3505                }
3506            }
3507            if !precise {
3508                batch.table(table_name);
3509            }
3510        }
3511    }
3512
3513    /// Whether a base or visible row matches the scope predicate; `false`
3514    /// without a local scope-column mapping. A SQLite failure is an error.
3515    fn scoped_rows_exist(
3516        &self,
3517        table_name: &str,
3518        effective: &[(String, Vec<String>)],
3519        owners: &[Vec<(String, Vec<String>)>],
3520    ) -> Result<bool, String> {
3521        let Some(table) = self.schema.table(table_name) else {
3522            return Ok(false);
3523        };
3524        let Ok(Some((predicate, params))) = local_scope_predicate(table, effective, owners) else {
3525            return Ok(false);
3526        };
3527        for source in [base_table(table_name), visible_table(table_name)] {
3528            if self
3529                .conn
3530                .query_row(
3531                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
3532                    rusqlite::params_from_iter(&params),
3533                    |row| row.get::<_, bool>(0),
3534                )
3535                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
3536            {
3537                return Ok(true);
3538            }
3539        }
3540        Ok(false)
3541    }
3542
3543    /// §5.6 first-page clear of `unit_id`'s pair: delete its rows except
3544    /// those another owner covers (§3.3), failing closed without a local
3545    /// scope-column mapping. Owners are read only when a row matches, inside
3546    /// the caller's transaction. Returns whether rows matched.
3547    fn clear_scope(
3548        &mut self,
3549        table: &TableSchema,
3550        effective: &[(String, Vec<String>)],
3551        unit_id: &str,
3552    ) -> Result<bool, SectionError> {
3553        let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
3554        let matched = self
3555            .scoped_rows_exist(&table.name, effective, &[])
3556            .map_err(storage)?;
3557        let owners = if matched {
3558            unit_owners(
3559                &self.stored(load_units(&self.conn)).map_err(storage)?,
3560                table,
3561                unit_id,
3562            )
3563        } else {
3564            Vec::new()
3565        };
3566        let changed = matched
3567            && (owners.is_empty()
3568                || self
3569                    .scoped_rows_exist(&table.name, effective, &owners)
3570                    .map_err(storage)?);
3571        if !self
3572            .purge_scope_rows(&table.name, effective, &owners)
3573            .map_err(storage)?
3574        {
3575            return Err(SectionError::FailClosed);
3576        }
3577        Ok(changed)
3578    }
3579
3580    /// §7.4.5: true while a schema-bump reset + first re-bootstrap runs.
3581    pub fn upgrading(&self) -> bool {
3582        self.upgrading
3583    }
3584
3585    /// §7.4.2 "app ships new code": swap to a NEW generated schema while
3586    /// keeping this client's local database (identity, outbox, tables). The
3587    /// §7.4.1 marker check then fires the wipe/re-bootstrap flow when the
3588    /// version increases. Recreation runs the same marker guard as opening
3589    /// a durable replica, holds the guard and every write it authorizes under
3590    /// one write transaction, and preserves the current client (compiled
3591    /// schema, outbox, tables) on refusal.
3592    pub fn recreate_with_schema(&mut self, schema_json: &Value) -> Result<(), String> {
3593        let new_schema = parse_schema_json(schema_json)?;
3594        validate_authority_reads(&new_schema, &self.limits.authority_reads)?;
3595        self.conn
3596            .execute_batch("BEGIN IMMEDIATE")
3597            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3598        let prior_schema = std::mem::replace(&mut self.schema, new_schema);
3599        // §7.4.3/§7.4.4: a reset inside this transaction mutates in-memory
3600        // state (dropped outbox commits, rejections, upgrade and floor flags,
3601        // overlay dirtiness) and appends change/intent batches. A COMMIT that
3602        // fails after the reset succeeded rolls the database back, so every
3603        // one of those fields is captured here and restored with it.
3604        let rollback = self.capture();
3605        let guarded = (|| -> Result<(), String> {
3606            // §7.4.2: the marker is re-read under the write lock the caller
3607            // holds, so a replica another process upgraded meanwhile refuses
3608            // this recreation instead of having its marker and tables
3609            // downgraded.
3610            let marker = read_local_schema_version(&self.conn, self.schema.version)?;
3611            self.create_bookkeeping_tables()?;
3612            match marker {
3613                Some(version) if version < self.schema.version => self.run_schema_reset()?,
3614                None => {
3615                    self.create_synced_tables()?;
3616                    self.persist_schema_version()?;
3617                }
3618                _ => {}
3619            }
3620            // §7.4.2: recreation IS the boot for the in-memory core, so reload the
3621            // durable outbox the same-version path is about to replay. Only the
3622            // outbox is reloaded: the recovery below reads it, and the caller's
3623            // rollback snapshot already covers this field.
3624            self.outbox = self.load_outbox()?.into();
3625            // §7.1/§7.4.4: recover intrinsically codec-invalid persisted values at
3626            // this guarded boundary once the schema and marker agree. A bump went
3627            // through `run_schema_reset`, which performs the same recovery after
3628            // it creates the new physical tables and before its final replay.
3629            self.drop_unencodable_outbox(false, None)?;
3630            if marker == Some(self.schema.version)
3631                && (!self.outbox.is_empty()
3632                    || !self.failed_commits.is_empty()
3633                    || self.has_acknowledged_rows()?)
3634            {
3635                self.overlay_dirty.set(true);
3636                self.rebuild_overlay()?;
3637            }
3638            self.prune_unknown_units(false)?;
3639            self.save_unit_scope_schema()?;
3640            // The conformance recreate is the in-memory equivalent of reopening
3641            // a durable client. Apply the same startup catch-up contract even
3642            // when the schema itself did not change.
3643            self.enqueue_startup_sync_if_needed()?;
3644            Ok(())
3645        })();
3646        let outcome = match guarded {
3647            Ok(()) => self
3648                .conn
3649                .execute_batch("COMMIT")
3650                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error)),
3651            Err(error) => Err(error),
3652        };
3653        if let Err(error) = outcome {
3654            if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3655                // Keep a failed rollback's typed storage classification.
3656                let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3657            }
3658            self.schema = prior_schema;
3659            self.restore(rollback);
3660            // Prepared insert statements were derived from the reverted schema.
3661            self.insert_sql.borrow_mut().clear();
3662            return Err(error);
3663        }
3664        if !self.security_preflight {
3665            self.drain_pending_evictions()?;
3666        }
3667        Ok(())
3668    }
3669
3670    fn enqueue_startup_sync_if_needed(&mut self) -> Result<(), String> {
3671        let startup_work = !self.stopped
3672            && (!self.outbox.is_empty()
3673                || self.has_acknowledged_rows()?
3674                || !self.load_pending_evictions()?.is_empty()
3675                || self
3676                    .stored(load_units(&self.conn))?
3677                    .iter()
3678                    .any(|unit| unit.status == UnitStatus::Active));
3679        if startup_work {
3680            self.sync_needed = true;
3681            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3682        }
3683        Ok(())
3684    }
3685
3686    /// A native client persists schema-floor stops across process restarts.
3687    /// Once the running app already satisfies that floor, the persisted stop
3688    /// is only stale evidence from an older server round (for example, the
3689    /// server was restarted after catching up to an app that was ahead).
3690    /// Clear it and let the normal startup pull re-negotiate. If the server is
3691    /// still incompatible it will return the floor again in that first round.
3692    fn clear_satisfied_persisted_schema_floor(&mut self) -> Result<(), String> {
3693        let satisfied = self
3694            .schema_floor
3695            .as_ref()
3696            .and_then(|floor| floor.required_schema_version)
3697            .is_some_and(|required| self.schema.version >= required);
3698        if !satisfied {
3699            return Ok(());
3700        }
3701        self.delete_meta(SCHEMA_FLOOR_KEY)?;
3702        self.schema_floor = None;
3703        self.stopped = false;
3704        Ok(())
3705    }
3706
3707    /// RFC 0005 D1: discard an orphan or stale container at boot. The reset
3708    /// path already swept it; this covers a same-version or fresh-install open,
3709    /// which runs no reset and therefore no sweep — plus the D7 TTL, which only
3710    /// an aware binary can apply.
3711    fn reconcile_previous_version_at_boot(&self) -> Result<(), String> {
3712        let Some(replica_path) = self.previous_version_replica_path() else {
3713            return Ok(());
3714        };
3715        let max_age_ms = self
3716            .previous_version
3717            .filter(|config| config.enabled)
3718            .map(|config| config.max_age_ms);
3719        reconcile_previous_version_at_boot(
3720            &self.conn,
3721            &replica_path,
3722            self.schema.version,
3723            max_age_ms,
3724            self.clock_now_ms(),
3725        )
3726    }
3727
3728    /// RFC 0005 D3: the sibling container path, or `None` when the replica has
3729    /// no file — an in-memory replica returns an empty path, and a `file:` URI
3730    /// has no plain sibling path — so the feature resolves as off there.
3731    fn previous_version_replica_path(&self) -> Option<String> {
3732        let path = self.conn.path()?;
3733        if path.is_empty() || path.starts_with("file:") {
3734            return None;
3735        }
3736        Some(path.to_owned())
3737    }
3738
3739    /// §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
3740    /// and leaseState. Drops/recreates every synced table from the new
3741    /// schema, resets unit sync state (keeping registrations), clears
3742    /// the schema-floor stop state, rewrites the marker, drops outbox commits
3743    /// that cannot re-encode (§7.4.4), and replays the survivors on top.
3744    fn run_schema_reset(&mut self) -> Result<(), String> {
3745        self.begin_observation("syncular_schema_reset")?;
3746        let rollback = self.capture();
3747        let mut batch = ChangeAccumulator::default();
3748        let result = self
3749            .run_schema_reset_observed(&mut batch, true)
3750            .and_then(|()| self.finish_observation("syncular_schema_reset", batch));
3751        if let Err(error) = result {
3752            self.rollback_observation("syncular_schema_reset");
3753            self.restore(rollback);
3754            return Err(error);
3755        }
3756        Ok(())
3757    }
3758
3759    fn run_log_epoch_reset(&mut self, log_epoch: &str) -> Result<Vec<String>, String> {
3760        if self.get_meta(LOG_EPOCH_KEY)?.is_none() {
3761            self.begin_observation("syncular_epoch_acquisition")?;
3762            let rollback = self.capture();
3763            if let Err(error) = self.conn.execute(
3764                "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3765                rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3766            ) {
3767                self.rollback_observation("syncular_epoch_acquisition");
3768                return Err(Self::sqlite_failure(&self.storage_failure, error));
3769            }
3770            self.sync_needed = true;
3771            let batch = ChangeAccumulator {
3772                status: true,
3773                ..ChangeAccumulator::default()
3774            };
3775            if let Err(error) = self.finish_observation("syncular_epoch_acquisition", batch) {
3776                self.rollback_observation("syncular_epoch_acquisition");
3777                self.restore(rollback);
3778                return Err(error);
3779            }
3780            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3781            return Ok(Vec::new());
3782        }
3783        let resets = self
3784            .stored(load_units(&self.conn))?
3785            .into_iter()
3786            .map(|unit| unit.id)
3787            .collect();
3788        self.begin_observation("syncular_log_epoch_reset")?;
3789        let rollback = self.capture();
3790        let mut batch = ChangeAccumulator::default();
3791        let result = self
3792            .run_schema_reset_observed(&mut batch, false)
3793            .and_then(|()| {
3794                self.conn
3795                    .execute(
3796                        "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3797                        rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3798                    )
3799                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3800                self.sync_needed = true;
3801                batch.status = true;
3802                self.finish_observation("syncular_log_epoch_reset", batch)
3803            });
3804        if let Err(error) = result {
3805            self.rollback_observation("syncular_log_epoch_reset");
3806            self.restore(rollback);
3807            return Err(error);
3808        }
3809        self.sync_intent_queue.push_back(SyncIntent::Interactive);
3810        Ok(resets)
3811    }
3812
3813    fn run_schema_reset_observed(
3814        &mut self,
3815        batch: &mut ChangeAccumulator,
3816        capture: bool,
3817    ) -> Result<(), String> {
3818        // §7.4.2: the reset is the only path that wipes local tables for a
3819        // version bump, and it rewrites the marker last. Re-read the marker
3820        // under this reset's transaction: a replica another process upgraded
3821        // meanwhile refuses here instead of being reset to this client's
3822        // older schema.
3823        read_local_schema_version(&self.conn, self.schema.version)?;
3824        self.conn
3825            .execute_batch(
3826                "DELETE FROM _syncular_acked_rows; DELETE FROM _syncular_row_deliveries;",
3827            )
3828            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3829        self.cancel_sync_round();
3830        self.upgrading = true;
3831        batch.status = true;
3832        // RFC 0005 D6: classify the pending outbox against the NEW compiled
3833        // schema BEFORE the wipe, and record the advisory audit. This pass
3834        // drops nothing, so the audit sees the original pending intent; the
3835        // §7.4.4 send-time drop and the intrinsic value recovery later in this
3836        // reset are the paths that remove a commit. The classification is
3837        // shared with the send-time drop so the two cannot disagree about what
3838        // is incompatible.
3839        if self.previous_version.is_some_and(|config| config.enabled) {
3840            let previous_version = self
3841                .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
3842                .and_then(|value| value.parse::<i32>().ok())
3843                .unwrap_or(self.schema.version);
3844            let pending = self
3845                .outbox
3846                .iter()
3847                .map(|commit| PendingCommitAudit {
3848                    commit_id: &commit.client_commit_id,
3849                    operations: commit_audit_operations(commit),
3850                })
3851                .collect::<Vec<_>>();
3852            crate::previous_version::write_previous_version_audit(
3853                &self.conn,
3854                &crate::previous_version::build_previous_version_audit(
3855                    &self.schema,
3856                    &pending,
3857                    previous_version,
3858                    self.schema.version,
3859                    self.clock_now_ms(),
3860                ),
3861            )?;
3862        }
3863        // RFC 0005 D5: the container lives in its own FILE, so the reset can
3864        // never reach it. Sweep first (unconditional — also on the log-epoch
3865        // reset, which captures nothing), then capture BEFORE the wipe drops
3866        // any row. A refused capture records its reason and leaves no file.
3867        if let Some(replica_path) = self.previous_version_replica_path() {
3868            sweep_previous_version_container(&self.conn, &replica_path)?;
3869            if capture {
3870                if let Some(config) = self.previous_version.filter(|config| config.enabled) {
3871                    let previous_version = self
3872                        .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
3873                        .and_then(|value| value.parse::<i32>().ok())
3874                        .unwrap_or(self.schema.version);
3875                    capture_previous_version_from_replica(
3876                        &self.conn,
3877                        &replica_path,
3878                        previous_version,
3879                        self.schema.version,
3880                        &config,
3881                        self.clock_now_ms(),
3882                    )?;
3883                }
3884            }
3885        }
3886        for table in &self.schema.tables {
3887            batch.table(&table.name);
3888        }
3889        for (base_key, value) in self.load_window_registry()? {
3890            batch.window(&base_key, &value);
3891        }
3892        if capture {
3893            self.prune_unknown_units(true)?;
3894        }
3895        // The per-table insert SQL is derived from the OLD column lists.
3896        self.insert_sql.borrow_mut().clear();
3897        self.overlay_dirty.set(true);
3898        // Drop every synced table (base + visible) that currently exists —
3899        // discovered from sqlite_master so a bump that adds/removes tables is
3900        // handled. Bookkeeping tables (`_syncular_outbox/_units/_meta`
3901        // and the blob cache) are preserved; base tables are `_syncular_base_*`
3902        // so they are matched explicitly, not by the bookkeeping filter.
3903        // Drop virtual tables first so SQLite removes every FTS shadow table
3904        // atomically instead of the generic discovery tearing it apart.
3905        let virtual_tables: Vec<String> = {
3906            let mut stmt = self
3907                .conn
3908                .prepare(
3909                    "SELECT name FROM sqlite_master WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%'",
3910                )
3911                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3912            let rows = stmt
3913                .query_map([], |row| row.get::<_, String>(0))
3914                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3915            rows.filter_map(Result::ok)
3916                .filter(|name| is_synced_table_name(name))
3917                .collect()
3918        };
3919        for name in virtual_tables {
3920            self.conn
3921                .execute_batch(&format!(
3922                    "DROP TABLE IF EXISTS {}",
3923                    quote_ident(&format!("_syncular_fts_{name}"))
3924                ))
3925                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3926            self.conn
3927                .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
3928                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3929        }
3930        let existing: Vec<String> = {
3931            let mut stmt = self
3932                .conn
3933                .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
3934                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3935            let rows = stmt
3936                .query_map([], |row| row.get::<_, String>(0))
3937                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3938            rows.filter_map(Result::ok)
3939                .filter(|name| is_synced_table_name(name))
3940                .collect()
3941        };
3942        for name in &existing {
3943            if let Some(table) = name.strip_prefix("_syncular_base_") {
3944                batch.table(table);
3945            } else if !name.starts_with("_syncular_") {
3946                batch.table(name);
3947            }
3948        }
3949        for name in existing {
3950            self.conn
3951                .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
3952                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3953        }
3954        // Recreate the synced tables from the NEW schema.
3955        self.create_synced_tables()?;
3956        // Reset every unit's sync state, keeping the registration.
3957        reset_units(&self.conn)
3958            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3959        // The stop state is over: this client now ships a servable schema.
3960        self.stopped = false;
3961        self.schema_floor = None;
3962        self.delete_meta(SCHEMA_FLOOR_KEY)?;
3963        // Rewrite the marker LAST so a crash mid-reset re-runs the reset.
3964        self.persist_schema_version()?;
3965        self.save_unit_scope_schema()?;
3966        // §7.1/§7.4.4: the previous-version capture and audit above saw the
3967        // original pending intent; the synced tables now carry the new schema, so
3968        // recover intrinsically codec-invalid persisted values here, before the
3969        // final replay. A pending upsert that names a column the new schema
3970        // removed stays pending for the send-time `drop_incompatible_outbox`
3971        // prepass. The reset wrapper snapshots and restores the outbox,
3972        // rejections, and change queues, so a failed commit rolls this recovery
3973        // back with the rest of the reset.
3974        // §7.4.4: the enclosing reset observation owns the publication, so the
3975        // recovery contributes its rejection, outcome, and table domains to it.
3976        self.drop_unencodable_outbox(false, Some(batch))?;
3977        // Re-apply the surviving outbox optimistically over the empty tables.
3978        self.rebuild_overlay()?;
3979        Ok(())
3980    }
3981
3982    /// §7.4.4 send-time prepass: a persisted upsert whose values reference a
3983    /// column the current schema lacks (or a removed table) cannot be encoded
3984    /// (`commit_audit_operations` inspects upserts, so a value-free delete stays
3985    /// encodable and is validated by the server), nor can an insert-intent
3986    /// upsert that lacks a non-nullable column (§7.1, the audit's
3987    /// `missing-required-column`). Drop the commit, undo
3988    /// its optimistic projection, and raise a client-local
3989    /// `sync.outbox_incompatible` rejection.
3990    fn drop_incompatible_outbox(&mut self) -> Result<bool, String> {
3991        let incompatible = self
3992            .outbox
3993            .iter()
3994            .filter(|commit| {
3995                first_incompatibility(&self.schema, &commit_audit_operations(commit)).is_some()
3996            })
3997            .cloned()
3998            .collect::<Vec<_>>();
3999        if incompatible.is_empty() {
4000            return Ok(false);
4001        }
4002        self.drop_outbox_commits(
4003            &incompatible,
4004            OUTBOX_INCOMPATIBLE_CODE,
4005            "the persisted commit cannot encode under the current schema",
4006        )?;
4007        Ok(true)
4008    }
4009
4010    /// §7.4.4 incompatible-commit path, also taken by a refused blob upload
4011    /// (§5.9.7) with the server's code: reject every operation of `commits`,
4012    /// remove them from the outbox, and undo their optimistic rows.
4013    fn drop_outbox_commits(
4014        &mut self,
4015        incompatible: &[Arc<OutboxCommit>],
4016        code: &str,
4017        message: &str,
4018    ) -> Result<(), String> {
4019        // §7.4.4: one observation covers the durable outcome writes, the outbox
4020        // removal, the in-memory drop, and the overlay rebuild, so a storage
4021        // fault leaves the replica and the client unchanged and publishes no
4022        // change; a successful drop publishes exactly one batch carrying the
4023        // rejections, outcomes, status, and the tables whose projection changed.
4024        let rollback = self.capture();
4025        let owns_transaction = self.conn.is_autocommit();
4026        self.begin_observation("syncular_outbox_drop")?;
4027        let mut batch = ChangeAccumulator::default();
4028        let dropped = (|| -> Result<(), String> {
4029            let mut rejections = Vec::new();
4030            for commit in incompatible {
4031                let results = commit
4032                    .ops
4033                    .iter()
4034                    .enumerate()
4035                    .map(|(op_index, operation)| {
4036                        let rejection = RejectionRecord {
4037                            client_commit_id: commit.client_commit_id.clone(),
4038                            op_index: op_index as i32,
4039                            code: code.to_owned(),
4040                            message: message.to_owned(),
4041                            retryable: false,
4042                            details: None,
4043                            operation: Some(CommitOperation::from(operation)),
4044                        };
4045                        rejections.push(rejection.clone());
4046                        CommitOperationOutcome::Error { rejection }
4047                    })
4048                    .collect::<Vec<_>>();
4049                self.persist_commit_outcome(
4050                    &commit.client_commit_id,
4051                    CommitOutcomeStatus::Rejected,
4052                    &results,
4053                    Some(&commit.ops),
4054                )?;
4055                self.delete_outbox_persisted(&commit.client_commit_id)?;
4056                // A removed table has no local projection to invalidate; every
4057                // surviving table the dropped commit touched does.
4058                for operation in &commit.ops {
4059                    if self.schema.table(&operation.table).is_some() {
4060                        batch.table(&operation.table);
4061                    }
4062                }
4063            }
4064            self.prune_commit_outcomes()?;
4065            let incompatible_ids = incompatible
4066                .iter()
4067                .map(|commit| commit.client_commit_id.as_str())
4068                .collect::<BTreeSet<_>>();
4069            self.outbox
4070                .retain(|commit| !incompatible_ids.contains(commit.client_commit_id.as_str()));
4071            self.rejections.extend(rejections);
4072            // The dropped commits' purely-optimistic rows are undone: the
4073            // visible projection is re-derived from the surviving base + outbox.
4074            self.overlay_dirty.set(true);
4075            self.rebuild_overlay()?;
4076            batch.status = true;
4077            batch.rejections = true;
4078            batch.outcomes = true;
4079            Ok(())
4080        })();
4081        let result = dropped.and_then(|()| self.finish_observation("syncular_outbox_drop", batch));
4082        if let Err(error) = result {
4083            // An outer RELEASE is the COMMIT. Roll back that transaction
4084            // directly: retrying RELEASE after ROLLBACK TO still needs the
4085            // reader's lock. A nested observation only rolls back its savepoint.
4086            if owns_transaction {
4087                if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
4088                    let mut failure = self.storage_failure.borrow_mut();
4089                    let failure =
4090                        failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
4091                    failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
4092                }
4093            } else {
4094                self.rollback_observation("syncular_outbox_drop");
4095            }
4096            self.restore(rollback);
4097            return Err(error);
4098        }
4099        Ok(())
4100    }
4101
4102    /// §7.4.3: (re)create the base + visible table pair for every synced
4103    /// table in the CURRENT schema (idempotent — `IF NOT EXISTS`).
4104    fn create_synced_tables(&self) -> Result<(), String> {
4105        for table in &self.schema.tables {
4106            // The base half + the visible half form the synced-table pair. An
4107            // index name is global in SQLite, so the base half's indexes are
4108            // name-prefixed (`_syncular_base_<index>`) to stay distinct.
4109            for (full, index_prefix) in [
4110                (base_table(&table.name), "_syncular_base_"),
4111                (visible_table(&table.name), ""),
4112            ] {
4113                let mut cols: Vec<String> =
4114                    table.columns.iter().map(|c| quote_ident(&c.name)).collect();
4115                cols.push("\"_syncular_version\" INTEGER NOT NULL".to_owned());
4116                let sql = format!(
4117                    "CREATE TABLE IF NOT EXISTS {full} ({} , PRIMARY KEY ({}))",
4118                    cols.join(", "),
4119                    quote_ident(&table.primary_key)
4120                );
4121                self.conn
4122                    .execute(&sql, [])
4123                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4124                // Local secondary indexes (CREATE INDEX subset). Created on
4125                // both halves so mirror reads hit an index on either. Runs on
4126                // both the initial create and the §7.4.3 reset recreate path.
4127                for index in &table.indexes {
4128                    let unique = if index.unique { "UNIQUE " } else { "" };
4129                    let index_name = quote_ident(&format!("{index_prefix}{}", index.name));
4130                    let cols_sql = index
4131                        .columns
4132                        .iter()
4133                        .map(|c| quote_ident(c))
4134                        .collect::<Vec<_>>()
4135                        .join(", ");
4136                    let index_sql = format!(
4137                        "CREATE {unique}INDEX IF NOT EXISTS {index_name} ON {full} ({cols_sql})"
4138                    );
4139                    self.conn
4140                        .execute(&index_sql, [])
4141                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4142                }
4143            }
4144        }
4145        // FTS exists only on the visible half. It is a local search
4146        // projection, never a synced/base table or a wire-schema member.
4147        for table in &self.schema.tables {
4148            for index in &table.fts_indexes {
4149                self.create_fts_projection(table, index)?;
4150            }
4151        }
4152        Ok(())
4153    }
4154
4155    fn fts_projection_exists(&self, index: &FtsIndexSchema) -> Result<bool, String> {
4156        let count: i64 = self
4157            .conn
4158            .query_row(
4159                "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?1",
4160                rusqlite::params![index.name],
4161                |row| row.get(0),
4162            )
4163            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4164        Ok(count > 0)
4165    }
4166
4167    fn drop_fts_triggers(&self, index: &FtsIndexSchema) -> Result<(), String> {
4168        for suffix in ["ai", "ad", "au"] {
4169            self.conn
4170                .execute(
4171                    &format!(
4172                        "DROP TRIGGER IF EXISTS {}",
4173                        quote_ident(&format!("{}_{suffix}", index.name))
4174                    ),
4175                    [],
4176                )
4177                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4178        }
4179        Ok(())
4180    }
4181
4182    fn create_fts_triggers(
4183        &self,
4184        table: &TableSchema,
4185        index: &FtsIndexSchema,
4186    ) -> Result<(), String> {
4187        let fts = quote_ident(&index.name);
4188        let source = visible_table(&table.name);
4189        let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4190        let pk = quote_ident(&table.primary_key);
4191        let projection_columns = std::iter::once(source_id.clone())
4192            .chain(index.columns.iter().map(|column| quote_ident(column)))
4193            .collect::<Vec<_>>()
4194            .join(", ");
4195        let new_values = std::iter::once(format!("CAST(new.{pk} AS TEXT)"))
4196            .chain(
4197                index
4198                    .columns
4199                    .iter()
4200                    .map(|column| format!("new.{}", quote_ident(column))),
4201            )
4202            .collect::<Vec<_>>()
4203            .join(", ");
4204        let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4205        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)");
4206        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)");
4207        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})");
4208        let bi = quote_ident(&format!("{}_bi", index.name));
4209        let ai = quote_ident(&format!("{}_ai", index.name));
4210        let ad = quote_ident(&format!("{}_ad", index.name));
4211        let au = quote_ident(&format!("{}_au", index.name));
4212        let replacement_exists = format!("EXISTS (SELECT 1 FROM {source} WHERE {pk} = new.{pk})");
4213        let sql = format!(
4214            "DROP TRIGGER IF EXISTS {bi};
4215             DROP TRIGGER IF EXISTS {ai};
4216             DROP TRIGGER IF EXISTS {ad};
4217             DROP TRIGGER IF EXISTS {au};
4218             CREATE TRIGGER {bi} BEFORE INSERT ON {source} WHEN {replacement_exists} BEGIN {delete_new}; END;
4219             CREATE TRIGGER {ai} AFTER INSERT ON {source} BEGIN {insert_new}; END;
4220             CREATE TRIGGER {ad} AFTER DELETE ON {source} BEGIN {delete_old}; END;
4221             CREATE TRIGGER {au} AFTER UPDATE ON {source} BEGIN {delete_old}; {delete_new}; {insert_new}; END;",
4222        );
4223        self.conn
4224            .execute_batch(&sql)
4225            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4226    }
4227
4228    fn rebuild_fts_projection(
4229        &self,
4230        table: &TableSchema,
4231        index: &FtsIndexSchema,
4232    ) -> Result<(), String> {
4233        let fts = quote_ident(&index.name);
4234        let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4235        let pk = quote_ident(&table.primary_key);
4236        let indexed_columns = index
4237            .columns
4238            .iter()
4239            .map(|column| quote_ident(column))
4240            .collect::<Vec<_>>();
4241        let projection_columns = std::iter::once(source_id.clone())
4242            .chain(indexed_columns.iter().cloned())
4243            .collect::<Vec<_>>()
4244            .join(", ");
4245        let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4246        let sql = format!(
4247            "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};",
4248            columns = indexed_columns.join(", "),
4249            source = visible_table(&table.name),
4250        );
4251        self.conn
4252            .execute_batch(&sql)
4253            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4254    }
4255
4256    fn create_fts_projection(
4257        &self,
4258        table: &TableSchema,
4259        index: &FtsIndexSchema,
4260    ) -> Result<(), String> {
4261        self.begin_observation("syncular_fts_schema")?;
4262        let result = (|| {
4263            let existed = self.fts_projection_exists(index)?;
4264            let tokenizer = index.tokenize.replace('\'', "''");
4265            let columns = index
4266                .columns
4267                .iter()
4268                .map(|column| quote_ident(column))
4269                .collect::<Vec<_>>()
4270                .join(", ");
4271            let sql = format!(
4272            "CREATE VIRTUAL TABLE IF NOT EXISTS {fts} USING fts5({source_id} UNINDEXED, {columns}, tokenize='{tokenizer}')",
4273            fts = quote_ident(&index.name),
4274            source_id = quote_ident(FTS_SOURCE_ID_COLUMN),
4275        );
4276            self.conn.execute(&sql, []).map_err(|error| {
4277                format!(
4278                    "cannot create local FTS5 projection {:?}: {error}",
4279                    index.name
4280                )
4281            })?;
4282            let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4283            let mapped: bool = self
4284                .conn
4285                .query_row(
4286                    "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1)",
4287                    [format!("_syncular_fts_{}", index.name)],
4288                    |row| row.get(0),
4289                )
4290                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4291            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))?;
4292            if !mapped && existed {
4293                self.conn
4294                    .execute_batch(&format!(
4295                        "INSERT INTO {mapping}(id, source_id) SELECT rowid, {} FROM {}",
4296                        quote_ident(FTS_SOURCE_ID_COLUMN),
4297                        quote_ident(&index.name)
4298                    ))
4299                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4300            }
4301            self.create_fts_triggers(table, index)?;
4302            if !existed {
4303                self.rebuild_fts_projection(table, index)?;
4304            }
4305            Ok(())
4306        })();
4307        if let Err(error) = result {
4308            self.rollback_observation("syncular_fts_schema");
4309            return Err(error);
4310        }
4311        if let Err(error) = self.conn.execute_batch("RELEASE syncular_fts_schema") {
4312            self.rollback_observation("syncular_fts_schema");
4313            return Err(error.to_string());
4314        }
4315        Ok(())
4316    }
4317
4318    // -- persistence write-through --------------------------------------------
4319
4320    fn persist_outbox_insert(&self, commit: &OutboxCommit) -> Result<(), String> {
4321        let ops: Vec<Value> = commit
4322            .ops
4323            .iter()
4324            .map(|op| {
4325                let mut entry = serde_json::json!({
4326                    "op": if op.upsert { "upsert" } else { "delete" },
4327                    "table": op.table,
4328                    "rowId": op.row_id,
4329                    "baseVersion": op.base_version,
4330                    "values": op.values.clone().map(Value::Object),
4331                });
4332                if op.insert {
4333                    entry["insert"] = Value::Bool(true);
4334                }
4335                entry
4336            })
4337            .collect();
4338        self.conn
4339            .execute(
4340                "INSERT OR REPLACE INTO _syncular_outbox (commit_id, ops_json) VALUES (?1, ?2)",
4341                rusqlite::params![commit.client_commit_id, Value::Array(ops).to_string()],
4342            )
4343            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4344        for operation in &commit.ops {
4345            let Some(values) = &operation.values else {
4346                continue;
4347            };
4348            let Some(table) = self.schema.table(&operation.table) else {
4349                continue;
4350            };
4351            for column in table
4352                .columns
4353                .iter()
4354                .filter(|column| column.ty == ColumnType::BlobRef)
4355            {
4356                let Some(Value::String(raw)) = values.get(&column.name) else {
4357                    continue;
4358                };
4359                let Ok(blob_ref) = serde_json::from_str::<Value>(raw) else {
4360                    continue;
4361                };
4362                let Some(blob_id) = blob_ref.get("blobId").and_then(Value::as_str) else {
4363                    continue;
4364                };
4365                self.conn
4366                    .execute(
4367                        "INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id, blob_id)
4368                         SELECT ?1, ?2 WHERE EXISTS (SELECT 1 FROM _syncular_blobs WHERE blob_id = ?2)",
4369                        rusqlite::params![commit.client_commit_id, blob_id],
4370                    )
4371                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4372            }
4373        }
4374        Ok(())
4375    }
4376
4377    fn delete_outbox_persisted(&self, client_commit_id: &str) -> Result<(), String> {
4378        self.conn
4379            .execute(
4380                "DELETE FROM _syncular_blob_commit_refs WHERE commit_id = ?1",
4381                rusqlite::params![client_commit_id],
4382            )
4383            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4384        self.conn
4385            .execute(
4386                "DELETE FROM _syncular_outbox WHERE commit_id = ?1",
4387                rusqlite::params![client_commit_id],
4388            )
4389            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4390        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)", [])
4391            .map(|_| ())
4392            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4393    }
4394
4395    fn outcome_status_name(status: CommitOutcomeStatus) -> &'static str {
4396        match status {
4397            CommitOutcomeStatus::Applied => "applied",
4398            CommitOutcomeStatus::Cached => "cached",
4399            CommitOutcomeStatus::Conflict => "conflict",
4400            CommitOutcomeStatus::Rejected => "rejected",
4401        }
4402    }
4403
4404    fn outcome_resolution_name(resolution: CommitOutcomeResolution) -> &'static str {
4405        match resolution {
4406            CommitOutcomeResolution::Active => "active",
4407            CommitOutcomeResolution::ResolvedKeepServer => "resolved_keep_server",
4408            CommitOutcomeResolution::Superseded => "superseded",
4409            CommitOutcomeResolution::Dismissed => "dismissed",
4410        }
4411    }
4412
4413    fn parse_outcome_status(value: &str) -> Result<CommitOutcomeStatus, String> {
4414        match value {
4415            "applied" => Ok(CommitOutcomeStatus::Applied),
4416            "cached" => Ok(CommitOutcomeStatus::Cached),
4417            "conflict" => Ok(CommitOutcomeStatus::Conflict),
4418            "rejected" => Ok(CommitOutcomeStatus::Rejected),
4419            _ => Err(format!("invalid persisted commit outcome status {value:?}")),
4420        }
4421    }
4422
4423    fn parse_outcome_resolution(value: &str) -> Result<CommitOutcomeResolution, String> {
4424        match value {
4425            "active" => Ok(CommitOutcomeResolution::Active),
4426            "resolved_keep_server" => Ok(CommitOutcomeResolution::ResolvedKeepServer),
4427            "superseded" => Ok(CommitOutcomeResolution::Superseded),
4428            "dismissed" => Ok(CommitOutcomeResolution::Dismissed),
4429            _ => Err(format!(
4430                "invalid persisted commit outcome resolution {value:?}"
4431            )),
4432        }
4433    }
4434
4435    fn persist_commit_outcome(
4436        &self,
4437        client_commit_id: &str,
4438        status: CommitOutcomeStatus,
4439        results: &[CommitOperationOutcome],
4440        operations: Option<&[OutboxOp]>,
4441    ) -> Result<(), String> {
4442        let results_json = serde_json::to_string(results).map_err(|error| error.to_string())?;
4443        let operations_json = operations
4444            .map(|items| {
4445                serde_json::to_string(&items.iter().map(CommitOperation::from).collect::<Vec<_>>())
4446            })
4447            .transpose()
4448            .map_err(|error| error.to_string())?;
4449        self.conn
4450            .execute(
4451                "INSERT INTO _syncular_commit_outcomes (
4452                   client_commit_id, status, recorded_at_ms, results_json,
4453                   operations_json, resolution
4454                 ) VALUES (?1, ?2, ?3, ?4, ?5, 'active')",
4455                rusqlite::params![
4456                    client_commit_id,
4457                    Self::outcome_status_name(status),
4458                    self.clock_now_ms(),
4459                    results_json,
4460                    operations_json
4461                ],
4462            )
4463            .map(|_| ())
4464            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4465    }
4466
4467    /// §7.2: the journal holds a stored cell only in its canonical shape. A cell
4468    /// the byte-envelope rule refuses cannot be journaled verbatim.
4469    fn stored_cell_is_representable(cell: &Value) -> bool {
4470        cell.is_null()
4471            || cell.is_string()
4472            || cell.is_boolean()
4473            || cell.is_number()
4474            || is_canonical_bytes_envelope(cell)
4475    }
4476
4477    fn stored_row_is_representable(value: &Value) -> bool {
4478        value
4479            .as_object()
4480            .is_some_and(|row| row.values().all(Self::stored_cell_is_representable))
4481    }
4482
4483    fn stored_operation_is_representable(value: &Value) -> bool {
4484        value.get("table").is_some_and(Value::is_string)
4485            && value.get("rowId").is_some_and(Value::is_string)
4486            && value.get("baseVersion").is_none_or(|v| {
4487                v.as_i64()
4488                    .is_some_and(|n| n.unsigned_abs() <= MAX_JS_SAFE_INTEGER)
4489            })
4490            && match value.get("op").and_then(Value::as_str) {
4491                Some("upsert") => {
4492                    value
4493                        .get("values")
4494                        .is_some_and(Self::stored_row_is_representable)
4495                        && value
4496                            .get("insert")
4497                            .is_none_or(|insert| *insert == Value::Bool(true))
4498                }
4499                Some("delete") => value.get("values").is_none() && value.get("insert").is_none(),
4500                _ => false,
4501            }
4502    }
4503
4504    /// §7.2/§7.4.4: a dropped commit keeps its operation envelope in the journal
4505    /// only when the journal reader accepts the serialized operation, which is the
4506    /// rule `outcome_from_row` applies to this same row later.
4507    fn outbox_op_is_journalable(operation: &OutboxOp) -> bool {
4508        serde_json::to_value(CommitOperation::from(operation))
4509            .is_ok_and(|value| Self::stored_operation_is_representable(&value))
4510    }
4511
4512    fn outcome_from_row(row: StoredCommitOutcomeRow) -> Result<CommitOutcome, String> {
4513        let StoredCommitOutcomeRow {
4514            sequence,
4515            client_commit_id,
4516            status,
4517            recorded_at_ms,
4518            results_json,
4519            operations_json,
4520            resolution,
4521            resolved_at_ms,
4522            replacement_client_commit_id,
4523        } = row;
4524        if sequence.unsigned_abs() > MAX_JS_SAFE_INTEGER
4525            || recorded_at_ms.unsigned_abs() > MAX_JS_SAFE_INTEGER
4526            || resolved_at_ms.is_some_and(|value| value.unsigned_abs() > MAX_JS_SAFE_INTEGER)
4527        {
4528            return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned());
4529        }
4530        let invalid = || "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
4531        let stored: Vec<Value> = serde_json::from_str(&results_json).map_err(|_| invalid())?;
4532        for result in &stored {
4533            let nested = match result.get("status").and_then(Value::as_str) {
4534                Some("conflict") => result.get("conflict"),
4535                Some("error") => result.get("rejection"),
4536                _ => None,
4537            };
4538            if nested
4539                .and_then(|record| record.get("operation"))
4540                .is_some_and(|op| !Self::stored_operation_is_representable(op))
4541                || (result.get("status").and_then(Value::as_str) == Some("conflict")
4542                    && nested
4543                        .and_then(|record| record.get("serverRow"))
4544                        .is_some_and(|row| !Self::stored_row_is_representable(row)))
4545            {
4546                return Err(invalid());
4547            }
4548        }
4549        let results: Vec<CommitOperationOutcome> =
4550            serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())?;
4551        let has_conflict = results
4552            .iter()
4553            .any(|result| matches!(result, CommitOperationOutcome::Conflict { .. }));
4554        let has_error = results
4555            .iter()
4556            .any(|result| matches!(result, CommitOperationOutcome::Error { .. }));
4557        let status = Self::parse_outcome_status(&status).map_err(|_| invalid())?;
4558        let redacted = results.is_empty() && operations_json.is_none();
4559        if match status {
4560            CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => has_conflict || has_error,
4561            CommitOutcomeStatus::Conflict => !(has_conflict || redacted),
4562            CommitOutcomeStatus::Rejected => has_conflict || !(has_error || redacted),
4563        } {
4564            return Err(invalid());
4565        }
4566        let operations: Option<Vec<CommitOperation>> = operations_json
4567            .map(|raw| {
4568                let stored: Vec<Value> = serde_json::from_str(&raw).map_err(|_| invalid())?;
4569                if !stored.iter().all(Self::stored_operation_is_representable) {
4570                    return Err(invalid());
4571                }
4572                serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())
4573            })
4574            .transpose()?;
4575        for result in &results {
4576            match result {
4577                CommitOperationOutcome::Conflict { conflict }
4578                    if conflict.server_version.unsigned_abs() > MAX_JS_SAFE_INTEGER =>
4579                {
4580                    return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned())
4581                }
4582                CommitOperationOutcome::Error { rejection } => {
4583                    if let Some(details) = &rejection.details {
4584                        let encoded = serde_json::to_string(details).map_err(|_| {
4585                            "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4586                        })?;
4587                        RejectionDetails::parse(&encoded).map_err(|_| {
4588                            "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4589                        })?;
4590                    }
4591                }
4592                _ => {}
4593            }
4594        }
4595        Ok(CommitOutcome {
4596            sequence,
4597            client_commit_id,
4598            status,
4599            recorded_at_ms,
4600            results,
4601            operations,
4602            retained_rows: None,
4603            resolution: Self::parse_outcome_resolution(&resolution)?,
4604            resolved_at_ms,
4605            replacement_client_commit_id,
4606        })
4607    }
4608
4609    /// Resolve declared unique keys through SQLite, including affinity and NULL semantics.
4610    fn unique_conflicts(
4611        &self,
4612        table: &TableSchema,
4613        values: &Map<String, Value>,
4614        base: bool,
4615    ) -> Result<Vec<RetainedUniqueConflict>, String> {
4616        let source = if base {
4617            base_table(&table.name)
4618        } else {
4619            visible_table(&table.name)
4620        };
4621        let mut conflicts = Vec::new();
4622        for index in table.indexes.iter().filter(|index| index.unique) {
4623            let mut params = vec![json_param_to_sql(
4624                values.get(&table.primary_key).ok_or("sync.local_corrupt")?,
4625            )?];
4626            for name in &index.columns {
4627                let column = table
4628                    .columns
4629                    .iter()
4630                    .find(|column| column.name == *name)
4631                    .ok_or("sync.local_corrupt")?;
4632                let cell = json_to_column_value(column, values.get(name))?;
4633                params.push(owned_sql_value(RowParam::Cell(&cell))?);
4634            }
4635            let sql = format!(
4636                "SELECT * FROM {source} WHERE {} != ? AND {}",
4637                quote_ident(&table.primary_key),
4638                index
4639                    .columns
4640                    .iter()
4641                    .map(|column| format!("{} = ?", quote_ident(column)))
4642                    .collect::<Vec<_>>()
4643                    .join(" AND ")
4644            );
4645            let mut statement = self
4646                .conn
4647                .prepare_cached(&sql)
4648                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4649            let records = statement
4650                .query_map(rusqlite::params_from_iter(params), |record| {
4651                    let values = table
4652                        .columns
4653                        .iter()
4654                        .enumerate()
4655                        .map(|(index, column)| {
4656                            let value = sql_ref_to_json(column, record.get_ref(index)?);
4657                            json_to_column_value(column, Some(&value)).map_err(|message| {
4658                                rusqlite::Error::ToSqlConversionFailure(message.into())
4659                            })
4660                        })
4661                        .collect::<Result<Row, _>>()?;
4662                    Ok((values, record.get::<_, i64>(table.columns.len())?))
4663                })
4664                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4665            for record in records {
4666                let (row, version) =
4667                    record.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4668                let row_id = render_row_id_json(Some(&column_value_to_json(&row[table.pk_index])))?;
4669                conflicts.push(RetainedUniqueConflict {
4670                    index: index.name.clone(),
4671                    columns: index.columns.clone(),
4672                    row_id,
4673                    server_row: table
4674                        .columns
4675                        .iter()
4676                        .zip(&row)
4677                        .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
4678                        .collect(),
4679                    server_version: version,
4680                });
4681            }
4682        }
4683        Ok(conflicts)
4684    }
4685
4686    fn attach_retained_rows(&self, mut outcome: CommitOutcome) -> Result<CommitOutcome, String> {
4687        if let Some((commit, initial)) = self
4688            .failed_commits
4689            .iter()
4690            .find(|(commit, _)| commit.client_commit_id == outcome.client_commit_id)
4691        {
4692            let mut rows = Vec::new();
4693            for operation in &commit.ops {
4694                // A table the current schema removed has no rows to retain.
4695                let Some(table) = self.schema.table(&operation.table) else {
4696                    continue;
4697                };
4698                let key =
4699                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
4700                        .map_err(|_| "sync.local_corrupt".to_owned())?;
4701                let base = self.stored_row(table, &operation.row_id, true)?;
4702                rows.push(RetainedCommitRow {
4703                    table: operation.table.clone(),
4704                    row_id: operation.row_id.clone(),
4705                    unique_conflicts: if operation.upsert {
4706                        self.unique_conflicts(
4707                            table,
4708                            initial
4709                                .get(&key)
4710                                .and_then(Value::as_object)
4711                                .or(operation.values.as_ref())
4712                                .ok_or("sync.local_corrupt")?,
4713                            true,
4714                        )?
4715                    } else {
4716                        Vec::new()
4717                    },
4718                    local_row: if operation.upsert {
4719                        initial
4720                            .get(&key)
4721                            .and_then(Value::as_object)
4722                            .cloned()
4723                            .or_else(|| operation.values.clone())
4724                    } else {
4725                        None
4726                    },
4727                    server_row: base.as_ref().map(|(values, _)| {
4728                        table
4729                            .columns
4730                            .iter()
4731                            .zip(values)
4732                            .map(|(column, value)| {
4733                                (column.name.clone(), column_value_to_json(value))
4734                            })
4735                            .collect()
4736                    }),
4737                    server_version: base.map(|(_, version)| version),
4738                });
4739            }
4740            outcome.retained_rows = Some(rows);
4741        }
4742        Ok(outcome)
4743    }
4744
4745    pub fn commit_outcome(&self, client_commit_id: &str) -> Result<Option<CommitOutcome>, String> {
4746        let row = self
4747            .conn
4748            .query_row(
4749                "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
4750                        resolution, resolved_at_ms, replacement_client_commit_id
4751                   FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
4752                rusqlite::params![client_commit_id],
4753                |row| {
4754                    Ok(StoredCommitOutcomeRow {
4755                        sequence: row.get(0)?,
4756                        client_commit_id: row.get(1)?,
4757                        status: row.get(2)?,
4758                        recorded_at_ms: row.get(3)?,
4759                        results_json: row.get(4)?,
4760                        operations_json: row.get(5)?,
4761                        resolution: row.get(6)?,
4762                        resolved_at_ms: row.get(7)?,
4763                        replacement_client_commit_id: row.get(8)?,
4764                    })
4765                },
4766            )
4767            .optional()
4768            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4769        row.map(|row| self.attach_retained_rows(Self::outcome_from_row(row)?))
4770            .transpose()
4771    }
4772
4773    /// Internal host step. The host must run its idle drive before finishing.
4774    #[doc(hidden)]
4775    pub fn prepare_current_base(
4776        &self,
4777        client_commit_id: &str,
4778        sequence: i64,
4779    ) -> Result<CurrentBasePreparation, CurrentBaseProof> {
4780        let outcome = self
4781            .commit_outcome(client_commit_id)
4782            .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?;
4783        let valid = outcome.as_ref().is_some_and(|outcome| {
4784            outcome.sequence == sequence
4785                && outcome.resolution == CommitOutcomeResolution::Active
4786                && matches!(
4787                    outcome.status,
4788                    CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
4789                )
4790                && outcome
4791                    .operations
4792                    .as_ref()
4793                    .zip(outcome.retained_rows.as_ref())
4794                    .is_some_and(|(operations, rows)| {
4795                        !rows.is_empty() && operations.len() == rows.len()
4796                    })
4797        });
4798        if !valid {
4799            return Err(CurrentBaseProof::failure(
4800                CurrentBaseProofReason::OutcomeUnavailable,
4801            ));
4802        }
4803        if !self.transport_enabled {
4804            return Err(CurrentBaseProof::failure(CurrentBaseProofReason::Offline));
4805        }
4806        Ok(CurrentBasePreparation {
4807            client_commit_id: client_commit_id.to_owned(),
4808            sequence,
4809            units: load_units(&self.conn)
4810                .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?,
4811            transport_epoch: self.transport_epoch,
4812            registration_epoch: self.registration_epoch,
4813            security_epoch: self.security_epoch,
4814        })
4815    }
4816
4817    /// Internal host step after the completed post-rejection idle drive.
4818    #[doc(hidden)]
4819    pub fn finish_current_base(
4820        &mut self,
4821        prepared: CurrentBasePreparation,
4822        drive: SyncOutcome,
4823    ) -> CurrentBaseProof {
4824        if !self.transport_enabled || self.transport_epoch != prepared.transport_epoch {
4825            return CurrentBaseProof::failure(CurrentBaseProofReason::Offline);
4826        }
4827        if self.registration_epoch != prepared.registration_epoch {
4828            return CurrentBaseProof::failure(CurrentBaseProofReason::MissingCoverage);
4829        }
4830        if self.security_preflight || self.security_epoch != prepared.security_epoch {
4831            return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed);
4832        }
4833        let report = match drive {
4834            SyncOutcome::Ok(report) => report,
4835            SyncOutcome::BudgetExhausted(_) => {
4836                return CurrentBaseProof::failure(CurrentBaseProofReason::BudgetExhausted)
4837            }
4838            _ => return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed),
4839        };
4840        if report.schema_floor.is_some() {
4841            return CurrentBaseProof::failure(CurrentBaseProofReason::SchemaFloor);
4842        }
4843        if self
4844            .conn
4845            .execute_batch("SAVEPOINT syncular_base_proof")
4846            .is_err()
4847        {
4848            return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
4849        }
4850        let proof = (|| {
4851            let snapshot = snapshot_read_connection(
4852                &self.conn,
4853                &SnapshotReadRequest {
4854                    units: prepared.units.iter().map(|unit| unit.id.clone()).collect(),
4855                    commit_ids: vec![prepared.client_commit_id.clone()],
4856                    ..Default::default()
4857                },
4858            )
4859            .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4860            let current = self
4861                .commit_outcome(&prepared.client_commit_id)
4862                .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4863            let unavailable = if report.revoked.is_empty() {
4864                CurrentBaseProofReason::OutcomeUnavailable
4865            } else {
4866                CurrentBaseProofReason::Revoked
4867            };
4868            let Some(outcome) = current else {
4869                return Err(unavailable);
4870            };
4871            if !matches!(
4872                snapshot.deliveries.first(),
4873                Some(CommitDelivery::Known { .. })
4874            ) || outcome.sequence != prepared.sequence
4875                || outcome.resolution != CommitOutcomeResolution::Active
4876                || !matches!(
4877                    outcome.status,
4878                    CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
4879                )
4880            {
4881                return Err(unavailable);
4882            }
4883            let (Some(operations), Some(rows)) = (outcome.operations, outcome.retained_rows) else {
4884                return Err(unavailable);
4885            };
4886            if rows.is_empty() || operations.len() != rows.len() {
4887                return Err(unavailable);
4888            }
4889            let after =
4890                load_units(&self.conn).map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4891            let complete: HashSet<&str> = snapshot
4892                .units
4893                .iter()
4894                .filter_map(|unit| match unit {
4895                    UnitCatchup::Known {
4896                        id,
4897                        bootstrap_complete: true,
4898                        ..
4899                    } => Some(id.as_str()),
4900                    _ => None,
4901                })
4902                .collect();
4903            // A unit id names one scope map (§4.1), so the same id before and
4904            // after the drive is the same registration.
4905            let candidates: Vec<&UnitRecord> = after
4906                .iter()
4907                .filter(|unit| {
4908                    complete.contains(unit.id.as_str())
4909                        && prepared.units.iter().any(|before| before.id == unit.id)
4910                })
4911                .collect();
4912            let covered = |table_name: &str, row: &Map<String, Value>| {
4913                let Some(table) = self.schema.table(table_name) else {
4914                    return false;
4915                };
4916                candidates.iter().any(|unit| {
4917                    covers(table, &unit.scopes)
4918                        && pair_scopes(&unit.scopes, table_name, unit.echo.as_deref()).is_some_and(
4919                            |scopes| {
4920                                scopes.iter().all(|(variable, allowed)| {
4921                                    table
4922                                        .scope_column(variable)
4923                                        .and_then(|column| match row.get(column) {
4924                                            Some(Value::String(value)) => Some(value.clone()),
4925                                            Some(Value::Bool(value)) => Some(value.to_string()),
4926                                            Some(Value::Number(value)) => {
4927                                                value.as_f64().map(|number| {
4928                                                    ryu_js::Buffer::new()
4929                                                        .format_finite(number)
4930                                                        .to_owned()
4931                                                })
4932                                            }
4933                                            _ => None,
4934                                        })
4935                                        .is_some_and(|value| {
4936                                            !value.is_empty() && allowed.contains(&value)
4937                                        })
4938                                })
4939                            },
4940                        )
4941                })
4942            };
4943            for row in &rows {
4944                let Some(base) = row.server_row.as_ref().or(row.local_row.as_ref()) else {
4945                    return Err(if report.revoked.is_empty() {
4946                        CurrentBaseProofReason::MissingCoverage
4947                    } else {
4948                        CurrentBaseProofReason::Revoked
4949                    });
4950                };
4951                if !covered(&row.table, base)
4952                    || row
4953                        .unique_conflicts
4954                        .iter()
4955                        .any(|conflict| !covered(&row.table, &conflict.server_row))
4956                {
4957                    return Err(if report.revoked.is_empty() {
4958                        CurrentBaseProofReason::MissingCoverage
4959                    } else {
4960                        CurrentBaseProofReason::Revoked
4961                    });
4962                }
4963            }
4964            Ok(rows)
4965        })();
4966        if self
4967            .conn
4968            .execute_batch("RELEASE syncular_base_proof")
4969            .is_err()
4970        {
4971            return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
4972        }
4973        match proof {
4974            Ok(rows) => CurrentBaseProof {
4975                proven: true,
4976                rows: Some(rows),
4977                reason: None,
4978            },
4979            Err(reason) => CurrentBaseProof::failure(reason),
4980        }
4981    }
4982
4983    pub fn prove_current_base(
4984        &mut self,
4985        transport: &mut dyn Transport,
4986        client_commit_id: &str,
4987        sequence: i64,
4988        max_rounds: Option<u32>,
4989    ) -> CurrentBaseProof {
4990        let prepared = match self.prepare_current_base(client_commit_id, sequence) {
4991            Ok(prepared) => prepared,
4992            Err(proof) => return proof,
4993        };
4994        let drive = self.sync_until_idle(transport, max_rounds);
4995        self.finish_current_base(prepared, drive)
4996    }
4997
4998    pub fn commit_outcomes(&self, query: CommitOutcomeQuery) -> Result<Vec<CommitOutcome>, String> {
4999        if query.limit == Some(0) {
5000            return Err("sync.invalid_request: commit outcome limit must be positive".to_owned());
5001        }
5002        let mut sql = String::from(
5003            "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
5004                    resolution, resolved_at_ms, replacement_client_commit_id
5005               FROM _syncular_commit_outcomes",
5006        );
5007        if query.active_only {
5008            sql.push_str(" WHERE resolution = 'active' AND status IN ('conflict', 'rejected')");
5009        }
5010        sql.push_str(" ORDER BY seq DESC");
5011        if let Some(limit) = query.limit {
5012            sql.push_str(&format!(" LIMIT {limit}"));
5013        }
5014        let mut stmt = self
5015            .conn
5016            .prepare(&sql)
5017            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5018        let rows = stmt
5019            .query_map([], |row| {
5020                Ok(StoredCommitOutcomeRow {
5021                    sequence: row.get(0)?,
5022                    client_commit_id: row.get(1)?,
5023                    status: row.get(2)?,
5024                    recorded_at_ms: row.get(3)?,
5025                    results_json: row.get(4)?,
5026                    operations_json: row.get(5)?,
5027                    resolution: row.get(6)?,
5028                    resolved_at_ms: row.get(7)?,
5029                    replacement_client_commit_id: row.get(8)?,
5030                })
5031            })
5032            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5033        let mut outcomes = Vec::new();
5034        for row in rows {
5035            outcomes.push(self.attach_retained_rows(Self::outcome_from_row(
5036                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
5037            )?)?);
5038        }
5039        Ok(outcomes)
5040    }
5041
5042    fn prune_commit_outcomes(&self) -> Result<(), String> {
5043        #[cfg(test)]
5044        self.outcome_prune_count
5045            .set(self.outcome_prune_count.get() + 1);
5046        let max_entries = self.limits.outcome_retention_max_entries.unwrap_or(1_000);
5047        let count = self
5048            .conn
5049            .query_row(
5050                "SELECT COUNT(*) FROM _syncular_commit_outcomes",
5051                [],
5052                |row| row.get::<_, i64>(0),
5053            )
5054            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5055            as usize;
5056        let excess = count.saturating_sub(max_entries);
5057        if excess == 0 {
5058            return Ok(());
5059        }
5060        let mut stmt = self
5061            .conn
5062            .prepare(
5063                "SELECT seq FROM _syncular_commit_outcomes
5064                  WHERE status IN ('applied', 'cached') OR resolution != 'active'
5065                  ORDER BY seq ASC LIMIT ?1",
5066            )
5067            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5068        let rows = stmt
5069            .query_map(rusqlite::params![excess as i64], |row| row.get::<_, i64>(0))
5070            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5071        let sequences = rows
5072            .collect::<Result<Vec<_>, _>>()
5073            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5074        drop(stmt);
5075        for sequence in sequences {
5076            self.conn
5077                .execute(
5078                    "DELETE FROM _syncular_commit_outcomes WHERE seq = ?1",
5079                    rusqlite::params![sequence],
5080                )
5081                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5082        }
5083        Ok(())
5084    }
5085
5086    // -- units (§4.1) ------------------------------------------------------------
5087
5088    /// Every registered unit in registration order (§4.1).
5089    pub fn units(&self) -> Result<Vec<UnitRecord>, String> {
5090        self.stored(load_units(&self.conn))
5091    }
5092
5093    pub fn unit(&self, id: &str) -> Result<Option<UnitRecord>, String> {
5094        self.stored(get_unit(&self.conn, id))
5095    }
5096
5097    /// Register one unit (§4.1) and return its id.
5098    pub fn subscribe(&mut self, scopes: UnitScopes) -> Result<String, String> {
5099        Ok(self.subscribe_many(vec![scopes])?.remove(0))
5100    }
5101
5102    /// Register several units in one local transaction and return their ids:
5103    /// one commit for all of them (on OPFS a commit costs milliseconds, so a
5104    /// cold start with hundreds of units pays it once). An error rolls back
5105    /// every registration of the call. Registering an active unit again
5106    /// changes nothing; a revoked unit re-arms (§3.3). A call that registers or
5107    /// re-arms a unit raises sync-needed with an interactive intent.
5108    pub fn subscribe_many(&mut self, units: Vec<UnitScopes>) -> Result<Vec<String>, String> {
5109        self.begin_observation("syncular_subscribe")?;
5110        let mut changed = false;
5111        let registered = (|| {
5112            let mut ids = Vec::with_capacity(units.len());
5113            for scopes in units {
5114                let (id, held) = self.hold_unit(scopes, true)?;
5115                changed |= held;
5116                ids.push(id);
5117            }
5118            self.conn
5119                .execute_batch("RELEASE syncular_subscribe")
5120                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5121            Ok(ids)
5122        })();
5123        let ids = match registered {
5124            Ok(ids) => ids,
5125            Err(error) => {
5126                self.rollback_observation("syncular_subscribe");
5127                return Err(error);
5128            }
5129        };
5130        if changed {
5131            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5132            self.set_sync_needed(true, true);
5133        }
5134        Ok(ids)
5135    }
5136
5137    /// Release the explicit reference to a unit. The unit leaves the
5138    /// registration list when no window base holds it (§4.1); its rows stay.
5139    pub fn unsubscribe(&mut self, id: &str) -> Result<(), String> {
5140        let Some(unit) = self.stored(get_unit(&self.conn, id))? else {
5141            return Ok(());
5142        };
5143        if !unit.explicit {
5144            return Ok(());
5145        }
5146        if !self.stored(window_refs(&self.conn, id))?.is_empty() {
5147            return self.stored(save_unit(
5148                &self.conn,
5149                &UnitRecord {
5150                    explicit: false,
5151                    ..unit
5152                },
5153            ));
5154        }
5155        self.conn
5156            .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5157            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5158        self.registration_epoch = self.registration_epoch.wrapping_add(1);
5159        if unit.status == UnitStatus::Active {
5160            self.set_sync_needed(true, true);
5161        }
5162        Ok(())
5163    }
5164
5165    /// Take one reference on a unit (§4.1): validate the scope map, register a
5166    /// new unit catching up with cursor `-1`, re-arm a revoked one (§3.3).
5167    /// Returns the id and whether the registration list changed.
5168    fn hold_unit(&mut self, scopes: UnitScopes, explicit: bool) -> Result<(String, bool), String> {
5169        if scopes.is_empty()
5170            || scopes.values().any(|value| value == "*")
5171            || !self
5172                .schema
5173                .tables
5174                .iter()
5175                .any(|table| covers(table, &scopes))
5176        {
5177            return Err("sync.invalid_subscription: a unit names one non-wildcard value per variable and covers a table".to_owned());
5178        }
5179        let id = ssp2::registration::unit_id(&scope_pairs(&scopes));
5180        let existing = self.stored(get_unit(&self.conn, &id))?;
5181        if let Some(existing) = existing
5182            .as_ref()
5183            .filter(|unit| unit.status != UnitStatus::Revoked)
5184        {
5185            if explicit && !existing.explicit {
5186                self.stored(save_unit(
5187                    &self.conn,
5188                    &UnitRecord {
5189                        explicit,
5190                        ..existing.clone()
5191                    },
5192                ))?;
5193            }
5194            return Ok((id, false));
5195        }
5196        self.delete_pending_evict(&id)?;
5197        self.stored(save_unit(
5198            &self.conn,
5199            &UnitRecord {
5200                id: id.clone(),
5201                scopes,
5202                explicit: explicit || existing.is_some_and(|unit| unit.explicit),
5203                status: UnitStatus::Active,
5204                reason_code: None,
5205                cursor: Some(-1),
5206                bootstrap_state: None,
5207                seeded: Vec::new(),
5208                echo: None,
5209            },
5210        ))?;
5211        Ok((id, true))
5212    }
5213
5214    // -- windows (§4.8) -----------------------------------------------------------
5215
5216    /// §4.8: set the windowed-in values of a base, one unit per value. Added
5217    /// values take a reference on their unit (a new unit bootstraps on the
5218    /// next sync); removed values release theirs, and a unit no reference
5219    /// holds leaves the registration list fused with its first eviction chunk
5220    /// (E1–E4). Idempotent; re-entry cancels a deferred eviction.
5221    pub fn set_window(
5222        &mut self,
5223        base: &WindowBase,
5224        units: &[String],
5225    ) -> Result<CommandEffects, String> {
5226        let base_key = window_base_key(base);
5227        let live = self.load_window_units(&base_key)?;
5228        let mut changed = false;
5229        for value in units {
5230            if live.iter().any(|(held, _)| held == value) {
5231                continue;
5232            }
5233            let rollback = self.capture();
5234            self.begin_observation("syncular_window")?;
5235            let widened = (|| {
5236                let (id, registered) = self.hold_unit(window_unit_scopes(base, value), false)?;
5237                self.sync_needed |= registered;
5238                self.conn
5239                    .execute(
5240                        "INSERT OR REPLACE INTO _syncular_windows(base, unit, sub_id) VALUES (?1, ?2, ?3)",
5241                        rusqlite::params![base_key, value, id],
5242                    )
5243                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5244                let mut batch = ChangeAccumulator::default();
5245                batch.window(&base_key, value);
5246                batch.status = true;
5247                self.finish_observation("syncular_window", batch)
5248            })();
5249            if let Err(error) = widened {
5250                self.rollback_observation("syncular_window");
5251                self.restore(rollback);
5252                return Err(error);
5253            }
5254            changed = true;
5255            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5256        }
5257        for (value, id) in live {
5258            if units.contains(&value) {
5259                continue;
5260            }
5261            self.rebuild_overlay_if_dirty()?;
5262            let rollback = self.capture();
5263            self.begin_observation("syncular_window")?;
5264            let remaining = self.release_window_unit(&base_key, &value, &id);
5265            let remaining = match remaining {
5266                Ok(remaining) => remaining,
5267                Err(error) => {
5268                    self.rollback_observation("syncular_window");
5269                    self.restore(rollback);
5270                    return Err(error);
5271                }
5272            };
5273            changed = true;
5274            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5275            if remaining {
5276                self.drain_pending_evictions()?;
5277            }
5278        }
5279        Ok(if changed && self.transport_enabled {
5280            CommandEffects::interactive()
5281        } else {
5282            CommandEffects::none()
5283        })
5284    }
5285
5286    /// §4.8 completeness oracle: the windowed-in values of a base and those
5287    /// whose unit is not complete. A value is complete once its unit is active
5288    /// and no longer bootstrapping; registration alone is not completeness.
5289    pub fn window_state(&self, base: &WindowBase) -> Result<WindowState, String> {
5290        persisted_window_state(&self.conn, base).map_err(|failure| failure.message)
5291    }
5292
5293    /// Registry rows for a base, ordered by value: (value, unit id).
5294    fn load_window_units(&self, base_key: &str) -> Result<Vec<(String, String)>, String> {
5295        let mut statement = self
5296            .conn
5297            .prepare_cached(
5298                "SELECT unit, sub_id FROM _syncular_windows WHERE base = ?1 ORDER BY unit ASC",
5299            )
5300            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5301        let rows = statement
5302            .query_map([base_key], |row| Ok((row.get(0)?, row.get(1)?)))
5303            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5304        rows.collect::<Result<_, _>>()
5305            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5306    }
5307
5308    /// Every window registry row: (base key, value).
5309    fn load_window_registry(&self) -> Result<Vec<(String, String)>, String> {
5310        let mut statement = self
5311            .conn
5312            .prepare_cached("SELECT base, unit FROM _syncular_windows ORDER BY base, unit")
5313            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5314        let rows = statement
5315            .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
5316            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5317        rows.collect::<Result<_, _>>()
5318            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5319    }
5320
5321    /// §4.8: release a window value's reference inside the caller's
5322    /// observation. When no reference holds the unit, unregister it fused with
5323    /// its first eviction chunk (E3): delete the rows of every covered table
5324    /// matching the persisted echo, except rows pinned by the outbox (E1) or
5325    /// owned by another unit (§3.3), and park the per-table scopes of what
5326    /// remains in the pending-eviction registry. Fails closed without a local
5327    /// scope-column mapping. Returns whether unpinned rows remain.
5328    fn release_window_unit(
5329        &mut self,
5330        base_key: &str,
5331        value: &str,
5332        id: &str,
5333    ) -> Result<bool, String> {
5334        self.conn
5335            .execute(
5336                "DELETE FROM _syncular_windows WHERE base = ?1 AND unit = ?2",
5337                rusqlite::params![base_key, value],
5338            )
5339            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5340        let mut batch = ChangeAccumulator::default();
5341        batch.window(base_key, value);
5342        batch.status = true;
5343        let unit = self.stored(get_unit(&self.conn, id))?;
5344        let mut remaining = false;
5345        if let Some(unit) = unit.filter(|unit| !unit.explicit) {
5346            if self.stored(window_refs(&self.conn, id))?.is_empty() {
5347                let units = self.stored(load_units(&self.conn))?;
5348                self.conn
5349                    .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5350                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5351                self.sync_needed = true;
5352                for table in self.schema.tables.clone() {
5353                    let Some(effective) = unit
5354                        .echo
5355                        .as_deref()
5356                        .filter(|_| covers(&table, &unit.scopes))
5357                        .and_then(|echo| pair_scopes(&unit.scopes, &table.name, Some(echo)))
5358                    else {
5359                        continue;
5360                    };
5361                    let pinned = self.pinned_row_ids(&table.name);
5362                    let owners = unit_owners(&units, &table, id);
5363                    let (more, deferred) =
5364                        self.evict_scope_rows(&table.name, &effective, &owners, &pinned)?;
5365                    remaining |= more;
5366                    if deferred {
5367                        self.save_pending_evict(id, &table.name, &effective)?;
5368                    }
5369                    self.record_scope_map(&mut batch, &table.name, &effective);
5370                }
5371            }
5372        }
5373        self.finish_observation("syncular_window", batch)?;
5374        Ok(remaining)
5375    }
5376
5377    /// §4.8 E1: delete base rows owned by the effective scopes
5378    /// ([`local_scope_predicate`]) EXCEPT pinned primary keys. Returns (more
5379    /// unpinned work, any scoped rows remain). A missing scope-column mapping
5380    /// fails without deleting rows.
5381    fn evict_scope_rows(
5382        &self,
5383        table_name: &str,
5384        effective: &[(String, Vec<String>)],
5385        owners: &[Vec<(String, Vec<String>)>],
5386        pinned: &std::collections::HashSet<String>,
5387    ) -> Result<(bool, bool), String> {
5388        let table = self.schema.table(table_name).ok_or("sync.unknown_table")?;
5389        let Some((scope, mut params)) = local_scope_predicate(table, effective, owners)
5390            .map_err(|()| "sync.scope_revoked".to_owned())?
5391        else {
5392            return Ok((false, false));
5393        };
5394        let scope_params = params.len();
5395        let pk = quote_ident(&table.primary_key);
5396        // Pinned ids are rowId text; the text form matches every key type.
5397        let predicate = if pinned.is_empty() {
5398            scope.clone()
5399        } else {
5400            params.extend(pinned.iter().cloned().map(SqlValue::Text));
5401            let holes = vec!["?"; pinned.len()].join(", ");
5402            format!("{scope} AND CAST({pk} AS TEXT) NOT IN ({holes})")
5403        };
5404        let base = base_table(table_name);
5405        let visible = visible_table(table_name);
5406        let mut ids: Vec<SqlValue> = Vec::new();
5407        for source in [&base, &visible] {
5408            let mut stmt = self
5409                .conn
5410                .prepare_cached(&format!(
5411                    "SELECT {pk} FROM {source} WHERE {predicate} LIMIT 1024"
5412                ))
5413                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5414            ids = stmt
5415                .query_map(rusqlite::params_from_iter(&params), |row| row.get(0))
5416                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5417                .collect::<Result<_, _>>()
5418                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5419            if !ids.is_empty() {
5420                break;
5421            }
5422        }
5423        if !ids.is_empty() {
5424            for id in &ids {
5425                self.conn
5426                    .execute(
5427                        "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2",
5428                        rusqlite::params![table_name, id],
5429                    )
5430                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5431            }
5432            let holes = vec!["?"; ids.len()].join(", ");
5433            for source in [&base, &visible] {
5434                self.conn
5435                    .execute(
5436                        &format!("DELETE FROM {source} WHERE {pk} IN ({holes})"),
5437                        rusqlite::params_from_iter(&ids),
5438                    )
5439                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5440            }
5441        }
5442        let mut remaining = false;
5443        let mut deferred = false;
5444        for source in [&base, &visible] {
5445            remaining |= self
5446                .conn
5447                .query_row(
5448                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
5449                    rusqlite::params_from_iter(&params),
5450                    |row| row.get::<_, bool>(0),
5451                )
5452                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5453            deferred |= self
5454                .conn
5455                .query_row(
5456                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {scope})"),
5457                    rusqlite::params_from_iter(&params[..scope_params]),
5458                    |row| row.get::<_, bool>(0),
5459                )
5460                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5461        }
5462        Ok((remaining, deferred))
5463    }
5464
5465    /// §4.8 E1: continue deferred evictions after the outbox drains or between
5466    /// chunks, retaining outbox pins and their durable marker. A unit that
5467    /// re-entered the window has no pending entry left.
5468    fn drain_pending_evictions(&mut self) -> Result<(), String> {
5469        let pending = self.load_pending_evictions()?;
5470        if pending.is_empty() {
5471            return Ok(());
5472        }
5473        self.rebuild_overlay_if_dirty()?;
5474        for (unit_id, table_name, effective) in pending {
5475            let Some(table) = self.schema.table(&table_name).cloned() else {
5476                self.delete_pending_evict_table(&unit_id, &table_name)?;
5477                continue;
5478            };
5479            loop {
5480                std::thread::yield_now();
5481                self.begin_observation("syncular_evict")?;
5482                let chunk = (|| {
5483                    let pinned = self.pinned_row_ids(&table_name);
5484                    let owners =
5485                        unit_owners(&self.stored(load_units(&self.conn))?, &table, &unit_id);
5486                    let (remaining, deferred) =
5487                        self.evict_scope_rows(&table_name, &effective, &owners, &pinned)?;
5488                    if !deferred {
5489                        self.delete_pending_evict_table(&unit_id, &table_name)?;
5490                    }
5491                    let mut batch = ChangeAccumulator::default();
5492                    self.record_scope_map(&mut batch, &table_name, &effective);
5493                    self.finish_observation("syncular_evict", batch)?;
5494                    Ok(remaining)
5495                })();
5496                match chunk {
5497                    Ok(true) => {}
5498                    Ok(false) => break,
5499                    Err(error) => {
5500                        self.rollback_observation("syncular_evict");
5501                        return Err(error);
5502                    }
5503                }
5504            }
5505        }
5506        Ok(())
5507    }
5508
5509    /// §4.8 E1: primary keys of `table` referenced by a pending outbox
5510    /// commit — rows that MUST NOT be evicted until the commit drains.
5511    fn pinned_row_ids(&self, table: &str) -> std::collections::HashSet<String> {
5512        let mut pinned = std::collections::HashSet::new();
5513        for commit in self
5514            .outbox
5515            .iter()
5516            .map(|commit| &**commit)
5517            .chain(self.failed_commits.iter().map(|(commit, _)| commit))
5518        {
5519            for op in &commit.ops {
5520                if op.table == table {
5521                    pinned.insert(op.row_id.clone());
5522                }
5523            }
5524        }
5525        pinned
5526    }
5527
5528    fn save_pending_evict(
5529        &self,
5530        unit_id: &str,
5531        table: &str,
5532        effective: &[(String, Vec<String>)],
5533    ) -> Result<(), String> {
5534        self.conn.execute(
5535            "INSERT OR REPLACE INTO _syncular_pending_evictions(unit_id, tbl, effective_scopes) VALUES (?1, ?2, ?3)",
5536            rusqlite::params![unit_id, table, scope_map_to_json(effective).to_string()],
5537        ).map(|_| ()).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5538    }
5539
5540    /// Re-entry cancels every pending eviction of the unit.
5541    fn delete_pending_evict(&self, unit_id: &str) -> Result<(), String> {
5542        self.conn
5543            .execute(
5544                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
5545                [unit_id],
5546            )
5547            .map(|_| ())
5548            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5549    }
5550
5551    fn delete_pending_evict_table(&self, unit_id: &str, table: &str) -> Result<(), String> {
5552        self.conn
5553            .execute(
5554                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1 AND tbl = ?2",
5555                [unit_id, table],
5556            )
5557            .map(|_| ())
5558            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5559    }
5560
5561    fn load_pending_evictions(&self) -> Result<Vec<PendingEvict>, String> {
5562        let mut stmt = self
5563            .conn
5564            .prepare("SELECT unit_id, tbl, effective_scopes FROM _syncular_pending_evictions")
5565            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5566        let rows = stmt
5567            .query_map([], |row| {
5568                Ok((
5569                    row.get::<_, String>(0)?,
5570                    row.get::<_, String>(1)?,
5571                    row.get::<_, String>(2)?,
5572                ))
5573            })
5574            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5575        rows.map(|row| {
5576            let (unit_id, table, json) =
5577                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5578            let value: Value = serde_json::from_str(&json)
5579                .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5580            let effective = json_to_scope_map(&value)
5581                .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5582            Ok((unit_id, table, effective))
5583        })
5584        .collect()
5585    }
5586
5587    /// Select failed-intent retention; reload durable retained aggregates.
5588    pub fn set_retain_failed_commits(&mut self, enabled: bool) -> Result<(), String> {
5589        self.retain_failed_commits = enabled;
5590        for (commit, _) in self.failed_commits.iter() {
5591            for operation in &commit.ops {
5592                self.overlay_dirty.table(&operation.table);
5593            }
5594        }
5595        self.failed_commits = self.load_failed_commits()?.into();
5596        for (commit, _) in self.failed_commits.iter() {
5597            for operation in &commit.ops {
5598                self.overlay_dirty.table(&operation.table);
5599            }
5600        }
5601        Ok(())
5602    }
5603
5604    fn load_failed_commits(&self) -> Result<Vec<FailedCommit>, String> {
5605        let mut statement = self.conn.prepare("SELECT client_commit_id, operations_json, initial_json FROM _syncular_failed_commits ORDER BY seq")
5606            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5607        let rows = statement
5608            .query_map([], |row| {
5609                Ok((
5610                    row.get::<_, String>(0)?,
5611                    row.get::<_, String>(1)?,
5612                    row.get::<_, String>(2)?,
5613                ))
5614            })
5615            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5616        rows.map(|row| {
5617            let (id, operations, initial) =
5618                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5619            let operations: Vec<CommitOperation> =
5620                serde_json::from_str(&operations).map_err(|_| "sync.local_corrupt".to_owned())?;
5621            let initial =
5622                serde_json::from_str(&initial).map_err(|_| "sync.local_corrupt".to_owned())?;
5623            Ok((
5624                OutboxCommit {
5625                    client_commit_id: id,
5626                    ops: operations
5627                        .into_iter()
5628                        .map(|op| OutboxOp {
5629                            upsert: op.op == "upsert",
5630                            table: op.table,
5631                            row_id: op.row_id,
5632                            base_version: op.base_version,
5633                            values: op.values,
5634                            insert: op.insert,
5635                        })
5636                        .collect(),
5637                },
5638                initial,
5639            ))
5640        })
5641        .collect()
5642    }
5643
5644    fn retain_failed_commit(&mut self, id: &str, operations: &[OutboxOp]) -> Result<(), String> {
5645        let mut initial = Map::new();
5646        for operation in operations {
5647            // A table the current schema removed has no rows to retain.
5648            let Some(table) = self.schema.table(&operation.table) else {
5649                continue;
5650            };
5651            let initial_row = match self.stored_row(table, &operation.row_id, true)? {
5652                Some(row) => Some(row),
5653                None => self.visible_row(table, &operation.row_id)?,
5654            };
5655            if let Some((values, _)) = initial_row {
5656                let mut intended: Map<String, Value> = table
5657                    .columns
5658                    .iter()
5659                    .zip(values.iter())
5660                    .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
5661                    .collect();
5662                if let Some(patch) = &operation.values {
5663                    intended.extend(patch.clone());
5664                }
5665                initial.insert(
5666                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5667                        .map_err(|_| "sync.local_corrupt".to_owned())?,
5668                    Value::Object(intended),
5669                );
5670            }
5671        }
5672        self.conn.execute("INSERT INTO _syncular_failed_commits(client_commit_id, operations_json, initial_json) VALUES (?1, ?2, ?3)", rusqlite::params![id,
5673            serde_json::to_string(&operations.iter().map(CommitOperation::from).collect::<Vec<_>>()).map_err(|_| "sync.local_corrupt".to_owned())?,
5674            serde_json::to_string(&initial).map_err(|_| "sync.local_corrupt".to_owned())?])
5675            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5676        self.failed_commits.push((
5677            OutboxCommit {
5678                client_commit_id: id.to_owned(),
5679                ops: operations.to_vec(),
5680            },
5681            initial,
5682        ));
5683        Ok(())
5684    }
5685
5686    fn drop_failed_commits(
5687        &mut self,
5688        matches: impl Fn(&str, &Map<String, Value>) -> bool,
5689    ) -> Result<Vec<OutboxCommit>, String> {
5690        let mut doomed = self.drop_acknowledged_rows(&matches)?;
5691        for (commit, initial) in self.failed_commits.iter() {
5692            for operation in &commit.ops {
5693                let key =
5694                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5695                        .map_err(|_| "sync.local_corrupt".to_owned())?;
5696                if initial
5697                    .get(&key)
5698                    .and_then(Value::as_object)
5699                    .is_some_and(|values| matches(&operation.table, values))
5700                {
5701                    doomed.push(commit.clone());
5702                    break;
5703                }
5704            }
5705        }
5706        for commit in &doomed {
5707            self.conn
5708                .execute(
5709                    "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
5710                    rusqlite::params![commit.client_commit_id],
5711                )
5712                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5713        }
5714        for commit in &doomed {
5715            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))?;
5716        }
5717        self.conflicts.retain(|record| {
5718            !doomed
5719                .iter()
5720                .any(|commit| commit.client_commit_id == record.client_commit_id)
5721        });
5722        self.rejections.retain(|record| {
5723            !doomed
5724                .iter()
5725                .any(|commit| commit.client_commit_id == record.client_commit_id)
5726        });
5727        self.failed_commits.retain(|(commit, _)| {
5728            !doomed
5729                .iter()
5730                .any(|dropped| dropped.client_commit_id == commit.client_commit_id)
5731        });
5732        for commit in &doomed {
5733            for operation in &commit.ops {
5734                self.overlay_dirty.table(&operation.table);
5735            }
5736        }
5737        Ok(doomed)
5738    }
5739
5740    /// Record one commit of local mutations. The returned commit ID is the
5741    /// §2.3 idempotency key. Failures are structured so callers read
5742    /// `code`/`message`/`details` instead of parsing a string prefix.
5743    pub fn mutate(&mut self, mutations: Vec<Mutation>) -> Result<String, ClientError> {
5744        self.mutate_with_commit_id(mutations, None)
5745    }
5746
5747    /// [`Self::mutate`] under a caller-supplied `clientCommitId` (§7.1), so an
5748    /// app that loses the reply knows its commit. The ID is non-empty (§6.1);
5749    /// one this replica still holds fails with `client.commit_id_reused`.
5750    pub fn mutate_with_commit_id(
5751        &mut self,
5752        mutations: Vec<Mutation>,
5753        client_commit_id: Option<String>,
5754    ) -> Result<String, ClientError> {
5755        let prior = self.storage_failure.borrow_mut().take();
5756        if let Some(id) = &client_commit_id {
5757            let held = if id.is_empty() {
5758                Err("sync.invalid_request: clientCommitId is empty".to_owned())
5759            } else {
5760                self.conn
5761                    .query_row(
5762                        "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id=?1 UNION ALL SELECT 1 FROM _syncular_commit_outcomes WHERE client_commit_id=?1)",
5763                        [id],
5764                        |row| row.get(0),
5765                    )
5766                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5767            };
5768            match held {
5769                Ok(false) => {}
5770                Ok(true) => {
5771                    return self.finish_authoring(
5772                        prior,
5773                        Err(ClientError {
5774                            code: "client.commit_id_reused".to_owned(),
5775                            message: "clientCommitId is held".to_owned(),
5776                            details: Some(json!({ "clientCommitId": id })),
5777                            retryable: false,
5778                        }),
5779                    )
5780                }
5781                Err(message) => return self.finish_authoring(prior, Err(message.into())),
5782            }
5783        }
5784        let outcome = (|| -> Result<String, ClientError> {
5785            if mutations.is_empty() {
5786                return Err(
5787                    "sync.invalid_request: a commit must contain at least one operation (§6.1)"
5788                        .to_owned()
5789                        .into(),
5790                );
5791            }
5792            let mut ops = Vec::with_capacity(mutations.len());
5793            for mutation in mutations {
5794                match mutation {
5795                    Mutation::Patch {
5796                        table,
5797                        values,
5798                        base_version,
5799                    } => {
5800                        let schema_table = self
5801                            .schema
5802                            .table(&table)
5803                            .ok_or_else(|| "sync.unknown_table".to_owned())?;
5804                        let values = normalize_values_casing(schema_table, values)?;
5805                        let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
5806                        ops.push(self.prepare_patch(&table, &row_id, values, base_version)?);
5807                    }
5808                    Mutation::Upsert {
5809                        table,
5810                        values,
5811                        base_version,
5812                    } => {
5813                        let schema_table = self.schema.table(&table).ok_or_else(|| {
5814                            format!("sync.unknown_table: unknown table {table:?}")
5815                        })?;
5816                        // §5: value keys are accepted in snake_case AND the
5817                        // generated row types' camelCase; normalize to SQL truth
5818                        // before the pk lookup / codec see them.
5819                        let values = normalize_values_casing(schema_table, values)?;
5820                        let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
5821                        // §6.7 `mutate` marks every column present: fill missing
5822                        // nullable columns with NULL before the payload is built.
5823                        let values = full_row_values(schema_table, values)?;
5824                        // §5.11: validate the payload encodes with the current
5825                        // codec. A key-selection or unknown-key failure is a
5826                        // durable rejection at the push seam (§10.3), never an
5827                        // author-time error. Full-row `mutate` presents every
5828                        // column, so no stored fallback is needed.
5829                        self.validate_author_encode(schema_table, &row_id, &values)?;
5830                        // §7.1 insert intent: the row is absent from the
5831                        // visible replica at call time, before this batch
5832                        // applies anything.
5833                        let insert = !self.visible_row_exists(schema_table, &row_id)?;
5834                        ops.push(OutboxOp {
5835                            upsert: true,
5836                            table,
5837                            row_id,
5838                            base_version,
5839                            values: Some(values),
5840                            insert,
5841                        });
5842                    }
5843                    Mutation::Delete {
5844                        table,
5845                        row_id,
5846                        base_version,
5847                    } => {
5848                        if self.schema.table(&table).is_none() {
5849                            return Err(
5850                                format!("sync.unknown_table: unknown table {table:?}").into()
5851                            );
5852                        }
5853                        // §2.4: the server rejects a rowId holding U+0000.
5854                        if row_id.contains('\0') {
5855                            return Err("sync.invalid_request: rowId holds U+0000 (§2.4)"
5856                                .to_owned()
5857                                .into());
5858                        }
5859                        ops.push(OutboxOp {
5860                            upsert: false,
5861                            table,
5862                            row_id,
5863                            base_version,
5864                            values: None,
5865                            insert: false,
5866                        });
5867                    }
5868                }
5869            }
5870            Ok(self.record_outbox_commit(ops, client_commit_id)?)
5871        })();
5872        self.finish_authoring(prior, outcome)
5873    }
5874
5875    /// Scope the retained `storage_failure` diagnostic to this call so an
5876    /// earlier operation's failure cannot classify a new one, and surface the
5877    /// call's own classified failure with its details. A fresh classified
5878    /// failure replaces the retained diagnostic; otherwise the earlier one is
5879    /// kept for the next sync.
5880    fn finish_authoring(
5881        &self,
5882        prior: Option<QueryReadFailure>,
5883        outcome: Result<String, ClientError>,
5884    ) -> Result<String, ClientError> {
5885        let fresh = self.storage_failure.borrow_mut().take();
5886        *self.storage_failure.borrow_mut() = fresh.clone().or(prior);
5887        outcome.map_err(|error| fresh.map(ClientError::from).unwrap_or(error))
5888    }
5889
5890    fn record_outbox_commit(
5891        &mut self,
5892        ops: Vec<OutboxOp>,
5893        client_commit_id: Option<String>,
5894    ) -> Result<String, String> {
5895        let commit = OutboxCommit {
5896            client_commit_id: client_commit_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
5897            ops,
5898        };
5899        self.begin_observation("syncular_mutation")?;
5900        let mut batch = ChangeAccumulator::default();
5901        for op in &commit.ops {
5902            let mut precise = self.record_row_scopes(&mut batch, &op.table, &op.row_id, false);
5903            if let Some(values) = &op.values {
5904                if let Some(table) = self.schema.table(&op.table) {
5905                    for scope in &table.scope_variables {
5906                        if let Some(Value::String(value)) = values.get(&scope.column) {
5907                            batch.scope(&op.table, format!("{}:{value}", scope.prefix));
5908                            precise = true;
5909                        }
5910                    }
5911                }
5912            }
5913            if !precise {
5914                batch.table(&op.table);
5915            }
5916        }
5917        if let Err(error) = self.persist_outbox_insert(&commit) {
5918            self.rollback_observation("syncular_mutation");
5919            return Err(error);
5920        }
5921        // A clean overlay contains the FIFO fold of every previous commit, so
5922        // the new commit applies over it. §7.1: an operation that does not
5923        // apply (a secondary unique collision) fails the whole commit; the
5924        // savepoint rollback removes the outbox entry and every visible write.
5925        // The append undoes itself: a rollback capture would copy the outbox.
5926        let was_dirty = self.overlay_dirty.snapshot();
5927        let id = commit.client_commit_id.clone();
5928        let appended = self.rebuild_overlay_if_dirty().and_then(|()| {
5929            commit
5930                .ops
5931                .iter()
5932                .try_for_each(|op| self.apply_outbox_op(op))?;
5933            self.outbox.push(Arc::new(commit));
5934            batch.status = true;
5935            self.finish_observation("syncular_mutation", batch)
5936                .inspect_err(|_| drop(self.outbox.pop()))
5937        });
5938        if let Err(error) = appended {
5939            self.rollback_observation("syncular_mutation");
5940            self.overlay_dirty.restore(was_dirty);
5941            return Err(error);
5942        }
5943        Ok(id)
5944    }
5945
5946    /// Record one §6.1 sparse upsert: the primary key plus the supplied
5947    /// non-scope columns are present; every other column is absent and stays
5948    /// untouched on the server and in the local overlay. An absent local base
5949    /// refuses the whole batch with sync.row_missing before enqueueing (§7.1).
5950    /// Failures are structured so callers read `code`/`message`/`details`.
5951    pub fn patch(
5952        &mut self,
5953        table: &str,
5954        row_id: &str,
5955        partial: Map<String, Value>,
5956        base_version: Option<i64>,
5957    ) -> Result<String, ClientError> {
5958        let prior = self.storage_failure.borrow_mut().take();
5959        let outcome = self.perform_patch(table, row_id, partial, base_version);
5960        self.finish_authoring(prior, outcome)
5961    }
5962
5963    /// The unscoped patch body. Public authoring entry points scope
5964    /// `storage_failure` around the whole operation, including any pre-read.
5965    fn perform_patch(
5966        &mut self,
5967        table: &str,
5968        row_id: &str,
5969        partial: Map<String, Value>,
5970        base_version: Option<i64>,
5971    ) -> Result<String, ClientError> {
5972        let operation = self.prepare_patch(table, row_id, partial, base_version)?;
5973        Ok(self.record_outbox_commit(vec![operation], None)?)
5974    }
5975
5976    fn prepare_patch(
5977        &self,
5978        table: &str,
5979        row_id: &str,
5980        partial: Map<String, Value>,
5981        base_version: Option<i64>,
5982    ) -> Result<OutboxOp, ClientError> {
5983        let schema_table = self
5984            .schema
5985            .table(table)
5986            .ok_or_else(|| format!("sync.unknown_table: unknown table {table:?}"))?;
5987        let partial = normalize_values_casing(schema_table, partial)?;
5988        if let Some(pk) = partial.get(&schema_table.primary_key) {
5989            if render_row_id_json(Some(pk)).ok().as_deref() != Some(row_id) {
5990                return Err(invalid_authoring(
5991                    "patch cannot change the primary key",
5992                    json!({ "table": table }),
5993                ));
5994            }
5995        }
5996        if !self.visible_row_exists(schema_table, row_id)? {
5997            return Err("sync.row_missing: a sparse patch requires a local row"
5998                .to_owned()
5999                .into());
6000        }
6001        // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
6002        // server accepts a present scope column whose value equals the
6003        // stored row and applies it as a no-op, so a decoded envelope
6004        // round-trips. The local row is the only value the client can prove
6005        // equality against; when the row is absent locally the client cannot
6006        // prove equality against the server's stored row and fails closed.
6007        // A primary key that is also a scope column needs no stored-row
6008        // read: the primary key in a sparse payload is by construction the
6009        // row id being patched (§6.1), so its value is proven equal already.
6010        for scope in &schema_table.scope_variables {
6011            if !partial.contains_key(&scope.column) || scope.column == schema_table.primary_key {
6012                continue;
6013            }
6014            let Some(column) = schema_table
6015                .columns
6016                .iter()
6017                .find(|column| column.name == scope.column)
6018            else {
6019                continue;
6020            };
6021            let stored = self
6022                .conn
6023                .query_row(
6024                    &format!(
6025                        "SELECT {} FROM {} WHERE {}",
6026                        quote_ident(&scope.column),
6027                        visible_table(&schema_table.name),
6028                        row_id_predicate(schema_table)
6029                    ),
6030                    rusqlite::params![row_id],
6031                    |row| Ok(sql_ref_to_json(column, row.get_ref(0)?)),
6032                )
6033                .optional()
6034                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6035            // Decode the supplied value through the same column-type path the
6036            // rest of the patch encoding uses, so a value that only equals
6037            // the stored one in another number representation still compares
6038            // equal.
6039            let incoming = json_to_column_value(column, partial.get(&scope.column))
6040                .ok()
6041                .map(|value| column_value_to_json(&value));
6042            // A stored blob never equals a patch value, matching the server's
6043            // scope-column comparison (§3.4): bytes are unstorable as scope
6044            // values.
6045            let equal = stored.as_ref().is_some_and(|stored| {
6046                stored.get("$bytes").is_none() && incoming.as_ref() == Some(stored)
6047            });
6048            if !equal {
6049                return Err(invalid_authoring(
6050                    "patch cannot write a scope column (§3.4)",
6051                    json!({ "table": table, "column": scope.column }),
6052                ));
6053            }
6054        }
6055        let mut values = partial;
6056        // Presence-set semantics: a proven-equal scope column is dropped, so
6057        // the patch leaves the stored value untouched (§6.2).
6058        for scope in &schema_table.scope_variables {
6059            values.remove(&scope.column);
6060        }
6061        let pk_value = match schema_table.columns[schema_table.pk_index].ty {
6062            // §2.4: the rowId of an integer key is its canonical decimal form.
6063            ColumnType::Integer => match row_id.parse::<i64>() {
6064                Ok(v)
6065                    if v.to_string() == row_id
6066                        && (-ssp2::primitives::I64_SAFE_MAX..=ssp2::primitives::I64_SAFE_MAX)
6067                            .contains(&v) =>
6068                {
6069                    Value::from(v)
6070                }
6071                _ => {
6072                    return Err(format!(
6073                    "sync.invalid_request: table {table:?}: invalid integer primary key {row_id:?}"
6074                )
6075                    .into())
6076                }
6077            },
6078            ColumnType::Boolean => match row_id {
6079                "true" => Value::Bool(true),
6080                "false" => Value::Bool(false),
6081                _ => {
6082                    return Err(format!(
6083                    "sync.invalid_request: table {table:?}: invalid boolean primary key {row_id:?}"
6084                )
6085                    .into())
6086                }
6087            },
6088            _ => Value::from(row_id.to_owned()),
6089        };
6090        values.insert(schema_table.primary_key.clone(), pk_value);
6091        // §6.1: a patch cannot null a non-nullable column.
6092        if let Some(column) = schema_table
6093            .columns
6094            .iter()
6095            .find(|column| !column.nullable && values.get(&column.name) == Some(&Value::Null))
6096        {
6097            return Err(invalid_authoring(
6098                "a non-nullable column is null (§6.1)",
6099                json!({ "table": table, "column": column.name }),
6100            ));
6101        }
6102        // §5.11: structural validation only; an absent key-id selector is
6103        // resolved at the push seam from the stored local row, and a
6104        // key-selection or unknown-key failure becomes a durable
6105        // `client.encrypt_failed` rejection there (§10.3), never an
6106        // author-time error.
6107        self.validate_author_encode(schema_table, row_id, &values)?;
6108        Ok(OutboxOp {
6109            upsert: true,
6110            table: table.to_owned(),
6111            row_id: row_id.to_owned(),
6112            base_version,
6113            values: Some(values),
6114            insert: false,
6115        })
6116    }
6117
6118    /// §5.11 key-id fallback: the stored local row's selector value as a
6119    /// positional row (only the selector slot filled). Returns None when no
6120    /// selector is configured, the row is locally absent, or the stored
6121    /// value is not a usable key id. A failed storage read is an error.
6122    fn stored_key_fallback(
6123        &self,
6124        table: &TableSchema,
6125        row_id: &str,
6126    ) -> Result<Option<Row>, String> {
6127        let Some(selector) = self.encryption.key_id_columns.get(&table.name) else {
6128            return Ok(None);
6129        };
6130        let Some(index) = table
6131            .columns
6132            .iter()
6133            .position(|column| &column.name == selector)
6134        else {
6135            return Ok(None);
6136        };
6137        let sql = format!(
6138            "SELECT {} FROM {} WHERE {}",
6139            quote_ident(selector),
6140            visible_table(&table.name),
6141            row_id_predicate(table)
6142        );
6143        let key = self
6144            .conn
6145            .query_row(&sql, rusqlite::params![row_id], |row| {
6146                row.get::<_, Option<String>>(0)
6147            })
6148            .optional()
6149            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6150            .flatten()
6151            .filter(|key| !key.is_empty());
6152        let Some(key) = key else {
6153            return Ok(None);
6154        };
6155        let mut fallback: Row = vec![None; table.columns.len()];
6156        fallback[index] = Some(ColumnValue::String(key));
6157        Ok(Some(fallback))
6158    }
6159
6160    /// §5.11/§10.3 author-time encode check: a structural failure (a
6161    /// non-nullable NULL, a value the codec rejects) is an author-time
6162    /// error; a key-selection or unknown-key failure is deferred to the push
6163    /// seam, where it becomes a durable `client.encrypt_failed` rejection.
6164    fn validate_author_encode(
6165        &self,
6166        table: &TableSchema,
6167        row_id: &str,
6168        values: &Map<String, Value>,
6169    ) -> Result<(), String> {
6170        match encode_sparse_row_json(table, row_id, values, &self.encryption, None) {
6171            Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => Ok(()),
6172            result => result.map(|_| ()),
6173        }
6174    }
6175
6176    /// §5.11/§10.3: drop every pending commit whose push encode fails with
6177    /// `client.encrypt_failed` (an unresolvable key id or an unknown key) and
6178    /// raise one durable rejection per commit. `sync()` never aborts for an
6179    /// encode failure. Mirrors §7.4.4's `drop_incompatible_outbox`, including
6180    /// undoing the dropped commit's purely-optimistic rows.
6181    /// §7.1/§7.4.4: drop pending commits whose values the current codec refuses
6182    /// (an envelope or a type an earlier version accepted). `with_encryption`
6183    /// additionally drops commits whose §5.11 encryption cannot resolve a key;
6184    /// the startup boundary leaves those to the send seam, where hosts configure
6185    /// keys after open.
6186    /// Recovery runs as one observation. An enclosing observation (the guarded
6187    /// schema reset) passes its `batch`, so the rejection, outcome, and table
6188    /// domains join that change event instead of publishing a second one.
6189    fn drop_unencodable_outbox(
6190        &mut self,
6191        with_encryption: bool,
6192        batch: Option<&mut ChangeAccumulator>,
6193    ) -> Result<bool, String> {
6194        let mut failures = Vec::new();
6195        for commit in self.outbox.iter() {
6196            for op in &commit.ops {
6197                let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6198                    continue;
6199                };
6200                // An insert lacking a non-nullable column is left to
6201                // `drop_incompatible_outbox` (§7.4.4).
6202                let Some(values) = op.presented_values(table) else {
6203                    continue;
6204                };
6205                let fallback = self.stored_key_fallback(table, &op.row_id)?;
6206                let failure = match encode_sparse_row_json(
6207                    table,
6208                    &op.row_id,
6209                    &values,
6210                    &self.encryption,
6211                    fallback.as_ref(),
6212                ) {
6213                    Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => {
6214                        with_encryption.then_some((error, ENCRYPT_FAILED_CODE))
6215                    }
6216                    // §7.1/§7.4.4: a value the current codec refuses was
6217                    // persisted by a version that accepted it; it leaves
6218                    // through the incompatible-outbox path, so the FIFO
6219                    // queue never wedges.
6220                    Err(error) if error.starts_with(INVALID_REQUEST_CODE) => Some((
6221                        LEGACY_VALUE_REFUSAL_MESSAGE.to_owned(),
6222                        OUTBOX_INCOMPATIBLE_CODE,
6223                    )),
6224                    _ => None,
6225                };
6226                if let Some((error, code)) = failure {
6227                    failures.push((commit.clone(), error, code));
6228                    break;
6229                }
6230            }
6231        }
6232        if failures.is_empty() {
6233            return Ok(false);
6234        }
6235        // §7.4.4: one observation covers the durable outcome writes, the outbox
6236        // removal, the in-memory drop, and the overlay rebuild, so a storage fault
6237        // leaves the replica and the client unchanged, a successful recovery
6238        // publishes one batch with the rejection, outcome, and table domains, and
6239        // an ordinary open with nothing to recover publishes nothing.
6240        let rollback = self.capture();
6241        let owns_observation = batch.is_none();
6242        let owns_transaction = self.conn.is_autocommit();
6243        let mut domains = ChangeAccumulator::default();
6244        if owns_observation {
6245            self.begin_observation("syncular_value_recovery")?;
6246        }
6247        let dropped = (|| -> Result<(), String> {
6248            for (commit, message, code) in failures {
6249                if self.retain_failed_commits && code == ENCRYPT_FAILED_CODE {
6250                    self.retain_failed_commit(&commit.client_commit_id, &commit.ops)?;
6251                }
6252                let representable = commit.ops.iter().all(Self::outbox_op_is_journalable);
6253                let rejection = RejectionRecord {
6254                    client_commit_id: commit.client_commit_id.clone(),
6255                    op_index: 0,
6256                    code: code.to_owned(),
6257                    message,
6258                    retryable: false,
6259                    details: (code == OUTBOX_INCOMPATIBLE_CODE).then(|| RejectionDetails {
6260                        field_paths: None,
6261                        reason: Some(INVALID_STORED_VALUES_REASON.to_owned()),
6262                        required_action: None,
6263                        references: None,
6264                    }),
6265                    operation: representable
6266                        .then(|| commit.ops.first())
6267                        .flatten()
6268                        .map(CommitOperation::from),
6269                };
6270                self.persist_commit_outcome(
6271                    &commit.client_commit_id,
6272                    CommitOutcomeStatus::Rejected,
6273                    &[CommitOperationOutcome::Error {
6274                        rejection: rejection.clone(),
6275                    }],
6276                    representable.then_some(commit.ops.as_slice()),
6277                )?;
6278                self.delete_outbox_persisted(&commit.client_commit_id)?;
6279                self.outbox
6280                    .retain(|candidate| candidate.client_commit_id != commit.client_commit_id);
6281                self.rejections.push(rejection);
6282                for operation in &commit.ops {
6283                    domains.table(operation.table.as_str());
6284                }
6285            }
6286            domains.status = true;
6287            domains.rejections = true;
6288            domains.outcomes = true;
6289            self.prune_commit_outcomes()?;
6290            // The visible projection is re-derived from the surviving base + outbox.
6291            self.overlay_dirty.set(true);
6292            self.rebuild_overlay()?;
6293            Ok(())
6294        })();
6295        let result = match batch {
6296            Some(batch) => {
6297                if dropped.is_ok() {
6298                    for table in domains.tables.keys() {
6299                        batch.table(table.as_str());
6300                    }
6301                    batch.status |= domains.status;
6302                    batch.rejections |= domains.rejections;
6303                    batch.outcomes |= domains.outcomes;
6304                }
6305                dropped
6306            }
6307            None => {
6308                dropped.and_then(|()| self.finish_observation("syncular_value_recovery", domains))
6309            }
6310        };
6311        if let Err(error) = result {
6312            if owns_observation {
6313                if owns_transaction {
6314                    if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
6315                        let mut failure = self.storage_failure.borrow_mut();
6316                        let failure =
6317                            failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
6318                        failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
6319                    }
6320                } else {
6321                    self.rollback_observation("syncular_value_recovery");
6322                }
6323            }
6324            self.restore(rollback);
6325            return Err(error);
6326        }
6327        Ok(true)
6328    }
6329
6330    pub fn pending_commit_ids(&self) -> Vec<String> {
6331        self.outbox
6332            .iter()
6333            .map(|c| c.client_commit_id.clone())
6334            .collect()
6335    }
6336
6337    /// §6.1: the sparse push payload bytes of every pending upsert operation,
6338    /// FIFO — exactly what the next push round would put on the wire. Used by
6339    /// conformance B.21(h) to pin cross-core byte identity.
6340    pub fn pending_payloads(&self) -> Result<Vec<Vec<u8>>, String> {
6341        let mut payloads = Vec::new();
6342        for commit in self.outbox.iter() {
6343            for op in &commit.ops {
6344                let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6345                    continue;
6346                };
6347                let Some(values) = op.presented_values(table) else {
6348                    continue;
6349                };
6350                let fallback = self.stored_key_fallback(table, &op.row_id)?;
6351                if let Ok(payload) = encode_sparse_row_json(
6352                    table,
6353                    &op.row_id,
6354                    &values,
6355                    &self.encryption,
6356                    fallback.as_ref(),
6357                ) {
6358                    payloads.push(payload);
6359                }
6360            }
6361        }
6362        Ok(payloads)
6363    }
6364
6365    pub fn conflicts(&self) -> &[ConflictRecord] {
6366        &self.conflicts
6367    }
6368
6369    pub fn rejections(&self) -> &[RejectionRecord] {
6370        &self.rejections
6371    }
6372
6373    pub fn resolve_commit_outcome(
6374        &mut self,
6375        input: ResolveCommitOutcomeInput,
6376    ) -> Result<CommitOutcome, String> {
6377        let current = self
6378            .commit_outcome(&input.client_commit_id)?
6379            .ok_or_else(|| {
6380                format!(
6381                    "sync.outcome_not_found: no durable outcome exists for {:?}",
6382                    input.client_commit_id
6383                )
6384            })?;
6385        if current.resolution != CommitOutcomeResolution::Active {
6386            return Ok(current);
6387        }
6388        if input.resolution == CommitOutcomeResolution::Active {
6389            return Err("sync.invalid_request: resolution must leave active state".to_owned());
6390        }
6391        match input.resolution {
6392            CommitOutcomeResolution::Superseded => {
6393                let replacement = input
6394                    .replacement_client_commit_id
6395                    .as_deref()
6396                    .filter(|value| !value.is_empty() && *value != input.client_commit_id)
6397                    .ok_or_else(|| {
6398                        "sync.invalid_request: superseded outcomes require a distinct replacementClientCommitId"
6399                            .to_owned()
6400                    })?;
6401                let _ = replacement;
6402            }
6403            _ if input.replacement_client_commit_id.is_some() => {
6404                return Err(
6405                    "sync.invalid_request: replacementClientCommitId is valid only for superseded outcomes"
6406                        .to_owned(),
6407                );
6408            }
6409            _ => {}
6410        }
6411        let allowed = match current.status {
6412            CommitOutcomeStatus::Conflict => matches!(
6413                input.resolution,
6414                CommitOutcomeResolution::ResolvedKeepServer | CommitOutcomeResolution::Superseded
6415            ),
6416            CommitOutcomeStatus::Rejected => {
6417                matches!(
6418                    input.resolution,
6419                    CommitOutcomeResolution::Superseded
6420                        | CommitOutcomeResolution::ResolvedKeepServer
6421                )
6422            }
6423            CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => {
6424                input.resolution == CommitOutcomeResolution::Dismissed
6425            }
6426        };
6427        if !allowed {
6428            return Err(format!(
6429                "sync.invalid_request: resolution {:?} is invalid for {:?} outcome",
6430                input.resolution, current.status
6431            ));
6432        }
6433
6434        let rollback = self.capture();
6435        self.begin_observation("syncular_outcome_resolution")?;
6436        let result = (|| {
6437            self.conn
6438                .execute(
6439                    "UPDATE _syncular_commit_outcomes
6440                        SET resolution = ?1, resolved_at_ms = ?2,
6441                            replacement_client_commit_id = ?3
6442                      WHERE client_commit_id = ?4 AND resolution = 'active'",
6443                    rusqlite::params![
6444                        Self::outcome_resolution_name(input.resolution),
6445                        self.clock_now_ms(),
6446                        input.replacement_client_commit_id,
6447                        input.client_commit_id
6448                    ],
6449                )
6450                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6451            let resolved = self
6452                .commit_outcome(&current.client_commit_id)?
6453                .ok_or_else(|| "sync.outcome_not_found: outcome disappeared".to_owned())?;
6454            self.conn
6455                .execute(
6456                    "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
6457                    rusqlite::params![input.client_commit_id],
6458                )
6459                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6460            for (commit, _) in self.failed_commits.iter() {
6461                if commit.client_commit_id == input.client_commit_id {
6462                    for operation in &commit.ops {
6463                        self.overlay_dirty.table(&operation.table);
6464                    }
6465                }
6466            }
6467            self.failed_commits
6468                .retain(|(commit, _)| commit.client_commit_id != input.client_commit_id);
6469            self.prune_commit_outcomes()?;
6470            Ok(resolved)
6471        })();
6472        let resolved = match result {
6473            Ok(outcome) => outcome,
6474            Err(error) => {
6475                self.rollback_observation("syncular_outcome_resolution");
6476                self.restore(rollback);
6477                return Err(error);
6478            }
6479        };
6480        self.conflicts
6481            .retain(|record| record.client_commit_id != current.client_commit_id);
6482        self.rejections
6483            .retain(|record| record.client_commit_id != current.client_commit_id);
6484        let mut batch = ChangeAccumulator {
6485            conflicts: current.status == CommitOutcomeStatus::Conflict,
6486            rejections: current.status == CommitOutcomeStatus::Rejected,
6487            outcomes: true,
6488            ..ChangeAccumulator::default()
6489        };
6490        if let Some(operations) = &current.operations {
6491            for operation in operations {
6492                batch.table(&operation.table);
6493            }
6494        }
6495        if let Err(error) = self
6496            .rebuild_overlay_if_dirty()
6497            .and_then(|()| self.finish_observation("syncular_outcome_resolution", batch))
6498        {
6499            self.rollback_observation("syncular_outcome_resolution");
6500            self.restore(rollback);
6501            return Err(error);
6502        }
6503        Ok(resolved)
6504    }
6505
6506    pub fn schema_floor(&self) -> Option<&SchemaFloor> {
6507        self.schema_floor.as_ref()
6508    }
6509
6510    /// §7.3.5: the client's opaque auth-lease state, if any.
6511    pub fn lease_state(&self) -> Option<&LeaseState> {
6512        self.lease_state.as_ref()
6513    }
6514
6515    /// §7.3.5: record a request-level lease error (stop-and-surface). Only
6516    /// the two lease codes set it; other errors leave leaseState untouched.
6517    fn record_lease_error(&mut self, code: &str) -> Result<(), String> {
6518        if code != "sync.auth_lease_required" && code != "sync.auth_lease_revoked" {
6519            return Ok(());
6520        }
6521        let mut next = self.lease_state.clone().unwrap_or_default();
6522        next.error_code = Some(code.to_owned());
6523        self.set_lease_state(Some(next))
6524    }
6525
6526    fn set_lease_state(&mut self, next: Option<LeaseState>) -> Result<(), String> {
6527        if self.lease_state == next {
6528            return Ok(());
6529        }
6530        self.begin_observation("syncular_lease")?;
6531        let rollback = self.capture();
6532        self.lease_state = next;
6533        let persisted = match &self.lease_state {
6534            Some(lease) => serde_json::to_string(lease)
6535                .map_err(|error| error.to_string())
6536                .and_then(|json| self.set_meta(LEASE_STATE_KEY, &json)),
6537            None => self.delete_meta(LEASE_STATE_KEY),
6538        };
6539        let batch = ChangeAccumulator {
6540            status: true,
6541            ..ChangeAccumulator::default()
6542        };
6543        if let Err(error) =
6544            persisted.and_then(|()| self.finish_observation("syncular_lease", batch))
6545        {
6546            self.rollback_observation("syncular_lease");
6547            self.restore(rollback);
6548            return Err(error);
6549        }
6550        Ok(())
6551    }
6552
6553    fn set_schema_floor(&mut self, next: Option<SchemaFloor>) -> Result<(), String> {
6554        if self.schema_floor == next {
6555            return Ok(());
6556        }
6557        self.begin_observation("syncular_schema_floor")?;
6558        let rollback = self.capture();
6559        self.stopped = next.is_some();
6560        self.schema_floor = next;
6561        let persisted = match &self.schema_floor {
6562            Some(floor) => serde_json::to_string(floor)
6563                .map_err(|error| error.to_string())
6564                .and_then(|json| self.set_meta(SCHEMA_FLOOR_KEY, &json)),
6565            None => self.delete_meta(SCHEMA_FLOOR_KEY),
6566        };
6567        let batch = ChangeAccumulator {
6568            status: true,
6569            ..ChangeAccumulator::default()
6570        };
6571        if let Err(error) =
6572            persisted.and_then(|()| self.finish_observation("syncular_schema_floor", batch))
6573        {
6574            self.rollback_observation("syncular_schema_floor");
6575            self.restore(rollback);
6576            return Err(error);
6577        }
6578        Ok(())
6579    }
6580
6581    fn set_upgrading(&mut self, value: bool) {
6582        if self.upgrading == value {
6583            return;
6584        }
6585        if self.begin_observation("syncular_upgrading").is_err() {
6586            return;
6587        }
6588        self.upgrading = value;
6589        let batch = ChangeAccumulator {
6590            status: true,
6591            ..ChangeAccumulator::default()
6592        };
6593        if self
6594            .finish_observation("syncular_upgrading", batch)
6595            .is_err()
6596        {
6597            self.rollback_observation("syncular_upgrading");
6598        }
6599    }
6600
6601    pub fn sync_needed(&self) -> bool {
6602        self.sync_needed
6603    }
6604
6605    pub fn read_rows(&self, table: &str) -> Result<Vec<RowState>, String> {
6606        let schema_table = self
6607            .schema
6608            .table(table)
6609            .ok_or_else(|| format!("unknown table {table:?}"))?;
6610        let sql = format!(
6611            "SELECT * FROM {} ORDER BY {} ASC",
6612            visible_table(table),
6613            quote_ident(&schema_table.primary_key)
6614        );
6615        let mut stmt = self
6616            .conn
6617            .prepare(&sql)
6618            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6619        let mut rows = stmt
6620            .query([])
6621            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6622        let mut out = Vec::new();
6623        while let Some(row) = rows
6624            .next()
6625            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6626        {
6627            let mut values = Map::new();
6628            for (i, column) in schema_table.columns.iter().enumerate() {
6629                let value = row
6630                    .get_ref(i)
6631                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6632                values.insert(column.name.clone(), sql_ref_to_json(column, value));
6633            }
6634            let version: i64 = row
6635                .get(schema_table.columns.len())
6636                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6637            let row_id = match values.get(&schema_table.primary_key) {
6638                Some(Value::String(s)) => s.clone(),
6639                Some(Value::Number(n)) => n.to_string(),
6640                Some(Value::Bool(b)) => b.to_string(),
6641                other => format!("{}", other.cloned().unwrap_or(Value::Null)),
6642            };
6643            out.push(RowState {
6644                row_id,
6645                version,
6646                values,
6647            });
6648        }
6649        Ok(out)
6650    }
6651
6652    // -- §5.10.5 native CRDT (the `crdt-yjs` feature) --------------------------
6653    //
6654    // The Rust face of the §5.10.4 client model: a local crdt edit loads the
6655    // current stored (server-merged ⊕ pending-overlay) column bytes, applies
6656    // the op with `yrs`, re-encodes the whole doc state, and records a
6657    // baseVersion-less sparse upsert carrying only the primary key and the
6658    // crdt column (§5.10.3, §6.6). No local merge — merging is server-side;
6659    // the overlay re-materializes the edit immediately (optimistic apply,
6660    // §7.1) and the server-merged bytes arrive on the next pull, idempotently.
6661    // Byte-compatible with `@syncular/crdt-yjs`.
6662
6663    /// The current stored value of a `crdt` column for one row — the visible
6664    /// (optimistic) bytes, or `None` when the row is absent or the column is
6665    /// NULL (the empty document, §5.10.1). Errors if the column is not a
6666    /// `crdt` column (guards the app against a typo'd column name).
6667    #[cfg(feature = "crdt-yjs")]
6668    fn crdt_column_bytes(
6669        &self,
6670        table: &str,
6671        row_id: &str,
6672        column: &str,
6673    ) -> Result<Option<Vec<u8>>, String> {
6674        let schema_table = self
6675            .schema
6676            .table(table)
6677            .ok_or_else(|| format!("unknown table {table:?}"))?;
6678        let col = schema_table
6679            .columns
6680            .iter()
6681            .find(|c| c.name == column)
6682            .ok_or_else(|| format!("table {table:?} has no column {column:?}"))?;
6683        if col.ty != ColumnType::Crdt {
6684            return Err(format!("column {column:?} is not a crdt column (§5.10.1)"));
6685        }
6686        let sql = format!(
6687            "SELECT {} FROM {} WHERE {}",
6688            quote_ident(column),
6689            visible_table(table),
6690            row_id_predicate(schema_table)
6691        );
6692        let bytes: Option<Vec<u8>> = self
6693            .conn
6694            .prepare_cached(&sql)
6695            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6696            .query_row(rusqlite::params![row_id], |row| {
6697                row.get::<_, Option<Vec<u8>>>(0)
6698            })
6699            .map_err(|e| match e {
6700                rusqlite::Error::QueryReturnedNoRows => "no such row".to_owned(),
6701                other => Self::sqlite_failure(&self.storage_failure, other),
6702            })?;
6703        Ok(bytes)
6704    }
6705
6706    /// §5.10.4 materialize: the collaborative text of a `crdt` column, decoded
6707    /// from the stored bytes with `yrs` — `YjsColumn.text(name).toString()`.
6708    /// An absent row / NULL column is the empty document (empty string).
6709    #[cfg(feature = "crdt-yjs")]
6710    pub fn crdt_text(
6711        &self,
6712        table: &str,
6713        row_id: &str,
6714        column: &str,
6715        name: &str,
6716    ) -> Result<String, String> {
6717        let bytes = self
6718            .crdt_column_bytes(table, row_id, column)?
6719            .unwrap_or_default();
6720        crate::crdt::text(&bytes, name)
6721    }
6722
6723    /// §5.10.4 push-an-update: apply a text insert to a `crdt` column and
6724    /// record the resulting crdt-only sparse operation. Returns the enqueued
6725    /// `clientCommitId`.
6726    #[cfg(feature = "crdt-yjs")]
6727    pub fn crdt_insert_text(
6728        &mut self,
6729        table: &str,
6730        row_id: &str,
6731        column: &str,
6732        name: &str,
6733        index: u32,
6734        value: &str,
6735    ) -> Result<String, ClientError> {
6736        let prior = self.storage_failure.borrow_mut().take();
6737        let outcome = (|| -> Result<String, ClientError> {
6738            let current = self
6739                .crdt_column_bytes(table, row_id, column)?
6740                .unwrap_or_default();
6741            let update = crate::crdt::insert_text(&current, name, index, value)?;
6742            self.perform_crdt_push_update(table, row_id, column, &update)
6743        })();
6744        self.finish_authoring(prior, outcome)
6745    }
6746
6747    /// §5.10.4 push-an-update: apply a text delete to a `crdt` column and
6748    /// record the resulting crdt-only sparse operation. Returns the enqueued
6749    /// `clientCommitId`.
6750    #[cfg(feature = "crdt-yjs")]
6751    pub fn crdt_delete_text(
6752        &mut self,
6753        table: &str,
6754        row_id: &str,
6755        column: &str,
6756        name: &str,
6757        index: u32,
6758        len: u32,
6759    ) -> Result<String, ClientError> {
6760        let prior = self.storage_failure.borrow_mut().take();
6761        let outcome = (|| -> Result<String, ClientError> {
6762            let current = self
6763                .crdt_column_bytes(table, row_id, column)?
6764                .unwrap_or_default();
6765            let update = crate::crdt::delete_text(&current, name, index, len)?;
6766            self.perform_crdt_push_update(table, row_id, column, &update)
6767        })();
6768        self.finish_authoring(prior, outcome)
6769    }
6770
6771    /// §5.10.4 generic escape hatch: apply an arbitrary Yjs update onto a
6772    /// `crdt` column's current state and record the resulting crdt-only sparse
6773    /// operation. The app authored the update with its own `yrs` model.
6774    /// Returns the enqueued `clientCommitId`.
6775    #[cfg(feature = "crdt-yjs")]
6776    pub fn crdt_apply_update(
6777        &mut self,
6778        table: &str,
6779        row_id: &str,
6780        column: &str,
6781        update: &[u8],
6782    ) -> Result<String, ClientError> {
6783        let prior = self.storage_failure.borrow_mut().take();
6784        let outcome = (|| -> Result<String, ClientError> {
6785            let current = self
6786                .crdt_column_bytes(table, row_id, column)?
6787                .unwrap_or_default();
6788            let next = crate::crdt::apply_update(&current, update)?;
6789            self.perform_crdt_push_update(table, row_id, column, &next)
6790        })();
6791        self.finish_authoring(prior, outcome)
6792    }
6793
6794    /// Shared tail of the crdt edit methods: record a §6.1 sparse crdt-only
6795    /// upsert — the primary key plus the crdt column, no `baseVersion` — and
6796    /// enqueue it. The server merges the crdt column and leaves every other
6797    /// column untouched (§5.10.3), so a baseVersion-less crdt edit cannot
6798    /// clobber a concurrent edit to another column. A locally absent row
6799    /// records the same partial operation; the server answers per §6.2.
6800    #[cfg(feature = "crdt-yjs")]
6801    fn perform_crdt_push_update(
6802        &mut self,
6803        table: &str,
6804        row_id: &str,
6805        column: &str,
6806        crdt_bytes: &[u8],
6807    ) -> Result<String, ClientError> {
6808        let mut bytes_obj = Map::new();
6809        bytes_obj.insert("$bytes".to_owned(), Value::from(bytes_to_hex(crdt_bytes)));
6810        let mut partial = Map::new();
6811        partial.insert(column.to_owned(), Value::Object(bytes_obj));
6812        self.perform_patch(table, row_id, partial, None)
6813    }
6814
6815    /// Run an arbitrary read-only SQL query against the local database and
6816    /// return each row as a `column-name → JSON value` map. This is the seam
6817    /// the React `useSyncQuery` live-query API needs (it takes app-authored
6818    /// SQL over the visible tables/views, not a fixed table read like
6819    /// [`read_rows`]).
6820    ///
6821    /// Bound `params` are the driver value forms: JSON strings/numbers/bools/
6822    /// null bind directly; a `{"$bytes": hex}` object binds as a BLOB — the
6823    /// same envelope the command surface uses everywhere else. Output BLOB
6824    /// columns come back as `{"$bytes": hex}` to round-trip cleanly.
6825    ///
6826    /// The result column typing is dynamic (SQLite's stored affinity), because
6827    /// arbitrary SQL can alias, join, and compute — there is no schema column
6828    /// to consult per output cell, unlike [`read_rows`].
6829    pub fn query(&self, sql: &str, params: &[QueryValue]) -> Result<Vec<QueryRow>, String> {
6830        query_connection(&self.conn, sql, params).map_err(|failure| failure.to_string())
6831    }
6832
6833    /// Repository benchmark and conformance access, present only with `bench-internals`.
6834    #[cfg(feature = "bench-internals")]
6835    #[doc(hidden)]
6836    pub fn benchmark_connection(&mut self) -> &mut Connection {
6837        &mut self.conn
6838    }
6839
6840    /// Private benchmark intervals; absent from ordinary builds and diagnostics.
6841    #[cfg(feature = "bench-internals")]
6842    #[doc(hidden)]
6843    pub fn benchmark_phases(
6844        &self,
6845        enabled: Option<bool>,
6846        reset: bool,
6847    ) -> Result<Option<Value>, String> {
6848        self.benchmark_phases.configure(enabled, reset)?;
6849        Ok(self.benchmark_phases.snapshot())
6850    }
6851
6852    /// One serialized, read-only authority observation, including durable coverage.
6853    pub fn authority_snapshot(&self) -> Result<Value, String> {
6854        validate_authority_reads(&self.schema, &self.limits.authority_reads)?;
6855        if self.limits.authority_reads.is_empty() {
6856            return Err("client.authority_read_forbidden: no authority reads were declared at client creation".into());
6857        }
6858        self.conn
6859            .execute_batch("SAVEPOINT authority_snapshot")
6860            .map_err(|e| e.to_string())?;
6861        let result = (|| {
6862            let revision = self
6863                .get_meta(LOCAL_REVISION_KEY)?
6864                .ok_or("sync.local_corrupt: authority revision is missing")?;
6865            let parsed_revision = revision
6866                .parse::<u64>()
6867                .map_err(|_| "sync.local_corrupt: authority revision is invalid")?;
6868            if parsed_revision.to_string() != revision {
6869                return Err("sync.local_corrupt: authority revision is invalid".into());
6870            }
6871            let mut tables = Vec::new();
6872            for read in &self.limits.authority_reads {
6873                let table = self
6874                    .schema
6875                    .table(&read.table)
6876                    .ok_or("client.authority_read_forbidden: authority table is not declared")?;
6877                let scalar = |column: &str, value: &Value| -> Result<String, String> {
6878                    let ty = table
6879                        .columns
6880                        .iter()
6881                        .find(|c| c.name == column)
6882                        .expect("validated authority column")
6883                        .ty;
6884                    if ty == ColumnType::Boolean {
6885                        if let Some(value) = value.as_bool() {
6886                            return Ok(value.to_string());
6887                        }
6888                        return match value.as_i64() {
6889                            Some(0) => Ok("false".into()),
6890                            Some(1) => Ok("true".into()),
6891                            _ => Err("sync.local_corrupt: authority boolean is invalid".into()),
6892                        };
6893                    }
6894                    match value {
6895                        Value::String(s) => Ok(s.clone()),
6896                        Value::Number(n) => Ok(n.to_string()),
6897                        Value::Object(o) if ty == ColumnType::Integer && o.len() == 1 => o
6898                            .get("$bigint")
6899                            .and_then(Value::as_str)
6900                            .map(str::to_owned)
6901                            .ok_or("sync.local_corrupt: authority integer is invalid".into()),
6902                        _ => {
6903                            Err("sync.local_corrupt: authority scalar is missing or invalid".into())
6904                        }
6905                    }
6906                };
6907                let matches = |row: &QueryRow| -> Result<bool, String> {
6908                    for (variable, values) in &read.scopes {
6909                        let column = table
6910                            .scope_column(variable)
6911                            .expect("validated authority scope");
6912                        let value = row
6913                            .get(column)
6914                            .ok_or("sync.local_corrupt: authority scope column is missing")?;
6915                        if value.is_null() || !values.contains(&scalar(column, value)?) {
6916                            return Ok(false);
6917                        }
6918                    }
6919                    Ok(true)
6920                };
6921                let selected = read
6922                    .columns
6923                    .iter()
6924                    .map(|c| quote_ident(c))
6925                    .collect::<Vec<_>>()
6926                    .join(",");
6927                let mut intent = BTreeSet::new();
6928                let mut relevant = BTreeSet::new();
6929                for row in query_connection(&self.conn,
6930                    "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=?",
6931                    &[Value::String(read.table.clone())]).map_err(|e| e.to_string())? {
6932                    let id = row.get("id").and_then(Value::as_str).ok_or("sync.local_corrupt: authority intent id is invalid")?.to_owned();
6933                    intent.insert(id.clone());
6934                    if let Some(raw) = row.get("values_json").and_then(Value::as_str) {
6935                        let values: QueryRow = serde_json::from_str(raw).map_err(|_| "sync.local_corrupt: authority intent values are invalid")?;
6936                        if read.scopes.keys().all(|v| values.contains_key(table.scope_column(v).expect("validated scope"))) && matches(&values)? {relevant.insert(id);}
6937                    }
6938                }
6939                let mut rows = BTreeMap::new();
6940                for full in [base_table(&read.table), visible_table(&read.table)] {
6941                    for mut values in query_connection(
6942                        &self.conn,
6943                        &format!(
6944                            "SELECT {selected},_syncular_version AS authority_version FROM {full}"
6945                        ),
6946                        &[],
6947                    )
6948                    .map_err(|e| e.to_string())?
6949                    {
6950                        if !matches(&values)? {
6951                            continue;
6952                        }
6953                        let id = scalar(
6954                            &table.primary_key,
6955                            values
6956                                .get(&table.primary_key)
6957                                .expect("selected primary key"),
6958                        )?;
6959                        relevant.insert(id.clone());
6960                        if full == base_table(&read.table) {
6961                            let version = values
6962                                .remove("authority_version")
6963                                .expect("selected version");
6964                            let version = version
6965                                .as_i64()
6966                                .ok_or("sync.local_corrupt: authority server version is invalid")?;
6967                            if version >= 0 {
6968                                rows.insert(id.clone(), json!({"values": values, "version": version, "hasLocalIntent": intent.contains(&id)}));
6969                            }
6970                        }
6971                    }
6972                }
6973                intent.retain(|id| relevant.contains(id));
6974                let rows = rows.into_values().collect::<Vec<_>>();
6975                // Every unit covering the table, as its (unit, table) pair (§4.4).
6976                let replica = self.stored(replica_cursor(&self.conn))?;
6977                let persisted = self
6978                    .stored(load_units(&self.conn))?
6979                    .into_iter()
6980                    .filter(|unit| covers(table, &unit.scopes))
6981                    .map(|unit| {
6982                        let effective = unit.echo.as_deref().and_then(|echo| {
6983                            pair_scopes(&unit.scopes, &read.table, Some(echo))
6984                        });
6985                        let requested = read
6986                            .scopes
6987                            .keys()
6988                            .map(|v| (v.clone(), json!(unit.scopes.get(v).into_iter().collect::<Vec<_>>())))
6989                            .collect::<Map<_, _>>();
6990                        let complete = effective
6991                            .as_ref()
6992                            .is_some_and(|scopes| scopes.len() == read.scopes.len())
6993                            && unit.status == UnitStatus::Active
6994                            && !unit.bootstrapping();
6995                        let exposed = effective.map(|scopes| {
6996                            read.scopes
6997                                .keys()
6998                                .map(|v| {
6999                                    let held = scopes.iter().find(|(variable, _)| variable == v);
7000                                    (v.clone(), json!(held.map_or(&Vec::new(), |(_, values)| values)))
7001                                })
7002                                .collect::<Map<_, _>>()
7003                        });
7004                        json!({"requestedScopes": requested, "status": unit.status, "cursor": unit.cursor.unwrap_or(replica), "effectiveScopes": exposed, "complete": complete})
7005                    })
7006                    .collect::<Vec<_>>();
7007                fn covered(selectors: &[(&String, &Vec<String>)], candidates: &[&Value]) -> bool {
7008                    match selectors.split_first() {
7009                        None => !candidates.is_empty(),
7010                        Some(((variable, values), rest)) => values.iter().all(|value| {
7011                            covered(
7012                                rest,
7013                                &candidates
7014                                    .iter()
7015                                    .copied()
7016                                    .filter(|p| {
7017                                        p["effectiveScopes"][variable.as_str()]
7018                                            .as_array()
7019                                            .is_some_and(|held| {
7020                                                held.contains(&Value::String(value.clone()))
7021                                                    || held.contains(&Value::String("*".into()))
7022                                            })
7023                                    })
7024                                    .collect::<Vec<_>>(),
7025                            )
7026                        }),
7027                    }
7028                }
7029                let coverage = if covered(
7030                    &read.scopes.iter().collect::<Vec<_>>(),
7031                    &persisted
7032                        .iter()
7033                        .filter(|p| p["complete"] == true)
7034                        .collect::<Vec<_>>(),
7035                ) {
7036                    "complete"
7037                } else if persisted.iter().any(|p| {
7038                    p["status"] == "active"
7039                        && read.scopes.iter().all(|(v, values)| {
7040                            values.iter().any(|value| {
7041                                p["requestedScopes"][v].as_array().is_some_and(|held| {
7042                                    held.contains(&Value::String(value.clone()))
7043                                })
7044                            })
7045                        })
7046                }) {
7047                    "pending"
7048                } else {
7049                    "missing"
7050                };
7051                tables.push(json!({"table": read.table, "rows": rows, "localIntentRowIds": intent, "scopes": read.scopes, "coverage": coverage, "persisted": persisted}));
7052            }
7053            Ok(
7054                json!({"revision": revision, "complete": tables.iter().all(|t| t["coverage"] == "complete"), "tables": tables}),
7055            )
7056        })();
7057        match result {
7058            Ok(snapshot) => {
7059                self.conn
7060                    .execute_batch("RELEASE authority_snapshot")
7061                    .map_err(|e| e.to_string())?;
7062                Ok(snapshot)
7063            }
7064            Err(error) => {
7065                self.conn
7066                    .execute_batch("ROLLBACK TO authority_snapshot; RELEASE authority_snapshot")
7067                    .map_err(|e| format!("{error}; rollback failed: {e}"))?;
7068                Err(error)
7069            }
7070        }
7071    }
7072
7073    /// Rows, coverage, and local revision from one SQLite read snapshot.
7074    /// §7.5 atomic snapshot read. An `owner` records a failure in
7075    /// `diagnostics_snapshot().query_failures` until its next successful read.
7076    pub fn query_snapshot(
7077        &mut self,
7078        sql: &str,
7079        params: &[QueryValue],
7080        coverage: &[WindowCoverage],
7081        owner: Option<QueryOwner<'_>>,
7082    ) -> Result<QuerySnapshot, String> {
7083        let result = snapshot_connection(&self.conn, sql, params, coverage);
7084        if let Some(owner) = owner {
7085            self.record_query_read(owner, result.as_ref().err());
7086        }
7087        result.map_err(|failure| failure.to_string())
7088    }
7089
7090    /// §7.6: record the outcome of one owned snapshot read, including reads a
7091    /// host ran on a separate connection. A success removes the owner's entry;
7092    /// an identical failure leaves it unchanged; a changed failure moves last.
7093    pub fn record_query_read(&mut self, owner: QueryOwner<'_>, failure: Option<&QueryReadFailure>) {
7094        let position = self
7095            .query_failures
7096            .iter()
7097            .position(|entry| entry.id == owner.id);
7098        let Some(failure) = failure else {
7099            if let Some(index) = position {
7100                self.query_failures.remove(index);
7101            }
7102            return;
7103        };
7104        let tables: Vec<String> = BTreeSet::from_iter(owner.tables.iter().copied())
7105            .into_iter()
7106            .map(str::to_owned)
7107            .collect();
7108        let code = failure.code.unwrap_or("client.query_failed").to_owned();
7109        if position.is_some_and(|index| {
7110            let entry = &self.query_failures[index];
7111            entry.tables == tables && entry.code == code && entry.sqlite_code == failure.sqlite_code
7112        }) {
7113            return;
7114        }
7115        if let Some(index) = position {
7116            self.query_failures.remove(index);
7117        }
7118        self.query_failures.push(DiagnosticQueryFailure {
7119            id: owner.id.to_owned(),
7120            tables,
7121            code,
7122            sqlite_code: failure.sqlite_code,
7123            at_ms: self.clock_now_ms(),
7124        });
7125        if self.query_failures.len() > MAX_DIAGNOSTIC_QUERY_FAILURES {
7126            self.query_failures.remove(0);
7127        }
7128    }
7129
7130    // -- request building ---------------------------------------------------------
7131
7132    fn build_request(&self, url_capable: bool) -> Result<(Message, RequestMeta), Box<SyncOutcome>> {
7133        #[cfg(feature = "bench-internals")]
7134        let _phase = self.benchmark_phases.start(Phase::RequestPrepare);
7135        let log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7136            Box::new(SyncOutcome::Failed {
7137                error_code: "storage.failed".into(),
7138                message,
7139                details: None,
7140                recommended_action: None,
7141            })
7142        })?;
7143        let max_commits = self.limits.max_push_commits_per_request;
7144        let max_ops = self
7145            .limits
7146            .max_push_operations_per_request
7147            .unwrap_or(PUSH_OPS_PER_REQUEST);
7148        let byte_cap = self.limits.max_push_request_bytes;
7149        // §4.2/§5.4: bit 3 is advertised iff the transport can fetch a
7150        // bare URL — capability negotiation, decided per transport.
7151        let accept = self.limits.accept.unwrap_or(if url_capable {
7152            DEFAULT_ACCEPT | ACCEPT_SIGNED_URLS
7153        } else {
7154            DEFAULT_ACCEPT
7155        });
7156        let storage_failed = |message: String| {
7157            Box::new(SyncOutcome::Failed {
7158                error_code: "storage.failed".into(),
7159                message,
7160                details: None,
7161                recommended_action: None,
7162            })
7163        };
7164        let header = Frame::ReqHeader {
7165            client_id: self.client_id.clone(),
7166            schema_version: self.schema.version,
7167            log_epoch: log_epoch.clone(),
7168            outbox_id: self.get_meta(OUTBOX_ID_KEY).map_err(storage_failed)?,
7169        };
7170        // §1.5: the lead frames are REQ_HEADER plus the optional ROUND_FAILURE,
7171        // which stays ahead of every push, pull, unit and progress frame; the
7172        // byte-capacity probes below measure this exact sequence.
7173        let mut lead = vec![header];
7174        lead.extend(
7175            self.round_failure
7176                .iter()
7177                .map(|code| Frame::RoundFailure { code: code.clone() }),
7178        );
7179        let registered: Vec<UnitRecord> = self
7180            .stored(load_units(&self.conn))
7181            .map_err(storage_failed)?
7182            .into_iter()
7183            .filter(|unit| unit.status == UnitStatus::Active)
7184            .collect();
7185        let registration_digest = ssp2::registration::registration_digest(
7186            registered
7187                .iter()
7188                .map(|unit| scope_pairs(&unit.scopes))
7189                .collect::<Vec<_>>()
7190                .iter()
7191                .map(Vec::as_slice),
7192        );
7193        let echo_digest = self
7194            .get_meta(ECHO_DIGEST_KEY)
7195            .map_err(storage_failed)?
7196            .filter(|hex| !hex.is_empty())
7197            .map(|hex| {
7198                crate::values::hex_to_bytes(&hex)
7199                    .ok()
7200                    .and_then(|bytes| <[u8; 32]>::try_from(bytes).ok())
7201                    .ok_or_else(|| {
7202                        "sync.local_corrupt: persisted echo digest is invalid".to_owned()
7203                    })
7204            })
7205            .transpose()
7206            .map_err(storage_failed)?;
7207        let pull = Frame::PullHeader {
7208            limit_commits: self.limits.limit_commits.unwrap_or(0),
7209            limit_snapshot_rows: self.limits.limit_snapshot_rows.unwrap_or(0),
7210            max_snapshot_pages: self.limits.max_snapshot_pages.unwrap_or(0),
7211            accept,
7212            cursor: self
7213                .stored(replica_cursor(&self.conn))
7214                .map_err(storage_failed)?,
7215            registration_digest,
7216            echo_digest,
7217        };
7218        let registration_digest = bytes_to_hex(&registration_digest);
7219        // §4.1: the list travels when it changed since the server stored it,
7220        // after `unregistered` and after a reset (both clear the stored digest).
7221        let travels = self
7222            .get_meta(REGISTERED_DIGEST_KEY)
7223            .map_err(storage_failed)?
7224            .as_deref()
7225            != Some(registration_digest.as_str());
7226        let mut sub_frames: Vec<Frame> = Vec::new();
7227        if travels {
7228            sub_frames.extend(registered.iter().map(|unit| Frame::Unit {
7229                scopes: scope_pairs(&unit.scopes),
7230            }));
7231        }
7232        // §4.3: one PROGRESS per catching-up unit, in registration order.
7233        sub_frames.extend(registered.iter().filter_map(|unit| {
7234            Some(Frame::Progress {
7235                id: unit.id.clone(),
7236                cursor: unit.cursor?,
7237                bootstrap_state: unit.bootstrap_state.clone().map(RawJson),
7238            })
7239        }));
7240        // The fixed frames (order-independent size) and the header+pull probe
7241        // both encode canonically, so the byte budget is the exact wire size.
7242        let fixed_bytes = match byte_cap {
7243            Some(_) => {
7244                let mut frames = lead.clone();
7245                frames.push(pull.clone());
7246                frames.extend(sub_frames.iter().cloned());
7247                encode_message(&Message {
7248                    wire_version: WIRE_VERSION,
7249                    msg_kind: MsgKind::Request,
7250                    frames,
7251                })
7252                .len()
7253            }
7254            None => 0,
7255        };
7256        if let Some(cap) = byte_cap {
7257            if fixed_bytes > cap {
7258                return Err(Self::push_capacity_outcome("bytes", cap, fixed_bytes, None));
7259            }
7260        }
7261        let base_bytes = match byte_cap {
7262            Some(_) => {
7263                let mut frames = lead.clone();
7264                frames.push(pull.clone());
7265                encode_message(&Message {
7266                    wire_version: WIRE_VERSION,
7267                    msg_kind: MsgKind::Request,
7268                    frames,
7269                })
7270                .len()
7271            }
7272            None => 0,
7273        };
7274        let total_outbox = if log_epoch.is_some() {
7275            self.outbox.len()
7276        } else {
7277            0
7278        };
7279        let mut push_frames: Vec<Frame> = Vec::new();
7280        let mut pushed_ids = Vec::new();
7281        let mut ops_in_request = 0usize;
7282        let mut bytes_in_request = 0usize;
7283        let mut deferred_commits = 0usize;
7284        #[cfg(feature = "bench-internals")]
7285        let outbox_phase = self.benchmark_phases.start(Phase::OutboxEncode);
7286        for (index, commit) in self.outbox.iter().take(total_outbox).enumerate() {
7287            // §6.1/§7.1: the commit-count and operation caps are hard. A
7288            // first commit over the operation cap is a typed capacity error
7289            // and stays queued; a later one defers with the complete suffix.
7290            if max_commits.is_some_and(|cap| push_frames.len() >= cap) {
7291                deferred_commits = total_outbox - index;
7292                break;
7293            }
7294            if ops_in_request + commit.ops.len() > max_ops {
7295                if push_frames.is_empty() {
7296                    return Err(Self::push_capacity_outcome(
7297                        "operations",
7298                        max_ops,
7299                        commit.ops.len(),
7300                        Some(commit.client_commit_id.as_str()),
7301                    ));
7302                }
7303                deferred_commits = total_outbox - index;
7304                break;
7305            }
7306            // §7.1 chained base: the commit waits for the change of the commit
7307            // it chains on, which supplies its rebased version.
7308            if self.outbox[..index]
7309                .iter()
7310                .flat_map(|earlier| &earlier.ops)
7311                .any(|earlier| commit.ops.iter().any(|op| chains_on(earlier, op)))
7312            {
7313                deferred_commits = total_outbox - index;
7314                break;
7315            }
7316            let operations = commit
7317                .ops
7318                .iter()
7319                .map(|op| {
7320                    let payload = match self
7321                        .schema
7322                        .table(&op.table)
7323                        .and_then(|table| Some((table, op.presented_values(table)?)))
7324                    {
7325                        Some((table, values)) => {
7326                            // §0: outbox entries encode at send time with the
7327                            // current codec (validated at mutate()). §6.1: the
7328                            // values map's keys are the sparse presence set; an
7329                            // insert-intent operation presents every column (§7.1).
7330                            // §5.11: encrypted columns are encrypted here, with
7331                            // an absent key-id selector read from the stored row.
7332                            // `sync_inner` runs `drop_unencodable_outbox` first,
7333                            // so an encrypt failure cannot reach this encode; the
7334                            // author seam validated every other failure.
7335                            let fallback =
7336                                self.stored_key_fallback(table, &op.row_id)
7337                                    .map_err(|message| {
7338                                        Box::new(SyncOutcome::Failed {
7339                                            error_code: "storage.failed".into(),
7340                                            message,
7341                                            details: None,
7342                                            recommended_action: None,
7343                                        })
7344                                    })?;
7345                            encode_sparse_row_json(
7346                                table,
7347                                &op.row_id,
7348                                &values,
7349                                &self.encryption,
7350                                fallback.as_ref(),
7351                            )
7352                            .ok()
7353                        }
7354                        None => None,
7355                    };
7356                    Ok(ssp2::model::Operation {
7357                        table: op.table.clone(),
7358                        row_id: op.row_id.clone(),
7359                        op: if op.upsert { Op::Upsert } else { Op::Delete },
7360                        base_version: op.base_version,
7361                        payload,
7362                    })
7363                })
7364                .collect::<Result<Vec<_>, Box<SyncOutcome>>>()?;
7365            // §6.3.2, §7.1: the commit's outbox sequence.
7366            let client_seq = self
7367                .conn
7368                .prepare_cached("SELECT seq FROM _syncular_outbox WHERE commit_id = ?1")
7369                .and_then(|mut statement| {
7370                    statement.query_row([&commit.client_commit_id], |row| row.get(0))
7371                })
7372                .map_err(|error| {
7373                    storage_failed(Self::sqlite_failure(&self.storage_failure, error))
7374                })?;
7375            let frame = Frame::PushCommit {
7376                client_commit_id: commit.client_commit_id.clone(),
7377                client_seq,
7378                operations,
7379            };
7380            let frame_bytes = match byte_cap {
7381                Some(_) => {
7382                    let mut frames = lead.clone();
7383                    frames.push(frame.clone());
7384                    frames.push(pull.clone());
7385                    encode_message(&Message {
7386                        wire_version: WIRE_VERSION,
7387                        msg_kind: MsgKind::Request,
7388                        frames,
7389                    })
7390                    .len()
7391                        - base_bytes
7392                }
7393                None => 0,
7394            };
7395            // The head is always encoded so the caller can report the full
7396            // projected request size; a later commit defers once it no longer
7397            // fits.
7398            if let Some(cap) = byte_cap {
7399                if !push_frames.is_empty() && fixed_bytes + bytes_in_request + frame_bytes > cap {
7400                    deferred_commits = total_outbox - index;
7401                    break;
7402                }
7403            }
7404            push_frames.push(frame);
7405            pushed_ids.push(commit.client_commit_id.clone());
7406            ops_in_request += commit.ops.len();
7407            bytes_in_request += frame_bytes;
7408        }
7409        #[cfg(feature = "bench-internals")]
7410        drop(outbox_phase);
7411        if let Some(cap) = byte_cap {
7412            if fixed_bytes + bytes_in_request > cap {
7413                // The head alone does not fit this budget; the commit stays
7414                // queued and no transport round is attempted.
7415                let blocked = if push_frames.is_empty() {
7416                    None
7417                } else {
7418                    self.outbox.first().map(|c| c.client_commit_id.as_str())
7419                };
7420                return Err(Self::push_capacity_outcome(
7421                    "bytes",
7422                    cap,
7423                    fixed_bytes + bytes_in_request,
7424                    blocked,
7425                ));
7426            }
7427        }
7428        let mut frames = lead;
7429        frames.extend(push_frames);
7430        frames.push(pull);
7431        frames.extend(sub_frames);
7432        let message = Message {
7433            wire_version: WIRE_VERSION,
7434            msg_kind: MsgKind::Request,
7435            frames,
7436        };
7437        Ok((
7438            message,
7439            RequestMeta {
7440                pushed_ids,
7441                registration_digest,
7442                accept,
7443                deferred_commits,
7444            },
7445        ))
7446    }
7447
7448    /// §7.1: a configured push capacity limit cannot carry this request.
7449    fn push_capacity_outcome(
7450        kind: &str,
7451        limit: usize,
7452        size: usize,
7453        client_commit_id: Option<&str>,
7454    ) -> Box<SyncOutcome> {
7455        let mut details = Map::new();
7456        details.insert("kind".to_owned(), Value::from(kind));
7457        details.insert("limit".to_owned(), Value::from(limit as u64));
7458        details.insert("size".to_owned(), Value::from(size as u64));
7459        if let Some(id) = client_commit_id {
7460            details.insert("clientCommitId".to_owned(), Value::from(id));
7461        }
7462        Box::new(SyncOutcome::Failed {
7463            error_code: "client.push_request_too_large".into(),
7464            message: "the push request exceeds a configured capacity limit".into(),
7465            details: Some(Value::Object(details)),
7466            recommended_action: None,
7467        })
7468    }
7469
7470    // -- sync -------------------------------------------------------------------
7471
7472    /// Cloneable observation handle; no client lock is needed to read it.
7473    pub fn progress(&self) -> ProgressObserver {
7474        self.progress.clone()
7475    }
7476
7477    pub fn sync(&mut self, transport: &mut dyn Transport) -> SyncOutcome {
7478        let prepared = match self.prepare_sync_round(transport.supports_url_fetch()) {
7479            Ok(prepared) => prepared,
7480            Err(outcome) => return *outcome,
7481        };
7482        // The round's network deadline rides `PreparedSyncRound` and is scoped
7483        // to each exchange, so uploads, continuations, the main request, and
7484        // every segment fetch share one monotonic anchor without leaving
7485        // deadline state on a reused transport.
7486        let mut next = prepared;
7487        loop {
7488            match self.apply_sync_round(next.exchange(transport)) {
7489                crate::AppliedSyncRound::Continue(prepared) => next = prepared,
7490                crate::AppliedSyncRound::Complete {
7491                    outcome, controls, ..
7492                } => {
7493                    if self.transport_enabled {
7494                        for text in controls {
7495                            let _ = transport.realtime_send(&text);
7496                        }
7497                    } else {
7498                        self.disconnect_realtime(transport);
7499                    }
7500                    return outcome;
7501                }
7502            }
7503        }
7504    }
7505
7506    fn finish_sync_round(&mut self, started_at_ms: i64, mut outcome: SyncOutcome) -> SyncOutcome {
7507        if let SyncOutcome::Failed {
7508            error_code,
7509            message,
7510            details,
7511            ..
7512        } = &mut outcome
7513        {
7514            if let Some((failure, code)) = self
7515                .storage_failure
7516                .borrow()
7517                .as_ref()
7518                .and_then(|failure| failure.code.map(|code| (failure, code)))
7519            {
7520                *error_code = code.to_owned();
7521                *message = match code {
7522                    "client.storage_busy" => "local SQLite storage is busy",
7523                    "client.storage_full" => "local SQLite storage is full",
7524                    "client.storage_io" => "local SQLite storage I/O failed",
7525                    "client.storage_corrupt" => "local SQLite storage is corrupt",
7526                    _ => unreachable!("unrecognized classified storage failure"),
7527                }
7528                .to_owned();
7529                *details = failure.details();
7530            }
7531        }
7532        let details = match &outcome {
7533            SyncOutcome::Failed { details, .. } => details.as_ref(),
7534            _ => None,
7535        };
7536        let cause_kind = details
7537            .and_then(|details| details.get("causeKind"))
7538            .and_then(Value::as_str)
7539            .and_then(|cause| match cause {
7540                "network" => Some(crate::TransportCauseKind::Network),
7541                "connect" => Some(crate::TransportCauseKind::Connect),
7542                "tls" => Some(crate::TransportCauseKind::Tls),
7543                "io" => Some(crate::TransportCauseKind::Io),
7544                "request" => Some(crate::TransportCauseKind::Request),
7545                "protocol" => Some(crate::TransportCauseKind::Protocol),
7546                "timeout" => Some(crate::TransportCauseKind::Timeout),
7547                "round_deadline" => Some(crate::TransportCauseKind::RoundDeadline),
7548                "aborted" => Some(crate::TransportCauseKind::Aborted),
7549                "body" => Some(crate::TransportCauseKind::Body),
7550                "status" => Some(crate::TransportCauseKind::Status),
7551                "redirect" => Some(crate::TransportCauseKind::Redirect),
7552                "unknown" => Some(crate::TransportCauseKind::Unknown),
7553                _ => None,
7554            });
7555        let http_status = if matches!(
7556            cause_kind,
7557            Some(
7558                crate::TransportCauseKind::Status
7559                    | crate::TransportCauseKind::Body
7560                    | crate::TransportCauseKind::Redirect
7561            )
7562        ) {
7563            details
7564                .and_then(|details| details.get("httpStatus"))
7565                .and_then(Value::as_f64)
7566                .filter(|status| status.fract() == 0.0 && (100.0..=599.0).contains(status))
7567                .map(|status| status as u16)
7568        } else {
7569            None
7570        };
7571        let retry_delay_ms = self.round_retry_delay_ms;
7572        self.progress.update(|p| match &outcome {
7573            SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report)
7574                if report.failed.is_empty() =>
7575            {
7576                p.state = ProgressState::Complete
7577            }
7578            SyncOutcome::Ok(_) | SyncOutcome::BudgetExhausted(_) => {
7579                p.state = ProgressState::Failed;
7580                p.error_code = Some("sync.scope_revoked".into());
7581            }
7582            SyncOutcome::Failed { error_code, .. } => {
7583                p.state = ProgressState::Failed;
7584                p.error_code = Some(Self::diagnostic_code(error_code));
7585                p.cause_kind = cause_kind;
7586                p.http_status = http_status;
7587                p.retry_delay_ms = retry_delay_ms;
7588            }
7589            SyncOutcome::RealtimeUnavailable { .. } => {
7590                p.state = ProgressState::Failed;
7591                p.error_code = Some(REALTIME_UNAVAILABLE_CODE.to_owned());
7592                p.retry_delay_ms = retry_delay_ms;
7593            }
7594        });
7595        let completed_at_ms = self.clock_now_ms();
7596        self.last_round = Some(match &outcome {
7597            SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report) => DiagnosticLastRound {
7598                status: "succeeded".to_owned(),
7599                started_at_ms,
7600                completed_at_ms,
7601                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7602                counters: Some(DiagnosticRoundCounters {
7603                    pushed: report.pushed,
7604                    applied: report.applied.len(),
7605                    rejected: report.rejected.len(),
7606                    retryable: report.retryable.len(),
7607                    conflicts: report.conflicts,
7608                    commits_applied: report.commits_applied,
7609                    segment_rows_applied: report.segment_rows_applied,
7610                    bootstrapping: report.bootstrapping.len(),
7611                    resets: report.resets.len(),
7612                    revoked: report.revoked.len(),
7613                    failed: report.failed.len(),
7614                    deferred_commits: report.deferred_commits,
7615                }),
7616                error_code: None,
7617                cause_kind: None,
7618                http_status: None,
7619            },
7620            SyncOutcome::Failed { error_code, .. } => DiagnosticLastRound {
7621                status: "failed".to_owned(),
7622                started_at_ms,
7623                completed_at_ms,
7624                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7625                counters: None,
7626                error_code: Some(Self::diagnostic_code(error_code)),
7627                cause_kind,
7628                http_status,
7629            },
7630            SyncOutcome::RealtimeUnavailable { .. } => DiagnosticLastRound {
7631                status: "failed".to_owned(),
7632                started_at_ms,
7633                completed_at_ms,
7634                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7635                counters: None,
7636                error_code: Some(REALTIME_UNAVAILABLE_CODE.to_owned()),
7637                cause_kind: None,
7638                http_status: None,
7639            },
7640        });
7641        outcome
7642    }
7643
7644    /// Capture one request on the client owner. Mutations made after this
7645    /// call remain in the outbox for a later round; no network I/O occurs here.
7646    pub fn prepare_sync_round(
7647        &mut self,
7648        url_capable: bool,
7649    ) -> Result<crate::PreparedSyncRound, Box<SyncOutcome>> {
7650        if !self.transport_enabled {
7651            return Err(Box::new(SyncOutcome::Failed {
7652                error_code: "sync.offline".into(),
7653                message: "transport gate is closed".into(),
7654                details: None,
7655                recommended_action: None,
7656            }));
7657        }
7658        if self.active_round.is_some() {
7659            return Err(Box::new(SyncOutcome::Failed {
7660                error_code: "client.round_in_progress".into(),
7661                message: "a sync round is already in flight".into(),
7662                details: None,
7663                recommended_action: None,
7664            }));
7665        }
7666        self.storage_failure.borrow_mut().take();
7667        self.progress.start();
7668        self.round_retry_delay_ms = None;
7669        let started_at_ms = self.clock_now_ms();
7670        let prepared = (|| {
7671            if self.stopped {
7672                return Err(Box::new(SyncOutcome::Ok(SyncReport {
7673                    schema_floor: self.schema_floor.clone(),
7674                    ..SyncReport::default()
7675                })));
7676            }
7677            if self.security_preflight {
7678                return Err(Box::new(SyncOutcome::Failed {
7679                    error_code: SECURITY_PREFLIGHT_REQUIRED_CODE.into(),
7680                    message: "security preflight must complete before syncing".into(),
7681                    details: None,
7682                    recommended_action: None,
7683                }));
7684            }
7685            self.set_sync_needed(false, false);
7686            self.drain_pending_evictions()
7687                .and_then(|_| self.drop_incompatible_outbox())
7688                .and_then(|_| self.drop_unencodable_outbox(true, None))
7689                .map_err(|message| {
7690                    Box::new(SyncOutcome::Failed {
7691                        error_code: "storage.failed".into(),
7692                        message,
7693                        details: None,
7694                        recommended_action: None,
7695                    })
7696                })?;
7697            let has_log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7698                Box::new(SyncOutcome::Failed {
7699                    error_code: "storage.failed".into(),
7700                    message,
7701                    details: None,
7702                    recommended_action: None,
7703                })
7704            })?;
7705            let uploads = if has_log_epoch.is_some() && self.schema_has_blobs() {
7706                self.pending_blob_uploads().map_err(|e| {
7707                    Box::new(SyncOutcome::Failed {
7708                        error_code: e.code,
7709                        message: e.message,
7710                        details: e.details,
7711                        recommended_action: None,
7712                    })
7713                })?
7714            } else {
7715                Vec::new()
7716            };
7717            if self.realtime_state != RealtimeState::Connected
7718                && self.realtime_policy == RealtimePolicy::Required
7719            {
7720                let retry_delay_ms = self.schedule_background_retry();
7721                self.realtime_retry_delay_ms = Some(retry_delay_ms);
7722                return Err(Box::new(SyncOutcome::RealtimeUnavailable {
7723                    state: self.realtime_state,
7724                    reason_code: self.realtime_reason_code.clone(),
7725                    retry_delay_ms,
7726                }));
7727            }
7728            let (message, meta) = self.build_request(url_capable)?;
7729            let id = uuid::Uuid::new_v4();
7730            self.active_round = Some(id);
7731            let phase = if uploads.is_empty() {
7732                crate::round::RoundPhase::Sync
7733            } else {
7734                crate::round::RoundPhase::UploadGrant
7735            };
7736            Ok(crate::PreparedSyncRound {
7737                id,
7738                started_at_ms,
7739                message,
7740                meta,
7741                uploads: uploads.into(),
7742                phase,
7743                encoded: None,
7744                continuation: None,
7745                completed: None,
7746                realtime: self.realtime_state == RealtimeState::Connected,
7747                // §5.5: the owning unit's scope map, each value a one-element list.
7748                scopes: self
7749                    .stored(load_units(&self.conn))
7750                    .map_err(|message| {
7751                        Box::new(SyncOutcome::Failed {
7752                            error_code: "storage.failed".into(),
7753                            message,
7754                            details: None,
7755                            recommended_action: None,
7756                        })
7757                    })?
7758                    .into_iter()
7759                    .map(|unit| {
7760                        (
7761                            unit.id,
7762                            canonical_scope_json(&unit_scope_lists(&unit.scopes)),
7763                        )
7764                    })
7765                    .collect(),
7766                #[cfg(feature = "bench-internals")]
7767                benchmark_phases: self.benchmark_phases.clone(),
7768                progress: self.progress.clone(),
7769                fixed_now: self.now_ms,
7770                round_deadline_at: None,
7771            })
7772        })();
7773        prepared.map_err(|outcome| Box::new(self.finish_sync_round(started_at_ms, *outcome)))
7774    }
7775
7776    /// Discard the reply of an old authorization or registration context. Its
7777    /// submitted commits stay durable and can be retried with the same ids.
7778    pub fn cancel_sync_round(&mut self) {
7779        self.active_round = None;
7780    }
7781
7782    /// Apply captured network results on the owner, preserving all normal
7783    /// version, schema, content-address and cursor checks. No network I/O.
7784    pub fn apply_sync_round(
7785        &mut self,
7786        completed: crate::CompletedSyncRound,
7787    ) -> crate::AppliedSyncRound {
7788        let mut prepared = completed.prepared;
7789        if self.active_round != Some(prepared.id) || self.security_preflight {
7790            return crate::AppliedSyncRound::Complete {
7791                outcome: SyncOutcome::Failed {
7792                    error_code: "client.round_cancelled".into(),
7793                    message: "sync round belongs to a released client context".into(),
7794                    details: None,
7795                    recommended_action: None,
7796                },
7797                controls: Vec::new(),
7798                more: false,
7799                bootstrap_advanced: false,
7800            };
7801        }
7802        self.storage_failure.borrow_mut().take();
7803        let (response, mut downloads, transport_failed) = match completed.exchange {
7804            crate::round::ExchangeResult::Upload { id, result } => {
7805                let result = match result {
7806                    // §5.9.7: a non-retryable server refusal (`blob.too_large`)
7807                    // is the body's final outcome. The commits naming it take
7808                    // the incompatible-commit path with the server's code and
7809                    // leave this round's request; the round continues.
7810                    Err(error)
7811                        if error
7812                            .details
7813                            .as_ref()
7814                            .and_then(|details| details.get("retryable"))
7815                            == Some(&Value::Bool(false)) =>
7816                    {
7817                        self.conn
7818                            .prepare(
7819                                "SELECT commit_id FROM _syncular_blob_commit_refs WHERE blob_id = ?",
7820                            )
7821                            .and_then(|mut statement| {
7822                                statement
7823                                    .query_map(rusqlite::params![id], |row| row.get::<_, String>(0))?
7824                                    .collect::<Result<HashSet<_>, _>>()
7825                            })
7826                            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
7827                            .and_then(|refused| {
7828                                let commits = self
7829                                    .outbox
7830                                    .iter()
7831                                    .filter(|commit| refused.contains(&commit.client_commit_id))
7832                                    .cloned()
7833                                    .collect::<Vec<_>>();
7834                                if !commits.is_empty() {
7835                                    self.drop_outbox_commits(&commits, &error.code, &error.message)?;
7836                                }
7837                                prepared.message.frames.retain(|frame| {
7838                                    !matches!(frame, Frame::PushCommit { client_commit_id, .. }
7839                                        if refused.contains(client_commit_id))
7840                                });
7841                                prepared.meta.pushed_ids.retain(|id| !refused.contains(id));
7842                                prepared.continuation = Some(crate::round::RoundPhase::UploadGrant);
7843                                Ok(())
7844                            })
7845                            .map_err(|message| TransportError::new("client.failed", message))
7846                    }
7847                    result => result,
7848                };
7849                let result = result.and_then(|()| {
7850                    self.conn
7851                        .execute(
7852                            "DELETE FROM _syncular_blob_uploads WHERE blob_id = ?",
7853                            rusqlite::params![id],
7854                        )
7855                        .map(|_| ())
7856                        .map_err(|error| {
7857                            TransportError::new(
7858                                "client.failed",
7859                                Self::sqlite_failure(&self.storage_failure, error),
7860                            )
7861                        })
7862                });
7863                match result {
7864                    Ok(()) => return crate::AppliedSyncRound::Continue(prepared),
7865                    Err(TransportError {
7866                        code,
7867                        message,
7868                        details,
7869                    }) => {
7870                        self.active_round = None;
7871                        if Self::unreachable_transport(&details) {
7872                            // The round's work is still owed; the host's
7873                            // connectivity resume runs it.
7874                            self.set_sync_needed(true, false);
7875                        } else if Self::retryable_failure_code(&code) {
7876                            self.schedule_background_retry();
7877                        }
7878                        let recommended_action = recommended_action_of(&details);
7879                        let outcome = self.finish_sync_round(
7880                            prepared.started_at_ms,
7881                            SyncOutcome::Failed {
7882                                error_code: code,
7883                                message,
7884                                details,
7885                                recommended_action,
7886                            },
7887                        );
7888                        return crate::AppliedSyncRound::Complete {
7889                            outcome,
7890                            controls: Vec::new(),
7891                            more: false,
7892                            bootstrap_advanced: false,
7893                        };
7894                    }
7895                }
7896            }
7897            crate::round::ExchangeResult::Reply {
7898                response,
7899                downloads,
7900                transport_failed,
7901            } => (response, downloads, transport_failed),
7902        };
7903        self.active_round = None;
7904        let before = self.resume_tokens();
7905        let outcome = (|| {
7906            let response = match response {
7907                Ok(response) => {
7908                    // §1.5: a complete, decodable response ends the report, an
7909                    // in-band ERROR included (the server already recorded it).
7910                    self.round_failure = None;
7911                    response
7912                }
7913                Err(TransportError {
7914                    code,
7915                    message,
7916                    details,
7917                }) => {
7918                    // §1.5: the server cannot see a round whose transport
7919                    // failed or whose response never decoded, so its code rides
7920                    // the following requests. A code the frame grammar rejects
7921                    // is not reportable, and the previous code stays.
7922                    if ssp2::model::valid_round_failure_code(&code) {
7923                        self.round_failure = Some(code.clone());
7924                    }
7925                    if transport_failed {
7926                        if prepared.realtime {
7927                            self.set_realtime_state(RealtimeState::Lost, Some(&code));
7928                        }
7929                        if let Err(message) = self.record_lease_error(&code) {
7930                            return SyncOutcome::Failed {
7931                                error_code: "storage.failed".to_owned(),
7932                                message,
7933                                details: None,
7934                                recommended_action: None,
7935                            };
7936                        }
7937                    }
7938                    if Self::retryable_failure_code(&code) && !Self::unreachable_transport(&details)
7939                    {
7940                        let delay = self.schedule_background_retry();
7941                        if prepared.realtime && transport_failed {
7942                            self.realtime_retry_delay_ms = Some(delay);
7943                        }
7944                    }
7945                    let recommended_action = recommended_action_of(&details);
7946                    return SyncOutcome::Failed {
7947                        error_code: code,
7948                        message,
7949                        details,
7950                        recommended_action,
7951                    };
7952                }
7953            };
7954            let mut outcome = self.process_response(&mut downloads, response, &prepared.meta);
7955            if let SyncOutcome::Ok(report) = &mut outcome {
7956                report.deferred_commits = prepared.meta.deferred_commits;
7957            }
7958            match &outcome {
7959                SyncOutcome::Ok(_) => self.reset_background_retry(),
7960                SyncOutcome::Failed {
7961                    error_code,
7962                    details,
7963                    ..
7964                } if Self::retryable_failure_code(error_code)
7965                    && !Self::unreachable_transport(details) =>
7966                {
7967                    self.schedule_background_retry();
7968                }
7969                _ => {}
7970            }
7971            if prepared.meta.deferred_commits > 0 {
7972                self.set_sync_needed(true, true);
7973            }
7974            self.previous_version_lifetime_check();
7975            outcome
7976        })();
7977        match &outcome {
7978            // §7.1: a unit still catching up needs another round, also when the
7979            // drive that started it ends early.
7980            SyncOutcome::Ok(report) if !report.bootstrapping.is_empty() => {
7981                self.set_sync_needed(true, false)
7982            }
7983            // The round's work is still owed; the host's connectivity resume
7984            // runs it.
7985            SyncOutcome::Failed { details, .. } if Self::unreachable_transport(details) => {
7986                self.set_sync_needed(true, false)
7987            }
7988            _ => {}
7989        }
7990        let more = self.transport_enabled
7991            && matches!(&outcome, SyncOutcome::Ok(report)
7992                if report.schema_floor.is_none()
7993                    && (!report.bootstrapping.is_empty()
7994                        || report.commits_applied > 0
7995                        || report.segment_rows_applied > 0
7996                        || !report.resets.is_empty()
7997                        || report.deferred_commits > 0
7998                        || self.sync_needed));
7999        let bootstrap_advanced = matches!(&outcome, SyncOutcome::Ok(report) if report.segment_rows_applied > 0 && !report.bootstrapping.is_empty())
8000            && before != self.resume_tokens();
8001        crate::AppliedSyncRound::Complete {
8002            outcome: self.finish_sync_round(prepared.started_at_ms, outcome),
8003            controls: if self.transport_enabled {
8004                downloads.controls
8005            } else {
8006                Vec::new()
8007            },
8008            more,
8009            bootstrap_advanced,
8010        }
8011    }
8012
8013    /// Every unit's resume token: a bootstrap that advanced changes one (§4.7).
8014    fn resume_tokens(&self) -> Option<Vec<(String, Option<String>)>> {
8015        load_units(&self.conn).ok().map(|units| {
8016            units
8017                .into_iter()
8018                .map(|unit| (unit.id, unit.bootstrap_state))
8019                .collect()
8020        })
8021    }
8022
8023    /// §7.8: one idle drive's default total deadline, the TS client's value.
8024    pub const SYNC_IDLE_TIMEOUT_MS: u64 = 60_000;
8025
8026    pub fn sync_until_idle(
8027        &mut self,
8028        transport: &mut dyn Transport,
8029        max_rounds: Option<u32>,
8030    ) -> SyncOutcome {
8031        self.sync_until_idle_with_deadline(transport, max_rounds, Some(Self::SYNC_IDLE_TIMEOUT_MS))
8032    }
8033
8034    /// As [`SyncClient::sync_until_idle`], with an explicit total deadline in
8035    /// milliseconds (`None` disables it). The deadline is checked between
8036    /// rounds; one blocking transport call is bounded by the transport's own
8037    /// whole-round deadline (§1.8).
8038    pub fn sync_until_idle_with_deadline(
8039        &mut self,
8040        transport: &mut dyn Transport,
8041        max_rounds: Option<u32>,
8042        timeout_ms: Option<u64>,
8043    ) -> SyncOutcome {
8044        // §7.8: an explicit budget is a strict positive round count. Zero is a
8045        // caller error, not an exhaustion.
8046        if max_rounds == Some(0) {
8047            return SyncOutcome::Failed {
8048                details: None,
8049                error_code: "sync.invalid_request".into(),
8050                message: "maxRounds must be a positive integer".into(),
8051                recommended_action: None,
8052            };
8053        }
8054        if timeout_ms.is_some_and(|ms| ms == 0 || i64::try_from(ms).is_err()) {
8055            return SyncOutcome::Failed {
8056                details: None,
8057                error_code: "sync.invalid_request".into(),
8058                message: "timeoutMs must be a positive integer".into(),
8059                recommended_action: None,
8060            };
8061        }
8062        let started_at_ms = self.clock_now_ms();
8063        let deadline_ms = timeout_ms.map(|ms| started_at_ms.saturating_add(ms as i64));
8064        self.sync_until_idle_bounded(transport, max_rounds, started_at_ms, deadline_ms)
8065    }
8066
8067    fn sync_until_idle_bounded(
8068        &mut self,
8069        transport: &mut dyn Transport,
8070        max_rounds: Option<u32>,
8071        started_at_ms: i64,
8072        deadline_ms: Option<i64>,
8073    ) -> SyncOutcome {
8074        let rounds = max_rounds.unwrap_or(20);
8075        let mut aggregate = SyncReport::default();
8076        let mut spent = 0;
8077        while spent < rounds {
8078            if let Some(deadline_ms) = deadline_ms {
8079                if self.clock_now_ms() >= deadline_ms {
8080                    return SyncOutcome::Failed {
8081                        error_code: "sync.idle_timeout".into(),
8082                        message: "sync_until_idle exceeded its deadline".into(),
8083                        details: Some(serde_json::json!({
8084                            "timeoutMs": deadline_ms
8085                                .saturating_sub(started_at_ms) as u64,
8086                            "rounds": spent,
8087                        })),
8088                        recommended_action: Some("retryLater".into()),
8089                    };
8090                }
8091            }
8092            spent += 1;
8093            let before = self.resume_tokens();
8094            match self.sync(transport) {
8095                SyncOutcome::Failed {
8096                    error_code,
8097                    message,
8098                    details,
8099                    recommended_action,
8100                } => {
8101                    return SyncOutcome::Failed {
8102                        details,
8103                        error_code,
8104                        message,
8105                        recommended_action,
8106                    };
8107                }
8108                outcome @ SyncOutcome::RealtimeUnavailable { .. } => return outcome,
8109                SyncOutcome::BudgetExhausted(_) => {
8110                    unreachable!("sync() never exhausts a round budget")
8111                }
8112                SyncOutcome::Ok(report) => {
8113                    if max_rounds.is_none()
8114                        && report.segment_rows_applied > 0
8115                        && !report.bootstrapping.is_empty()
8116                        && before != self.resume_tokens()
8117                    {
8118                        spent = 0;
8119                    }
8120                    // TS parity: a disabled transport or a schema floor ends
8121                    // the loop. The latest round still merges first.
8122                    let stop = !self.transport_enabled() || report.schema_floor.is_some();
8123                    aggregate.merge(&report);
8124                    if stop {
8125                        return SyncOutcome::Ok(aggregate);
8126                    }
8127                    // §4.5: pull again whenever the response contained
8128                    // commits or segments; resets re-bootstrap; a pending
8129                    // resume token continues paging (§4.7); deferred outbox
8130                    // commits and a raised sync-needed signal push on the next
8131                    // round.
8132                    let more = !report.bootstrapping.is_empty()
8133                        || report.commits_applied > 0
8134                        || report.segment_rows_applied > 0
8135                        || !report.resets.is_empty()
8136                        || report.deferred_commits > 0
8137                        || self.sync_needed;
8138                    if !more {
8139                        return SyncOutcome::Ok(aggregate);
8140                    }
8141                }
8142            }
8143        }
8144        // §7.8: partial success. The aggregate report is retained and the run
8145        // is explicitly not idle.
8146        SyncOutcome::BudgetExhausted(aggregate)
8147    }
8148
8149    fn process_response(
8150        &mut self,
8151        transport: &mut dyn Transport,
8152        response: Message,
8153        meta: &RequestMeta,
8154    ) -> SyncOutcome {
8155        #[cfg(feature = "bench-internals")]
8156        let _phase = self.benchmark_phases.start(Phase::ResponseApply);
8157        let mut report = SyncReport {
8158            pushed: meta.pushed_ids.len() as u32,
8159            ..SyncReport::default()
8160        };
8161        let mut rejection_details_by_commit: HashMap<String, BTreeMap<i32, RejectionDetails>> =
8162            HashMap::new();
8163        let pushed_ids = meta
8164            .pushed_ids
8165            .iter()
8166            .map(String::as_str)
8167            .collect::<HashSet<_>>();
8168        let mut last_final_push_result_id: Option<String> = None;
8169        for frame in &response.frames {
8170            match frame {
8171                Frame::PushResultDetails {
8172                    client_commit_id,
8173                    entries,
8174                } => {
8175                    let details = rejection_details_by_commit
8176                        .entry(client_commit_id.clone())
8177                        .or_default();
8178                    for entry in entries {
8179                        let parsed = match RejectionDetails::parse(&entry.details.0) {
8180                            Ok(value) => value,
8181                            Err(message) => {
8182                                return SyncOutcome::Failed {
8183                                    details: None,
8184                                    error_code: "sync.invalid_request".to_owned(),
8185                                    message,
8186                                    recommended_action: None,
8187                                };
8188                            }
8189                        };
8190                        details.insert(entry.op_index, parsed);
8191                    }
8192                }
8193                Frame::PushResult {
8194                    client_commit_id,
8195                    status,
8196                    results,
8197                    ..
8198                } if pushed_ids.contains(client_commit_id.as_str())
8199                    && Self::push_result_is_final(*status, results) =>
8200                {
8201                    last_final_push_result_id = Some(client_commit_id.clone());
8202                }
8203                _ => {}
8204            }
8205        }
8206        let mut frames = response.frames.into_iter().peekable();
8207        match frames.next() {
8208            Some(Frame::RespHeader {
8209                required_schema_version,
8210                latest_schema_version,
8211                log_epoch,
8212                reset_required,
8213            }) => {
8214                if let Some(required) = required_schema_version {
8215                    // §1.6 schema-floor response: nothing else is processed;
8216                    // stop syncing and surface the upgrade requirement.
8217                    let floor = SchemaFloor {
8218                        required_schema_version: Some(required),
8219                        latest_schema_version,
8220                    };
8221                    if let Err(message) = self.set_schema_floor(Some(floor.clone())) {
8222                        return SyncOutcome::Failed {
8223                            details: None,
8224                            error_code: "storage.failed".to_owned(),
8225                            message,
8226                            recommended_action: None,
8227                        };
8228                    }
8229                    report.schema_floor = Some(floor);
8230                    return SyncOutcome::Ok(report);
8231                }
8232                if reset_required {
8233                    if frames.next().is_some() {
8234                        return SyncOutcome::Failed {
8235                            details: None,
8236                            error_code: "client.invalid_host_response".to_owned(),
8237                            message: "log-epoch reset response contains body frames".to_owned(),
8238                            recommended_action: None,
8239                        };
8240                    }
8241                    match self.run_log_epoch_reset(&log_epoch) {
8242                        Ok(resets) => {
8243                            report.resets = resets;
8244                            return SyncOutcome::Ok(report);
8245                        }
8246                        Err(message) => {
8247                            return SyncOutcome::Failed {
8248                                details: None,
8249                                error_code: "sync.local_corrupt".to_owned(),
8250                                message,
8251                                recommended_action: None,
8252                            };
8253                        }
8254                    }
8255                }
8256                let stored_epoch = match self.get_meta(LOG_EPOCH_KEY) {
8257                    Ok(stored) => stored,
8258                    Err(message) => {
8259                        return SyncOutcome::Failed {
8260                            details: None,
8261                            error_code: "storage.failed".to_owned(),
8262                            message,
8263                            recommended_action: None,
8264                        };
8265                    }
8266                };
8267                if stored_epoch.as_deref() != Some(log_epoch.as_str()) {
8268                    return SyncOutcome::Failed {
8269                        details: None,
8270                        error_code: "client.invalid_host_response".to_owned(),
8271                        message: "server changed logEpoch without requiring a reset".to_owned(),
8272                        recommended_action: None,
8273                    };
8274                }
8275            }
8276            _ => {
8277                return SyncOutcome::Failed {
8278                    details: None,
8279                    error_code: "sync.invalid_request".to_owned(),
8280                    message: "response does not start with RESP_HEADER".to_owned(),
8281                    recommended_action: None,
8282                };
8283            }
8284        }
8285
8286        if let Err(message) = self.begin_coalesced_apply() {
8287            return SyncOutcome::Failed {
8288                details: None,
8289                error_code: "storage.failed".into(),
8290                message,
8291                recommended_action: None,
8292            };
8293        }
8294        let mut failure: Option<(String, String, Option<String>, Option<Value>)> = None;
8295        // §4.5 client application: the units whose persisted echo a live
8296        // change must match, fixed at LIVE_START after every SUB_END persisted.
8297        let mut live: Option<(LiveStatus, String, Vec<UnitRecord>)> = None;
8298        let mut live_ended = false;
8299        while let Some(frame) = frames.next() {
8300            match frame {
8301                frame @ Frame::PushResult { .. } => {
8302                    let successful = matches!(
8303                        &frame,
8304                        Frame::PushResult {
8305                            status: PushStatus::Applied | PushStatus::Cached,
8306                            ..
8307                        }
8308                    );
8309                    let mut results = vec![frame];
8310                    if successful {
8311                        while matches!(
8312                            frames.peek(),
8313                            Some(Frame::PushResult {
8314                                status: PushStatus::Applied | PushStatus::Cached,
8315                                ..
8316                            })
8317                        ) {
8318                            if let Some(next) = frames.next() {
8319                                results.push(next);
8320                            }
8321                        }
8322                    }
8323                    if self
8324                        .handle_push_results(
8325                            &results,
8326                            &pushed_ids,
8327                            &rejection_details_by_commit,
8328                            &mut report,
8329                            last_final_push_result_id.as_deref(),
8330                        )
8331                        .is_err()
8332                    {
8333                        failure = Some((
8334                            "client.outcome_persistence_failed".to_owned(),
8335                            "local commit outcome could not be persisted".to_owned(),
8336                            None,
8337                            None,
8338                        ));
8339                        break;
8340                    }
8341                }
8342                Frame::PushResultDetails { .. } => {}
8343                Frame::SubStart {
8344                    id,
8345                    status,
8346                    reason_code,
8347                    bootstrap,
8348                    fenced,
8349                } => {
8350                    // §1.4 rule 5: an ERROR closes the section; its body still
8351                    // applied, its SUB_END values are never persisted.
8352                    let mut body = Vec::new();
8353                    let mut sub_end: Option<(i64, Option<String>)> = None;
8354                    let mut error: Option<Frame> = None;
8355                    for inner in frames.by_ref() {
8356                        match inner {
8357                            Frame::SubEnd {
8358                                next_cursor,
8359                                bootstrap_state,
8360                            } => {
8361                                sub_end = Some((next_cursor, bootstrap_state.map(|r| r.0)));
8362                                break;
8363                            }
8364                            inner @ Frame::Error { .. } => {
8365                                error = Some(inner);
8366                                break;
8367                            }
8368                            Frame::Unknown { .. } => {}
8369                            other => body.push(other),
8370                        }
8371                    }
8372                    let ended = sub_end.is_some();
8373                    let section = SectionStart {
8374                        id,
8375                        status,
8376                        reason_code,
8377                        bootstrap,
8378                        fenced,
8379                    };
8380                    match self.process_section(
8381                        transport,
8382                        &section,
8383                        body,
8384                        sub_end,
8385                        meta,
8386                        &mut report,
8387                    ) {
8388                        Err(SectionError::Abort(code, message)) => {
8389                            failure = Some((code, message, None, None));
8390                            break;
8391                        }
8392                        Err(SectionError::Transport(error)) => {
8393                            failure = Some((error.code, error.message, None, error.details));
8394                            break;
8395                        }
8396                        _ => {}
8397                    }
8398                    if ended {
8399                        // The counters stay: `complete` and `failed` report them.
8400                        self.progress.update(|p| {
8401                            p.unit_id = None;
8402                            p.table = None;
8403                            p.segment_id = None;
8404                        });
8405                    }
8406                    match error {
8407                        Some(Frame::Error {
8408                            code,
8409                            message,
8410                            recommended_action,
8411                            details,
8412                            ..
8413                        }) => {
8414                            failure = Some(Self::error_frame_failure(
8415                                code,
8416                                message,
8417                                recommended_action,
8418                                details,
8419                            ));
8420                            break;
8421                        }
8422                        Some(_) => unreachable!("only an ERROR closes a section early"),
8423                        None if !ended => {
8424                            failure = Some((
8425                                "sync.invalid_request".to_owned(),
8426                                "unit section without SUB_END".to_owned(),
8427                                None,
8428                                None,
8429                            ));
8430                            break;
8431                        }
8432                        None => {}
8433                    }
8434                }
8435                Frame::LiveStart {
8436                    status,
8437                    reason_code,
8438                } => {
8439                    let receivers = match self.stored(load_units(&self.conn)) {
8440                        Ok(units) => units
8441                            .into_iter()
8442                            .filter(|unit| {
8443                                unit.status == UnitStatus::Active
8444                                    && unit.echo.is_some()
8445                                    && !unit.bootstrapping()
8446                            })
8447                            .collect(),
8448                        Err(message) => {
8449                            failure = Some(("storage.failed".to_owned(), message, None, None));
8450                            break;
8451                        }
8452                    };
8453                    live = Some((status, reason_code, receivers));
8454                }
8455                Frame::Commit {
8456                    commit_seq,
8457                    tables,
8458                    changes,
8459                    ..
8460                } => {
8461                    let Some((LiveStatus::Active, _, receivers)) = &live else {
8462                        continue;
8463                    };
8464                    let receivers = receivers.clone();
8465                    match self.apply_live_commit(
8466                        &receivers,
8467                        &tables,
8468                        changes,
8469                        commit_seq,
8470                        AppliedServerCommitSource::Pull,
8471                    ) {
8472                        Ok(applied) => report.commits_applied += u32::from(applied),
8473                        Err(error) => {
8474                            failure = Some((error.code, error.message, None, error.details));
8475                            break;
8476                        }
8477                    }
8478                }
8479                Frame::LiveEnd {
8480                    through_seq,
8481                    echo_digest,
8482                } => {
8483                    let Some((status, reason_code, _)) = live.take() else {
8484                        continue;
8485                    };
8486                    live_ended = true;
8487                    live = Some((status, String::new(), Vec::new()));
8488                    if let Err(message) = self.finish_live_section(
8489                        status,
8490                        &reason_code,
8491                        through_seq,
8492                        echo_digest,
8493                        &meta.registration_digest,
8494                        &mut report,
8495                    ) {
8496                        failure = Some(("storage.failed".to_owned(), message, None, None));
8497                        break;
8498                    }
8499                }
8500                Frame::Lease {
8501                    lease_id,
8502                    expires_at_ms,
8503                } => {
8504                    // §7.3.5: persist the opaque lease; a fresh lease clears
8505                    // any prior lease error (the outage/revocation is over).
8506                    if let Err(message) = self.set_lease_state(Some(LeaseState {
8507                        lease_id: Some(lease_id),
8508                        expires_at_ms: Some(expires_at_ms),
8509                        error_code: None,
8510                    })) {
8511                        failure = Some(("storage.failed".to_owned(), message, None, None));
8512                        break;
8513                    }
8514                }
8515                Frame::Error {
8516                    code,
8517                    message,
8518                    recommended_action,
8519                    details,
8520                    ..
8521                } => {
8522                    // §1.6: the whole request failed; already-completed
8523                    // units keep their applied data and cursors.
8524                    failure = Some(Self::error_frame_failure(
8525                        code,
8526                        message,
8527                        recommended_action,
8528                        details,
8529                    ));
8530                    break;
8531                }
8532                Frame::Unknown { .. } => {}
8533                _ => {
8534                    failure = Some((
8535                        "sync.invalid_request".to_owned(),
8536                        "unexpected frame in response".to_owned(),
8537                        None,
8538                        None,
8539                    ));
8540                    break;
8541                }
8542            }
8543        }
8544
8545        let applied = match failure {
8546            Some(failure) => Err(failure),
8547            // Local apply boundaries already reconciled their affected overlay.
8548            // Refuse round success if any remaining dirty work fails to
8549            // reconcile. §4.8 E1: the push half may have drained commits that
8550            // pinned rows of a shrunk window unit, so retry deferred evictions.
8551            None => self
8552                .rebuild_overlay_if_dirty()
8553                .and_then(|()| self.drain_pending_evictions())
8554                .map_err(|message| ("storage.failed".to_owned(), message, None, None)),
8555        };
8556        // §1.4 rule 4: frames completed before a failure stay committed; a
8557        // failed COMMIT of the coalesced transaction fails the round.
8558        if let Err(message) = self.finish_coalesced_apply() {
8559            return SyncOutcome::Failed {
8560                details: None,
8561                error_code: "storage.failed".into(),
8562                message,
8563                recommended_action: None,
8564            };
8565        }
8566        if let Err((error_code, message, recommended_action, details)) = applied {
8567            return SyncOutcome::Failed {
8568                details,
8569                error_code,
8570                message,
8571                recommended_action,
8572            };
8573        }
8574        let catching_up = match self.stored(load_units(&self.conn)) {
8575            Ok(units) => units
8576                .into_iter()
8577                .filter(|unit| unit.status == UnitStatus::Active && unit.cursor.is_some())
8578                .map(|unit| unit.id)
8579                .collect::<Vec<_>>(),
8580            Err(message) => {
8581                return SyncOutcome::Failed {
8582                    details: None,
8583                    error_code: "storage.failed".into(),
8584                    message,
8585                    recommended_action: None,
8586                }
8587            }
8588        };
8589        // §7.1: a response without LIVE_END, one answered `unregistered` or
8590        // `reset`, or a unit still catching up leaves sync-needed raised;
8591        // after `unregistered` the next round starts at once.
8592        let status = live.map(|(status, _, _)| status);
8593        if !live_ended || status != Some(LiveStatus::Active) || !catching_up.is_empty() {
8594            self.set_sync_needed(true, status == Some(LiveStatus::Unregistered));
8595        }
8596        self.ack_after_pull(transport);
8597        // §7.4.5: the reset is over once the first post-reset pull round
8598        // leaves no unit catching up: the tables are rebuilt and current.
8599        if self.upgrading && catching_up.is_empty() {
8600            self.set_upgrading(false);
8601        }
8602        report.bootstrapping = catching_up;
8603        SyncOutcome::Ok(report)
8604    }
8605
8606    /// §1.6 / §10.1: the failure an in-band `ERROR` frame reports.
8607    fn error_frame_failure(
8608        code: String,
8609        message: String,
8610        recommended_action: String,
8611        details: Option<RawJson>,
8612    ) -> (String, String, Option<String>, Option<Value>) {
8613        let recommended_action = (!recommended_action.is_empty()).then_some(recommended_action);
8614        let details = details
8615            .and_then(|details| serde_json::from_str::<Value>(&details.0).ok())
8616            .filter(Value::is_object);
8617        (code, message, recommended_action, details)
8618    }
8619
8620    /// §4.5 at `LIVE_END` of a pull: join rule J for an `active` section, the
8621    /// §4.6 replica reset for `reset`, nothing for `unregistered`; then the
8622    /// replica cursor, the echo digest and the digest of the list the server
8623    /// now stores.
8624    fn finish_live_section(
8625        &mut self,
8626        status: LiveStatus,
8627        reason_code: &str,
8628        through_seq: i64,
8629        echo_digest: Option<[u8; 32]>,
8630        registration_digest: &str,
8631        report: &mut SyncReport,
8632    ) -> Result<(), String> {
8633        let rollback = self.capture();
8634        let resets = report.resets.len();
8635        self.begin_observation("syncular_live_end")?;
8636        let finished = (|| {
8637            let mut batch = ChangeAccumulator::default();
8638            let before = self.stored(replica_cursor(&self.conn))?;
8639            let mut cursor = if status == LiveStatus::Unregistered {
8640                before
8641            } else {
8642                -1
8643            };
8644            let joined = before.max(through_seq);
8645            for unit in self.stored(load_units(&self.conn))? {
8646                if unit.status != UnitStatus::Active || unit.bootstrapping() {
8647                    continue;
8648                }
8649                match status {
8650                    // §4.6 replica reset: every live unit bootstraps again;
8651                    // post-bootstrap units keep their cursors.
8652                    LiveStatus::Reset if unit.cursor.is_none() => {
8653                        for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
8654                            batch.window(&base_key, &value);
8655                        }
8656                        report.resets.push(unit.id.clone());
8657                        self.stored(save_unit(
8658                            &self.conn,
8659                            &UnitRecord {
8660                                reason_code: Some(reason_code.to_owned()),
8661                                cursor: Some(-1),
8662                                seeded: Vec::new(),
8663                                ..unit
8664                            },
8665                        ))?;
8666                    }
8667                    // §4.5 join rule J.
8668                    LiveStatus::Active => {
8669                        let next = unit.cursor.unwrap_or(joined).max(through_seq);
8670                        if next >= joined {
8671                            cursor = joined;
8672                        }
8673                        if unit.cursor.is_some() {
8674                            self.stored(save_unit(
8675                                &self.conn,
8676                                &UnitRecord {
8677                                    cursor: (next < joined).then_some(next),
8678                                    ..unit
8679                                },
8680                            ))?;
8681                        }
8682                    }
8683                    _ => {}
8684                }
8685            }
8686            self.set_meta(REPLICA_CURSOR_KEY, &cursor.to_string())?;
8687            self.set_meta(
8688                ECHO_DIGEST_KEY,
8689                &echo_digest
8690                    .map(|digest| bytes_to_hex(&digest))
8691                    .unwrap_or_default(),
8692            )?;
8693            if status == LiveStatus::Unregistered {
8694                self.delete_meta(REGISTERED_DIGEST_KEY)?;
8695            } else {
8696                self.set_meta(REGISTERED_DIGEST_KEY, registration_digest)?;
8697            }
8698            self.finish_observation("syncular_live_end", batch)
8699        })();
8700        if finished.is_err() {
8701            self.rollback_observation("syncular_live_end");
8702            self.restore(rollback);
8703            report.resets.truncate(resets);
8704        }
8705        finished
8706    }
8707
8708    // -- push results (§6.3, §7.2) ------------------------------------------------
8709
8710    fn handle_push_results(
8711        &mut self,
8712        frames: &[Frame],
8713        pushed_ids: &HashSet<&str>,
8714        rejection_details_by_commit: &HashMap<String, BTreeMap<i32, RejectionDetails>>,
8715        report: &mut SyncReport,
8716        last_final_push_result_id: Option<&str>,
8717    ) -> Result<(), String> {
8718        self.begin_observation("syncular_push_results")?;
8719        let rollback = self.capture();
8720        let conflict_count = self.conflicts.len();
8721        let applied_count = report.applied.len();
8722        let rejected_count = report.rejected.len();
8723        let retryable_count = report.retryable.len();
8724        let mut drained = Vec::new();
8725        let mut batch = ChangeAccumulator::default();
8726        let persisted = (|| {
8727            for frame in frames {
8728                let Frame::PushResult {
8729                    client_commit_id,
8730                    status,
8731                    results,
8732                    commit_seq,
8733                } = frame
8734                else {
8735                    return Err("unexpected acknowledgement frame".to_owned());
8736                };
8737                if !pushed_ids.contains(client_commit_id.as_str()) {
8738                    continue;
8739                }
8740                let Some(index) = self
8741                    .outbox
8742                    .iter()
8743                    .position(|commit| commit.client_commit_id == *client_commit_id)
8744                else {
8745                    continue;
8746                };
8747                let status = *status;
8748                let rejection_details = rejection_details_by_commit.get(client_commit_id);
8749                let operations = self.outbox[index].ops.clone();
8750                match status {
8751                    PushStatus::Applied | PushStatus::Cached => {
8752                        // §7.2: a lost ack replays as `cached` — proceed as if the
8753                        // ack had arrived.
8754                        let sequence =
8755                            commit_seq.ok_or_else(|| "ACK lacks a commit sequence".to_owned())?;
8756                        let affected: HashSet<_> = operations
8757                            .iter()
8758                            .map(|op| (op.table.as_str(), op.row_id.as_str()))
8759                            .collect();
8760                        let prior = self.acknowledged_operations(Some(&affected), None)?;
8761                        for (op_index, operation) in operations.iter().enumerate() {
8762                            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))
8763                                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
8764                            if delivered {
8765                                continue;
8766                            }
8767                            let table = self
8768                                .schema
8769                                .table(&operation.table)
8770                                .ok_or_else(|| "sync.unknown_table".to_owned())?;
8771                            let mut intended: Map<String, Value> = self
8772                                .stored_row(table, &operation.row_id, true)?
8773                                .map(|(row, _)| {
8774                                    table
8775                                        .columns
8776                                        .iter()
8777                                        .zip(&row)
8778                                        .map(|(column, value)| {
8779                                            (column.name.clone(), column_value_to_json(value))
8780                                        })
8781                                        .collect()
8782                                })
8783                                .unwrap_or_default();
8784                            let mut scope_image = intended.clone();
8785                            for op in prior
8786                                .iter()
8787                                .chain(
8788                                    self.failed_commits
8789                                        .iter()
8790                                        .flat_map(|(commit, _)| &commit.ops),
8791                                )
8792                                .chain(
8793                                    self.outbox
8794                                        .iter()
8795                                        .take(index)
8796                                        .flat_map(|commit| &commit.ops),
8797                                )
8798                                .chain(operations.iter().take(op_index + 1))
8799                            {
8800                                if op.table != operation.table || op.row_id != operation.row_id {
8801                                    continue;
8802                                }
8803                                if let Some(values) = &op.values {
8804                                    intended.extend(values.clone());
8805                                } else {
8806                                    scope_image = intended.clone();
8807                                    intended.clear();
8808                                }
8809                            }
8810                            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)",
8811                                rusqlite::params![client_commit_id, op_index as i64, operation.table, operation.row_id, sequence,
8812                                    serde_json::to_string(&CommitOperation::from(operation)).map_err(|_| "sync.local_corrupt".to_owned())?,
8813                                    serde_json::to_string(if operation.upsert { &intended } else { &scope_image }).map_err(|_| "sync.local_corrupt".to_owned())?])
8814                                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
8815                        }
8816                        let journal_results = results
8817                            .iter()
8818                            .map(|result| {
8819                                let op_index = match result {
8820                                    OpResult::Applied { op_index }
8821                                    | OpResult::Conflict { op_index, .. }
8822                                    | OpResult::Error { op_index, .. } => *op_index,
8823                                };
8824                                CommitOperationOutcome::Applied { op_index }
8825                            })
8826                            .collect::<Vec<_>>();
8827                        let outcome_status = if status == PushStatus::Applied {
8828                            CommitOutcomeStatus::Applied
8829                        } else {
8830                            CommitOutcomeStatus::Cached
8831                        };
8832                        let persisted = self
8833                            .persist_commit_outcome(
8834                                client_commit_id,
8835                                outcome_status,
8836                                &journal_results,
8837                                None,
8838                            )
8839                            .and_then(|()| self.delete_outbox_persisted(client_commit_id));
8840                        persisted?;
8841                        self.sync_needed = true;
8842                        batch.status = true;
8843                        batch.outcomes = true;
8844                    }
8845                    PushStatus::Rejected => {
8846                        if results.iter().any(|result| {
8847                            matches!(
8848                                result,
8849                                OpResult::Error {
8850                                    code,
8851                                    retryable: true,
8852                                    ..
8853                                } if code == "sync.idempotency_cache_miss"
8854                            )
8855                        }) {
8856                            // §6.3/§7.2: a serving failure, not an outcome — keep the
8857                            // exact commit queued for an identical retry.
8858                            report.retryable.push(client_commit_id.to_owned());
8859                            continue;
8860                        }
8861
8862                        let mut journal_results = Vec::with_capacity(results.len());
8863                        let mut conflicts = Vec::new();
8864                        let mut rejections = Vec::new();
8865                        for result in results {
8866                            match result {
8867                                OpResult::Applied { op_index } => {
8868                                    journal_results.push(CommitOperationOutcome::Applied {
8869                                        op_index: *op_index,
8870                                    });
8871                                }
8872                                OpResult::Conflict {
8873                                    op_index,
8874                                    code,
8875                                    message,
8876                                    server_version,
8877                                    server_row,
8878                                    conflict_columns: conflict_columns_bitmap,
8879                                } => {
8880                                    let operation = operations
8881                                        .get(*op_index as usize)
8882                                        .map(CommitOperation::from);
8883                                    let (table, row_id) = operation
8884                                        .as_ref()
8885                                        .map(|op| (op.table.clone(), op.row_id.clone()))
8886                                        .unwrap_or_default();
8887                                    let server_row_json = self
8888                                        .schema
8889                                        .table(&table)
8890                                        .and_then(|t| {
8891                                            decode_row_bytes(t, server_row, &self.encryption)
8892                                                .ok()
8893                                                .map(|row| (t, row))
8894                                        })
8895                                        .map(|(t, row)| {
8896                                            let mut map = Map::new();
8897                                            for (i, column) in t.columns.iter().enumerate() {
8898                                                map.insert(
8899                                                    column.name.clone(),
8900                                                    column_value_to_json(
8901                                                        row.get(i).unwrap_or(&None),
8902                                                    ),
8903                                                );
8904                                            }
8905                                            map
8906                                        })
8907                                        .unwrap_or_default();
8908                                    // §6.3: decode the presence-layout bitmap
8909                                    // into the marked column names.
8910                                    let conflict_columns = self
8911                                        .schema
8912                                        .table(&table)
8913                                        .map(|t| {
8914                                            t.columns
8915                                                .iter()
8916                                                .enumerate()
8917                                                .filter(|(index, _)| {
8918                                                    conflict_columns_bitmap
8919                                                        .get(index / 8)
8920                                                        .is_some_and(|byte| {
8921                                                            byte & (1 << (index % 8)) != 0
8922                                                        })
8923                                                })
8924                                                .map(|(_, column)| column.name.clone())
8925                                                .collect::<Vec<_>>()
8926                                        })
8927                                        .unwrap_or_default();
8928                                    let conflict = ConflictRecord {
8929                                        client_commit_id: client_commit_id.to_owned(),
8930                                        op_index: *op_index,
8931                                        table,
8932                                        row_id,
8933                                        code: code.clone(),
8934                                        message: message.clone(),
8935                                        server_version: *server_version,
8936                                        server_row: server_row_json,
8937                                        conflict_columns,
8938                                        operation,
8939                                    };
8940                                    journal_results.push(CommitOperationOutcome::Conflict {
8941                                        conflict: conflict.clone(),
8942                                    });
8943                                    conflicts.push(conflict);
8944                                }
8945                                OpResult::Error {
8946                                    op_index,
8947                                    code,
8948                                    message,
8949                                    retryable,
8950                                } => {
8951                                    let rejection = RejectionRecord {
8952                                        client_commit_id: client_commit_id.to_owned(),
8953                                        op_index: *op_index,
8954                                        code: code.clone(),
8955                                        message: message.clone(),
8956                                        retryable: *retryable,
8957                                        details: rejection_details
8958                                            .and_then(|details| details.get(op_index))
8959                                            .cloned(),
8960                                        operation: operations
8961                                            .get(*op_index as usize)
8962                                            .map(CommitOperation::from),
8963                                    };
8964                                    journal_results.push(CommitOperationOutcome::Error {
8965                                        rejection: rejection.clone(),
8966                                    });
8967                                    rejections.push(rejection);
8968                                }
8969                            }
8970                        }
8971                        if self.retain_failed_commits {
8972                            self.retain_failed_commit(client_commit_id, &operations)?;
8973                        }
8974                        let outcome_status = if conflicts.is_empty() {
8975                            CommitOutcomeStatus::Rejected
8976                        } else {
8977                            CommitOutcomeStatus::Conflict
8978                        };
8979                        let persisted = self
8980                            .persist_commit_outcome(
8981                                client_commit_id,
8982                                outcome_status,
8983                                &journal_results,
8984                                Some(&operations),
8985                            )
8986                            .and_then(|()| self.delete_outbox_persisted(client_commit_id));
8987                        persisted?;
8988                        batch.conflicts = !conflicts.is_empty();
8989                        batch.rejections = !rejections.is_empty();
8990                        batch.status = true;
8991                        batch.outcomes = true;
8992                        self.conflicts.extend(conflicts);
8993                        self.rejections.extend(rejections);
8994                    }
8995                }
8996                drained.push(self.outbox.remove(index));
8997                if batch.status {
8998                    for operation in &operations {
8999                        if !self.record_row_scopes(
9000                            &mut batch,
9001                            &operation.table,
9002                            &operation.row_id,
9003                            false,
9004                        ) {
9005                            batch.table(&operation.table);
9006                        }
9007                    }
9008                }
9009                match status {
9010                    PushStatus::Applied | PushStatus::Cached => {
9011                        report.applied.push(client_commit_id.to_owned())
9012                    }
9013                    PushStatus::Rejected => report.rejected.push(client_commit_id.to_owned()),
9014                }
9015            }
9016            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)) {
9017                self.prune_commit_outcomes()?;
9018            }
9019            self.reconcile_rows(&drained)?;
9020            self.rebuild_overlay_if_dirty()?;
9021            self.finish_observation("syncular_push_results", batch)
9022        })();
9023        if let Err(error) = persisted {
9024            self.rollback_observation("syncular_push_results");
9025            self.restore(rollback);
9026            report.applied.truncate(applied_count);
9027            report.rejected.truncate(rejected_count);
9028            report.retryable.truncate(retryable_count);
9029            return Err(error);
9030        }
9031        if !rollback.sync_needed && self.sync_needed {
9032            self.sync_intent_queue.push_back(SyncIntent::Interactive);
9033        }
9034        report.conflicts += (self.conflicts.len() - conflict_count) as u32;
9035        Ok(())
9036    }
9037
9038    fn push_result_is_final(status: PushStatus, results: &[OpResult]) -> bool {
9039        status != PushStatus::Rejected
9040            || !results.iter().any(|result| {
9041                matches!(
9042                    result,
9043                    OpResult::Error {
9044                        code,
9045                        retryable: true,
9046                        ..
9047                    } if code == "sync.idempotency_cache_miss"
9048                )
9049            })
9050    }
9051
9052    // -- unit sections and the live section ------------------------------------------
9053
9054    /// One unit section (§4.4): apply its segments, then persist its
9055    /// `SUB_END` (§4.6 reset, §3.3 revocation and purge, the echo, cursor and
9056    /// resume token). A section of a unit the app released while the round was
9057    /// in flight is skipped; a fail-closed first page fails the unit and skips
9058    /// the rest of its section (§5.6).
9059    fn process_section(
9060        &mut self,
9061        transport: &mut dyn Transport,
9062        start: &SectionStart,
9063        body: Vec<Frame>,
9064        sub_end: Option<(i64, Option<String>)>,
9065        meta: &RequestMeta,
9066        report: &mut SyncReport,
9067    ) -> Result<(), SectionError> {
9068        let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
9069        let unit = self
9070            .stored(get_unit(&self.conn, &start.id))
9071            .map_err(storage)?
9072            .filter(|unit| unit.status == UnitStatus::Active);
9073        // §7.7: a section boundary ends the previous payload.
9074        self.progress.update(|p| {
9075            p.phase = ProgressPhase::Import;
9076            p.unit_id = unit.as_ref().map(|unit| unit.id.clone());
9077            p.table = None;
9078            p.segment_id = None;
9079            p.bytes_received = 0;
9080            p.bytes_total = None;
9081            p.rows_processed = 0;
9082            p.rows_total = None;
9083            p.import_write_ms = None;
9084            p.import_commit_ms = None;
9085        });
9086        let Some(unit) = unit else {
9087            return Ok(());
9088        };
9089        let echo: Vec<EchoRecord> = start
9090            .fenced
9091            .iter()
9092            .map(|record| EchoRecord {
9093                table: record.table.clone(),
9094                status: record.status.name().to_owned(),
9095                scopes: record.scopes.iter().cloned().collect(),
9096            })
9097            .collect();
9098        // §5.6: a resumed bootstrap keeps the tables it already seeded.
9099        let mut seeded: BTreeSet<String> = if unit.bootstrap_state.is_none() {
9100            BTreeSet::new()
9101        } else {
9102            unit.seeded.iter().cloned().collect()
9103        };
9104        let applied = (|| {
9105            for frame in body {
9106                match frame {
9107                    Frame::SegmentInline { payload } => {
9108                        let segment = decode_rows_segment(&payload).map_err(|e| {
9109                            SectionError::Abort(e.code.as_str().to_owned(), e.detail)
9110                        })?;
9111                        self.progress.update(|p| {
9112                            p.phase = ProgressPhase::Import;
9113                            p.unit_id = Some(unit.id.clone());
9114                            p.table = Some(segment.table.clone());
9115                            p.segment_id = None;
9116                            p.bytes_received = payload.len() as u64;
9117                            p.bytes_total = Some(payload.len() as u64);
9118                            p.rows_processed = 0;
9119                            p.rows_total =
9120                                Some(segment.blocks.iter().map(|block| block.len() as u64).sum());
9121                            p.import_write_ms = None;
9122                            p.import_commit_ms = None;
9123                        });
9124                        let (pair, clear, effective) =
9125                            self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
9126                        report.segment_rows_applied +=
9127                            self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
9128                        seeded.insert(segment.table);
9129                    }
9130                    Frame::SegmentRef {
9131                        segment_id,
9132                        byte_length,
9133                        media_type,
9134                        table,
9135                        row_count,
9136                        as_of_commit_seq,
9137                        scope_digest,
9138                        row_cursor,
9139                        next_row_cursor,
9140                        url,
9141                        url_expires_at_ms,
9142                        ..
9143                    } => {
9144                        // §4.2: reject a descriptor whose mediaType was not
9145                        // advertised — never skip or guess.
9146                        let advertised = match media_type {
9147                            MediaType::Rows => {
9148                                meta.accept & ACCEPT_EXTERNAL_ROWS != 0
9149                                    || meta.accept & ACCEPT_INLINE_ROWS != 0
9150                            }
9151                            MediaType::Sqlite => meta.accept & ACCEPT_SQLITE != 0,
9152                        };
9153                        if !advertised {
9154                            return Err(SectionError::Abort(
9155                                "sync.invalid_request".to_owned(),
9156                                format!(
9157                                    "SEGMENT_REF mediaType {} was not advertised in accept (§4.2)",
9158                                    media_type.name()
9159                                ),
9160                            ));
9161                        }
9162                        self.progress.update(|p| {
9163                            p.phase = ProgressPhase::Download;
9164                            p.unit_id = Some(unit.id.clone());
9165                            p.table = Some(table.clone());
9166                            p.segment_id = Some(segment_id.clone());
9167                            p.bytes_received = 0;
9168                            p.bytes_total = u64::try_from(byte_length).ok();
9169                            p.rows_processed = 0;
9170                            p.rows_total = u64::try_from(row_count).ok();
9171                            p.import_write_ms = None;
9172                            p.import_commit_ms = None;
9173                        });
9174                        let observer = self.progress.clone();
9175                        let mut on_progress = |bytes| observer.update(|p| p.bytes_received = bytes);
9176                        let bytes = if let Some(url) = url {
9177                            // §5.4: a url-carrying descriptor MUST be fetched
9178                            // from that URL; failure invalidates the whole
9179                            // descriptor (no fall-through to §5.5 — re-pull
9180                            // recovers, §1.4 rule 5).
9181                            if meta.accept & ACCEPT_SIGNED_URLS == 0 {
9182                                return Err(SectionError::Abort(
9183                                    "sync.invalid_request".to_owned(),
9184                                    "SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)"
9185                                        .to_owned(),
9186                                ));
9187                            }
9188                            // §5.4: MUST NOT start a fetch at/past expiry.
9189                            if url_expires_at_ms.is_some_and(|exp| {
9190                                exp <= transport
9191                                    .segment_fetch_started_at(&url)
9192                                    .unwrap_or_else(|| self.clock_now_ms())
9193                            }) {
9194                                return Err(SectionError::Abort(
9195                                    "sync.segment_expired".to_owned(),
9196                                    format!(
9197                                        "signed URL for segment {segment_id} expired before fetch — re-pull mints fresh descriptors (§5.4)"
9198                                    ),
9199                                ));
9200                            }
9201                            transport
9202                                .fetch_url(
9203                                    &url,
9204                                    u64::try_from(byte_length).unwrap_or(0),
9205                                    &mut on_progress,
9206                                )
9207                                .map_err(|e| self.segment_fetch_failed(e))?
9208                        } else {
9209                            // §5.5: the owning unit's scope map, each value a one-element list.
9210                            let requested_scopes_json =
9211                                canonical_scope_json(&unit_scope_lists(&unit.scopes));
9212                            transport
9213                                .download_segment(
9214                                    &SegmentRequest {
9215                                        segment_id: segment_id.clone(),
9216                                        table: table.clone(),
9217                                        requested_scopes_json,
9218                                        byte_length: u64::try_from(byte_length).unwrap_or(0),
9219                                    },
9220                                    &mut on_progress,
9221                                )
9222                                .map_err(|e| self.segment_fetch_failed(e))?
9223                        };
9224                        // §5.4: the descriptor's byteLength caps the body before
9225                        // §5.1 verifies the content address; the client discards
9226                        // the segment and re-pulls on either failure.
9227                        if bytes.len() as i64 > byte_length {
9228                            self.schedule_background_retry();
9229                            return Err(SectionError::Abort(
9230                                "sync.invalid_request".to_owned(),
9231                                "segment exceeds its byteLength".to_owned(),
9232                            ));
9233                        }
9234                        on_progress(bytes.len() as u64);
9235                        let digest = Sha256::digest(&bytes);
9236                        let expected = segment_id
9237                            .strip_prefix("sha256:")
9238                            .unwrap_or(segment_id.as_str());
9239                        if bytes_to_hex(&digest) != expected {
9240                            // §5.1: the client discards the segment and re-pulls.
9241                            self.schedule_background_retry();
9242                            return Err(SectionError::Abort(
9243                                "sync.invalid_request".to_owned(),
9244                                "segment bytes do not match the content address (§5.1)".to_owned(),
9245                            ));
9246                        }
9247                        self.progress.update(|p| p.phase = ProgressPhase::Import);
9248                        if media_type == MediaType::Sqlite {
9249                            // §5.3: images are whole-table — a paged sqlite
9250                            // descriptor is invalid.
9251                            if row_cursor.is_some() || next_row_cursor.is_some() {
9252                                return Err(SectionError::Abort(
9253                                    "sync.invalid_request".to_owned(),
9254                                    "sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)"
9255                                        .to_owned(),
9256                                ));
9257                            }
9258                            let (pair, clear, effective) =
9259                                self.segment_pair(&unit, &echo, &seeded, &table)?;
9260                            report.segment_rows_applied += self.apply_sqlite_segment(
9261                                &pair,
9262                                &bytes,
9263                                clear,
9264                                &effective,
9265                                &unit.id,
9266                                row_count,
9267                                as_of_commit_seq,
9268                                &scope_digest,
9269                            )?;
9270                            seeded.insert(table);
9271                        } else {
9272                            let segment = decode_rows_segment(&bytes).map_err(|e| {
9273                                SectionError::Abort(e.code.as_str().to_owned(), e.detail)
9274                            })?;
9275                            let (pair, clear, effective) =
9276                                self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
9277                            report.segment_rows_applied +=
9278                                self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
9279                            seeded.insert(segment.table);
9280                        }
9281                    }
9282                    _ => {
9283                        return Err(SectionError::Abort(
9284                            "sync.invalid_request".to_owned(),
9285                            "unexpected frame inside a unit section".to_owned(),
9286                        ));
9287                    }
9288                }
9289            }
9290            Ok(())
9291        })();
9292        match applied {
9293            Ok(()) => {}
9294            Err(SectionError::FailClosed) => {
9295                // §5.6: the failure is unit-local; the rest of the response
9296                // still applies and the failed unit leaves the list.
9297                self.begin_observation("syncular_section_failure")
9298                    .map_err(storage)?;
9299                let failed = (|| {
9300                    let mut batch = ChangeAccumulator::default();
9301                    for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9302                        batch.window(&base_key, &value);
9303                    }
9304                    batch.status = true;
9305                    self.stored(save_unit(
9306                        &self.conn,
9307                        &UnitRecord {
9308                            status: UnitStatus::Failed,
9309                            reason_code: Some("sync.scope_revoked".to_owned()),
9310                            ..unit.clone()
9311                        },
9312                    ))?;
9313                    self.finish_observation("syncular_section_failure", batch)
9314                })();
9315                if let Err(message) = failed {
9316                    self.rollback_observation("syncular_section_failure");
9317                    return Err(storage(message));
9318                }
9319                report.failed.push(unit.id);
9320                return Ok(());
9321            }
9322            Err(error) => return Err(error),
9323        }
9324        let Some((next_cursor, bootstrap_state)) = sub_end else {
9325            return Ok(());
9326        };
9327        let rollback = self.capture();
9328        let counts = (
9329            report.resets.len(),
9330            report.revoked.len(),
9331            report.failed.len(),
9332        );
9333        self.begin_observation("syncular_sub_end")
9334            .map_err(storage)?;
9335        let finished = self
9336            .finish_section(start, echo, next_cursor, bootstrap_state, seeded, report)
9337            .and_then(|batch| {
9338                self.rebuild_overlay_if_dirty()?;
9339                self.finish_observation("syncular_sub_end", batch)
9340            });
9341        if let Err(message) = finished {
9342            self.rollback_observation("syncular_sub_end");
9343            self.restore(rollback);
9344            report.resets.truncate(counts.0);
9345            report.revoked.truncate(counts.1);
9346            report.failed.truncate(counts.2);
9347            return Err(storage(message));
9348        }
9349        Ok(())
9350    }
9351
9352    /// §5.6: the table, first-page flag and effective scopes of one segment
9353    /// of `unit`'s section.
9354    #[allow(clippy::type_complexity)]
9355    fn segment_pair(
9356        &self,
9357        unit: &UnitRecord,
9358        echo: &[EchoRecord],
9359        seeded: &BTreeSet<String>,
9360        name: &str,
9361    ) -> Result<(TableSchema, bool, Vec<(String, Vec<String>)>), SectionError> {
9362        let table = self.schema.table(name).cloned().ok_or_else(|| {
9363            SectionError::Abort(
9364                "sync.schema_mismatch".to_owned(),
9365                format!("segment table {name:?} is not in the client schema"),
9366            )
9367        })?;
9368        let effective = covers(&table, &unit.scopes)
9369            .then(|| pair_scopes(&unit.scopes, name, Some(echo)))
9370            .flatten()
9371            .ok_or_else(|| {
9372                SectionError::Abort(
9373                    "sync.invalid_request".to_owned(),
9374                    "a segment names no active pair of its unit".to_owned(),
9375                )
9376            })?;
9377        Ok((table, !seeded.contains(name), effective))
9378    }
9379
9380    /// §4.4 `SUB_END` of an active, revoked or reset section, inside the
9381    /// caller's observation: a reset discards cursor, resume token and
9382    /// first-page record and keeps the echo; a revoked pair purges by its last
9383    /// echo (§3.3); otherwise the echo replaces the persisted one, a revoked
9384    /// fenced record that turns active again re-bootstraps the unit, and a
9385    /// bootstrap section persists its pin, resume token and seeded tables.
9386    fn finish_section(
9387        &mut self,
9388        start: &SectionStart,
9389        echo: Vec<EchoRecord>,
9390        next_cursor: i64,
9391        bootstrap_state: Option<String>,
9392        seeded: BTreeSet<String>,
9393        report: &mut SyncReport,
9394    ) -> Result<ChangeAccumulator, String> {
9395        #[cfg(feature = "bench-internals")]
9396        let _phase = self.benchmark_phases.start(Phase::CursorPersist);
9397        let mut batch = ChangeAccumulator::default();
9398        // §4.4: SUB_END writes only into a unit that is still registered.
9399        let Some(unit) = self
9400            .stored(get_unit(&self.conn, &start.id))?
9401            .filter(|unit| unit.status == UnitStatus::Active)
9402        else {
9403            return Ok(batch);
9404        };
9405        for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9406            batch.window(&base_key, &value);
9407        }
9408        if start.status == SubStatus::Reset {
9409            // §4.6: staleness, never a purge; the rows stay until the
9410            // bootstrap replaces them.
9411            report.resets.push(unit.id.clone());
9412            self.stored(save_unit(
9413                &self.conn,
9414                &UnitRecord {
9415                    reason_code: Some(start.reason_code.clone()),
9416                    cursor: Some(-1),
9417                    bootstrap_state: None,
9418                    seeded: Vec::new(),
9419                    ..unit
9420                },
9421            ))?;
9422            return Ok(batch);
9423        }
9424        let revoked = start.status == SubStatus::Revoked;
9425        let mut units = None;
9426        let mut failed = false;
9427        let mut rearmed = false;
9428        for table in self.schema.tables.clone() {
9429            if !covers(&table, &unit.scopes) {
9430                continue;
9431            }
9432            let last = unit
9433                .echo
9434                .as_deref()
9435                .and_then(|last| pair_scopes(&unit.scopes, &table.name, Some(last)));
9436            let next = (!revoked)
9437                .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
9438                .flatten();
9439            // §3.3: a revoked fenced record that turns active again re-bootstraps.
9440            rearmed |= unit.echo.is_some() && last.is_none() && next.is_some();
9441            // §3.3: purge a pair the response revokes, keyed on the echo the
9442            // client persisted while the pair was active.
9443            if let (Some(last), None) = (&last, &next) {
9444                let units = match units {
9445                    Some(ref units) => units,
9446                    None => units.insert(self.stored(load_units(&self.conn))?),
9447                };
9448                let owners = unit_owners(units, &table, &unit.id);
9449                failed |= !self.purge_pair(&mut batch, &table, last, &owners)?;
9450            }
9451        }
9452        if revoked || failed {
9453            if revoked {
9454                report.revoked.push(unit.id.clone());
9455            }
9456            if failed {
9457                report.failed.push(unit.id.clone());
9458            }
9459            batch.status = true;
9460            self.stored(save_unit(
9461                &self.conn,
9462                &UnitRecord {
9463                    status: if failed {
9464                        UnitStatus::Failed
9465                    } else {
9466                        UnitStatus::Revoked
9467                    },
9468                    reason_code: Some(if failed {
9469                        "sync.scope_revoked".to_owned()
9470                    } else {
9471                        start.reason_code.clone()
9472                    }),
9473                    cursor: Some(-1),
9474                    bootstrap_state: None,
9475                    seeded: Vec::new(),
9476                    echo: None,
9477                    ..unit
9478                },
9479            ))?;
9480            return Ok(batch);
9481        }
9482        let completed = start.bootstrap && !rearmed && bootstrap_state.is_none();
9483        let (cursor, bootstrap_state, seeded) = if rearmed {
9484            (Some(-1), None, Vec::new())
9485        } else if start.bootstrap {
9486            let seeded = if bootstrap_state.is_none() {
9487                Vec::new()
9488            } else {
9489                seeded.into_iter().collect()
9490            };
9491            (Some(next_cursor), bootstrap_state, seeded)
9492        } else {
9493            (
9494                unit.cursor,
9495                unit.bootstrap_state.clone(),
9496                unit.seeded.clone(),
9497            )
9498        };
9499        self.stored(save_unit(
9500            &self.conn,
9501            &UnitRecord {
9502                reason_code: None,
9503                echo: Some(echo.clone()),
9504                cursor,
9505                bootstrap_state,
9506                seeded,
9507                ..unit.clone()
9508            },
9509        ))?;
9510        if !completed {
9511            return Ok(batch);
9512        }
9513        // §7.1: a completed bootstrap covers acknowledged intent of its pairs
9514        // at or below its pin.
9515        for table in self.schema.tables.clone() {
9516            let Some(effective) = covers(&table, &unit.scopes)
9517                .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
9518                .flatten()
9519            else {
9520                continue;
9521            };
9522            let mut statement = self
9523                .conn
9524                .prepare("SELECT id,intent_json FROM _syncular_acked_rows WHERE tbl=?1 AND commit_seq<=?2")
9525                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9526            let rows = statement
9527                .query_map(rusqlite::params![table.name, next_cursor], |row| {
9528                    Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
9529                })
9530                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9531            let mut covered = HashSet::new();
9532            for row in rows {
9533                let (id, intent) =
9534                    row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9535                let values: Map<String, Value> =
9536                    serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
9537                if owns_local_row(&table, &effective, &[], &values) {
9538                    covered.insert(id);
9539                }
9540            }
9541            drop(statement);
9542            for id in covered {
9543                self.conn
9544                    .execute(
9545                        "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3",
9546                        rusqlite::params![table.name, id, next_cursor],
9547                    )
9548                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9549                self.overlay_dirty.table(&table.name);
9550                batch.table(&table.name);
9551            }
9552        }
9553        Ok(batch)
9554    }
9555
9556    /// §3.3: purge one revoked pair inside the caller's observation: delete
9557    /// the rows matching its last effective scopes that no owner holds, drop
9558    /// the retained intent and every pending commit that provably writes into
9559    /// them, and delete now-unauthorized blob bodies. `Ok(false)` when the
9560    /// table has no local scope-column mapping (fail closed: nothing deleted).
9561    fn purge_pair(
9562        &mut self,
9563        batch: &mut ChangeAccumulator,
9564        table: &TableSchema,
9565        last: &[(String, Vec<String>)],
9566        owners: &[Vec<(String, Vec<String>)>],
9567    ) -> Result<bool, String> {
9568        if local_scope_predicate(table, last, owners).is_err() {
9569            return Ok(false);
9570        }
9571        for commit in self.drop_failed_commits(|name, values| {
9572            name == table.name && owns_local_row(table, last, owners, values)
9573        })? {
9574            batch.conflicts = true;
9575            batch.rejections = true;
9576            batch.outcomes = true;
9577            for operation in commit.ops {
9578                batch.table(&operation.table);
9579            }
9580        }
9581        if !self.purge_scope_rows(&table.name, last, owners)? {
9582            return Err("storage.failed: the revoked scope purge failed".to_owned());
9583        }
9584        self.record_scope_map(batch, &table.name, last);
9585        if self.drop_doomed_outbox(table, last, owners)? {
9586            batch.status = true;
9587            batch.rejections = true;
9588            batch.outcomes = true;
9589        }
9590        // §5.9.7 B2: revocation deletes now-unauthorized blob bodies.
9591        self.delete_unreferenced_cached_blobs()?;
9592        Ok(true)
9593    }
9594
9595    /// §4.5 client application: apply one live-section or delta `COMMIT`
9596    /// with only the changes that match the persisted echo of a receiving
9597    /// unit; every applied change then goes through the version guard.
9598    /// Returns whether any change of the frame applied.
9599    fn apply_live_commit(
9600        &mut self,
9601        receivers: &[UnitRecord],
9602        tables: &[String],
9603        changes: Vec<ssp2::model::Change>,
9604        commit_seq: i64,
9605        source: AppliedServerCommitSource,
9606    ) -> Result<bool, TransportError> {
9607        let changes: Vec<ssp2::model::Change> = changes
9608            .into_iter()
9609            .filter(|change| {
9610                // An unknown table fails loud in the apply below.
9611                let Some(table) = tables
9612                    .get(change.table_index as usize)
9613                    .and_then(|name| self.schema.table(name))
9614                else {
9615                    return true;
9616                };
9617                receivers.iter().any(|unit| {
9618                    covers(table, &unit.scopes)
9619                        && pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()).is_some_and(
9620                            |scopes| {
9621                                scopes.iter().all(|(variable, values)| {
9622                                    change
9623                                        .scopes
9624                                        .iter()
9625                                        .find(|(key, _)| key == variable)
9626                                        .is_some_and(|(_, value)| values.contains(value))
9627                                })
9628                            },
9629                        )
9630                })
9631            })
9632            .collect();
9633        if changes.is_empty() {
9634            return Ok(false);
9635        }
9636        let affected_tables = changes
9637            .iter()
9638            .filter_map(|change| tables.get(change.table_index as usize))
9639            .cloned()
9640            .collect::<BTreeSet<_>>();
9641        let previous_batches = self.change_queue.len();
9642        self.apply_commit_frame(tables, &changes, commit_seq)?;
9643        if self.change_queue.len() > previous_batches {
9644            if let Some(batch) = self.change_queue.back_mut() {
9645                batch
9646                    .applied_commits
9647                    .extend(
9648                        affected_tables
9649                            .into_iter()
9650                            .map(|table| AppliedServerCommit {
9651                                table,
9652                                commit_seq,
9653                                source,
9654                            }),
9655                    );
9656            }
9657        }
9658        Ok(true)
9659    }
9660
9661    // Both pull and realtime frames use the same durable observation boundary.
9662    fn apply_commit_frame(
9663        &mut self,
9664        tables: &[String],
9665        changes: &[ssp2::model::Change],
9666        sequence: i64,
9667    ) -> Result<(), TransportError> {
9668        #[cfg(feature = "bench-internals")]
9669        let _phase = self.benchmark_phases.start(Phase::CommitApply);
9670        let rollback = self.capture();
9671        self.coalesce_unit(changes.len())
9672            .and_then(|()| self.begin_observation("syncular_commit"))
9673            .map_err(|message| TransportError::new("storage.failed", message))?;
9674        let applied = (|| {
9675            let mut batch = ChangeAccumulator::default();
9676            self.record_commit_changes(&mut batch, tables, changes);
9677            // §7.1 chained base: a change names the version an acknowledged own
9678            // commit wrote; pending upserts chained on it move to that version.
9679            for change in changes {
9680                let Some(table) = tables.get(change.table_index as usize) else {
9681                    continue;
9682                };
9683                let acknowledged = self
9684                    .conn
9685                    .prepare_cached("SELECT op_json FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq=?3")
9686                    .and_then(|mut statement| {
9687                        statement
9688                            .query_map(rusqlite::params![table, change.row_id, sequence], |row| row.get::<_, String>(0))?
9689                            .collect::<Result<Vec<_>, _>>()
9690                    })
9691                    .map_err(|error| TransportError::new("storage.failed", Self::sqlite_failure(&self.storage_failure, error)))?
9692                    .iter()
9693                    .map(|op| serde_json::from_str::<CommitOperation>(op).map(OutboxOp::from))
9694                    .collect::<Result<Vec<_>, _>>()
9695                    .map_err(|_| TransportError::new("storage.failed", "sync.local_corrupt: invalid acknowledged operation".to_owned()))?;
9696                for index in 0..self.outbox.len() {
9697                    if !self.outbox[index]
9698                        .ops
9699                        .iter()
9700                        .any(|op| acknowledged.iter().any(|earlier| chains_on(earlier, op)))
9701                    {
9702                        continue;
9703                    }
9704                    let commit = Arc::make_mut(&mut self.outbox[index]);
9705                    for op in &mut commit.ops {
9706                        if acknowledged.iter().any(|earlier| chains_on(earlier, op)) {
9707                            op.base_version = Some(change.row_version);
9708                        }
9709                    }
9710                    let ops = serde_json::to_string(
9711                        &commit
9712                            .ops
9713                            .iter()
9714                            .map(CommitOperation::from)
9715                            .collect::<Vec<_>>(),
9716                    )
9717                    .map_err(|_| {
9718                        TransportError::new(
9719                            "storage.failed",
9720                            "sync.local_corrupt: unencodable outbox".to_owned(),
9721                        )
9722                    })?;
9723                    let id = commit.client_commit_id.clone();
9724                    self.conn
9725                        .execute(
9726                            "UPDATE _syncular_outbox SET ops_json=?1 WHERE commit_id=?2",
9727                            rusqlite::params![ops, id],
9728                        )
9729                        .map_err(|error| {
9730                            TransportError::new(
9731                                "storage.failed",
9732                                Self::sqlite_failure(&self.storage_failure, error),
9733                            )
9734                        })?;
9735                }
9736            }
9737            {
9738                let storage_failed = |error| {
9739                    TransportError::new(
9740                        "storage.failed",
9741                        Self::sqlite_failure(&self.storage_failure, error),
9742                    )
9743                };
9744                let pinned: HashSet<(&str, &str)> = self
9745                    .outbox
9746                    .iter()
9747                    .flat_map(|commit| &commit.ops)
9748                    .map(|op| (op.table.as_str(), op.row_id.as_str()))
9749                    .collect();
9750                for change in changes {
9751                    let table = tables.get(change.table_index as usize).ok_or_else(|| {
9752                        TransportError::new(
9753                            "sync.invalid_request",
9754                            "change tableIndex out of range".to_owned(),
9755                        )
9756                    })?;
9757                    if pinned.contains(&(table.as_str(), change.row_id.as_str())) {
9758                        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)")
9759                            .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
9760                            .map_err(storage_failed)?;
9761                    }
9762                    self.conn.prepare_cached("DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3")
9763                        .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
9764                        .map_err(storage_failed)?;
9765                }
9766            }
9767            self.apply_commit_changes(tables, changes)?;
9768            self.rebuild_overlay_if_dirty()
9769                .map_err(|message| TransportError::new("storage.failed", message))?;
9770            self.finish_observation("syncular_commit", batch)
9771                .map_err(|message| TransportError::new("storage.failed", message))
9772        })();
9773        if applied.is_err() {
9774            self.rollback_observation("syncular_commit");
9775            self.restore(rollback);
9776        }
9777        applied
9778    }
9779
9780    fn apply_commit_changes(
9781        &mut self,
9782        tables: &[String],
9783        changes: &[ssp2::model::Change],
9784    ) -> Result<(), TransportError> {
9785        // A clean overlay can reconcile changed primary keys independently
9786        // when their tables have no secondary unique constraints. Such a
9787        // constraint can change whether another row's write succeeds, so a
9788        // table with one and any local intent takes the table rebuild.
9789        let changed_tables: BTreeSet<&str> = changes
9790            .iter()
9791            .filter_map(|change| tables.get(change.table_index as usize))
9792            .map(String::as_str)
9793            .collect();
9794        let mut mirror_visible = !self.overlay_dirty.get();
9795        for name in &changed_tables {
9796            if mirror_visible
9797                && self
9798                    .schema
9799                    .table(name)
9800                    .is_some_and(|table| table.indexes.iter().any(|index| index.unique))
9801            {
9802                let (pending, protected) = self
9803                    .table_intent(name)
9804                    .map_err(|message| TransportError::new("storage.failed", message))?;
9805                mirror_visible = !pending && !protected;
9806            }
9807        }
9808        for change in changes {
9809            let table_name = tables.get(change.table_index as usize).ok_or_else(|| {
9810                TransportError::new(
9811                    "sync.invalid_request",
9812                    "change tableIndex out of range".to_owned(),
9813                )
9814            })?;
9815            let table = self.schema.table(table_name).ok_or_else(|| {
9816                TransportError::new(
9817                    "sync.schema_mismatch",
9818                    format!("change targets unknown table {table_name:?}"),
9819                )
9820            })?;
9821            let landed = match change.op {
9822                Op::Upsert => {
9823                    let payload = change.row.as_ref().ok_or_else(|| {
9824                        TransportError::new(
9825                            "sync.invalid_request",
9826                            "upsert change without row payload".to_owned(),
9827                        )
9828                    })?;
9829                    // §5.11: decrypt encrypted columns on apply.
9830                    let row = {
9831                        #[cfg(feature = "bench-internals")]
9832                        let _phase = self.benchmark_phases.start(Phase::RowDecode);
9833                        // §5.11: a decrypt failure keeps its own identity.
9834                        decode_row_bytes(table, payload, &self.encryption)?
9835                    };
9836                    let table_name = table.name.clone();
9837                    // §4.5 version guard: only a newer upsert lands.
9838                    let landed = self
9839                        .write_base_row(&table_name, &row, change.row_version)
9840                        .map_err(|m| TransportError::new("sync.invalid_request", m))?;
9841                    if mirror_visible && landed {
9842                        self.write_row(
9843                            &visible_table(&table_name),
9844                            &table_name,
9845                            &row,
9846                            change.row_version,
9847                        )
9848                        .map_err(|m| TransportError::new("sync.invalid_request", m))?;
9849                    }
9850                    landed
9851                }
9852                // §4.5 version guard: a delete at or below the local version
9853                // is skipped, a delete of an absent row is a no-op.
9854                Op::Delete => self
9855                    .delete_base_row(table_name, &change.row_id, change.row_version)
9856                    .map_err(|m| TransportError::new("sync.invalid_request", m))?,
9857            };
9858            // The change dropped the row's acknowledged intent either way
9859            // (§7.1), so the overlay of a skipped change rebuilds from the
9860            // unchanged base.
9861            self.overlay_dirty.table(table_name);
9862            if mirror_visible && !(landed && change.op == Op::Upsert) {
9863                let predicate = row_id_predicate(table);
9864                let visible = visible_table(table_name);
9865                let mut statements = vec![format!("DELETE FROM {visible} WHERE {predicate}")];
9866                if !landed {
9867                    statements.push(format!(
9868                        "INSERT INTO {visible} SELECT * FROM {} WHERE {predicate}",
9869                        base_table(table_name)
9870                    ));
9871                }
9872                for statement in &statements {
9873                    self.conn
9874                        .prepare_cached(statement)
9875                        .and_then(|mut statement| {
9876                            statement.execute(rusqlite::params![change.row_id])
9877                        })
9878                        .map_err(|error| {
9879                            TransportError::new("sync.invalid_request", error.to_string())
9880                        })?;
9881                }
9882            }
9883        }
9884        if mirror_visible {
9885            let changed_rows: HashSet<(&str, &str)> = changes
9886                .iter()
9887                .map(|change| {
9888                    (
9889                        tables[change.table_index as usize].as_str(),
9890                        change.row_id.as_str(),
9891                    )
9892                })
9893                .collect();
9894            self.replay_overlay(&changed_tables, Some(&changed_rows))
9895                .map_err(|message| TransportError::new("storage.failed", message))?;
9896            self.overlay_dirty.set(false);
9897        }
9898        Ok(())
9899    }
9900
9901    /// §5.6 segment application: validate against the generated schema,
9902    /// clear the pair's scope on the table's first page (fail closed
9903    /// without a mapping), then upsert each row with its segment-carried
9904    /// server version under the §4.5 version guard (§5.2).
9905    fn apply_segment(
9906        &mut self,
9907        table: &TableSchema,
9908        segment: &RowsSegment,
9909        first_page: bool,
9910        effective: &[(String, Vec<String>)],
9911        unit_id: &str,
9912    ) -> Result<u32, SectionError> {
9913        // §5.2: the column table validates against the generated schema —
9914        // order, names, types, nullability; mismatch is fatal. §5.11: the
9915        // server sends the WIRE types (bytes for an encrypted column), so
9916        // validate against wire_columns.
9917        let column = if segment.columns.len() != table.wire_columns.len() {
9918            Some(Value::from("count"))
9919        } else {
9920            segment
9921                .columns
9922                .iter()
9923                .zip(table.wire_columns.iter())
9924                .position(|(a, b)| a.name != b.name || a.ty != b.ty || a.nullable != b.nullable)
9925                .map(Value::from)
9926        };
9927        if segment.table != table.name
9928            || segment.schema_version != self.schema.version
9929            || column.is_some()
9930        {
9931            let mut details = Map::new();
9932            details.insert("table".to_owned(), Value::from(table.name.as_str()));
9933            if let Some(column) = column {
9934                details.insert("column".to_owned(), column);
9935            }
9936            return Err(SectionError::Transport(TransportError {
9937                code: "sync.schema_mismatch".to_owned(),
9938                message: "rows segment columns do not match the generated schema (§5.2)".to_owned(),
9939                details: Some(Value::Object(details)),
9940            }));
9941        }
9942        let mut applied = 0u32;
9943        let empty = Vec::new();
9944        let blocks = if segment.blocks.is_empty() {
9945            std::slice::from_ref(&empty)
9946        } else {
9947            &segment.blocks
9948        };
9949        for (index, block) in blocks.iter().enumerate() {
9950            let clear = first_page && index == 0;
9951            if !clear && block.is_empty() {
9952                continue;
9953            }
9954            let rollback = self.capture();
9955            let (pending, protected) = self
9956                .table_intent(&table.name)
9957                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9958            let reconcile_pending =
9959                !protected && pending && table.indexes.iter().any(|index| index.unique);
9960            let mirror_visible = !protected && !reconcile_pending;
9961            self.coalesce_unit(block.len())
9962                .and_then(|()| self.begin_observation("syncular_segment_block"))
9963                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9964            let outcome = (|| {
9965                self.rebuild_overlay_if_dirty()
9966                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9967                let mut changed_keys = Vec::new();
9968                let mut batch = ChangeAccumulator::default();
9969                if clear && self.clear_scope(table, effective, unit_id)? || !block.is_empty() {
9970                    batch.table(&table.name);
9971                }
9972                for (row_index, row) in block.iter().enumerate() {
9973                    let decrypted;
9974                    let values = if table.has_encrypted_columns() {
9975                        let mut values = row.values.clone();
9976                        crate::values::decrypt_segment_row(table, &mut values, &self.encryption)
9977                            .map_err(SectionError::Transport)?;
9978                        decrypted = values;
9979                        &decrypted
9980                    } else {
9981                        &row.values
9982                    };
9983                    if !self
9984                        .write_base_row(&table.name, values, row.server_version)
9985                        .map_err(|message| {
9986                            SectionError::Abort("sync.invalid_request".into(), message)
9987                        })?
9988                    {
9989                        continue;
9990                    }
9991                    if reconcile_pending {
9992                        changed_keys.push(
9993                            owned_sql_value(RowParam::Cell(&values[table.pk_index])).map_err(
9994                                |message| SectionError::Abort("storage.failed".into(), message),
9995                            )?,
9996                        );
9997                    }
9998                    if mirror_visible {
9999                        self.write_row(
10000                            &visible_table(&table.name),
10001                            &table.name,
10002                            values,
10003                            row.server_version,
10004                        )
10005                        .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10006                    }
10007                    let processed = u64::from(applied) + row_index as u64 + 1;
10008                    if processed.is_multiple_of(1024) {
10009                        self.progress.update(|p| p.rows_processed = processed);
10010                    }
10011                }
10012                self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
10013                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10014                self.finish_observation("syncular_segment_block", batch)
10015                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))
10016            })();
10017            if let Err(error) = outcome {
10018                self.rollback_observation("syncular_segment_block");
10019                self.restore(rollback);
10020                return Err(error);
10021            }
10022            applied += block.len() as u32;
10023            self.progress
10024                .update(|p| p.rows_processed = u64::from(applied));
10025            std::thread::yield_now();
10026        }
10027        self.progress
10028            .update(|p| p.rows_processed = u64::from(applied));
10029        Ok(applied)
10030    }
10031
10032    /// §5.3 sqlite-image application: validate the in-file metadata
10033    /// against the descriptor, validate column names/order against the
10034    /// generated schema, run the §5.6 first-page clear when fresh, then
10035    /// replace-or-upsert every image row with its `_syncular_version`.
10036    /// Mechanics: the image lands in a temp file read through a second
10037    /// rusqlite connection, equivalent to ATTACH + INSERT…SELECT.
10038    /// Each image chunk commits its writes and revision before readers continue.
10039    #[allow(clippy::too_many_arguments)]
10040    fn apply_sqlite_segment(
10041        &mut self,
10042        table: &TableSchema,
10043        bytes: &[u8],
10044        first_page: bool,
10045        effective: &[(String, Vec<String>)],
10046        unit_id: &str,
10047        row_count: i64,
10048        as_of_commit_seq: i64,
10049        scope_digest: &str,
10050    ) -> Result<u32, SectionError> {
10051        let invalid = |detail: &str| {
10052            SectionError::Abort(
10053                "sync.invalid_request".to_owned(),
10054                format!("sqlite segment rejected: {detail} (§5.3)"),
10055            )
10056        };
10057        // §5.11: an image bypasses the decrypt seam, so a server cannot serve
10058        // one for a table with encrypted columns.
10059        if table.has_encrypted_columns() {
10060            return Err(invalid("table has encrypted columns"));
10061        }
10062
10063        // The image lands beside the replica so it shares the replica's
10064        // directory permissions and volume; an in-memory replica has no
10065        // directory and uses the system temp dir. The file is owner-only.
10066        let directory = self
10067            .previous_version_replica_path()
10068            .and_then(|replica| std::path::Path::new(&replica).parent().map(Into::into))
10069            .unwrap_or_else(std::env::temp_dir);
10070        let path = directory.join(format!(".syncular-image-{}.tmp", uuid::Uuid::new_v4()));
10071        let outcome = (|| {
10072            let mut options = std::fs::OpenOptions::new();
10073            options.write(true).create_new(true);
10074            #[cfg(unix)]
10075            std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);
10076            std::io::Write::write_all(
10077                &mut options
10078                    .open(&path)
10079                    .map_err(|_| invalid("image temp file write failed"))?,
10080                bytes,
10081            )
10082            .map_err(|_| invalid("image temp file write failed"))?;
10083            let img = rusqlite::Connection::open_with_flags(
10084                &path,
10085                rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
10086            )
10087            .map_err(|_| invalid("bytes do not open as a SQLite database"))?;
10088            self.apply_sqlite_image(
10089                &img,
10090                table,
10091                first_page,
10092                effective,
10093                unit_id,
10094                row_count,
10095                as_of_commit_seq,
10096                scope_digest,
10097            )
10098        })();
10099        let _ = std::fs::remove_file(&path);
10100        outcome
10101    }
10102
10103    #[allow(clippy::too_many_arguments)]
10104    fn apply_sqlite_image(
10105        &mut self,
10106        img: &rusqlite::Connection,
10107        table: &crate::schema::TableSchema,
10108        first_fresh_page: bool,
10109        effective: &[(String, Vec<String>)],
10110        unit_id: &str,
10111        row_count: i64,
10112        as_of_commit_seq: i64,
10113        scope_digest: &str,
10114    ) -> Result<u32, SectionError> {
10115        let invalid = |detail: String| {
10116            SectionError::Abort(
10117                "sync.invalid_request".to_owned(),
10118                format!("sqlite segment rejected: {detail} (§5.3)"),
10119            )
10120        };
10121
10122        // 1. Metadata vs descriptor + client state (§5.3 rule 2; exactly
10123        //    one row).
10124        type MetaRow = (i64, String, i64, i64, String, i64, i64);
10125        let meta: MetaRow = img
10126            .query_row(
10127                "SELECT format, \"table\", \"schemaVersion\", \"asOfCommitSeq\",
10128                        \"scopeDigest\", \"rowCount\",
10129                        (SELECT count(*) FROM _syncular_segment)
10130                 FROM _syncular_segment",
10131                [],
10132                |row| {
10133                    Ok((
10134                        row.get(0)?,
10135                        row.get(1)?,
10136                        row.get(2)?,
10137                        row.get(3)?,
10138                        row.get(4)?,
10139                        row.get(5)?,
10140                        row.get(6)?,
10141                    ))
10142                },
10143            )
10144            .map_err(|_| invalid("missing or unreadable _syncular_segment metadata".to_owned()))?;
10145        let (format, meta_table, schema_version, pin, digest, meta_rows, meta_count) = meta;
10146        if meta_count != 1 {
10147            return Err(invalid(format!(
10148                "_syncular_segment must contain exactly one row, found {meta_count}"
10149            )));
10150        }
10151        if format != 1 {
10152            return Err(invalid(format!("format {format}")));
10153        }
10154        if meta_table != table.name {
10155            return Err(invalid(format!("image table {meta_table:?}")));
10156        }
10157        if schema_version != i64::from(self.schema.version) {
10158            return Err(invalid(format!("schemaVersion {schema_version}")));
10159        }
10160        if pin != as_of_commit_seq {
10161            return Err(invalid(format!("asOfCommitSeq {pin}")));
10162        }
10163        if digest != scope_digest {
10164            return Err(invalid("scopeDigest mismatch".to_owned()));
10165        }
10166        if meta_rows != row_count {
10167            return Err(invalid(format!("rowCount {meta_rows}")));
10168        }
10169
10170        // 2. Column names and order vs the generated schema (§5.3 rule 3).
10171        let mut names: Vec<String> = Vec::new();
10172        let mut primary_keys: Vec<String> = Vec::new();
10173        {
10174            let mut stmt = img
10175                .prepare(&format!("PRAGMA table_info({})", quote_ident(&table.name)))
10176                .map_err(|_| invalid("image data table missing".to_owned()))?;
10177            let mut rows = stmt
10178                .query([])
10179                .map_err(|_| invalid("image data table unreadable".to_owned()))?;
10180            while let Some(row) = rows
10181                .next()
10182                .map_err(|_| invalid("image data table unreadable".to_owned()))?
10183            {
10184                if row
10185                    .get::<_, i64>(5)
10186                    .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?
10187                    > 0
10188                {
10189                    primary_keys.push(row.get(1).map_err(|error| {
10190                        invalid(Self::sqlite_failure(&self.storage_failure, error))
10191                    })?);
10192                }
10193                names.push(
10194                    row.get::<_, String>(1)
10195                        .map_err(|_| invalid("image data table unreadable".to_owned()))?,
10196                );
10197            }
10198        }
10199        let mut expected: Vec<&str> = table.columns.iter().map(|c| c.name.as_str()).collect();
10200        expected.push("_syncular_version");
10201        if names.len() != expected.len() || names.iter().zip(expected.iter()).any(|(a, b)| a != b) {
10202            return Err(SectionError::Transport(TransportError {
10203                code: "sync.schema_mismatch".to_owned(),
10204                message: "sqlite segment columns do not match the generated schema (§5.3)"
10205                    .to_owned(),
10206                details: Some(serde_json::json!({ "table": table.name })),
10207            }));
10208        }
10209
10210        if primary_keys != vec![table.primary_key.clone()] {
10211            return Err(invalid(
10212                "image primary key does not match generated schema".into(),
10213            ));
10214        }
10215        let actual_count: i64 = img
10216            .query_row(
10217                &format!("SELECT count(*) FROM {}", quote_ident(&table.name)),
10218                [],
10219                |row| row.get(0),
10220            )
10221            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10222        if actual_count != row_count {
10223            return Err(invalid("image row count does not match descriptor".into()));
10224        }
10225        let insert = self.insert_row_sql(&base_table(&table.name), table);
10226        let visible_insert = self.insert_row_sql(&visible_table(&table.name), table);
10227        let column_list = names
10228            .iter()
10229            .map(|n| quote_ident(n))
10230            .collect::<Vec<_>>()
10231            .join(", ");
10232        let mut stmt = img
10233            .prepare(&format!(
10234                "SELECT {column_list} FROM {} ORDER BY {}",
10235                quote_ident(&table.name),
10236                quote_ident(&table.primary_key)
10237            ))
10238            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10239        let mut rows = stmt
10240            .query([])
10241            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10242        let mut applied = 0u32;
10243        let mut limit = 1024u32;
10244        let (mut write, mut commit) = (std::time::Duration::ZERO, std::time::Duration::ZERO);
10245        loop {
10246            let clear = applied == 0 && first_fresh_page;
10247            let rollback = self.capture();
10248            let (pending, protected) = self
10249                .table_intent(&table.name)
10250                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10251            let reconcile_pending =
10252                !protected && pending && table.indexes.iter().any(|index| index.unique);
10253            let mirror_visible = !protected && !reconcile_pending;
10254            // §5.3: a chunk holds 1,024 rows at first and doubles after each
10255            // commit up to 65,536; a chunk that replays local writes holds 1,024.
10256            let chunk = if pending || protected { 1024 } else { limit };
10257            self.coalesce_unit(chunk as usize)
10258                .and_then(|()| self.begin_observation("syncular_image_chunk"))
10259                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10260            let started = std::time::Instant::now();
10261            let result = (|| {
10262                self.rebuild_overlay_if_dirty()
10263                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10264                let mut changed_keys = Vec::new();
10265                let mut batch = ChangeAccumulator::default();
10266                if clear && self.clear_scope(table, effective, unit_id)? {
10267                    batch.table(&table.name);
10268                }
10269                let mut processed = 0u32;
10270                {
10271                    let mut ins = self.conn.prepare_cached(&insert).map_err(|error| {
10272                        invalid(Self::sqlite_failure(&self.storage_failure, error))
10273                    })?;
10274                    let mut mirror = if mirror_visible {
10275                        Some(self.conn.prepare_cached(&visible_insert).map_err(|error| {
10276                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10277                        })?)
10278                    } else {
10279                        None
10280                    };
10281                    for _ in 0..chunk {
10282                        let Some(row) = rows.next().map_err(|error| {
10283                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10284                        })?
10285                        else {
10286                            break;
10287                        };
10288                        for (i, column) in table.columns.iter().enumerate() {
10289                            let cell = row.get_ref(i).map_err(|error| {
10290                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10291                            })?;
10292                            let param = image_cell_param(column, cell).map_err(invalid)?;
10293                            ins.raw_bind_parameter(i + 1, &param).map_err(|error| {
10294                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10295                            })?;
10296                            if let Some(mirror) = &mut mirror {
10297                                mirror.raw_bind_parameter(i + 1, &param).map_err(|error| {
10298                                    invalid(Self::sqlite_failure(&self.storage_failure, error))
10299                                })?;
10300                            }
10301                        }
10302                        let version_index = table.columns.len();
10303                        let version: i64 = row.get(version_index).map_err(|error| {
10304                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10305                        })?;
10306                        if version < 1 {
10307                            return Err(invalid("image row version must be positive".into()));
10308                        }
10309                        ins.raw_bind_parameter(version_index + 1, version)
10310                            .map_err(|error| {
10311                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10312                            })?;
10313                        // §4.5 version guard: the base upsert decides.
10314                        let landed = ins.raw_execute().map_err(|error| {
10315                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10316                        })? > 0;
10317                        processed += 1;
10318                        if processed.is_multiple_of(1024) && processed < chunk {
10319                            self.progress
10320                                .update(|p| p.rows_processed = u64::from(applied + processed));
10321                        }
10322                        if !landed {
10323                            continue;
10324                        }
10325                        if let Some(mirror) = &mut mirror {
10326                            mirror
10327                                .raw_bind_parameter(version_index + 1, version)
10328                                .map_err(|error| {
10329                                    invalid(Self::sqlite_failure(&self.storage_failure, error))
10330                                })?;
10331                            mirror.raw_execute().map_err(|error| {
10332                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10333                            })?;
10334                        }
10335                        if reconcile_pending {
10336                            changed_keys.push(row.get::<_, SqlValue>(table.pk_index).map_err(
10337                                |error| invalid(Self::sqlite_failure(&self.storage_failure, error)),
10338                            )?);
10339                        }
10340                    }
10341                }
10342                if processed > 0 {
10343                    batch.table(&table.name);
10344                    self.overlay_dirty.table(&table.name);
10345                }
10346                self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
10347                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10348                let written = std::time::Instant::now();
10349                self.finish_observation("syncular_image_chunk", batch)
10350                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10351                Ok((processed, written))
10352            })();
10353            let (processed, written) = match result {
10354                Ok(done) => done,
10355                Err(error) => {
10356                    self.rollback_observation("syncular_image_chunk");
10357                    self.restore(rollback);
10358                    return Err(error);
10359                }
10360            };
10361            // The chunk commits before the yield, also inside a coalesced apply.
10362            let coalesced = self.coalesced.is_some();
10363            if coalesced {
10364                self.commit_coalesced_apply()
10365                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10366            }
10367            write += written - started;
10368            commit += written.elapsed();
10369            applied += processed;
10370            let last = processed < chunk || i64::from(applied) == actual_count;
10371            // A file replica's WAL keeps its high-water size until truncated.
10372            if last && self.conn.is_autocommit() {
10373                self.conn
10374                    .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
10375                    .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10376            }
10377            if coalesced {
10378                self.begin_coalesced_apply()
10379                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10380            }
10381            self.progress.update(|p| {
10382                p.rows_processed = u64::from(applied);
10383                p.import_write_ms = u64::try_from(write.as_millis()).ok();
10384                p.import_commit_ms = u64::try_from(commit.as_millis()).ok();
10385            });
10386            std::thread::yield_now();
10387            if last {
10388                break;
10389            }
10390            limit = (limit * 2).min(65_536);
10391        }
10392        if i64::from(applied) != actual_count {
10393            return Err(invalid(format!(
10394                "image yielded {applied} rows, expected {actual_count}"
10395            )));
10396        }
10397        Ok(applied)
10398    }
10399
10400    /// §7.1 keyed reconciliation of the rows `drained` commits touch: restore
10401    /// them from the base and replay their remaining intent. A table with a
10402    /// secondary unique index restores and replays every row with intent,
10403    /// since one row's value can admit or defer another row's write.
10404    fn reconcile_rows(&self, drained: &[Arc<OutboxCommit>]) -> Result<(), String> {
10405        let names: BTreeSet<&str> = drained
10406            .iter()
10407            .flat_map(|commit| &commit.ops)
10408            .map(|op| op.table.as_str())
10409            .collect();
10410        for name in names {
10411            let Some(table) = self.schema.table(name) else {
10412                continue;
10413            };
10414            let ops = drained.iter().flat_map(|commit| &commit.ops);
10415            let tables = BTreeSet::from([name]);
10416            let rows: HashSet<_> = ops
10417                .clone()
10418                .map(|op| (op.table.as_str(), op.row_id.as_str()))
10419                .collect();
10420            let unique = table.indexes.iter().any(|index| index.unique);
10421            let acknowledged = if unique {
10422                self.acknowledged_operations(None, Some(&tables))?
10423            } else {
10424                Vec::new()
10425            };
10426            let peers = acknowledged
10427                .iter()
10428                .chain(
10429                    self.failed_commits
10430                        .iter()
10431                        .flat_map(|(commit, _)| &commit.ops),
10432                )
10433                .chain(self.outbox.iter().flat_map(|commit| &commit.ops))
10434                .filter(|_| unique);
10435            self.restore_base_rows(table, &mut Vec::new(), peers.chain(ops.clone()))?;
10436            self.replay_overlay(&tables, (!unique).then_some(&rows))?;
10437        }
10438        Ok(())
10439    }
10440
10441    /// Whether `table` has pending outbox intent, and whether it has protected
10442    /// (acknowledged or retained failed) intent.
10443    fn table_intent(&self, table: &str) -> Result<(bool, bool), String> {
10444        let touches = |op: &OutboxOp| op.table == table;
10445        Ok((
10446            self.outbox
10447                .iter()
10448                .flat_map(|commit| &commit.ops)
10449                .any(touches),
10450            self.failed_commits
10451                .iter()
10452                .flat_map(|(commit, _)| &commit.ops)
10453                .any(touches)
10454                || self
10455                    .conn
10456                    .query_row(
10457                        "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows WHERE tbl=?1)",
10458                        [table],
10459                        |row| row.get(0),
10460                    )
10461                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10462        ))
10463    }
10464
10465    /// §7.1 reconciliation after an import block or chunk. Keyed replay covers
10466    /// only pending intent, so a table with protected intent rebuilds; a
10467    /// `restore` restores the imported `keys` and every pending row first.
10468    fn reconcile_import(
10469        &mut self,
10470        table: &TableSchema,
10471        keys: &mut Vec<SqlValue>,
10472        protected: bool,
10473        restore: bool,
10474    ) -> Result<(), String> {
10475        if protected {
10476            return self.rebuild_overlay_if_dirty();
10477        }
10478        let pending = self.outbox.iter().flat_map(|commit| &commit.ops);
10479        if restore {
10480            self.restore_base_rows(table, keys, pending.clone())?;
10481        }
10482        self.apply_outbox_ops(pending.filter(|op| op.table == table.name))?;
10483        self.overlay_dirty.set(false);
10484        Ok(())
10485    }
10486
10487    /// Restore the visible rows of `keys` and of the rows `ops` touch in
10488    /// `table` from the base before the caller replays their intent. The
10489    /// caller owns the transaction and publishes its revision after replay.
10490    fn restore_base_rows<'a>(
10491        &self,
10492        table: &TableSchema,
10493        keys: &mut Vec<SqlValue>,
10494        ops: impl IntoIterator<Item = &'a OutboxOp>,
10495    ) -> Result<(), String> {
10496        let visible = visible_table(&table.name);
10497        let base = base_table(&table.name);
10498        let pk = quote_ident(&table.primary_key);
10499        let predicate = row_id_predicate(table);
10500        let mut lookup = self.conn.prepare_cached(&format!(
10501            "SELECT {pk} FROM {base} WHERE {predicate} UNION SELECT {pk} FROM {visible} WHERE {predicate}"
10502        )).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10503        let mut deleted = HashSet::new();
10504        for op in ops.into_iter().filter(|op| op.table == table.name) {
10505            if op.upsert {
10506                if let Some(values) = &op.values {
10507                    let key = json_to_column_value(
10508                        &table.columns[table.pk_index],
10509                        values.get(&table.primary_key),
10510                    )?;
10511                    keys.push(owned_sql_value(RowParam::Cell(&key))?);
10512                }
10513            } else if deleted.insert(&op.row_id) {
10514                keys.extend(
10515                    lookup
10516                        .query_map([&op.row_id], |row| row.get::<_, SqlValue>(0))
10517                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
10518                        .collect::<Result<Vec<_>, _>>()
10519                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10520                );
10521            }
10522        }
10523        // Delete the complete affected set before restoring any base value, so
10524        // old optimistic unique values cannot collide with the new server rows.
10525        for chunk in keys.chunks(400) {
10526            let holes = vec!["?"; chunk.len()].join(",");
10527            self.conn
10528                .prepare_cached(&format!("DELETE FROM {visible} WHERE {pk} IN ({holes})"))
10529                .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
10530                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10531        }
10532        let updates = table
10533            .columns
10534            .iter()
10535            .map(|column| column.name.as_str())
10536            .chain(std::iter::once("_syncular_version"))
10537            .filter(|name| *name != table.primary_key)
10538            .map(|name| {
10539                let name = quote_ident(name);
10540                format!("{name}=excluded.{name}")
10541            })
10542            .collect::<Vec<_>>()
10543            .join(",");
10544        for chunk in keys.chunks(400) {
10545            let holes = vec!["?"; chunk.len()].join(",");
10546            self.conn.prepare_cached(&format!("INSERT INTO {visible} SELECT * FROM {base} WHERE {pk} IN ({holes}) ON CONFLICT ({pk}) DO UPDATE SET {updates}"))
10547                .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
10548                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10549        }
10550        Ok(())
10551    }
10552
10553    // -- application-authorized local purge ---------------------------------------
10554
10555    fn compile_local_data_purge(
10556        &self,
10557        input: &LocalDataPurgeInput,
10558    ) -> Result<(Vec<CompiledLocalDataPurgeTarget>, String), String> {
10559        let invalid = |message: String| format!("sync.invalid_request: {message}");
10560        if input.purge_id.is_empty()
10561            || input.purge_id.len() > 128
10562            || !is_local_operation_code_like(&input.purge_id)
10563        {
10564            return Err(invalid(
10565                "local purge purgeId must be a 1–128 character code-like identifier".to_owned(),
10566            ));
10567        }
10568        if input.targets.is_empty() || input.targets.len() > MAX_LOCAL_PURGE_TARGETS {
10569            return Err(invalid(format!(
10570                "local purge needs between 1 and {MAX_LOCAL_PURGE_TARGETS} targets"
10571            )));
10572        }
10573
10574        let mut deduplicated: BTreeMap<
10575            String,
10576            (CompiledLocalDataPurgeTarget, LocalDataPurgeTarget),
10577        > = BTreeMap::new();
10578        for target in &input.targets {
10579            let table = self.schema.table(&target.table).ok_or_else(|| {
10580                invalid(format!(
10581                    "local purge names unknown table {:?}",
10582                    target.table
10583                ))
10584            })?;
10585            if target.selectors.is_empty() || target.selectors.len() > MAX_LOCAL_PURGE_SELECTORS {
10586                return Err(invalid(format!(
10587                    "local purge target {:?} needs between 1 and {MAX_LOCAL_PURGE_SELECTORS} selectors",
10588                    target.table
10589                )));
10590            }
10591            let mut selectors = Vec::with_capacity(target.selectors.len());
10592            let mut canonical_selectors = BTreeMap::new();
10593            for (column_name, raw_values) in &target.selectors {
10594                let Some((column_index, column)) = table
10595                    .columns
10596                    .iter()
10597                    .enumerate()
10598                    .find(|(_, column)| column.name == *column_name)
10599                else {
10600                    return Err(invalid(format!(
10601                        "local purge target {:?} names unknown column {:?}",
10602                        target.table, column_name
10603                    )));
10604                };
10605                let encrypted = table
10606                    .encrypted_columns
10607                    .iter()
10608                    .any(|candidate| candidate.index == column_index);
10609                if column.ty != ColumnType::String || encrypted {
10610                    return Err(invalid(format!(
10611                        "local purge selector {:?}.{:?} must be a plaintext string column",
10612                        target.table, column_name
10613                    )));
10614                }
10615                if raw_values.is_empty() || raw_values.len() > MAX_LOCAL_PURGE_VALUES {
10616                    return Err(invalid(format!(
10617                        "local purge selector {:?}.{:?} needs between 1 and {MAX_LOCAL_PURGE_VALUES} values",
10618                        target.table, column_name
10619                    )));
10620                }
10621                let mut values = raw_values.clone();
10622                values.sort();
10623                values.dedup();
10624                if values.iter().any(|value| {
10625                    value.is_empty()
10626                        || value.len() > MAX_LOCAL_PURGE_VALUE_LENGTH
10627                        || !is_local_operation_code_like(value)
10628                }) {
10629                    return Err(invalid(format!(
10630                        "local purge selector values must be 1–{MAX_LOCAL_PURGE_VALUE_LENGTH} character code-like identifiers"
10631                    )));
10632                }
10633                selectors.push((column_name.clone(), values.clone()));
10634                canonical_selectors.insert(column_name.clone(), values);
10635            }
10636            let canonical = LocalDataPurgeTarget {
10637                table: target.table.clone(),
10638                selectors: canonical_selectors,
10639            };
10640            let key = serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
10641            deduplicated.insert(
10642                key,
10643                (
10644                    CompiledLocalDataPurgeTarget {
10645                        table: target.table.clone(),
10646                        selectors,
10647                    },
10648                    canonical,
10649                ),
10650            );
10651        }
10652        let targets = deduplicated
10653            .values()
10654            .map(|(compiled, _)| compiled.clone())
10655            .collect::<Vec<_>>();
10656        let canonical = deduplicated
10657            .values()
10658            .map(|(_, target)| target.clone())
10659            .collect::<Vec<_>>();
10660        let canonical_plan =
10661            serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
10662        Ok((targets, canonical_plan))
10663    }
10664
10665    fn local_purge_base_row_ids(
10666        &self,
10667        targets: &[CompiledLocalDataPurgeTarget],
10668    ) -> Result<BTreeMap<String, BTreeSet<String>>, String> {
10669        let mut by_table: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
10670        for target in targets {
10671            let table = self
10672                .schema
10673                .table(&target.table)
10674                .ok_or_else(|| format!("sync.invalid_request: unknown table {:?}", target.table))?;
10675            let mut clauses = Vec::with_capacity(target.selectors.len());
10676            let mut params = Vec::new();
10677            for (column, values) in &target.selectors {
10678                clauses.push(format!(
10679                    "{} IN ({})",
10680                    quote_ident(column),
10681                    values.iter().map(|_| "?").collect::<Vec<_>>().join(", ")
10682                ));
10683                params.extend(values.iter().cloned().map(SqlValue::Text));
10684            }
10685            let sql = format!(
10686                "SELECT CAST({} AS TEXT) FROM {} WHERE {}",
10687                quote_ident(&table.primary_key),
10688                base_table(&target.table),
10689                clauses.join(" AND ")
10690            );
10691            let mut statement = self
10692                .conn
10693                .prepare(&sql)
10694                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10695            let rows = statement
10696                .query_map(rusqlite::params_from_iter(params), |row| {
10697                    let value = sql_ref_to_json(&table.columns[table.pk_index], row.get_ref(0)?);
10698                    render_row_id_json(Some(&value))
10699                        .map_err(|message| rusqlite::Error::ToSqlConversionFailure(message.into()))
10700                })
10701                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10702            let ids = by_table.entry(target.table.clone()).or_default();
10703            for row in rows {
10704                ids.insert(
10705                    row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10706                );
10707            }
10708        }
10709        Ok(by_table)
10710    }
10711
10712    fn local_purge_values_match(
10713        target: &CompiledLocalDataPurgeTarget,
10714        values: &Map<String, Value>,
10715    ) -> bool {
10716        target.selectors.iter().all(|(column, allowed)| {
10717            values
10718                .get(column)
10719                .and_then(Value::as_str)
10720                .is_some_and(|value| allowed.iter().any(|candidate| candidate == value))
10721        })
10722    }
10723
10724    /// Apply one host-authorized local security purge. The host MUST gate the
10725    /// corresponding subscriptions first; this primitive owns local SQLite
10726    /// cleanup and never grants/revokes server authority by itself.
10727    pub fn purge_local_data(
10728        &mut self,
10729        input: &LocalDataPurgeInput,
10730    ) -> Result<LocalDataPurgeResult, String> {
10731        let (targets, canonical_plan) = self.compile_local_data_purge(input)?;
10732        let meta_key = format!("localPurge:{}", input.purge_id);
10733        let applied_plan = self
10734            .conn
10735            .query_row(
10736                "SELECT value FROM _syncular_meta WHERE key = ?1",
10737                rusqlite::params![meta_key],
10738                |row| row.get::<_, String>(0),
10739            )
10740            .optional()
10741            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10742        if let Some(applied_plan) = applied_plan {
10743            if applied_plan != canonical_plan {
10744                return Err(format!(
10745                    "sync.invalid_request: local purge id {:?} was already used with a different plan",
10746                    input.purge_id
10747                ));
10748            }
10749            return Ok(LocalDataPurgeResult {
10750                already_applied: true,
10751                purged_rows: 0,
10752                dropped_commits: 0,
10753            });
10754        }
10755
10756        // RFC 0005 D7: the container file cannot be a purge target (its name is
10757        // not in the running schema), so purge drops it as a fixed step, before
10758        // any mirror row is touched and unconditionally.
10759        let _ = self.drop_previous_version();
10760
10761        let rollback = self.capture();
10762        self.begin_observation("syncular_local_purge")?;
10763        let applied = (|| -> Result<(ChangeAccumulator, LocalDataPurgeResult), String> {
10764            let row_ids = self.local_purge_base_row_ids(&targets)?;
10765            let retained_dropped = self.drop_failed_commits(|table, values| {
10766                targets.iter().any(|target| {
10767                    target.table == table && Self::local_purge_values_match(target, values)
10768                })
10769            })?;
10770            let doomed = self
10771                .outbox
10772                .iter()
10773                .filter(|commit| {
10774                    commit.ops.iter().any(|operation| {
10775                        let matching_targets = targets
10776                            .iter()
10777                            .filter(|target| target.table == operation.table)
10778                            .collect::<Vec<_>>();
10779                        if matching_targets.is_empty() {
10780                            return false;
10781                        }
10782                        if row_ids
10783                            .get(&operation.table)
10784                            .is_some_and(|ids| ids.contains(&operation.row_id))
10785                        {
10786                            return true;
10787                        }
10788                        operation.values.as_ref().is_some_and(|values| {
10789                            matching_targets
10790                                .iter()
10791                                .any(|target| Self::local_purge_values_match(target, values))
10792                        })
10793                    })
10794                })
10795                .cloned()
10796                .collect::<Vec<_>>();
10797            let doomed_ids = doomed
10798                .iter()
10799                .map(|commit| commit.client_commit_id.clone())
10800                .collect::<BTreeSet<_>>();
10801            let mut batch = ChangeAccumulator::default();
10802            for commit in &retained_dropped {
10803                batch.conflicts = true;
10804                batch.rejections = true;
10805                batch.outcomes = true;
10806                for operation in &commit.ops {
10807                    batch.table(&operation.table);
10808                }
10809            }
10810            let mut rejections = Vec::new();
10811            for commit in &doomed {
10812                for operation in &commit.ops {
10813                    batch.table(&operation.table);
10814                    self.overlay_dirty.table(&operation.table);
10815                }
10816                let results = commit
10817                    .ops
10818                    .iter()
10819                    .enumerate()
10820                    .map(|(op_index, operation)| {
10821                        let rejection = RejectionRecord {
10822                            client_commit_id: commit.client_commit_id.clone(),
10823                            op_index: op_index as i32,
10824                            code: "client.local_data_purged".to_owned(),
10825                            message: "the commit was dropped by an application-authorized local data purge".to_owned(),
10826                            retryable: false,
10827                            details: None,
10828                            operation: Some(CommitOperation::from(operation)),
10829                        };
10830                        rejections.push(rejection.clone());
10831                        CommitOperationOutcome::Error { rejection }
10832                    })
10833                    .collect::<Vec<_>>();
10834                self.persist_commit_outcome(
10835                    &commit.client_commit_id,
10836                    CommitOutcomeStatus::Rejected,
10837                    &results,
10838                    Some(&commit.ops),
10839                )?;
10840                self.delete_outbox_persisted(&commit.client_commit_id)?;
10841            }
10842            if !doomed.is_empty() {
10843                self.outbox
10844                    .retain(|commit| !doomed_ids.contains(&commit.client_commit_id));
10845                self.rejections.extend(rejections);
10846                self.prune_commit_outcomes()?;
10847                batch.status = true;
10848                batch.rejections = true;
10849                batch.outcomes = true;
10850            }
10851
10852            let mut purged_rows = 0usize;
10853            for (table, ids) in &row_ids {
10854                if ids.is_empty() {
10855                    continue;
10856                }
10857                batch.table(table);
10858                self.overlay_dirty.table(table);
10859                for row_id in ids {
10860                    self.delete_base_row(table, row_id, i64::MAX)?;
10861                    purged_rows += 1;
10862                }
10863            }
10864            self.rebuild_overlay_if_dirty()?;
10865            self.delete_unreferenced_cached_blobs()?;
10866            self.conn
10867                .execute(
10868                    "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
10869                    rusqlite::params![meta_key, canonical_plan],
10870                )
10871                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10872            Ok((
10873                batch,
10874                LocalDataPurgeResult {
10875                    already_applied: false,
10876                    purged_rows,
10877                    dropped_commits: doomed.len(),
10878                },
10879            ))
10880        })()
10881        .and_then(|(batch, result)| {
10882            self.finish_observation("syncular_local_purge", batch)
10883                .map(|()| result)
10884        });
10885        let result = match applied {
10886            Ok(result) => result,
10887            Err(error) => {
10888                self.rollback_observation("syncular_local_purge");
10889                self.restore(rollback);
10890                return Err(error);
10891            }
10892        };
10893        self.cancel_sync_round();
10894        Ok(result)
10895    }
10896
10897    /// Application-authorized recovery of the replicated projection. Unlike a
10898    /// local security purge, this retains the entire outbox, device identity,
10899    /// lease, outcomes, unit registrations, and protected bookkeeping.
10900    /// The projection reset, unit rewind, optimistic replay, and
10901    /// idempotency marker share one savepoint for interruption safety.
10902    pub fn rebootstrap_local_data(
10903        &mut self,
10904        input: &LocalDataRebootstrapInput,
10905    ) -> Result<LocalDataRebootstrapResult, String> {
10906        if input.rebootstrap_id.is_empty()
10907            || input.rebootstrap_id.len() > 128
10908            || !is_local_operation_code_like(&input.rebootstrap_id)
10909        {
10910            return Err(
10911                "sync.invalid_request: local rebootstrap rebootstrapId must be a 1–128 character code-like identifier"
10912                    .to_owned(),
10913            );
10914        }
10915        let meta_key = format!("localRebootstrap:{}", input.rebootstrap_id);
10916        if let Some(persisted) = meta_get(&self.conn, &meta_key).map_err(|_| {
10917            "sync.local_corrupt: persisted local rebootstrap receipt is unreadable".to_owned()
10918        })? {
10919            let (retained_commits, reset_subscriptions) =
10920                decode_local_rebootstrap_receipt(&persisted)?;
10921            return Ok(LocalDataRebootstrapResult {
10922                already_applied: true,
10923                retained_commits,
10924                reset_subscriptions,
10925            });
10926        }
10927        if self.stopped || self.schema_floor.is_some() {
10928            return Err(
10929                "sync.invalid_request: local rebootstrap cannot bypass an active schema-floor stop; update the application first"
10930                    .to_owned(),
10931            );
10932        }
10933
10934        let retained_commits = self.outbox.len();
10935        let reset_subscriptions = self.stored(load_units(&self.conn))?.len();
10936        let receipt = encode_local_rebootstrap_receipt(retained_commits, reset_subscriptions)?;
10937        let rollback = self.capture();
10938        self.begin_observation("syncular_local_rebootstrap")?;
10939        let mut batch = ChangeAccumulator::default();
10940        let applied = (|| -> Result<(), String> {
10941            self.run_schema_reset_observed(&mut batch, false)?;
10942            self.conn
10943                .execute(
10944                    "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
10945                    rusqlite::params![meta_key, receipt],
10946                )
10947                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10948            self.sync_needed = true;
10949            self.sync_intent_queue.push_back(SyncIntent::Interactive);
10950            batch.status = true;
10951            Ok(())
10952        })()
10953        .and_then(|()| self.finish_observation("syncular_local_rebootstrap", batch));
10954        if let Err(error) = applied {
10955            self.rollback_observation("syncular_local_rebootstrap");
10956            self.restore(rollback);
10957            return Err(error);
10958        }
10959
10960        Ok(LocalDataRebootstrapResult {
10961            already_applied: false,
10962            retained_commits,
10963            reset_subscriptions,
10964        })
10965    }
10966
10967    // -- scope purge + doomed outbox (§3.3) ----------------------------------------
10968
10969    /// Delete base and visible rows owned by the effective scopes
10970    /// ([`local_scope_predicate`]); `Ok(false)` = no local scope-column
10971    /// mapping for a key (the fail-closed case). A SQLite failure is an error.
10972    fn purge_scope_rows(
10973        &mut self,
10974        table_name: &str,
10975        effective: &[(String, Vec<String>)],
10976        owners: &[Vec<(String, Vec<String>)>],
10977    ) -> Result<bool, String> {
10978        let Some(table) = self.schema.table(table_name) else {
10979            return Ok(false);
10980        };
10981        let Ok(predicate) = local_scope_predicate(table, effective, owners) else {
10982            return Ok(false);
10983        };
10984        let Some((predicate, params)) = predicate else {
10985            return Ok(true);
10986        };
10987        self.overlay_dirty.table(table_name);
10988        for source in [base_table(table_name), visible_table(table_name)] {
10989            self.conn
10990                .execute(
10991                    &format!("DELETE FROM {source} WHERE {predicate}"),
10992                    rusqlite::params_from_iter(&params),
10993                )
10994                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10995        }
10996        Ok(true)
10997    }
10998
10999    /// §3.3: drop pending commits whose upserts provably land in the
11000    /// revoked effective scopes and no other owner covers (row ownership)
11001    /// — whole-commit, never per-operation.
11002    fn drop_doomed_outbox(
11003        &mut self,
11004        table: &TableSchema,
11005        effective: &[(String, Vec<String>)],
11006        owners: &[Vec<(String, Vec<String>)>],
11007    ) -> Result<bool, String> {
11008        let doomed: Vec<_> =
11009            self.outbox
11010                .iter()
11011                .filter(|commit| {
11012                    commit.ops.iter().any(|op| {
11013                        op.upsert
11014                            && op.table == table.name
11015                            && op.values.as_ref().is_some_and(|values| {
11016                                owns_local_row(table, effective, owners, values)
11017                            })
11018                    })
11019                })
11020                .cloned()
11021                .collect();
11022        if doomed.is_empty() {
11023            return Ok(false);
11024        }
11025        let mut rejections = Vec::new();
11026        for commit in &doomed {
11027            let results = commit
11028                .ops
11029                .iter()
11030                .enumerate()
11031                .map(|(op_index, operation)| {
11032                    self.overlay_dirty.table(&operation.table);
11033                    let rejection = RejectionRecord {
11034                        client_commit_id: commit.client_commit_id.clone(),
11035                        op_index: op_index as i32,
11036                        code: "sync.scope_revoked".to_owned(),
11037                        message: "the commit was dropped because its effective scope was revoked"
11038                            .to_owned(),
11039                        retryable: false,
11040                        details: None,
11041                        operation: Some(CommitOperation::from(operation)),
11042                    };
11043                    rejections.push(rejection.clone());
11044                    CommitOperationOutcome::Error { rejection }
11045                })
11046                .collect::<Vec<_>>();
11047            self.persist_commit_outcome(
11048                &commit.client_commit_id,
11049                CommitOutcomeStatus::Rejected,
11050                &results,
11051                Some(&commit.ops),
11052            )?;
11053            self.delete_outbox_persisted(&commit.client_commit_id)?;
11054        }
11055        self.prune_commit_outcomes()?;
11056        let doomed_ids = doomed
11057            .iter()
11058            .map(|commit| commit.client_commit_id.as_str())
11059            .collect::<BTreeSet<_>>();
11060        self.outbox
11061            .retain(|commit| !doomed_ids.contains(commit.client_commit_id.as_str()));
11062        self.rejections.extend(rejections);
11063        Ok(true)
11064    }
11065
11066    // -- blobs (§5.9) ----------------------------------------------------------------
11067
11068    /// §5.9.7: hash bytes into the content address, cache them, queue the
11069    /// upload (flushed before the next push, B4). Returns the canonical
11070    /// BlobRef JSON `{blobId, byteLength, mediaType?}` for a `blob_ref`
11071    /// column value.
11072    pub fn upload_blob(
11073        &mut self,
11074        bytes: &[u8],
11075        media_type: Option<String>,
11076        name: Option<String>,
11077    ) -> Result<Value, String> {
11078        let blob_id = blob_id_for(bytes);
11079        let now = self.clock_now_ms();
11080        let tx = self
11081            .conn
11082            .transaction()
11083            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11084        tx.execute(
11085            "INSERT INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,?,?)
11086             ON CONFLICT(blob_id) DO NOTHING",
11087            rusqlite::params![blob_id, bytes, bytes.len() as i64, media_type, now],
11088        )
11089        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11090        tx.execute(
11091            "INSERT OR IGNORE INTO _syncular_blob_uploads(blob_id, media_type, created_at_ms) VALUES (?,?,?)",
11092            rusqlite::params![blob_id, media_type, now],
11093        )
11094        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11095        tx.commit()
11096            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11097        self.enforce_blob_cache_cap();
11098        let mut obj = Map::new();
11099        obj.insert("blobId".to_owned(), Value::from(blob_id));
11100        obj.insert("byteLength".to_owned(), Value::from(bytes.len() as i64));
11101        if let Some(mt) = media_type {
11102            obj.insert("mediaType".to_owned(), Value::from(mt));
11103        }
11104        if let Some(n) = name {
11105            obj.insert("name".to_owned(), Value::from(n));
11106        }
11107        Ok(Value::Object(obj))
11108    }
11109
11110    /// §5.9.7: resolve an owned blob body without driver encoding. A
11111    /// content-addressed cache hit serves with no fetch (B1); a miss downloads
11112    /// (§5.9.5), verifies the address, caches the bytes, and returns them.
11113    pub fn fetch_blob_bytes(
11114        &mut self,
11115        transport: &mut dyn Transport,
11116        blob_id_or_ref: &str,
11117    ) -> Result<FetchedBlob, (String, String)> {
11118        let simple = |m: String| ("client.failed".to_owned(), m);
11119        // A BlobRef declares the size that caps the download (§5.9.5); a bare
11120        // blobId declares none.
11121        let (blob_id, byte_length) = if blob_id_or_ref.starts_with("sha256:") {
11122            (blob_id_or_ref.to_owned(), None)
11123        } else {
11124            let value: Value = serde_json::from_str(blob_id_or_ref)
11125                .map_err(|_| simple("blob ref is not JSON".to_owned()))?;
11126            (
11127                value
11128                    .get("blobId")
11129                    .and_then(Value::as_str)
11130                    .ok_or_else(|| simple("blob ref has no blobId".to_owned()))?
11131                    .to_owned(),
11132                value.get("byteLength").and_then(Value::as_u64),
11133            )
11134        };
11135        if let Some(cached) = self.get_cached_blob_bytes(&blob_id).map_err(simple)? {
11136            return Ok(cached);
11137        }
11138        if !self.transport_enabled {
11139            return Err(("sync.offline".into(), "transport gate is closed".into()));
11140        }
11141        // §5.9.5: propagate the server's blob.* code (blob.forbidden /
11142        // blob.not_found) verbatim so the harness can assert on it. The
11143        // authorized endpoint serves bytes inline OR (always-issue, presign
11144        // configured) a signed url the client fetches directly — no host auth,
11145        // no fall-through: failure => re-request (the caller's next fetch_blob_bytes).
11146        #[cfg(feature = "bench-internals")]
11147        let download_phase = self.benchmark_phases.start(Phase::BlobDownload);
11148        let bytes = match transport
11149            .blob_download(&blob_id, byte_length)
11150            .map_err(|e| (e.code, e.message))?
11151        {
11152            BlobDownload::Bytes(bytes) => bytes,
11153            BlobDownload::Url {
11154                url,
11155                url_expires_at_ms,
11156            } => {
11157                // §5.9.5: MUST NOT start a fetch at/past expiry.
11158                if url_expires_at_ms.is_some_and(|exp| exp <= self.clock_now_ms()) {
11159                    return Err((
11160                        "sync.segment_expired".to_owned(),
11161                        format!(
11162                            "blob url for {blob_id} expired before fetch — re-request mints a fresh url (§5.9.5)"
11163                        ),
11164                    ));
11165                }
11166                transport
11167                    .fetch_blob_url(&url, byte_length)
11168                    .map_err(|e| (e.code, e.message))?
11169            }
11170        };
11171        #[cfg(feature = "bench-internals")]
11172        drop(download_phase);
11173        #[cfg(feature = "bench-internals")]
11174        let validate_phase = self.benchmark_phases.start(Phase::BlobValidate);
11175        // §5.9.5 inherits §5.1: the declared size caps the body before the
11176        // content address is verified.
11177        if byte_length.is_some_and(|cap| bytes.len() as u64 > cap) {
11178            return Err((
11179                "sync.invalid_request".to_owned(),
11180                "blob exceeds its byteLength".to_owned(),
11181            ));
11182        }
11183        if blob_id_for(&bytes) != blob_id {
11184            return Err(simple(format!(
11185                "blob content address mismatch for {blob_id}"
11186            )));
11187        }
11188        #[cfg(feature = "bench-internals")]
11189        drop(validate_phase);
11190        #[cfg(feature = "bench-internals")]
11191        let insert_phase = self.benchmark_phases.start(Phase::BlobCacheInsert);
11192        let now = self.clock_now_ms();
11193        self.conn
11194            .execute(
11195                "INSERT OR IGNORE INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,NULL,?)",
11196                rusqlite::params![blob_id, bytes, bytes.len() as i64, now],
11197            )
11198            .map_err(|e| simple(e.to_string()))?;
11199        self.conn
11200            .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
11201            .map_err(|e| simple(e.to_string()))?;
11202        self.enforce_blob_cache_cap();
11203        #[cfg(feature = "bench-internals")]
11204        drop(insert_phase);
11205        self.get_cached_blob_bytes(&blob_id)
11206            .map_err(simple)?
11207            .ok_or_else(|| simple("blob cache write failed".to_owned()))
11208    }
11209
11210    fn get_cached_blob_bytes(&self, blob_id: &str) -> Result<Option<FetchedBlob>, String> {
11211        #[cfg(feature = "bench-internals")]
11212        let _phase = self.benchmark_phases.start(Phase::BlobCacheRead);
11213        let mut stmt = self
11214            .conn
11215            .prepare("SELECT bytes, byte_length, media_type FROM _syncular_blobs WHERE blob_id = ?")
11216            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11217        let mut rows = stmt
11218            .query(rusqlite::params![blob_id])
11219            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11220        if let Some(row) = rows
11221            .next()
11222            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11223        {
11224            let bytes: Vec<u8> = row
11225                .get(0)
11226                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11227            let byte_length: i64 = row
11228                .get(1)
11229                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11230            let media_type: Option<String> = row
11231                .get(2)
11232                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11233            return Ok(Some(FetchedBlob {
11234                blob_id: blob_id.to_owned(),
11235                byte_length,
11236                bytes,
11237                media_type,
11238            }));
11239        }
11240        Ok(None)
11241    }
11242
11243    /// §5.9.7 B4: upload every queued blob before push.
11244    fn pending_blob_uploads(&self) -> Result<Vec<crate::round::PendingUpload>, TransportError> {
11245        let pending: Vec<(String, Option<String>)> = {
11246            let mut stmt = self
11247                .conn
11248                .prepare(
11249                    "SELECT blob_id, media_type FROM (
11250                      SELECT blob_id, media_type, created_at_ms FROM _syncular_blob_uploads
11251                      UNION ALL
11252                      SELECT DISTINCT r.blob_id, b.media_type, 9223372036854775807 AS created_at_ms
11253                      FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id = r.blob_id
11254                      WHERE NOT EXISTS (SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id = r.blob_id)
11255                    ) ORDER BY created_at_ms, blob_id",
11256                )
11257                .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11258            let rows = stmt
11259                .query_map([], |row| {
11260                    Ok((row.get::<_, String>(0)?, row.get::<_, Option<String>>(1)?))
11261                })
11262                .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11263            rows.collect::<Result<_, _>>()
11264                .map_err(|error| match error {
11265                    rusqlite::Error::InvalidColumnType(..)
11266                    | rusqlite::Error::FromSqlConversionFailure(..) => TransportError::new(
11267                        "sync.local_corrupt",
11268                        "Pending blob upload metadata is invalid",
11269                    ),
11270                    _ => TransportError::new("client.failed", error.to_string()),
11271                })?
11272        };
11273        let mut uploads = Vec::new();
11274        for (blob_id, media_type) in pending {
11275            let bytes = (|| {
11276                let stored: Option<(SqlValue, SqlValue)> = self
11277                    .conn
11278                    .query_row(
11279                        "SELECT bytes, byte_length FROM _syncular_blobs WHERE blob_id = ?",
11280                        rusqlite::params![blob_id],
11281                        |row| Ok((row.get(0)?, row.get(1)?)),
11282                    )
11283                    .optional()
11284                    .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11285                let Some((SqlValue::Blob(bytes), SqlValue::Integer(byte_length))) = stored else {
11286                    return Err(TransportError::new(
11287                        "sync.local_corrupt",
11288                        "Pending blob upload body is missing or corrupt",
11289                    ));
11290                };
11291                if byte_length != bytes.len() as i64 || blob_id_for(&bytes) != blob_id {
11292                    return Err(TransportError::new(
11293                        "sync.local_corrupt",
11294                        "Pending blob upload body is missing or corrupt",
11295                    ));
11296                }
11297                Ok(bytes)
11298            })();
11299            let failed = bytes.is_err();
11300            uploads.push(crate::round::PendingUpload {
11301                id: blob_id,
11302                bytes,
11303                media_type,
11304            });
11305            if failed {
11306                break;
11307            }
11308        }
11309        Ok(uploads)
11310    }
11311
11312    fn visible_blob_ids_sql(&self) -> String {
11313        let mut selects = Vec::new();
11314        for table in &self.schema.tables {
11315            for column in table
11316                .columns
11317                .iter()
11318                .filter(|column| column.ty == ColumnType::BlobRef)
11319            {
11320                let identifier = quote_ident(&column.name);
11321                selects.push(format!(
11322                    "SELECT json_extract({identifier}, '$.blobId') AS blob_id FROM {} \
11323                     WHERE typeof({identifier}) = 'text' AND json_valid({identifier}) \
11324                     AND json_type({identifier}, '$.blobId') = 'text'",
11325                    quote_ident(&table.name),
11326                ));
11327            }
11328        }
11329        if selects.is_empty() {
11330            "SELECT NULL AS blob_id WHERE 0".to_owned()
11331        } else {
11332            selects.join(" UNION ")
11333        }
11334    }
11335
11336    /// §5.9.7 B1 size cap. Visible rows, pending commits, and
11337    /// staged uploads pin bodies directly; no derived refcount is stored.
11338    fn enforce_blob_cache_cap(&self) {
11339        let Some(max_bytes) = self.limits.blob_cache_max_bytes else {
11340            return;
11341        };
11342        let mut total: i64 = self
11343            .conn
11344            .query_row(
11345                "SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs",
11346                [],
11347                |row| row.get(0),
11348            )
11349            .unwrap_or(0);
11350        if total <= max_bytes {
11351            return;
11352        }
11353        let query = format!(
11354            "SELECT blob_id, byte_length FROM _syncular_blobs
11355             WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
11356               AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
11357               AND blob_id NOT IN ({})
11358             ORDER BY created_at_ms ASC, blob_id ASC",
11359            self.visible_blob_ids_sql(),
11360        );
11361        let candidates: Vec<(String, i64)> = {
11362            let Ok(mut stmt) = self.conn.prepare(&query) else {
11363                return;
11364            };
11365            let Ok(rows) = stmt.query_map([], |row| {
11366                Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
11367            }) else {
11368                return;
11369            };
11370            rows.filter_map(Result::ok).collect()
11371        };
11372        for (blob_id, byte_length) in candidates {
11373            if total <= max_bytes {
11374                break;
11375            }
11376            let _ = self.conn.execute(
11377                "DELETE FROM _syncular_blobs WHERE blob_id = ?",
11378                rusqlite::params![blob_id],
11379            );
11380            total -= byte_length;
11381        }
11382    }
11383
11384    fn delete_unreferenced_cached_blobs(&mut self) -> Result<(), String> {
11385        #[cfg(feature = "bench-internals")]
11386        let _phase = self.benchmark_phases.start(Phase::BlobRetention);
11387        if !self.schema_has_blobs() {
11388            return Ok(());
11389        }
11390        self.rebuild_overlay_if_dirty()?;
11391        self.conn
11392            .execute(
11393                &format!(
11394                    "DELETE FROM _syncular_blobs
11395                 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
11396                   AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
11397                   AND blob_id NOT IN ({})",
11398                    self.visible_blob_ids_sql(),
11399                ),
11400                [],
11401            )
11402            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11403        Ok(())
11404    }
11405
11406    // -- local row storage ----------------------------------------------------------
11407
11408    /// The cached per-table primary-key upsert SQL for `full_table` (see
11409    /// the `insert_sql` field: built once, reused per row).
11410    fn insert_row_sql(&self, full_table: &str, table: &crate::schema::TableSchema) -> String {
11411        if let Some(sql) = self.insert_sql.borrow().get(full_table) {
11412            return sql.clone();
11413        }
11414        let mut columns: Vec<String> = table.columns.iter().map(|c| quote_ident(&c.name)).collect();
11415        columns.push(quote_ident("_syncular_version"));
11416        let placeholders: Vec<&str> = columns.iter().map(|_| "?").collect();
11417        let primary_key = quote_ident(&table.primary_key);
11418        let updates = columns
11419            .iter()
11420            .filter(|column| **column != primary_key)
11421            .map(|column| format!("{column}=excluded.{column}"))
11422            .collect::<Vec<_>>()
11423            .join(", ");
11424        // §4.5 version guard: server state lands in the base table only above
11425        // the stored version; the visible overlay takes every write.
11426        let guard = if full_table == base_table(&table.name) {
11427            format!(" WHERE excluded._syncular_version > {full_table}._syncular_version")
11428        } else {
11429            String::new()
11430        };
11431        let sql = format!(
11432            "INSERT INTO {full_table} ({}) VALUES ({}) ON CONFLICT ({primary_key}) DO UPDATE SET {updates}{guard}",
11433            columns.join(", "),
11434            placeholders.join(", ")
11435        );
11436        self.insert_sql
11437            .borrow_mut()
11438            .insert(full_table.to_owned(), sql.clone());
11439        sql
11440    }
11441
11442    /// §4.5: write a server row under the version guard; returns whether it
11443    /// landed.
11444    fn write_base_row(&self, table_name: &str, row: &Row, version: i64) -> Result<bool, String> {
11445        let landed = self.write_row(&base_table(table_name), table_name, row, version)?;
11446        if landed {
11447            self.overlay_dirty.table(table_name);
11448        }
11449        Ok(landed)
11450    }
11451
11452    fn write_row(
11453        &self,
11454        full_table: &str,
11455        table_name: &str,
11456        row: &Row,
11457        version: i64,
11458    ) -> Result<bool, String> {
11459        #[cfg(feature = "bench-internals")]
11460        let _phase = self.benchmark_phases.start(Phase::RowWrite);
11461        let table = self
11462            .schema
11463            .table(table_name)
11464            .ok_or_else(|| format!("unknown table {table_name:?}"))?;
11465        let sql = self.insert_row_sql(full_table, table);
11466        let mut stmt = self
11467            .conn
11468            .prepare_cached(&sql)
11469            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11470        let params = row
11471            .iter()
11472            .map(RowParam::Cell)
11473            .chain(std::iter::once(RowParam::Version(version)));
11474        stmt.execute(rusqlite::params_from_iter(params))
11475            .map(|changed| changed > 0)
11476            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11477    }
11478
11479    /// §4.5: delete a server row whose stored version lies below `version`;
11480    /// returns whether a row left.
11481    fn delete_base_row(
11482        &self,
11483        table_name: &str,
11484        row_id: &str,
11485        version: i64,
11486    ) -> Result<bool, String> {
11487        let table = self
11488            .schema
11489            .table(table_name)
11490            .ok_or_else(|| format!("unknown table {table_name:?}"))?;
11491        let sql = format!(
11492            "DELETE FROM {} WHERE {} AND _syncular_version < ?2",
11493            base_table(table_name),
11494            row_id_predicate(table)
11495        );
11496        let mut stmt = self
11497            .conn
11498            .prepare_cached(&sql)
11499            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11500        let landed = stmt
11501            .execute(rusqlite::params![row_id, version])
11502            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11503            > 0;
11504        if landed {
11505            self.overlay_dirty.table(table_name);
11506        }
11507        Ok(landed)
11508    }
11509
11510    fn has_acknowledged_rows(&self) -> Result<bool, String> {
11511        self.conn
11512            .query_row(
11513                "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows)",
11514                [],
11515                |row| row.get(0),
11516            )
11517            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11518    }
11519
11520    fn acknowledged_operations(
11521        &self,
11522        rows: Option<&HashSet<(&str, &str)>>,
11523        tables: Option<&BTreeSet<&str>>,
11524    ) -> Result<Vec<OutboxOp>, String> {
11525        let keys = rows.map(|rows| serde_json::to_string(&rows).expect("row keys"));
11526        let mut statement = self
11527            .conn
11528            .prepare_cached(if keys.is_some() {
11529                ACKED_ROWS_BY_ROW
11530            } else {
11531                "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"
11532            })
11533            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11534        let rows = statement
11535            .query_map(
11536                rusqlite::params![
11537                    keys,
11538                    tables.map(|tables| serde_json::to_string(tables).expect("table keys"))
11539                ],
11540                |row| {
11541                    #[cfg(test)]
11542                    self.acknowledged_replay_count
11543                        .set(self.acknowledged_replay_count.get() + 1);
11544                    Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
11545                },
11546            )
11547            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11548        rows.map(|row| {
11549            let (op, intent) =
11550                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11551            let op: CommitOperation =
11552                serde_json::from_str(&op).map_err(|_| "sync.local_corrupt".to_owned())?;
11553            let table = self
11554                .schema
11555                .table(&op.table)
11556                .ok_or_else(|| "sync.unknown_table".to_owned())?;
11557            let values = if op.op == "upsert" && self.visible_row(table, &op.row_id)?.is_none() {
11558                Some(serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?)
11559            } else {
11560                op.values.clone()
11561            };
11562            Ok(OutboxOp {
11563                values,
11564                ..op.into()
11565            })
11566        })
11567        .collect()
11568    }
11569
11570    fn drop_acknowledged_rows(
11571        &self,
11572        matches: impl Fn(&str, &Map<String, Value>) -> bool,
11573    ) -> Result<Vec<OutboxCommit>, String> {
11574        let mut statement = self
11575            .conn
11576            .prepare("SELECT commit_id,tbl,intent_json,id FROM _syncular_acked_rows")
11577            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11578        let rows = statement
11579            .query_map([], |row| {
11580                Ok((
11581                    row.get::<_, String>(0)?,
11582                    row.get::<_, String>(1)?,
11583                    row.get::<_, String>(2)?,
11584                    row.get::<_, String>(3)?,
11585                ))
11586            })
11587            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11588        let mut doomed = HashSet::new();
11589        for row in rows {
11590            let (id, table, intent, row_id) =
11591                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11592            let values =
11593                serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
11594            let base_matches = self
11595                .schema
11596                .table(&table)
11597                .map(|schema| self.stored_row(schema, &row_id, true))
11598                .transpose()?
11599                .flatten()
11600                .is_some_and(|(base, _)| {
11601                    let schema = self.schema.table(&table).expect("acknowledged table");
11602                    let values = schema
11603                        .columns
11604                        .iter()
11605                        .zip(base.iter())
11606                        .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
11607                        .collect();
11608                    matches(&table, &values)
11609                });
11610            if matches(&table, &values) || base_matches {
11611                doomed.insert(id);
11612            }
11613        }
11614        let mut dropped = Vec::new();
11615        for id in doomed {
11616            let mut statement = self
11617                .conn
11618                .prepare("SELECT op_json FROM _syncular_acked_rows WHERE commit_id=?1 ORDER BY idx")
11619                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11620            let operations = statement
11621                .query_map([&id], |row| row.get::<_, String>(0))
11622                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11623            let mut ops = Vec::new();
11624            for operation in operations {
11625                let json = operation
11626                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11627                let op: CommitOperation =
11628                    serde_json::from_str(&json).map_err(|_| "sync.local_corrupt".to_owned())?;
11629                self.overlay_dirty.table(&op.table);
11630                ops.push(OutboxOp {
11631                    table: op.table,
11632                    row_id: op.row_id,
11633                    upsert: op.op == "upsert",
11634                    base_version: op.base_version,
11635                    values: op.values,
11636                    insert: op.insert,
11637                });
11638            }
11639            dropped.push(OutboxCommit {
11640                client_commit_id: id.clone(),
11641                ops,
11642            });
11643            self.conn
11644                .execute("DELETE FROM _syncular_acked_rows WHERE commit_id=?1", [id])
11645                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11646        }
11647        Ok(dropped)
11648    }
11649
11650    /// [`Self::rebuild_overlay`], skipped when neither the base tables nor
11651    /// the outbox changed since the last rebuild (the no-op sync round).
11652    fn rebuild_overlay_if_dirty(&mut self) -> Result<(), String> {
11653        if self.overlay_dirty.get() {
11654            self.rebuild_overlay()?;
11655        }
11656        Ok(())
11657    }
11658
11659    /// §7.1: local reads see outbox state applied optimistically — rebuild
11660    /// every visible table as (base server state) + (pending outbox replay
11661    /// on top). Optimistic rows carry version `-1`.
11662    fn rebuild_overlay(&mut self) -> Result<(), String> {
11663        #[cfg(feature = "bench-internals")]
11664        let _phase = self.benchmark_phases.start(Phase::OverlayRebuild);
11665        #[cfg(test)]
11666        self.overlay_rebuild_count
11667            .set(self.overlay_rebuild_count.get() + 1);
11668        let dirty = self.overlay_dirty.snapshot();
11669        let tables: Vec<_> = self
11670            .schema
11671            .tables
11672            .iter()
11673            .filter(|table| {
11674                dirty
11675                    .as_ref()
11676                    .is_none_or(|names| names.is_empty() || names.contains(&table.name))
11677            })
11678            .cloned()
11679            .collect();
11680        let names: BTreeSet<_> = tables.iter().map(|table| table.name.as_str()).collect();
11681        self.begin_observation("syncular_overlay")?;
11682        let rebuilt = (|| {
11683            for table in &tables {
11684                for index in &table.fts_indexes {
11685                    self.drop_fts_triggers(index)?;
11686                }
11687                let visible = visible_table(&table.name);
11688                let base = base_table(&table.name);
11689                self.conn
11690                    .execute_batch(&format!(
11691                        "DELETE FROM {visible}; INSERT INTO {visible} SELECT * FROM {base}"
11692                    ))
11693                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11694            }
11695            self.replay_overlay(&names, None)?;
11696            for table in &tables {
11697                for index in &table.fts_indexes {
11698                    self.rebuild_fts_projection(table, index)?;
11699                    self.create_fts_triggers(table, index)?;
11700                }
11701            }
11702            self.conn
11703                .execute_batch("RELEASE syncular_overlay")
11704                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11705            Ok(())
11706        })();
11707        if rebuilt.is_err() {
11708            self.conn
11709                .execute_batch("ROLLBACK TO syncular_overlay; RELEASE syncular_overlay")
11710                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11711        } else {
11712            self.overlay_dirty.set(false);
11713        }
11714        rebuilt
11715    }
11716
11717    /// §7.1 replay of acknowledged, retained failed and pending intent, in
11718    /// that order, for the operations of `tables` on `rows` (every row for
11719    /// `None`) over their current visible state.
11720    fn replay_overlay(
11721        &self,
11722        tables: &BTreeSet<&str>,
11723        rows: Option<&HashSet<(&str, &str)>>,
11724    ) -> Result<(), String> {
11725        let replays = |op: &&OutboxOp| {
11726            tables.contains(op.table.as_str())
11727                && rows.is_none_or(|rows| rows.contains(&(op.table.as_str(), op.row_id.as_str())))
11728        };
11729        self.apply_outbox_ops(&self.acknowledged_operations(rows, Some(tables))?)?;
11730        for (commit, initial) in self.failed_commits.iter() {
11731            for operation in commit.ops.iter().filter(replays) {
11732                let Some(table) = self.schema.table(&operation.table) else {
11733                    continue;
11734                };
11735                if operation.upsert
11736                    && self.visible_row(table, &operation.row_id)?.is_none()
11737                    && operation.presented_values(table).is_some_and(|values| {
11738                        table
11739                            .columns
11740                            .iter()
11741                            .all(|column| values.contains_key(&column.name))
11742                    })
11743                {
11744                    let key = serde_json::to_string(&(&operation.table, &operation.row_id))
11745                        .expect("row key serialization");
11746                    if let Some(Value::Object(values)) = initial.get(&key) {
11747                        self.apply_outbox_ops(&[OutboxOp {
11748                            values: Some(values.clone()),
11749                            ..operation.clone()
11750                        }])?;
11751                    }
11752                }
11753            }
11754            self.apply_outbox_ops(commit.ops.iter().filter(replays))?;
11755        }
11756        self.apply_outbox_ops(
11757            self.outbox
11758                .iter()
11759                .flat_map(|commit| &commit.ops)
11760                .filter(replays),
11761        )
11762    }
11763
11764    /// §7.1 replay: every operation is applied over the current visible
11765    /// state. An operation that no longer applies (a server row now holds its
11766    /// unique value) stays pending and invisible until a later replay admits
11767    /// it or the server answers its push.
11768    fn apply_outbox_ops<'a>(
11769        &self,
11770        ops: impl IntoIterator<Item = &'a OutboxOp>,
11771    ) -> Result<(), String> {
11772        #[cfg(feature = "bench-internals")]
11773        let mut phase = self.benchmark_phases.start(Phase::PendingReplay);
11774        for op in ops {
11775            #[cfg(feature = "bench-internals")]
11776            if let Some(phase) = &mut phase {
11777                phase.unit();
11778            }
11779            if op.upsert {
11780                if let Some((table, values)) = self
11781                    .schema
11782                    .table(&op.table)
11783                    .filter(|table| table.indexes.iter().any(|index| index.unique))
11784                    .and_then(|table| Some((table, op.presented_values(table)?)))
11785                {
11786                    let mut intended: Map<String, Value> = self
11787                        .visible_row(table, &op.row_id)?
11788                        .map(|(row, _)| {
11789                            table
11790                                .columns
11791                                .iter()
11792                                .zip(&row)
11793                                .map(|(column, value)| {
11794                                    (column.name.clone(), column_value_to_json(value))
11795                                })
11796                                .collect()
11797                        })
11798                        .unwrap_or_default();
11799                    intended.extend(values.into_owned());
11800                    if !self.unique_conflicts(table, &intended, false)?.is_empty() {
11801                        continue;
11802                    }
11803                }
11804            }
11805            self.apply_outbox_op(op)?;
11806        }
11807        Ok(())
11808    }
11809
11810    fn apply_outbox_op(&self, op: &OutboxOp) -> Result<(), String> {
11811        let Some(table) = self.schema.table(&op.table) else {
11812            return Ok(());
11813        };
11814        let visible = visible_table(&table.name);
11815        if !op.upsert {
11816            let sql = format!("DELETE FROM {visible} WHERE {}", row_id_predicate(table));
11817            self.conn
11818                .prepare_cached(&sql)
11819                .and_then(|mut statement| statement.execute(rusqlite::params![op.row_id]))
11820                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11821            return Ok(());
11822        }
11823        // §7.1: an insert-intent operation that lacks a non-nullable column
11824        // cannot encode; it stays invisible until the send-time prepass drops
11825        // it as sync.outbox_incompatible (§7.4.4).
11826        let Some(values) = op.presented_values(table) else {
11827            return Ok(());
11828        };
11829        // §7.1: the overlay applies the operation's PRESENT columns
11830        // over the current local row. A partial operation over an
11831        // absent local row leaves it absent — the server answers it
11832        // with sync.row_deleted or sync.row_missing (§6.2). An
11833        // insert-intent operation presents every column.
11834        let full = table
11835            .columns
11836            .iter()
11837            .all(|column| values.contains_key(&column.name));
11838        let local = self.visible_row(table, &op.row_id)?;
11839        if local.is_none() && !full {
11840            return Ok(());
11841        }
11842        let mut row: Row = Vec::with_capacity(table.columns.len());
11843        for (index, column) in table.columns.iter().enumerate() {
11844            let incoming = match values.get(&column.name) {
11845                Some(raw) => json_to_column_value(
11846                    if raw.get("$bytes").is_some()
11847                        && table
11848                            .encrypted_columns
11849                            .iter()
11850                            .any(|encrypted| encrypted.index == index)
11851                    {
11852                        &table.wire_columns[index]
11853                    } else {
11854                        column
11855                    },
11856                    Some(raw),
11857                ),
11858                None => Ok(local
11859                    .as_ref()
11860                    .and_then(|(values, _)| values.get(index).cloned())
11861                    .flatten()),
11862            };
11863            row.push(incoming.map_err(|_| {
11864                "sync.local_corrupt: persisted optimistic row value is invalid".to_owned()
11865            })?);
11866        }
11867        let version = local.as_ref().map_or(-1, |(_, version)| *version);
11868        self.write_row(&visible, &table.name, &row, version)
11869            .map(|_| ())
11870            .map_err(|error| {
11871                if error.starts_with("UNIQUE constraint failed:") {
11872                    "sync.constraint_violation: local write violates a unique constraint".to_owned()
11873                } else {
11874                    error
11875                }
11876            })
11877    }
11878
11879    /// Whether the row is present in the overlay. Existence reads only the
11880    /// key: locked encrypted values stay opaque, and decoding the complete row
11881    /// would reject a valid plain write.
11882    fn visible_row_exists(&self, table: &TableSchema, row_id: &str) -> Result<bool, String> {
11883        self.conn
11884            .query_row(
11885                &format!(
11886                    "SELECT EXISTS(SELECT 1 FROM {} WHERE {})",
11887                    visible_table(&table.name),
11888                    row_id_predicate(table)
11889                ),
11890                rusqlite::params![row_id],
11891                |row| row.get(0),
11892            )
11893            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11894    }
11895
11896    /// The visible (optimistic) row's values plus version, or `None` when the
11897    /// row is absent from the overlay.
11898    fn visible_row(&self, table: &TableSchema, row_id: &str) -> Result<Option<(Row, i64)>, String> {
11899        self.stored_row(table, row_id, false)
11900    }
11901
11902    fn stored_row(
11903        &self,
11904        table: &TableSchema,
11905        row_id: &str,
11906        base: bool,
11907    ) -> Result<Option<(Row, i64)>, String> {
11908        let sql = format!(
11909            "SELECT * FROM {} WHERE {}",
11910            if base {
11911                base_table(&table.name)
11912            } else {
11913                visible_table(&table.name)
11914            },
11915            row_id_predicate(table)
11916        );
11917        let mut stmt = self
11918            .conn
11919            .prepare_cached(&sql)
11920            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11921        let mut rows = stmt
11922            .query(rusqlite::params![row_id])
11923            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11924        let Some(row) = rows
11925            .next()
11926            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11927        else {
11928            return Ok(None);
11929        };
11930        let mut values = Vec::with_capacity(table.columns.len());
11931        for (index, column) in table.columns.iter().enumerate() {
11932            let raw = row
11933                .get_ref(index)
11934                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11935            if let rusqlite::types::ValueRef::Blob(bytes) = raw {
11936                if table
11937                    .encrypted_columns
11938                    .iter()
11939                    .any(|encrypted| encrypted.index == index)
11940                {
11941                    values.push(Some(ColumnValue::Bytes(bytes.to_vec())));
11942                    continue;
11943                }
11944            }
11945            let json = sql_ref_to_json(column, raw);
11946            values.push(json_to_column_value(column, Some(&json)).map_err(|_| {
11947                "sync.local_corrupt: persisted local row value is invalid".to_owned()
11948            })?);
11949        }
11950        let version: i64 = row
11951            .get(table.columns.len())
11952            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11953        Ok(Some((values, version)))
11954    }
11955
11956    // -- realtime (§8) ---------------------------------------------------------------
11957
11958    /// §8.8: the configured realtime policy.
11959    #[must_use]
11960    pub fn realtime_policy(&self) -> RealtimePolicy {
11961        self.realtime_policy
11962    }
11963
11964    /// §8.8: the explicit realtime availability state.
11965    #[must_use]
11966    pub fn realtime_state(&self) -> RealtimeState {
11967        self.realtime_state
11968    }
11969
11970    /// §8.8: set the realtime policy. Refused while the socket is connected:
11971    /// a policy change never silently re-routes an ownership state.
11972    pub fn set_realtime_policy(&mut self, policy: RealtimePolicy) -> Result<(), String> {
11973        if self.realtime_state == RealtimeState::Connected && policy != self.realtime_policy {
11974            return Err(
11975                "sync.invalid_request: disconnect realtime before changing the realtime policy"
11976                    .to_owned(),
11977            );
11978        }
11979        self.realtime_policy = policy;
11980        match policy {
11981            RealtimePolicy::Off => self.set_realtime_state(RealtimeState::Disabled, None),
11982            RealtimePolicy::Required | RealtimePolicy::Optional
11983                if self.realtime_state == RealtimeState::Disabled =>
11984            {
11985                self.set_realtime_state(RealtimeState::Disconnected, None);
11986            }
11987            RealtimePolicy::Required | RealtimePolicy::Optional => {}
11988        }
11989        Ok(())
11990    }
11991
11992    /// Record an availability transition, keeping the reason code bounded and
11993    /// code-like (§7.6) and clearing it where it cannot apply.
11994    fn set_realtime_state(&mut self, state: RealtimeState, reason_code: Option<&str>) {
11995        self.realtime_state = state;
11996        self.realtime_reason_code = reason_code.map(Self::diagnostic_code);
11997        if matches!(state, RealtimeState::Connected | RealtimeState::Disabled) {
11998            self.realtime_reason_code = None;
11999            self.realtime_retry_delay_ms = None;
12000        }
12001    }
12002
12003    #[must_use]
12004    fn realtime_connected(&self) -> bool {
12005        self.realtime_state == RealtimeState::Connected
12006    }
12007
12008    pub fn connect_realtime(&mut self, transport: &mut dyn Transport) -> Result<(), String> {
12009        if !self.transport_enabled {
12010            return Err("sync.offline: transport gate is closed".into());
12011        }
12012        if self.realtime_policy == RealtimePolicy::Off {
12013            return Err(
12014                "sync.invalid_request: realtime is off; realtime connect is refused".to_owned(),
12015            );
12016        }
12017        if self.realtime_connected() {
12018            return Ok(());
12019        }
12020        self.realtime_state = RealtimeState::Connecting;
12021        match transport.realtime_connect_for_client(&self.client_id) {
12022            Ok(()) => {
12023                self.set_realtime_state(RealtimeState::Connected, None);
12024                Ok(())
12025            }
12026            Err(error) => {
12027                self.set_realtime_state(RealtimeState::Refused, Some(&error.code));
12028                Err(format!("{}: {}", error.code, error.message))
12029            }
12030        }
12031    }
12032
12033    pub fn disconnect_realtime(&mut self, transport: &mut dyn Transport) {
12034        self.cancel_sync_round();
12035        // A deliberately disconnected or policy-disabled client has nothing
12036        // to release; a `lost` socket still does (the host owns the handle).
12037        if self.realtime_state == RealtimeState::Disconnected
12038            || self.realtime_state == RealtimeState::Disabled
12039        {
12040            return;
12041        }
12042        let _ = transport.realtime_close();
12043        self.set_realtime_state(
12044            if self.realtime_policy == RealtimePolicy::Off {
12045                RealtimeState::Disabled
12046            } else {
12047                RealtimeState::Disconnected
12048            },
12049            None,
12050        );
12051        self.presence.clear(); // §8.6.1: presence is per-connection
12052    }
12053
12054    /// §8.8: the host observed the socket end without disconnecting it (a
12055    /// peer close, an I/O error, a failed send; the native transport reports
12056    /// these as `Inbound::Disconnected`). Releases the transport, moves a
12057    /// `Connected` state to `Lost` with the transport's code as the reason, and schedules
12058    /// one background retry intent so the host reconnects and catches up.
12059    pub fn realtime_lost(&mut self, transport: &mut dyn Transport, error: &TransportError) {
12060        if self.realtime_state != RealtimeState::Connected {
12061            return;
12062        }
12063        self.cancel_sync_round();
12064        let _ = transport.realtime_close();
12065        self.set_realtime_state(RealtimeState::Lost, Some(&error.code));
12066        self.realtime_retry_delay_ms = Some(self.schedule_background_retry());
12067        self.presence.clear();
12068    }
12069
12070    /// §8.6.2: publish (or clear, `doc: None`) this client's presence
12071    /// document for `scope_key`. Requires a live socket; the document is
12072    /// ephemeral (lost on disconnect). Authorization is the connection's
12073    /// registration (§8.6.3) — an unheld key is rejected loudly by the
12074    /// server with `presence.forbidden`.
12075    pub fn set_presence(
12076        &mut self,
12077        transport: &mut dyn Transport,
12078        scope_key: &str,
12079        doc: Option<&Value>,
12080    ) -> Result<(), String> {
12081        if !self.transport_enabled {
12082            return Err("sync.offline: transport gate is closed".into());
12083        }
12084        if !self.realtime_connected() {
12085            return Err("setPresence requires a connected realtime socket (§8.6)".to_string());
12086        }
12087        let text = encode_presence_publish(scope_key, doc);
12088        transport
12089            .realtime_send(&text)
12090            .map_err(|e| format!("{}: {}", e.code, e.message))
12091    }
12092
12093    /// §8.6: the peers currently present on a scope key (ephemeral).
12094    pub fn presence(&self, scope_key: &str) -> Vec<PresencePeer> {
12095        self.presence
12096            .get(scope_key)
12097            .map(|peers| peers.values().cloned().collect())
12098            .unwrap_or_default()
12099    }
12100
12101    /// §8.6 apply an inbound presence fanout to the local map.
12102    fn apply_presence(
12103        &mut self,
12104        scope_key: String,
12105        kind: Option<PresenceKind>,
12106        actor_id: Option<String>,
12107        client_id: Option<String>,
12108        doc: Option<Value>,
12109        error: Option<String>,
12110    ) {
12111        // A refused publish (§8.6.2) changes no peer; the native host surfaces
12112        // it as a `presence` event carrying the server's `error` code.
12113        if error.is_some() {
12114            return;
12115        }
12116        let (Some(kind), Some(actor_id), Some(client_id)) = (kind, actor_id, client_id) else {
12117            return;
12118        };
12119        let peer_key = format!("{actor_id} {client_id}");
12120        match kind {
12121            PresenceKind::Leave => {
12122                if let Some(peers) = self.presence.get_mut(&scope_key) {
12123                    peers.remove(&peer_key);
12124                    if peers.is_empty() {
12125                        self.presence.remove(&scope_key);
12126                    }
12127                }
12128            }
12129            _ => {
12130                let doc = match doc {
12131                    Some(Value::Object(_)) => doc.unwrap(),
12132                    _ => return,
12133                };
12134                self.presence.entry(scope_key).or_default().insert(
12135                    peer_key,
12136                    PresencePeer {
12137                        actor_id,
12138                        client_id,
12139                        doc,
12140                    },
12141                );
12142            }
12143        }
12144    }
12145
12146    /// Inbound JSON control message (§8.1). Unknown events are tolerated.
12147    pub fn on_realtime_text(&mut self, text: &str) {
12148        if self.stopped || !self.transport_enabled || self.security_preflight {
12149            return;
12150        }
12151        match parse_control(text) {
12152            Ok(ControlMessage::Hello { requires_sync, .. }) => {
12153                if requires_sync {
12154                    // §8.1: pull before trusting the socket for continuity.
12155                    self.set_sync_needed(true, true);
12156                }
12157            }
12158            Ok(ControlMessage::Presence {
12159                scope_key,
12160                kind,
12161                actor_id,
12162                client_id,
12163                doc,
12164                error,
12165                ..
12166            }) => {
12167                self.apply_presence(scope_key, kind, actor_id, client_id, doc, error);
12168            }
12169            Ok(ControlMessage::Wake { .. }) => {
12170                // §8.3: any wake-up means "run a pull soon", never data.
12171                self.set_sync_needed(true, true);
12172            }
12173            _ => {}
12174        }
12175    }
12176
12177    /// Inbound binary delta: a complete SSP2 response (§8.2), applied like
12178    /// a pull response per section; an unapplied delta is a wake-up.
12179    /// Mailbox hosts send durable acknowledgements on their I/O executor.
12180    pub fn on_realtime_binary_queued(&mut self, bytes: &[u8]) -> Vec<String> {
12181        let mut transport = crate::round::DownloadResults::default();
12182        self.on_realtime_binary(&mut transport, bytes);
12183        transport.controls
12184    }
12185
12186    /// §8.2: a delta applies exactly like a live section and sets the replica
12187    /// cursor to its `throughSeq`; one at or below the replica cursor is a
12188    /// duplicate. A delta the client does not apply (no live unit, a status
12189    /// other than `active`, a decode or apply failure) is a drop and raises
12190    /// sync-needed.
12191    pub fn on_realtime_binary(&mut self, transport: &mut dyn Transport, bytes: &[u8]) {
12192        if self.stopped || !self.transport_enabled || self.security_preflight {
12193            return;
12194        }
12195        #[cfg(feature = "bench-internals")]
12196        let decode_phase = self.benchmark_phases.start(Phase::ResponseDecode);
12197        let message = match decode_message(bytes) {
12198            Ok(m) if m.msg_kind == MsgKind::Response => m,
12199            _ => {
12200                self.set_sync_needed(true, true);
12201                return;
12202            }
12203        };
12204        #[cfg(feature = "bench-internals")]
12205        drop(decode_phase);
12206        // §8.2: a delta's header means what a pull response's header means. A
12207        // schema floor (§1.6) is recorded, stops syncing and applies nothing.
12208        if let Some(Frame::RespHeader {
12209            required_schema_version: Some(required),
12210            latest_schema_version,
12211            ..
12212        }) = message.frames.first()
12213        {
12214            let floor = SchemaFloor {
12215                required_schema_version: Some(*required),
12216                latest_schema_version: *latest_schema_version,
12217            };
12218            if self.set_schema_floor(Some(floor)).is_err() {
12219                self.set_sync_needed(true, true);
12220            }
12221            return;
12222        }
12223        let through = message.frames.iter().find_map(|frame| match frame {
12224            Frame::LiveEnd { through_seq, .. } => Some(*through_seq),
12225            _ => None,
12226        });
12227        let epoch = self.get_meta(LOG_EPOCH_KEY).ok().flatten();
12228        let mut dropped = !matches!(message.frames.first(), Some(Frame::RespHeader {
12229                reset_required: false,
12230                log_epoch,
12231                ..
12232            }) if Some(log_epoch) == epoch.as_ref());
12233        let mut applied: Option<i64> = None;
12234        dropped |= self.begin_coalesced_apply().is_err();
12235        let mut receivers: Option<Vec<UnitRecord>> = None;
12236        for frame in message.frames {
12237            if dropped {
12238                break;
12239            }
12240            match frame {
12241                Frame::LiveStart { status, .. } => {
12242                    let Ok(cursor) = self.stored(replica_cursor(&self.conn)) else {
12243                        dropped = true;
12244                        break;
12245                    };
12246                    if status != LiveStatus::Active || cursor < 0 {
12247                        dropped = true;
12248                    } else if !through.is_some_and(|through| through <= cursor) {
12249                        // A catching-up unit receives no delta (§8.2).
12250                        receivers = self.stored(load_units(&self.conn)).ok().map(|units| {
12251                            units
12252                                .into_iter()
12253                                .filter(|unit| {
12254                                    unit.status == UnitStatus::Active
12255                                        && unit.echo.is_some()
12256                                        && unit.cursor.is_none()
12257                                })
12258                                .collect()
12259                        });
12260                        dropped = receivers.is_none();
12261                    }
12262                }
12263                Frame::Commit {
12264                    commit_seq,
12265                    tables,
12266                    changes,
12267                    ..
12268                } => {
12269                    let Some(receivers) = receivers.clone() else {
12270                        continue;
12271                    };
12272                    dropped = self
12273                        .apply_live_commit(
12274                            &receivers,
12275                            &tables,
12276                            changes,
12277                            commit_seq,
12278                            AppliedServerCommitSource::Delta,
12279                        )
12280                        .is_err();
12281                }
12282                Frame::LiveEnd { through_seq, .. } if receivers.is_some() => {
12283                    dropped = self
12284                        .set_meta(REPLICA_CURSOR_KEY, &through_seq.to_string())
12285                        .is_err();
12286                    applied = Some(through_seq);
12287                }
12288                Frame::Error { .. } => dropped = true,
12289                _ => {}
12290            }
12291        }
12292        // §1.4 rule 4: the ack follows the COMMIT. A failed COMMIT restored
12293        // the replica cursor, so the delta counts as a drop.
12294        if self.finish_coalesced_apply().is_err() || dropped {
12295            applied = None;
12296            dropped = true;
12297        }
12298        if let Some(cursor) = applied {
12299            // §8.2 ack point: the delta's throughSeq.
12300            let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
12301            let _ = transport.realtime_send(&ack);
12302        }
12303        if dropped {
12304            self.set_sync_needed(true, true);
12305        }
12306    }
12307
12308    /// §8.2 ack point after a pull round on a live connection: the replica
12309    /// cursor while it is at least `0`.
12310    fn ack_after_pull(&mut self, transport: &mut dyn Transport) {
12311        if !self.realtime_connected() {
12312            return;
12313        }
12314        if let Ok(cursor @ 0..) = self.stored(replica_cursor(&self.conn)) {
12315            let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
12316            let _ = transport.realtime_send(&ack);
12317        }
12318    }
12319}
12320
12321#[cfg(test)]
12322mod previous_version_wiring_tests;
12323
12324#[cfg(test)]
12325mod identity_tests;
12326
12327#[cfg(test)]
12328mod insert_intent_tests;
12329
12330#[cfg(test)]
12331mod robustness_tests;