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    /// §5.5: the server refused a segment with `sync.forbidden`.
353    Refused,
354    Abort(String, String),
355    Transport(TransportError),
356}
357
358#[derive(Debug)]
359pub(crate) struct RequestMeta {
360    pushed_ids: Vec<String>,
361    /// Hex of the registration digest this pull carried; the server stores
362    /// that list once the round completes (§4.1).
363    registration_digest: String,
364    pub(crate) accept: u8,
365    /// §6.1 splitBatch: outbox commits held back from THIS request because
366    /// the running operation count reached the push cap — the next round
367    /// pushes them (`sync_needed` stays set while any remain).
368    deferred_commits: usize,
369}
370
371#[derive(Default)]
372struct ChangeAccumulator {
373    /// None means table-wide; Some is the exact scoped domain.
374    tables: BTreeMap<String, Option<BTreeSet<String>>>,
375    windows: BTreeMap<String, BTreeSet<String>>,
376    status: bool,
377    conflicts: bool,
378    rejections: bool,
379    outcomes: bool,
380}
381
382impl ChangeAccumulator {
383    fn table(&mut self, table: &str) {
384        self.tables.insert(table.to_owned(), None);
385    }
386
387    fn scope(&mut self, table: &str, key: String) {
388        match self.tables.get_mut(table) {
389            Some(None) => {}
390            Some(Some(keys)) => {
391                keys.insert(key);
392            }
393            None => {
394                self.tables
395                    .insert(table.to_owned(), Some(BTreeSet::from([key])));
396            }
397        }
398    }
399
400    fn window(&mut self, base_key: &str, value: &str) {
401        self.windows
402            .entry(base_key.to_owned())
403            .or_default()
404            .insert(value.to_owned());
405    }
406
407    fn touched(&self) -> bool {
408        !self.tables.is_empty()
409            || !self.windows.is_empty()
410            || self.status
411            || self.conflicts
412            || self.rejections
413            || self.outcomes
414    }
415}
416
417/// §6.1: the server caps total operations per request (reference default
418/// 500) and rejects the whole batch with `sync.too_many_operations`; the
419/// client "splits and retries". Splitting happens at build time: commits are
420/// included IN ORDER until the operation budget is spent, the rest wait for
421/// the next round.
422const PUSH_OPS_PER_REQUEST: usize = 500;
423const MAX_LOCAL_PURGE_TARGETS: usize = 64;
424const MAX_LOCAL_PURGE_SELECTORS: usize = 8;
425const MAX_LOCAL_PURGE_VALUES: usize = 128;
426const MAX_LOCAL_PURGE_VALUE_LENGTH: usize = 256;
427pub const SECURITY_PREFLIGHT_REQUIRED_CODE: &str = "client.security_preflight_required";
428
429/// Dirty visible tables; `None` means a whole-replica recovery/reset.
430struct OverlayDirty(RefCell<Option<BTreeSet<String>>>);
431
432impl OverlayDirty {
433    fn clean() -> Self {
434        Self(RefCell::new(Some(BTreeSet::new())))
435    }
436    fn get(&self) -> bool {
437        self.0
438            .borrow()
439            .as_ref()
440            .is_none_or(|tables| !tables.is_empty())
441    }
442    fn set(&self, dirty: bool) {
443        *self.0.borrow_mut() = if dirty { None } else { Some(BTreeSet::new()) };
444    }
445    fn table(&self, table: &str) {
446        if let Some(tables) = self.0.borrow_mut().as_mut() {
447            tables.insert(table.to_owned());
448        }
449    }
450    fn snapshot(&self) -> Option<BTreeSet<String>> {
451        self.0.borrow().clone()
452    }
453    fn restore(&self, tables: Option<BTreeSet<String>>) {
454        *self.0.borrow_mut() = tables;
455    }
456}
457
458/// A copy-on-write in-memory mirror: a [`Rollback`] shares it, and the first
459/// write after a capture copies it once.
460#[derive(Debug, Clone, Default)]
461struct Shared<T>(Arc<T>);
462
463impl<T> std::ops::Deref for Shared<T> {
464    type Target = T;
465    fn deref(&self) -> &T {
466        &self.0
467    }
468}
469
470impl<T: Clone> std::ops::DerefMut for Shared<T> {
471    fn deref_mut(&mut self) -> &mut T {
472        Arc::make_mut(&mut self.0)
473    }
474}
475
476impl<T> From<T> for Shared<T> {
477    fn from(value: T) -> Self {
478        Self(Arc::new(value))
479    }
480}
481
482/// The in-memory mirrors of durable state, captured before a local
483/// transaction and restored when it rolls back. Queues only grow inside a
484/// transaction, so their lengths suffice.
485#[derive(Debug, Clone)]
486struct Rollback {
487    outbox: Shared<Vec<Arc<OutboxCommit>>>,
488    failed_commits: Shared<Vec<FailedCommit>>,
489    conflicts: Shared<Vec<ConflictRecord>>,
490    rejections: Shared<Vec<RejectionRecord>>,
491    schema_floor: Option<SchemaFloor>,
492    lease_state: Option<LeaseState>,
493    stopped: bool,
494    upgrading: bool,
495    sync_needed: bool,
496    active_round: Option<uuid::Uuid>,
497    overlay_dirty: Option<BTreeSet<String>>,
498    change_queue: usize,
499    sync_intent_queue: usize,
500    last_change: Option<DiagnosticLastChange>,
501}
502
503pub struct SyncClient {
504    #[cfg(feature = "bench-internals")]
505    benchmark_phases: Recorder,
506    conn: Connection,
507    schema: ClientSchema,
508    client_id: String,
509    limits: ClientLimits,
510    outbox: Shared<Vec<Arc<OutboxCommit>>>,
511    failed_commits: Shared<Vec<FailedCommit>>,
512    retain_failed_commits: bool,
513    conflicts: Shared<Vec<ConflictRecord>>,
514    rejections: Shared<Vec<RejectionRecord>>,
515    schema_floor: Option<SchemaFloor>,
516    /// §7.3.5: the opaque auth-lease state (from LEASE frames + lease errors).
517    lease_state: Option<LeaseState>,
518    /// §1.6: the schema-floor response stops syncing until an upgrade.
519    stopped: bool,
520    /// §7.4.5: true while a schema-bump reset + first re-bootstrap is in flight.
521    upgrading: bool,
522    /// §8.4 coalesced sync-needed signal.
523    sync_needed: bool,
524    /// §8.8: how sync rounds treat the realtime binding, and its exact
525    /// availability state with the evidence behind a lost or refused one.
526    realtime_policy: RealtimePolicy,
527    realtime_state: RealtimeState,
528    realtime_reason_code: Option<String>,
529    realtime_retry_delay_ms: Option<u64>,
530    /// §8.6 presence: scopeKey → (`actorId clientId` peer key → peer).
531    presence: HashMap<String, HashMap<String, PresencePeer>>,
532    /// Client clock (epoch ms) for the §5.4 `urlExpiresAtMs` check; the
533    /// host may pin it (conformance runs on a virtual clock).
534    now_ms: Option<i64>,
535    /// §5.11 client-side encryption keys (`keyId → key bytes`). Empty ⇒ E2EE
536    /// off. The encrypt/decrypt seam (`values.rs`) is compiled only under the
537    /// `e2ee` feature; without it, a schema with encrypted columns fails loud.
538    encryption: crate::values::EncryptionConfig,
539    /// Fail-closed host bootstrap gate. While set, command hosts permit only
540    /// status/lifecycle inspection and an exact authorized local purge.
541    security_preflight: bool,
542    security_epoch: u64,
543    transport_enabled: bool,
544    transport_epoch: u64,
545    /// Raised by every registration change; a current-base proof spanning
546    /// one reports missing coverage.
547    registration_epoch: u64,
548    /// RFC 0005 D2/D8: the previous-version capture config. `None` (default)
549    /// means the feature is off; the descriptor write and the container orphan
550    /// sweep still happen.
551    previous_version: Option<PreviousVersionContextConfig>,
552    /// Per-table primary-key upsert SQL, built once per (full table name) —
553    /// the row write path runs per row during bootstrap (§5.6), so the SQL
554    /// string (and, via `prepare_cached`, its compiled statement) is reused
555    /// instead of being rebuilt and re-prepared per row. Cleared on a §7.4.3
556    /// schema reset (the column lists may have changed).
557    insert_sql: RefCell<HashMap<String, String>>,
558    /// §7.1: reconcile only tables whose base/outbox changed. Whole-replica
559    /// reset and restart explicitly invalidate every table.
560    overlay_dirty: OverlayDirty,
561    // First SQLite failure of the current operation, before savepoint cleanup.
562    storage_failure: RefCell<Option<QueryReadFailure>>,
563    /// Test-only structural performance signal: response processing must not
564    /// turn a batch of acknowledgements into one full overlay rebuild each.
565    #[cfg(test)]
566    overlay_rebuild_count: Cell<usize>,
567    #[cfg(test)]
568    acknowledged_replay_count: Cell<usize>,
569    /// Test-only structural performance signal: outcome retention is enforced
570    /// once per response rather than once per acknowledgement.
571    #[cfg(test)]
572    outcome_prune_count: Cell<usize>,
573    /// Exact observer-transaction output drained by command/FFI hosts.
574    progress: ProgressObserver,
575    change_queue: VecDeque<ClientChangeBatch>,
576    sync_intent_queue: VecDeque<SyncIntent>,
577    /// Explicit exponential retry policy for transient transport failures.
578    retry_delay_ms: u64,
579    /// §7.7: the background retry the current round scheduled, if any.
580    round_retry_delay_ms: Option<u64>,
581    /// A round whose response never completed (§1.5): the client keeps its
582    /// code and reports it on every following request until a round receives a
583    /// complete, decodable response. The server already recorded the round, so
584    /// nothing else can tell it the round failed on this side.
585    round_failure: Option<String>,
586    active_round: Option<uuid::Uuid>,
587    last_round: Option<DiagnosticLastRound>,
588    last_change: Option<DiagnosticLastChange>,
589    /// §7.6: latest failed owned snapshot read per owner id, oldest first.
590    query_failures: Vec<DiagnosticQueryFailure>,
591    /// SPEC §1.4 rule 4: the open coalesced apply transaction of a response.
592    coalesced: Option<CoalescedApply>,
593    /// A coalesced apply transaction of the current response failed; every
594    /// later observation of that response fails until it ends.
595    coalesced_failure: Option<String>,
596}
597
598/// SPEC §1.4 rule 4: the frames and blocks of one response share one local
599/// write transaction of at most `COALESCED_APPLY_ROWS` rows. The in-memory
600/// state captured at its `BEGIN` is restored when its `COMMIT` fails.
601struct CoalescedApply {
602    rows: usize,
603    rollback: Rollback,
604}
605
606const COALESCED_APPLY_ROWS: usize = 1024;
607
608pub(crate) fn quote_ident(name: &str) -> String {
609    format!("\"{}\"", name.replace('"', "\"\""))
610}
611/// §7.4.1 `_syncular_meta` helpers. Free functions so RFC 0005's
612/// previous-version module reads and writes the SAME records as the client
613/// instead of growing a parallel meta layer.
614pub(crate) fn meta_get(conn: &Connection, key: &str) -> rusqlite::Result<Option<String>> {
615    conn.query_row(
616        "SELECT value FROM _syncular_meta WHERE key = ?1",
617        rusqlite::params![key],
618        |row| row.get::<_, String>(0),
619    )
620    .optional()
621}
622
623pub(crate) fn meta_set(conn: &Connection, key: &str, value: &str) -> rusqlite::Result<()> {
624    conn.execute(
625        "INSERT OR REPLACE INTO _syncular_meta (key, value) VALUES (?1, ?2)",
626        rusqlite::params![key, value],
627    )
628    .map(|_| ())
629}
630
631pub(crate) fn meta_delete(conn: &Connection, key: &str) -> rusqlite::Result<()> {
632    conn.execute(
633        "DELETE FROM _syncular_meta WHERE key = ?1",
634        rusqlite::params![key],
635    )
636    .map(|_| ())
637}
638
639/// Seek by the existing key while retaining the exact legacy text match.
640fn row_id_predicate(table: &TableSchema) -> String {
641    let key = quote_ident(&table.primary_key);
642    let text_match = format!("CAST({key} AS TEXT) = ?1");
643    match table.columns[table.pk_index].ty {
644        ColumnType::String | ColumnType::Json => {
645            format!("{key} = ?1 AND {text_match}")
646        }
647        // Native columns have no declared SQLite affinity. Match the stored
648        // integer bind type explicitly. Unary + removes expression affinity so
649        // SQLite can seek the typeless key; the text check preserves exact IDs.
650        ColumnType::Integer | ColumnType::Boolean => {
651            format!("{key} = +CAST(?1 AS INTEGER) AND {text_match}")
652        }
653        // REAL-to-text conversion can round distinct values to the same text.
654        // Narrowing those matches by numeric equality would change behavior.
655        _ => text_match,
656    }
657}
658
659/// §3.3/§4.8/§5.6 row ownership: rows whose local scope columns match
660/// `effective` and that no entry of `owners` matches. `owners` holds the
661/// pair scopes of every owner of the table (§3.3 row ownership); a scoped delete never removes a row one of them still covers.
662/// Scope values bind by the column's declared type, as `row_id_predicate`
663/// does. `Ok(None)` matches nothing (an empty map or value list); `Err(())`
664/// is a missing local scope-column mapping (the fail-closed case).
665fn local_scope_predicate(
666    table: &TableSchema,
667    effective: &[(String, Vec<String>)],
668    owners: &[Vec<(String, Vec<String>)>],
669) -> Result<Option<(String, Vec<SqlValue>)>, ()> {
670    if effective.is_empty() || effective.iter().any(|(_, values)| values.is_empty()) {
671        return Ok(None);
672    }
673    let column = |variable: &str| {
674        let name = table.scope_column(variable).ok_or(())?;
675        let column = table
676            .columns
677            .iter()
678            .find(|column| column.name == name)
679            .ok_or(())?;
680        Ok((quote_ident(name), column.ty == ColumnType::Integer))
681    };
682    let mut clauses = Vec::new();
683    let mut params = Vec::new();
684    for (variable, values) in effective {
685        let (key, integer) = column(variable)?;
686        let holes = vec!["?"; values.len()].join(", ");
687        clauses.push(if integer {
688            params.extend(values.iter().cloned().map(SqlValue::Text));
689            let seek = vec!["+CAST(? AS INTEGER)"; values.len()].join(", ");
690            format!("{key} IN ({seek}) AND CAST({key} AS TEXT) IN ({holes})")
691        } else {
692            format!("{key} IN ({holes})")
693        });
694        params.extend(values.iter().cloned().map(SqlValue::Text));
695    }
696    // Owners bind as one JSON parameter per variable set, so the statement
697    // keeps its size at any owner count; owners of one variable bind the
698    // union of their values. An owner holding other values of a variable
699    // `effective` names owns none of its rows and drops out. Values compare
700    // as text, the exact semantics of the effective clauses.
701    let mut groups: BTreeMap<Vec<&str>, Vec<Vec<&[String]>>> = BTreeMap::new();
702    for owner in owners {
703        if owner.is_empty()
704            || owner.iter().any(|(variable, values)| {
705                values.is_empty()
706                    || effective.iter().any(|(name, wanted)| {
707                        name == variable && wanted.iter().all(|value| !values.contains(value))
708                    })
709            })
710        {
711            continue;
712        }
713        let mut owner: Vec<_> = owner.iter().collect();
714        owner.sort_by(|a, b| a.0.cmp(&b.0));
715        groups
716            .entry(
717                owner
718                    .iter()
719                    .map(|(variable, _)| variable.as_str())
720                    .collect(),
721            )
722            .or_default()
723            .push(owner.iter().map(|(_, values)| values.as_slice()).collect());
724    }
725    let within = |variable: &str, list: &str| {
726        let (key, integer) = column(variable)?;
727        let key = if integer {
728            format!("CAST({key} AS TEXT)")
729        } else {
730            key
731        };
732        Ok(format!("{key} IN (SELECT value FROM json_each({list}))"))
733    };
734    for (variables, tuples) in groups {
735        if let [variable] = variables[..] {
736            let values: BTreeSet<&String> = tuples.iter().flatten().copied().flatten().collect();
737            params.push(SqlValue::Text(
738                Value::from_iter(values.into_iter().cloned()).to_string(),
739            ));
740            clauses.push(format!("NOT {}", within(variable, "?")?));
741        } else {
742            params.push(SqlValue::Text(
743                serde_json::to_string(&tuples).expect("owner tuples serialize"),
744            ));
745            let matches = variables
746                .iter()
747                .enumerate()
748                .map(|(index, variable)| within(variable, &format!("o.value,'$[{index}]'")))
749                .collect::<Result<Vec<_>, ()>>()?;
750            clauses.push(format!(
751                "NOT EXISTS (SELECT 1 FROM json_each(?) o WHERE {})",
752                matches.join(" AND ")
753            ));
754        }
755    }
756    Ok(Some((clauses.join(" AND "), params)))
757}
758
759/// [`local_scope_predicate`] over decoded row values (retained rows).
760fn owns_local_row(
761    table: &TableSchema,
762    effective: &[(String, Vec<String>)],
763    owners: &[Vec<(String, Vec<String>)>],
764    values: &Map<String, Value>,
765) -> bool {
766    let matches = |scopes: &[(String, Vec<String>)]| {
767        !scopes.is_empty()
768            && scopes.iter().all(|(variable, allowed)| {
769                table
770                    .scope_column(variable)
771                    .and_then(|column| values.get(column))
772                    .filter(|value| !value.is_null())
773                    .is_some_and(|value| {
774                        allowed.contains(
775                            &value
776                                .as_str()
777                                .map_or_else(|| value.to_string(), str::to_owned),
778                        )
779                    })
780            })
781    };
782    matches(effective) && !owners.iter().any(|owner| matches(owner))
783}
784
785fn is_local_operation_code_like(value: &str) -> bool {
786    let bytes = value.as_bytes();
787    bytes.first().is_some_and(u8::is_ascii_alphanumeric)
788        && bytes
789            .iter()
790            .all(|byte| byte.is_ascii_alphanumeric() || matches!(*byte, b'.' | b'_' | b':' | b'-'))
791}
792
793fn base_table(name: &str) -> String {
794    quote_ident(&format!("_syncular_base_{name}"))
795}
796
797/// §4.8 deferred eviction record: (unit id, table, effective scope map).
798type PendingEvict = (String, String, Vec<(String, Vec<String>)>);
799
800/// §4.8: a stable key for a window base: variable + canonical fixed scopes.
801fn window_base_key(base: &WindowBase) -> String {
802    format!(
803        "{}\0{}",
804        base.variable,
805        ssp2::registration::canonical_unit_json(&scope_pairs(&base.fixed_scopes))
806    )
807}
808
809/// The unit of one window value: the fixed scopes plus the value.
810fn window_unit_scopes(base: &WindowBase, value: &str) -> UnitScopes {
811    let mut scopes = base.fixed_scopes.clone();
812    scopes.insert(base.variable.clone(), value.to_owned());
813    scopes
814}
815
816/// A unit's scope map as the codec and the digests take it.
817fn scope_pairs(scopes: &UnitScopes) -> Vec<(String, String)> {
818    let mut pairs: Vec<(String, String)> = scopes
819        .iter()
820        .map(|(variable, value)| (variable.clone(), value.clone()))
821        .collect();
822    pairs.sort_by(|a, b| a.0.encode_utf16().cmp(b.0.encode_utf16()));
823    pairs
824}
825
826/// §4.1: the unit covers every table declaring all of its variables.
827fn covers(table: &TableSchema, scopes: &UnitScopes) -> bool {
828    scopes
829        .keys()
830        .all(|variable| table.scope_column(variable).is_some())
831}
832
833/// §4.4: the effective scopes of the (unit, table) pair under `echo`: the
834/// scope map as one-element lists plus the fenced lists. `None` when the
835/// fence revoked the pair.
836fn pair_scopes(
837    scopes: &UnitScopes,
838    table: &str,
839    echo: Option<&[EchoRecord]>,
840) -> Option<Vec<(String, Vec<String>)>> {
841    let fenced = echo.and_then(|echo| echo.iter().find(|record| record.table == table));
842    if fenced.is_some_and(|record| record.status == "revoked") {
843        return None;
844    }
845    let mut effective: BTreeMap<String, Vec<String>> = fenced
846        .map(|record| record.scopes.clone())
847        .unwrap_or_default();
848    for (variable, value) in scopes {
849        effective.insert(variable.clone(), vec![value.clone()]);
850    }
851    Some(effective.into_iter().collect())
852}
853
854/// §3.3 row ownership: the pair scopes of every owner of `table` except
855/// `except_id`. An owner is active with a persisted echo and live or
856/// post-bootstrap, or bootstrapping with a segment of the table in its
857/// current bootstrap.
858fn unit_owners(
859    units: &[UnitRecord],
860    table: &TableSchema,
861    except_id: &str,
862) -> Vec<Vec<(String, Vec<String>)>> {
863    units
864        .iter()
865        .filter(|unit| {
866            unit.id != except_id
867                && unit.status == UnitStatus::Active
868                && unit.echo.is_some()
869                && (!unit.bootstrapping() || unit.seeded.contains(&table.name))
870                && covers(table, &unit.scopes)
871        })
872        .filter_map(|unit| pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()))
873        .collect()
874}
875
876/// §5.5 / §5.6: the unit's scope map, each value a one-element list.
877fn unit_scope_lists(scopes: &UnitScopes) -> Vec<(String, Vec<String>)> {
878    scopes
879        .iter()
880        .map(|(variable, value)| (variable.clone(), vec![value.clone()]))
881        .collect()
882}
883
884/// §7.1 acknowledged intent of the rows `?1` names (`[[table, id], ...]`).
885/// It joins through the (tbl, id) index: a scan per acknowledgement would
886/// make draining a batch quadratic.
887const 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";
888
889const UNIT_COLUMNS: &str =
890    "id, scopes, explicit, status, reason_code, cursor, bootstrap_state, seeded, echo";
891
892/// A unit row; a field that does not parse is a conversion failure, which
893/// both read paths classify as `sync.local_corrupt`.
894fn unit_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<UnitRecord> {
895    fn json<T: serde::de::DeserializeOwned>(index: usize, raw: &str) -> rusqlite::Result<T> {
896        serde_json::from_str(raw).map_err(|error| {
897            rusqlite::Error::FromSqlConversionFailure(
898                index,
899                rusqlite::types::Type::Text,
900                Box::new(error),
901            )
902        })
903    }
904    Ok(UnitRecord {
905        id: row.get(0)?,
906        scopes: json(1, &row.get::<_, String>(1)?)?,
907        explicit: row.get::<_, i64>(2)? == 1,
908        status: json(
909            3,
910            &serde_json::to_string(&row.get::<_, String>(3)?).expect("text"),
911        )?,
912        reason_code: row.get(4)?,
913        cursor: row.get(5)?,
914        bootstrap_state: row.get(6)?,
915        seeded: json(7, &row.get::<_, String>(7)?)?,
916        echo: row
917            .get::<_, Option<String>>(8)?
918            .map(|echo| json::<Vec<EchoRecord>>(8, &echo))
919            .transpose()?
920            .map(|echo| {
921                if echo
922                    .iter()
923                    .all(|record| record.status == "active" || record.status == "revoked")
924                {
925                    Ok(echo)
926                } else {
927                    Err(rusqlite::Error::FromSqlConversionFailure(
928                        8,
929                        rusqlite::types::Type::Text,
930                        "echo status is neither active nor revoked".into(),
931                    ))
932                }
933            })
934            .transpose()?,
935    })
936}
937
938/// Every unit in registration order (§4.1).
939fn load_units(conn: &Connection) -> rusqlite::Result<Vec<UnitRecord>> {
940    conn.prepare_cached(&format!(
941        "SELECT {UNIT_COLUMNS} FROM _syncular_units ORDER BY rowid"
942    ))?
943    .query_map([], unit_from_row)?
944    .collect()
945}
946
947fn get_unit(conn: &Connection, id: &str) -> rusqlite::Result<Option<UnitRecord>> {
948    conn.query_row(
949        &format!("SELECT {UNIT_COLUMNS} FROM _syncular_units WHERE id = ?1"),
950        [id],
951        unit_from_row,
952    )
953    .optional()
954}
955
956/// Insert or update in place: an update keeps the registration order.
957fn save_unit(conn: &Connection, unit: &UnitRecord) -> rusqlite::Result<()> {
958    conn.prepare_cached(&format!(
959        "INSERT INTO _syncular_units({UNIT_COLUMNS}) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9)
960         ON CONFLICT(id) DO UPDATE SET explicit=excluded.explicit, status=excluded.status,
961           reason_code=excluded.reason_code, cursor=excluded.cursor,
962           bootstrap_state=excluded.bootstrap_state, seeded=excluded.seeded, echo=excluded.echo"
963    ))?
964    .execute(rusqlite::params![
965        unit.id,
966        serde_json::to_string(&unit.scopes).expect("scope map serializes"),
967        i64::from(unit.explicit),
968        unit.status.name(),
969        unit.reason_code,
970        unit.cursor,
971        unit.bootstrap_state,
972        serde_json::to_string(&unit.seeded).expect("table list serializes"),
973        unit.echo
974            .as_ref()
975            .map(|echo| serde_json::to_string(echo).expect("echo serializes")),
976    ])
977    .map(|_| ())
978}
979
980/// §4.1 references: every window registry entry `(base, value)` holding a unit.
981fn window_refs(conn: &Connection, unit_id: &str) -> rusqlite::Result<Vec<(String, String)>> {
982    conn.prepare_cached("SELECT base, unit FROM _syncular_windows WHERE sub_id = ?1")?
983        .query_map([unit_id], |row| Ok((row.get(0)?, row.get(1)?)))?
984        .collect()
985}
986
987/// §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
988/// registrations and discard every synced state, so the next round sends the
989/// list and fresh-bootstraps every unit. The caller owns the transaction.
990fn reset_units(conn: &Connection) -> rusqlite::Result<()> {
991    conn.execute_batch(
992        "UPDATE _syncular_units SET status='active', reason_code=NULL, cursor=-1,
993           bootstrap_state=NULL, seeded='[]', echo=NULL;
994         DELETE FROM _syncular_meta WHERE key IN ('replicaCursor','echoDigest','registrationDigest');",
995    )
996}
997
998/// §4.5: the replica cursor, `-1` while no unit is live.
999fn replica_cursor(conn: &Connection) -> rusqlite::Result<i64> {
1000    meta_get(conn, REPLICA_CURSOR_KEY)?.map_or(Ok(-1), |raw| {
1001        raw.parse().map_err(|error| {
1002            rusqlite::Error::FromSqlConversionFailure(
1003                0,
1004                rusqlite::types::Type::Text,
1005                Box::new(error),
1006            )
1007        })
1008    })
1009}
1010
1011fn visible_table(name: &str) -> String {
1012    quote_ident(name)
1013}
1014
1015const FTS_SOURCE_ID_COLUMN: &str = "_syncular_source_id";
1016
1017/// §7.4.3: is a `sqlite_master` table name a synced table (visible or base),
1018/// i.e. NOT one of the durable bookkeeping tables the reset preserves?
1019fn is_synced_table_name(name: &str) -> bool {
1020    if name.starts_with("sqlite_") {
1021        return false;
1022    }
1023    if name.starts_with("_syncular_base_") {
1024        return true; // the base half of a synced table pair
1025    }
1026    // Bookkeeping: outbox, units, meta, blob cache/uploads.
1027    !name.starts_with("_syncular_")
1028}
1029
1030/// `"sha256:" + hex` of the bytes — the content address (§5.9.1).
1031fn blob_id_for(bytes: &[u8]) -> String {
1032    let digest = Sha256::digest(bytes);
1033    format!("sha256:{}", bytes_to_hex(&digest))
1034}
1035
1036/// One [`SyncClient::write_row`] bind parameter, borrowing the row-codec
1037/// value it wraps — strings/JSON/bytes bind as borrowed TEXT/BLOB (no copy
1038/// per row on the §5.6 bootstrap path), scalars bind owned.
1039enum RowParam<'a> {
1040    Cell(&'a Option<ColumnValue>),
1041    Version(i64),
1042}
1043
1044impl rusqlite::ToSql for RowParam<'_> {
1045    fn to_sql(&self) -> rusqlite::Result<ToSqlOutput<'_>> {
1046        Ok(match self {
1047            RowParam::Version(v) => ToSqlOutput::Owned(SqlValue::Integer(*v)),
1048            RowParam::Cell(cell) => match cell {
1049                None => ToSqlOutput::Owned(SqlValue::Null),
1050                Some(ColumnValue::String(s)) => ToSqlOutput::Borrowed(ValueRef::Text(s.as_bytes())),
1051                Some(ColumnValue::Integer(i)) => ToSqlOutput::Owned(SqlValue::Integer(*i)),
1052                Some(ColumnValue::Float(f)) => ToSqlOutput::Owned(SqlValue::Real(*f)),
1053                Some(ColumnValue::Boolean(b)) => {
1054                    ToSqlOutput::Owned(SqlValue::Integer(i64::from(*b)))
1055                }
1056                Some(ColumnValue::Json(raw)) | Some(ColumnValue::BlobRef(raw)) => {
1057                    ToSqlOutput::Borrowed(ValueRef::Text(raw.0.as_bytes()))
1058                }
1059                // §5.10: crdt bytes store as BLOB, like bytes.
1060                Some(ColumnValue::Bytes(b)) | Some(ColumnValue::Crdt(b)) => {
1061                    ToSqlOutput::Borrowed(ValueRef::Blob(b))
1062                }
1063            },
1064        })
1065    }
1066}
1067
1068// Retain a typed primary key across the current import chunk without copying row payloads.
1069fn owned_sql_value(param: impl rusqlite::ToSql) -> Result<SqlValue, String> {
1070    match param.to_sql().map_err(|error| error.to_string())? {
1071        ToSqlOutput::Owned(value) => Ok(value),
1072        ToSqlOutput::Borrowed(value) => {
1073            SqlValue::try_from(value).map_err(|error| error.to_string())
1074        }
1075        _ => Err("sync.invalid_request: unsupported SQLite key parameter".into()),
1076    }
1077}
1078
1079/// §5.3 image cell → bind parameter, strict per the declared column type
1080/// (`boolean` from INTEGER 0/1, `json` from its raw TEXT, NULL only when
1081/// nullable). Mismatches are image-producer violations. Returns the cell
1082/// borrowed when the stored representation already matches what the row
1083/// codec would write, or the normalized scalar (boolean → 0/1, float from
1084/// INTEGER → REAL) otherwise — the local write is byte-identical to the
1085/// old convert-then-insert path without allocating per cell.
1086fn image_cell_param<'a>(column: &Column, value: ValueRef<'a>) -> Result<ToSqlOutput<'a>, String> {
1087    use ssp2::segment::ColumnType;
1088    let mismatch = || {
1089        Err(format!(
1090            "image column {:?} holds a value of the wrong type",
1091            column.name
1092        ))
1093    };
1094    match value {
1095        ValueRef::Null => {
1096            if !column.nullable {
1097                return Err(format!(
1098                    "image column {:?} is NULL but not nullable",
1099                    column.name
1100                ));
1101            }
1102            Ok(ToSqlOutput::Owned(SqlValue::Null))
1103        }
1104        ValueRef::Integer(i) => match column.ty {
1105            ColumnType::Integer => Ok(ToSqlOutput::Borrowed(value)),
1106            ColumnType::Boolean => Ok(ToSqlOutput::Owned(SqlValue::Integer(i64::from(i != 0)))),
1107            ColumnType::Float => Ok(ToSqlOutput::Owned(SqlValue::Real(i as f64))),
1108            _ => mismatch(),
1109        },
1110        ValueRef::Real(_) => match column.ty {
1111            ColumnType::Float => Ok(ToSqlOutput::Borrowed(value)),
1112            _ => mismatch(),
1113        },
1114        ValueRef::Text(t) => {
1115            std::str::from_utf8(t)
1116                .map_err(|_| format!("image column {:?} is not UTF-8", column.name))?;
1117            match column.ty {
1118                ColumnType::String | ColumnType::Json | ColumnType::BlobRef => {
1119                    Ok(ToSqlOutput::Borrowed(value))
1120                }
1121                _ => mismatch(),
1122            }
1123        }
1124        ValueRef::Blob(_) => match column.ty {
1125            // §5.10: a crdt column stores its opaque bytes as BLOB, like bytes.
1126            ColumnType::Bytes | ColumnType::Crdt => Ok(ToSqlOutput::Borrowed(value)),
1127            _ => mismatch(),
1128        },
1129    }
1130}
1131
1132pub(crate) fn sql_ref_to_json(column: &Column, value: rusqlite::types::ValueRef<'_>) -> Value {
1133    use rusqlite::types::ValueRef;
1134    match value {
1135        ValueRef::Null => Value::Null,
1136        ValueRef::Integer(i) => match column.ty {
1137            ssp2::segment::ColumnType::Boolean => Value::Bool(i != 0),
1138            ssp2::segment::ColumnType::Float => {
1139                serde_json::Number::from_f64(i as f64).map_or(Value::Null, Value::Number)
1140            }
1141            _ => Value::from(i),
1142        },
1143        ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1144        ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1145        ValueRef::Blob(b) => {
1146            let mut map = Map::new();
1147            map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1148            Value::Object(map)
1149        }
1150    }
1151}
1152
1153/// Bind a driver JSON value form as a rusqlite parameter for [`SyncClient::query`].
1154/// Objects are accepted in lossless `{"$bytes": hex}` and
1155/// `{"$bigint": decimal}` envelope forms.
1156fn json_param_to_sql(value: &Value) -> Result<SqlValue, String> {
1157    Ok(match value {
1158        Value::Null => SqlValue::Null,
1159        Value::Bool(b) => SqlValue::Integer(i64::from(*b)),
1160        Value::Number(n) => {
1161            if let Some(i) = n.as_i64() {
1162                SqlValue::Integer(i)
1163            } else if let Some(f) = n.as_f64() {
1164                SqlValue::Real(f)
1165            } else {
1166                return Err(format!("query param number {n} is out of range"));
1167            }
1168        }
1169        Value::String(s) => SqlValue::Text(s.clone()),
1170        Value::Object(_) => {
1171            if let Some(hex) = value.get("$bytes").and_then(Value::as_str) {
1172                SqlValue::Blob(crate::values::hex_to_bytes(hex)?)
1173            } else if let Some(decimal) = value.get("$bigint").and_then(Value::as_str) {
1174                SqlValue::Integer(decimal.parse::<i64>().map_err(|_| {
1175                    format!("query bigint param {decimal:?} is outside SQLite's i64 range")
1176                })?)
1177            } else {
1178                return Err(
1179                    "query object param must be a {$bytes: hex} or {$bigint: decimal} value"
1180                        .to_owned(),
1181                );
1182            }
1183        }
1184        Value::Array(_) => return Err("query array params are not supported".to_owned()),
1185    })
1186}
1187
1188/// Map a rusqlite value with no schema column to consult (arbitrary query
1189/// output): integers/reals/text pass through by stored affinity, blobs ride
1190/// as `{"$bytes": hex}`. Distinct from [`sql_ref_to_json`], which uses the
1191/// schema column type to recover booleans/floats/json.
1192fn sql_ref_to_json_dynamic(value: rusqlite::types::ValueRef<'_>) -> Value {
1193    use rusqlite::types::ValueRef;
1194    match value {
1195        ValueRef::Null => Value::Null,
1196        ValueRef::Integer(i) => {
1197            // JSON/Tauri IPC cannot represent every SQLite i64 exactly. Keep
1198            // ordinary UI-sized integers ergonomic and envelope only values
1199            // beyond JavaScript's safe range.
1200            const MAX_SAFE_INTEGER: i64 = 9_007_199_254_740_991;
1201            if (-MAX_SAFE_INTEGER..=MAX_SAFE_INTEGER).contains(&i) {
1202                Value::from(i)
1203            } else {
1204                let mut map = Map::new();
1205                map.insert("$bigint".to_owned(), Value::from(i.to_string()));
1206                Value::Object(map)
1207            }
1208        }
1209        ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1210        ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1211        ValueRef::Blob(b) => {
1212            let mut map = Map::new();
1213            map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1214            Value::Object(map)
1215        }
1216    }
1217}
1218
1219/// §7.5: SQLite failures classify by result code into [`QueryReadFailure`].
1220fn query_connection(
1221    conn: &Connection,
1222    sql: &str,
1223    params: &[QueryValue],
1224) -> Result<Vec<QueryRow>, QueryReadFailure> {
1225    let lowered_sql = crate::query_guard::lower_public_query_sql(sql);
1226    let mut stmt = crate::query_guard::prepare_read_only(conn, &lowered_sql)?;
1227    let bound: Vec<SqlValue> = params
1228        .iter()
1229        .map(json_param_to_sql)
1230        .collect::<Result<_, _>>()?;
1231    // §2.4: an unaliased physical version column stays engine-internal, so a
1232    // `SELECT *` row feeds straight back into mutation values. An explicit
1233    // alias (`_sync_version AS v`) returns it as ordinary query data.
1234    let columns: Vec<(usize, String)> = stmt
1235        .column_names()
1236        .enumerate()
1237        .filter(|(_, name)| *name != "_syncular_version")
1238        .map(|(i, name)| (i, name.to_owned()))
1239        .collect();
1240    let bound_refs: Vec<&dyn rusqlite::ToSql> =
1241        bound.iter().map(|v| v as &dyn rusqlite::ToSql).collect();
1242    let mut sql_rows = stmt.query(bound_refs.as_slice())?;
1243    let mut out = Vec::new();
1244    while let Some(row) = sql_rows.next()? {
1245        let mut record = Map::new();
1246        for (i, name) in &columns {
1247            let value = row.get_ref(*i)?;
1248            record.insert(name.clone(), sql_ref_to_json_dynamic(value));
1249        }
1250        out.push(record);
1251    }
1252    Ok(out)
1253}
1254
1255fn persisted_window_state(
1256    conn: &Connection,
1257    base: &WindowBase,
1258) -> Result<WindowState, QueryReadFailure> {
1259    let mut stmt = conn.prepare(
1260        "SELECT windows.unit, units.status, units.cursor, units.bootstrap_state
1261           FROM _syncular_windows AS windows
1262           LEFT JOIN _syncular_units AS units ON units.id = windows.sub_id
1263          WHERE windows.base = ?1
1264          ORDER BY windows.unit ASC",
1265    )?;
1266    let rows = stmt.query_map(rusqlite::params![window_base_key(base)], |row| {
1267        Ok((
1268            row.get::<_, String>(0)?,
1269            row.get::<_, Option<String>>(1)?,
1270            row.get::<_, Option<i64>>(2)?,
1271            row.get::<_, Option<String>>(3)?,
1272        ))
1273    })?;
1274    let mut units = Vec::new();
1275    let mut pending = Vec::new();
1276    for row in rows {
1277        let (unit, status, cursor, bootstrap_state) = row?;
1278        // §4.8: complete iff registered, active and not bootstrapping.
1279        if status.as_deref() != Some("active")
1280            || cursor.is_some_and(|cursor| cursor < 0 || bootstrap_state.is_some())
1281        {
1282            pending.push(unit.clone());
1283        }
1284        units.push(unit);
1285    }
1286    Ok(WindowState { units, pending })
1287}
1288
1289/// One read-only statement in a §7.5 snapshot read.
1290#[derive(Debug, Clone, Copy)]
1291pub struct SnapshotStatement<'a> {
1292    pub sql: &'a str,
1293    pub params: &'a [Value],
1294}
1295
1296/// A §7.5 atomic read request: read-only statements, window coverage, unit
1297/// catch-up states, and commit deliveries, all resolved from one SQLite read
1298/// transaction and one revision.
1299#[derive(Debug, Clone, Default)]
1300pub struct SnapshotReadRequest<'a> {
1301    pub statements: Vec<SnapshotStatement<'a>>,
1302    pub coverage: &'a [WindowCoverage],
1303    pub units: Vec<String>,
1304    pub commit_ids: Vec<String>,
1305}
1306
1307#[cfg(test)]
1308thread_local! {
1309    /// Test-only rendezvous that runs between the statements of one snapshot
1310    /// read. A test uses it to commit on another connection mid-read and prove
1311    /// the read transaction's snapshot and revision stay stable.
1312    static SNAPSHOT_READ_HOOK: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
1313        std::cell::RefCell::new(None);
1314}
1315
1316#[cfg(test)]
1317fn run_snapshot_read_hook() {
1318    SNAPSHOT_READ_HOOK.with(|slot| {
1319        if let Some(hook) = slot.borrow_mut().take() {
1320            hook();
1321        }
1322    });
1323}
1324
1325/// §7.5: resolve a request over one SQLite read transaction. The revision,
1326/// every statement's rows, coverage, catch-up states, and deliveries are
1327/// captured under one `SAVEPOINT`; any statement's failure rolls the whole
1328/// read back and releases the connection.
1329fn snapshot_read_connection(
1330    conn: &Connection,
1331    request: &SnapshotReadRequest<'_>,
1332) -> Result<SnapshotRead, QueryReadFailure> {
1333    conn.execute_batch("SAVEPOINT syncular_snapshot_read")?;
1334    let corrupt = |message: &str| QueryReadFailure {
1335        code: Some("sync.local_corrupt"),
1336        sqlite_code: None,
1337        sqlite_message: None,
1338        rollback_failure: None,
1339        message: message.to_owned(),
1340    };
1341    let stored_failure = |error: rusqlite::Error, message: &str| match error {
1342        rusqlite::Error::Utf8Error(..)
1343        | rusqlite::Error::InvalidColumnType(..)
1344        | rusqlite::Error::FromSqlConversionFailure(..)
1345        | rusqlite::Error::IntegralValueOutOfRange(..) => corrupt(message),
1346        _ => QueryReadFailure::from(error),
1347    };
1348    let result: Result<SnapshotRead, QueryReadFailure> = (|| {
1349        // The durable revision as a canonical decimal `u64`; a missing marker
1350        // is the legacy zero, and any other non-canonical value is corrupt.
1351        let revision: Option<String> = conn
1352            .query_row(
1353                "SELECT value FROM _syncular_meta WHERE key = ?1",
1354                rusqlite::params![LOCAL_REVISION_KEY],
1355                |row| row.get(0),
1356            )
1357            .optional()
1358            .map_err(|error| stored_failure(error, "persisted local revision is invalid"))?;
1359        let revision = match revision {
1360            None => "0".to_owned(),
1361            Some(value)
1362                if value == "0"
1363                    || (matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1364                        && value.bytes().all(|b| b.is_ascii_digit())
1365                        && value.parse::<u64>().is_ok()) =>
1366            {
1367                value
1368            }
1369            Some(_) => return Err(corrupt("persisted local revision is invalid")),
1370        };
1371        let mut queries = Vec::with_capacity(request.statements.len());
1372        for statement in &request.statements {
1373            queries.push(query_connection(conn, statement.sql, statement.params)?);
1374            #[cfg(test)]
1375            run_snapshot_read_hook();
1376        }
1377        let mut pending = Vec::new();
1378        let mut missing = Vec::new();
1379        for requested in request.coverage {
1380            let base_key = window_base_key(&requested.base);
1381            let state = persisted_window_state(conn, &requested.base)?;
1382            for unit in BTreeSet::from_iter(requested.units.iter().cloned()) {
1383                let reference = WindowUnitRef {
1384                    base_key: base_key.clone(),
1385                    unit: unit.clone(),
1386                };
1387                if !state.units.iter().any(|held| held == &unit) {
1388                    missing.push(reference);
1389                } else if state.pending.iter().any(|held| held == &unit) {
1390                    pending.push(reference);
1391                }
1392            }
1393        }
1394        let mut units = Vec::with_capacity(request.units.len());
1395        for id in &request.units {
1396            let exists: bool = conn.query_row(
1397                "SELECT EXISTS(SELECT 1 FROM _syncular_units WHERE id = ?1)",
1398                [id],
1399                |row| row.get(0),
1400            )?;
1401            if !exists {
1402                units.push(UnitCatchup::Unknown { id: id.clone() });
1403                continue;
1404            }
1405            // Every persisted field is required to be well typed; a corrupt
1406            // record fails typed instead of inventing a state.
1407            let unit = get_unit(conn, id)
1408                .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?
1409                .ok_or_else(|| corrupt("persisted unit state is invalid"))?;
1410            let cursor = match unit.cursor {
1411                Some(cursor) => cursor,
1412                None => replica_cursor(conn)
1413                    .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?,
1414            };
1415            if cursor.unsigned_abs() > MAX_JS_SAFE_INTEGER {
1416                return Err(corrupt("persisted unit state is invalid"));
1417            }
1418            let active = unit.status == UnitStatus::Active;
1419            let pending = unit.bootstrapping();
1420            units.push(UnitCatchup::Known {
1421                id: id.clone(),
1422                status: unit.status,
1423                live: unit.cursor.is_none(),
1424                cursor,
1425                has_resume_token: unit.bootstrap_state.is_some(),
1426                bootstrap_complete: active && !pending,
1427                known_pending_pages: active && pending,
1428                reason_code: unit.reason_code,
1429            });
1430        }
1431        let mut deliveries = Vec::with_capacity(request.commit_ids.len());
1432        for id in &request.commit_ids {
1433            let pending: bool = conn.query_row(
1434                "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id = ?1)",
1435                rusqlite::params![id],
1436                |row| row.get(0),
1437            )?;
1438            if pending {
1439                deliveries.push(CommitDelivery::Pending {
1440                    client_commit_id: id.clone(),
1441                });
1442                continue;
1443            }
1444            let row = conn
1445                .query_row(
1446                    "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
1447                            resolution, resolved_at_ms, replacement_client_commit_id
1448                       FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
1449                    rusqlite::params![id],
1450                    StoredCommitOutcomeRow::from_row,
1451                )
1452                .optional()
1453                .map_err(|error| stored_failure(error, "persisted commit outcome is invalid"))?;
1454            deliveries.push(match row {
1455                Some(row) => CommitDelivery::Known {
1456                    client_commit_id: id.clone(),
1457                    outcome: SyncClient::outcome_from_row(row)
1458                        .map_err(|_| corrupt("persisted commit outcome is invalid"))?,
1459                },
1460                None => CommitDelivery::Unknown {
1461                    client_commit_id: id.clone(),
1462                },
1463            });
1464        }
1465        Ok(SnapshotRead {
1466            revision,
1467            queries,
1468            coverage: CoverageSnapshot {
1469                complete: pending.is_empty() && missing.is_empty(),
1470                pending,
1471                missing,
1472            },
1473            units,
1474            deliveries,
1475        })
1476    })();
1477    match result {
1478        Ok(read) => {
1479            conn.execute_batch("RELEASE syncular_snapshot_read")?;
1480            Ok(read)
1481        }
1482        Err(mut error) => {
1483            if let Err(rollback) = conn
1484                .execute_batch("ROLLBACK TO syncular_snapshot_read; RELEASE syncular_snapshot_read")
1485            {
1486                error.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
1487            }
1488            Err(error)
1489        }
1490    }
1491}
1492
1493fn snapshot_connection(
1494    conn: &Connection,
1495    sql: &str,
1496    params: &[Value],
1497    coverage: &[WindowCoverage],
1498) -> Result<QuerySnapshot, QueryReadFailure> {
1499    let read = snapshot_read_connection(
1500        conn,
1501        &SnapshotReadRequest {
1502            statements: vec![SnapshotStatement { sql, params }],
1503            coverage,
1504            units: Vec::new(),
1505            commit_ids: Vec::new(),
1506        },
1507    )?;
1508    Ok(QuerySnapshot {
1509        revision: read.revision,
1510        rows: read
1511            .queries
1512            .into_iter()
1513            .next()
1514            .expect("single-query snapshot returns one result"),
1515        coverage: read.coverage,
1516    })
1517}
1518
1519/// A long-lived read-only SQLite sidecar for latency-critical native views.
1520/// Network rounds stay serialized on the mutable core owner, while atomic
1521/// query snapshots use this independent connection and therefore never queue
1522/// behind HTTP/WebSocket latency.
1523pub struct FileQuerySnapshotReader {
1524    path: String,
1525    conn: Option<Connection>,
1526}
1527
1528impl FileQuerySnapshotReader {
1529    #[must_use]
1530    pub fn new(path: impl Into<String>) -> Self {
1531        Self {
1532            path: path.into(),
1533            conn: None,
1534        }
1535    }
1536
1537    fn connection(&mut self) -> Result<&Connection, QueryReadFailure> {
1538        if self.conn.is_none() {
1539            let conn = Connection::open_with_flags(
1540                &self.path,
1541                OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
1542            )
1543            .map_err(QueryReadFailure::from)?;
1544            conn.busy_timeout(std::time::Duration::from_millis(250))
1545                .map_err(QueryReadFailure::from)?;
1546            self.conn = Some(conn);
1547        }
1548        self.conn
1549            .as_ref()
1550            .ok_or_else(|| QueryReadFailure::from("read sidecar connection missing".to_owned()))
1551    }
1552
1553    /// One atomic read over the shared primitive: every statement, coverage,
1554    /// catch-up, and delivery under one `SAVEPOINT` and one revision.
1555    pub fn snapshot_read(
1556        &mut self,
1557        request: &SnapshotReadRequest<'_>,
1558    ) -> Result<SnapshotRead, QueryReadFailure> {
1559        snapshot_read_connection(self.connection()?, request)
1560    }
1561
1562    /// The current durable local revision. A host can skip a read when it is
1563    /// unchanged; a corrupt or unreadable marker fails typed.
1564    pub fn local_revision(&mut self) -> Result<String, QueryReadFailure> {
1565        Ok(self
1566            .snapshot_read(&SnapshotReadRequest::default())?
1567            .revision)
1568    }
1569
1570    /// One unit's persisted catch-up state (see the §7.5 contract).
1571    pub fn unit_catchup(&mut self, id: &str) -> Result<UnitCatchup, QueryReadFailure> {
1572        let read = self.snapshot_read(&SnapshotReadRequest {
1573            units: vec![id.to_owned()],
1574            ..Default::default()
1575        })?;
1576        Ok(read
1577            .units
1578            .into_iter()
1579            .next()
1580            .expect("one requested catch-up"))
1581    }
1582
1583    /// One client commit's delivery status: pending, its retained outcome, or
1584    /// an explicit unknown (never held, or pruned by retention).
1585    pub fn commit_delivery(&mut self, id: &str) -> Result<CommitDelivery, QueryReadFailure> {
1586        let read = self.snapshot_read(&SnapshotReadRequest {
1587            commit_ids: vec![id.to_owned()],
1588            ..Default::default()
1589        })?;
1590        Ok(read
1591            .deliveries
1592            .into_iter()
1593            .next()
1594            .expect("one requested delivery"))
1595    }
1596
1597    /// Hosts report an owned failure, and the first success after it, to the
1598    /// owning core through [`SyncClient::record_query_read`] (§7.6).
1599    pub fn query_snapshot(
1600        &mut self,
1601        sql: &str,
1602        params: &[Value],
1603        coverage: &[WindowCoverage],
1604    ) -> Result<QuerySnapshot, QueryReadFailure> {
1605        snapshot_connection(self.connection()?, sql, params, coverage)
1606    }
1607}
1608
1609fn validate_authority_reads(
1610    schema: &ClientSchema,
1611    declarations: &[crate::api::AuthorityReadDeclaration],
1612) -> Result<(), String> {
1613    let mut seen = BTreeSet::new();
1614    for read in declarations {
1615        let table = schema
1616            .table(&read.table)
1617            .ok_or("client.authority_read_forbidden: authority table is not declared")?;
1618        let plain = |name: &str| {
1619            table.columns.iter().enumerate().any(|(i, c)| {
1620                c.name == name
1621                    && name != "authority_version"
1622                    && !name.starts_with("_sync")
1623                    && !table.encrypted_columns.iter().any(|e| e.index == i)
1624                    && matches!(
1625                        c.ty,
1626                        ssp2::segment::ColumnType::String
1627                            | ssp2::segment::ColumnType::Integer
1628                            | ssp2::segment::ColumnType::Float
1629                            | ssp2::segment::ColumnType::Boolean
1630                            | ssp2::segment::ColumnType::Json
1631                    )
1632            })
1633        };
1634        if !seen.insert(&read.table)
1635            || read.columns.is_empty()
1636            || read.columns.iter().collect::<BTreeSet<_>>().len() != read.columns.len()
1637            || !read.columns.contains(&table.primary_key)
1638            || !read.columns.iter().all(|c| plain(c))
1639            || read.scopes.is_empty()
1640            || !read.scopes.iter().all(|(v, values)| {
1641                table
1642                    .scope_column(v)
1643                    .is_some_and(|c| read.columns.iter().any(|column| column == c) && plain(c))
1644                    && !values.is_empty()
1645                    && values.iter().all(|v| !v.is_empty() && v != "*")
1646            })
1647        {
1648            return Err("client.authority_read_forbidden: authority reads require plain columns, a primary key and nonempty plain scope selectors".into());
1649        }
1650    }
1651    Ok(())
1652}
1653
1654// §7.4.2: every open and recreation checks before any persistent writes.
1655/// A marker read that hit a recognized SQLite storage failure keeps that
1656/// classification (BUSY/LOCKED stay retryable); only an unclassified read
1657/// failure is the invalid-marker `sync.local_corrupt`.
1658fn schema_marker_read_failure(error: rusqlite::Error) -> String {
1659    let failure = QueryReadFailure::from(error);
1660    if failure.code.is_some() {
1661        failure.to_string()
1662    } else {
1663        "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned()
1664    }
1665}
1666
1667/// §7.1: reject an invalid configured client limit before any storage is
1668/// opened or written. Zero would wedge the push queue and an out-of-range
1669/// value would differ per target; the TS core enforces the same bounds.
1670fn validate_client_limits(limits: &crate::api::ClientLimits) -> Result<(), String> {
1671    if limits.outcome_retention_max_entries == Some(0) {
1672        return Err("sync.invalid_request: outcomeRetentionMaxEntries must be positive".to_owned());
1673    }
1674    if [
1675        limits.max_push_commits_per_request,
1676        limits.max_push_operations_per_request,
1677        limits.max_push_request_bytes,
1678    ]
1679    .into_iter()
1680    .flatten()
1681    .any(|value| value == 0 || value > u32::MAX as usize)
1682    {
1683        return Err(
1684            "sync.invalid_request: push limit must be an integer in 1..=4294967295".to_owned(),
1685        );
1686    }
1687    Ok(())
1688}
1689
1690fn read_local_schema_version(conn: &Connection, requested: i32) -> Result<Option<i32>, String> {
1691    let corrupt =
1692        || "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned();
1693    let table_type: Option<String> = conn
1694        .query_row(
1695            "SELECT type FROM sqlite_master WHERE name = '_syncular_meta'",
1696            [],
1697            |row| row.get(0),
1698        )
1699        .optional()
1700        .map_err(schema_marker_read_failure)?;
1701    let Some(table_type) = table_type else {
1702        return Ok(None);
1703    };
1704    if table_type != "table" {
1705        return Err(corrupt());
1706    }
1707    // §7.4.2: a duplicated marker cannot be resolved. `query_row` would take
1708    // whichever row SQLite returns first, and an older one would drive a
1709    // destructive reset over a newer replica.
1710    let mut statement = conn
1711        .prepare("SELECT value FROM _syncular_meta WHERE key = ?1")
1712        .map_err(schema_marker_read_failure)?;
1713    let mut rows = statement
1714        .query([LOCAL_SCHEMA_VERSION_KEY])
1715        .map_err(schema_marker_read_failure)?;
1716    let value: Option<String> = rows
1717        .next()
1718        .map_err(schema_marker_read_failure)?
1719        .map(|row| row.get(0))
1720        .transpose()
1721        .map_err(schema_marker_read_failure)?;
1722    if rows.next().map_err(schema_marker_read_failure)?.is_some() {
1723        return Err(corrupt());
1724    }
1725    let Some(value) = value else {
1726        let has_descriptor = conn
1727            .query_row(
1728                "SELECT 1 FROM _syncular_meta WHERE key = ?1 LIMIT 1",
1729                [crate::previous_version::LOCAL_SCHEMA_DESCRIPTOR_KEY],
1730                |_| Ok(()),
1731            )
1732            .optional()
1733            .map_err(schema_marker_read_failure)?
1734            .is_some();
1735        if has_descriptor {
1736            return Err(corrupt());
1737        }
1738        return Ok(None);
1739    };
1740    if !matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1741        || !value.bytes().all(|b| b.is_ascii_digit())
1742    {
1743        return Err(corrupt());
1744    }
1745    let version = value.parse::<i32>().map_err(|_| corrupt())?;
1746    if version > requested {
1747        return Err(
1748            "client.schema_downgrade: persisted local schema is newer than the requested schema"
1749                .to_owned(),
1750        );
1751    }
1752    Ok(Some(version))
1753}
1754
1755/// A file replica on a browser worker must recover a hot journal before any
1756/// statement reads it. `wasm_vfs` replaces the installed OPFS VFS's reserved
1757/// lock callback, so install it before the connection opens its file.
1758#[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
1759fn prepare_wasm_replica(path: &str) -> Result<(), String> {
1760    if path.is_empty() || path == ":memory:" {
1761        return Ok(());
1762    }
1763    crate::wasm_vfs::disable_foreign_lock_check()
1764}
1765
1766#[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
1767fn prepare_wasm_replica(_path: &str) -> Result<(), String> {
1768    Ok(())
1769}
1770
1771impl SyncClient {
1772    pub fn new_with_identity(
1773        client_id: Option<String>,
1774        schema_json: &Value,
1775        limits: ClientLimits,
1776    ) -> Result<Self, String> {
1777        let resolved = client_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
1778        let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1779        Self::with_connection(resolved, schema_json, limits, conn)
1780    }
1781
1782    pub fn new(
1783        client_id: String,
1784        schema_json: &Value,
1785        limits: ClientLimits,
1786    ) -> Result<Self, String> {
1787        let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1788        Self::with_connection(client_id, schema_json, limits, conn)
1789    }
1790
1791    /// Build a client backed by an on-disk SQLite database at `path` — the
1792    /// seam a native host (Tauri plugin, FFI file-DB variant) uses to persist
1793    /// across process restarts. `create_tables` runs `IF NOT EXISTS`, so
1794    /// re-opening the same file reuses the persisted rows. Keeps rusqlite out
1795    /// of the command router's dependency set (the router only holds a path).
1796    pub fn open_path(
1797        client_id: String,
1798        schema_json: &Value,
1799        limits: ClientLimits,
1800        path: &str,
1801    ) -> Result<Self, String> {
1802        validate_client_limits(&limits)?;
1803        parse_schema_json(schema_json)?;
1804        prepare_wasm_replica(path)?;
1805        let conn = Connection::open(path).map_err(|e| format!("open db {path:?}: {e}"))?;
1806        Self::with_connection(client_id, schema_json, limits, conn)
1807    }
1808
1809    /// Open a file replica and resolve its client id. Native targets require
1810    /// WAL for the independent snapshot reader; `wasm32-unknown-unknown`
1811    /// accepts the sqlite-wasm worker journal instead.
1812    pub fn open_path_with_identity(
1813        client_id: Option<String>,
1814        schema_json: &Value,
1815        limits: ClientLimits,
1816        path: &str,
1817    ) -> Result<Self, String> {
1818        Self::open_path_with_identity_journal(
1819            client_id,
1820            schema_json,
1821            limits,
1822            path,
1823            !cfg!(all(target_arch = "wasm32", target_os = "unknown")),
1824        )
1825    }
1826
1827    fn open_path_with_identity_journal(
1828        client_id: Option<String>,
1829        schema_json: &Value,
1830        limits: ClientLimits,
1831        path: &str,
1832        require_wal: bool,
1833    ) -> Result<Self, String> {
1834        validate_client_limits(&limits)?;
1835        // §7.4.2: an invalid requested version is refused before the replica is
1836        // even created, so a rejected constructor leaves no file behind.
1837        parse_schema_json(schema_json)?;
1838        prepare_wasm_replica(path)?;
1839        let conn = Connection::open(path).map_err(|e| format!("open db {path:?}: {e}"))?;
1840        // A file-backed native client uses an independent read connection for
1841        // latency-critical snapshots. WAL is SQLite's intended reader/writer
1842        // concurrency mode: a view read never holds a rollback-journal lock
1843        // that delays the client's next commit. The busy timeout must precede
1844        // this replica's own startup transaction; WAL is applied only after
1845        // startup succeeded, because a refused open must leave the replica's
1846        // journal mode and contents untouched (§7.4.2).
1847        conn.busy_timeout(std::time::Duration::from_millis(250))
1848            .map_err(|error| format!("configure db {path:?} busy timeout: {error}"))?;
1849        // Durability is the caller's contract here, not the VFS default: a
1850        // rollback-journal commit needs FULL before it writes the database
1851        // pages, or a killed worker can leave a half-written image behind.
1852        // WAL below inherits the same setting.
1853        conn.pragma_update(None, "synchronous", "FULL")
1854            .map_err(|error| format!("configure db {path:?} synchronous: {error}"))?;
1855        let client = Self::with_connection_identity(client_id, schema_json, limits, conn)?;
1856        // A browser worker's sqlite-wasm VFS has no WAL mode, and the wasm
1857        // host has no independent snapshot reader. The WAL requirement exists
1858        // for native file replicas, where it is the reader/writer boundary.
1859        if require_wal {
1860            let journal_mode: String = client
1861                .conn
1862                .pragma_update_and_check(None, "journal_mode", "WAL", |row| row.get(0))
1863                .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
1864            if journal_mode != "wal" {
1865                return Err(
1866                    "sync.invalid_request: file-backed client requires WAL journal mode".to_owned(),
1867                );
1868            }
1869        }
1870        Ok(client)
1871    }
1872
1873    /// Delete a file replica at `path`, including its `-journal`, `-wal`, and
1874    /// `-shm` sidecars, through the VFS that owns it. Use this after
1875    /// `client.storage_corrupt`: an OPFS SAH pool stores those files under
1876    /// opaque names, so deleting the pool directory behind SQLite bypasses the
1877    /// pool's slot accounting.
1878    ///
1879    /// Close the client and every [`FileQuerySnapshotReader`] on `path` first;
1880    /// a VFS cannot delete a file another handle still owns. A file that does
1881    /// not exist counts as deleted, so a cleanly closed replica without
1882    /// sidecars resets. The next open
1883    /// creates a fresh replica (new client id) and re-bootstraps from the
1884    /// server. A memory replica has nothing to delete and fails with
1885    /// `sync.invalid_request`.
1886    pub fn reset_replica(path: &str) -> Result<(), String> {
1887        if path.is_empty() || path == ":memory:" {
1888            return Err("sync.invalid_request: a memory replica has nothing to reset".to_owned());
1889        }
1890        // SAFETY: a null VFS name asks SQLite for its process-wide default VFS,
1891        // the same one `Connection::open(path)` above selects. `xDelete` is
1892        // that VFS's own function pointer, and `c_name` outlives the call.
1893        let vfs = unsafe { rusqlite::ffi::sqlite3_vfs_find(std::ptr::null()) };
1894        if vfs.is_null() {
1895            return Err("client.storage_io: no SQLite VFS is registered".to_owned());
1896        }
1897        let delete = unsafe { (*vfs).xDelete }
1898            .ok_or_else(|| "client.storage_io: the SQLite VFS cannot delete files".to_owned())?;
1899        for suffix in ["-wal", "-shm", "-journal", ""] {
1900            let file_name = format!("{path}{suffix}");
1901            let c_name = std::ffi::CString::new(file_name.as_str()).map_err(|_| {
1902                format!("sync.invalid_request: replica path {file_name:?} contains a NUL byte")
1903            })?;
1904            // SAFETY: `vfs` and its `xDelete` pointer come from the live
1905            // SQLite library; `c_name` is a valid NUL-terminated path.
1906            let code = unsafe { delete(vfs, c_name.as_ptr(), 1) };
1907            // A cleanly closed WAL replica has no sidecars; a missing file is
1908            // already deleted.
1909            if code != rusqlite::ffi::SQLITE_OK && code != rusqlite::ffi::SQLITE_IOERR_DELETE_NOENT
1910            {
1911                return Err(format!(
1912                    "client.storage_io: deleting replica file {file_name:?} failed with SQLite code {code}"
1913                ));
1914            }
1915        }
1916        Ok(())
1917    }
1918
1919    #[must_use]
1920    pub fn client_id(&self) -> &str {
1921        &self.client_id
1922    }
1923
1924    /// Rotate the caller's client id (§1.5) and return the new one. Use it
1925    /// after a `sync.invalid_client_id` refusal (`recommendedAction:
1926    /// resetClientId`): the next round carries the new id. A live realtime
1927    /// socket is closed so the next connection registers with the new id.
1928    /// The replica and its outbox stay in place; wipe them yourself when the
1929    /// stored data belongs to the account that signed out.
1930    pub fn reset_client_id(&mut self, transport: &mut dyn Transport) -> Result<String, String> {
1931        self.disconnect_realtime(transport);
1932        let client_id = uuid::Uuid::new_v4().to_string();
1933        self.set_meta(CLIENT_ID_KEY, &client_id)?;
1934        self.client_id.clone_from(&client_id);
1935        self.round_failure = None;
1936        Ok(client_id)
1937    }
1938
1939    /// Build a client over a caller-supplied rusqlite connection — the seam a
1940    /// native host (Tauri plugin, FFI file-DB variant) uses to back the core
1941    /// with an on-disk database (`Connection::open(path)`) rather than the
1942    /// default `:memory:`. The connection MUST be fresh (no pre-existing
1943    /// syncular tables); `create_tables` runs `IF NOT EXISTS`, so re-opening
1944    /// the same file across process restarts reuses the persisted rows.
1945    pub fn with_connection(
1946        client_id: String,
1947        schema_json: &Value,
1948        limits: ClientLimits,
1949        conn: Connection,
1950    ) -> Result<Self, String> {
1951        Self::with_connection_identity(Some(client_id), schema_json, limits, conn)
1952    }
1953
1954    /// [`Self::with_connection`] for `open_path_with_identity`: no requested id
1955    /// means a durable replica's persisted `clientId` wins over a fresh one.
1956    fn with_connection_identity(
1957        client_id: Option<String>,
1958        schema_json: &Value,
1959        limits: ClientLimits,
1960        conn: Connection,
1961    ) -> Result<Self, String> {
1962        validate_client_limits(&limits)?;
1963        let schema = parse_schema_json(schema_json)?;
1964        validate_authority_reads(&schema, &limits.authority_reads)?;
1965        // RFC 0005 D8: resolve the previous-version config before the opening
1966        // reset runs — the capture happens inside it. Bad bounds fail loud.
1967        let previous_version = match limits.previous_version_context {
1968            Some(config) => {
1969                config.validate()?;
1970                Some(config)
1971            }
1972            None => None,
1973        };
1974        let mut client = SyncClient {
1975            #[cfg(feature = "bench-internals")]
1976            benchmark_phases: Recorder::default(),
1977            conn,
1978            schema,
1979            client_id: client_id
1980                .clone()
1981                .unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
1982            limits,
1983            outbox: Shared::default(),
1984            failed_commits: Shared::default(),
1985            retain_failed_commits: false,
1986            conflicts: Shared::default(),
1987            rejections: Shared::default(),
1988            schema_floor: None,
1989            lease_state: None,
1990            stopped: false,
1991            upgrading: false,
1992            sync_needed: false,
1993            realtime_policy: RealtimePolicy::Optional,
1994            realtime_state: RealtimeState::Disconnected,
1995            realtime_reason_code: None,
1996            realtime_retry_delay_ms: None,
1997            presence: HashMap::new(),
1998            now_ms: None,
1999            encryption: crate::values::EncryptionConfig::default(),
2000            security_preflight: false,
2001            security_epoch: 0,
2002            transport_enabled: true,
2003            transport_epoch: 0,
2004            registration_epoch: 0,
2005            previous_version,
2006            insert_sql: RefCell::new(HashMap::new()),
2007            overlay_dirty: OverlayDirty::clean(),
2008            storage_failure: RefCell::new(None),
2009            #[cfg(test)]
2010            overlay_rebuild_count: Cell::new(0),
2011            #[cfg(test)]
2012            acknowledged_replay_count: Cell::new(0),
2013            #[cfg(test)]
2014            outcome_prune_count: Cell::new(0),
2015            progress: ProgressObserver::default(),
2016            change_queue: VecDeque::new(),
2017            sync_intent_queue: VecDeque::new(),
2018            retry_delay_ms: 250,
2019            round_retry_delay_ms: None,
2020            round_failure: None,
2021            active_round: None,
2022            last_round: None,
2023            last_change: None,
2024            query_failures: Vec::new(),
2025            coalesced: None,
2026            coalesced_failure: None,
2027        };
2028        // The row write path leans on the prepared-statement cache (two
2029        // insert statements per synced table, plus the bookkeeping
2030        // statements); size it so a multi-table schema never thrashes.
2031        client
2032            .conn
2033            .set_prepared_statement_cache_capacity(64.max(client.schema.tables.len() * 4));
2034        // §7.4.2: one write transaction (SQLite `BEGIN IMMEDIATE`, a reserved
2035        // writer) covers the marker read, the identity check, and every
2036        // bookkeeping/schema write, so a concurrent open that upgraded the
2037        // replica cannot interleave between the guard and the writes, and a
2038        // refusal leaves the replica unchanged.
2039        client
2040            .conn
2041            .execute_batch("BEGIN IMMEDIATE")
2042            .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2043        let startup = (|| -> Result<(), String> {
2044            // The marker guard runs inside the write transaction, so the version
2045            // it validates is the version every write below commits under.
2046            let marker = read_local_schema_version(&client.conn, client.schema.version)?;
2047            // New app indexes may reference columns that only exist after a
2048            // version-bump reset.
2049            client.create_bookkeeping_tables()?;
2050            match client.get_meta(CLIENT_ID_KEY)? {
2051                Some(existing) => match client_id {
2052                    Some(requested) if existing != requested => {
2053                        return Err(format!(
2054                            "client.identity_mismatch: this database belongs to {existing:?}; refusing to rebind it to {requested:?}"
2055                        ))
2056                    }
2057                    _ => client.client_id = existing,
2058                },
2059                None => client.set_meta(CLIENT_ID_KEY, &client.client_id)?,
2060            }
2061            client.restore_persisted_state()?;
2062            client.failed_commits = client.load_failed_commits()?.into();
2063            match marker {
2064                None => {
2065                    client.create_synced_tables()?;
2066                    client.persist_schema_version()?;
2067                    client.save_unit_scope_schema()?;
2068                }
2069                Some(version) if version == client.schema.version => {
2070                    client.create_synced_tables()?;
2071                    // RFC 0005 D1: the same-version open backfills the descriptor
2072                    // for a database first opened by an unaware binary, so the
2073                    // NEXT bump can capture without needing a schema bump first.
2074                    set_local_schema_descriptor(&client.conn, &client.schema)
2075                        .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2076                    client.save_unit_scope_schema()?;
2077                }
2078                Some(_) => client.run_schema_reset()?,
2079            }
2080            // RFC 0005 D9: the reset sweep cannot see a container whose capture
2081            // committed in its OWN file while the replica's savepoint never
2082            // released — a crash at that seam leaves a container beside a matching
2083            // OLD marker, and the next open at that version runs no reset. Discard
2084            // it before anything can read it. No-op when no container exists.
2085            client.reconcile_previous_version_at_boot()?;
2086            client.clear_satisfied_persisted_schema_floor()?;
2087            client.prune_unknown_units(false)?;
2088            // §7.1/§7.4.4: recover intrinsically codec-invalid persisted values at
2089            // the full startup/reset reconciliation boundary, inside this open
2090            // transaction and after the schema and identity guards, so a commit
2091            // an earlier version accepted is dropped with durable rejection
2092            // evidence before any replay. A table the current schema removed
2093            // keeps the §7.4.4 send-time classification, and an unresolved
2094            // encryption key stays with the send seam because hosts configure
2095            // keys after open.
2096            client.drop_unencodable_outbox(false, None)?;
2097            if marker == Some(client.schema.version)
2098                && (!client.outbox.is_empty()
2099                    || !client.failed_commits.is_empty()
2100                    || client.has_acknowledged_rows()?)
2101            {
2102                // Reconstruct the visible optimistic overlay from the durable
2103                // base plus outbox instead of trusting a process-interrupted
2104                // mirror.
2105                client.overlay_dirty.set(true);
2106                client.rebuild_overlay()?;
2107            }
2108            // Every persisted active unit needs one catch-up pull on
2109            // open: realtime only covers changes after connection, while an
2110            // idempotent setWindow correctly creates no fresh command effect.
2111            // Pending outbox work has the same restart requirement. The core
2112            // owns this intent so native hosts never poll or require an
2113            // application-issued sync().
2114            client.enqueue_startup_sync_if_needed()?;
2115            Ok(())
2116        })();
2117        match startup {
2118            Ok(()) => match client.conn.execute_batch("COMMIT") {
2119                // §4.8: an eviction a crash interrupted finishes before any
2120                // read, with or without a transport; a replica reopened in
2121                // preflight finishes it at activation.
2122                Ok(()) => {
2123                    if !client.security_preflight {
2124                        client.drain_pending_evictions()?;
2125                    }
2126                    Ok(client)
2127                }
2128                Err(error) => {
2129                    let failure = Self::sqlite_failure(&client.storage_failure, error);
2130                    if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2131                        // Keep a failed rollback's typed storage classification.
2132                        let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2133                    }
2134                    Err(failure)
2135                }
2136            },
2137            Err(error) => {
2138                if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2139                    // Keep a failed rollback's typed storage classification.
2140                    let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2141                }
2142                Err(error)
2143            }
2144        }
2145    }
2146
2147    /// Pin the client clock (epoch ms) — the §5.4 expiry check runs
2148    /// against this instead of system time (conformance virtual clock).
2149    pub fn set_now_ms(&mut self, now_ms: i64) {
2150        self.now_ms = Some(now_ms);
2151    }
2152
2153    /// §5.11: install the client-side encryption keys (`keyId → key bytes`).
2154    /// The command router parses these from the `create` command's
2155    /// `encryption` config (keys as `{$bytes: hex}`).
2156    pub fn set_encryption(&mut self, encryption: crate::values::EncryptionConfig) {
2157        self.encryption = encryption;
2158    }
2159
2160    #[must_use]
2161    pub fn security_lifecycle(&self) -> &'static str {
2162        if self.security_preflight {
2163            "preflight"
2164        } else {
2165            "active"
2166        }
2167    }
2168
2169    #[must_use]
2170    pub fn security_preflight(&self) -> bool {
2171        self.security_preflight
2172    }
2173
2174    /// Host-owned, non-persisted network gate. Local operations remain available.
2175    pub fn set_transport_enabled(&mut self, transport: &mut dyn Transport, enabled: bool) {
2176        if self.transport_enabled != enabled {
2177            self.transport_enabled = enabled;
2178            self.transport_epoch = self.transport_epoch.wrapping_add(1);
2179            self.sync_intent_queue.clear();
2180            self.sync_intent_queue
2181                .push_back(if enabled && !self.security_preflight {
2182                    SyncIntent::Interactive
2183                } else {
2184                    SyncIntent::None
2185                });
2186        }
2187        // A captured reply keeps its normal apply/revocation semantics.
2188        if !enabled && self.active_round.is_none() {
2189            self.disconnect_realtime(transport);
2190        }
2191    }
2192
2193    pub fn transport_enabled(&self) -> bool {
2194        self.transport_enabled
2195    }
2196
2197    /// Quarantine this replica: enter the fail-closed gate, release all
2198    /// core-owned key material, and record the gate in the database so
2199    /// reopening re-enters preflight until `activate_security` clears it.
2200    ///
2201    /// Use [`SyncClient::seal_security_on_teardown`] for the shutdown barrier,
2202    /// which must NOT leave that durable mark.
2203    pub fn begin_security_preflight(&mut self) -> Result<(), String> {
2204        let entering = !self.security_preflight;
2205        self.seal_security_on_teardown();
2206        // Persist the quarantine so it survives handle teardown and restart:
2207        // reopening this replica re-enters preflight until activation clears it.
2208        self.set_meta(SECURITY_PREFLIGHT_PENDING_KEY, "1")?;
2209        if entering {
2210            self.emit_status_batch()?;
2211        }
2212        Ok(())
2213    }
2214
2215    /// One change batch carrying the status snapshot (§5.11 lifecycle).
2216    fn emit_status_batch(&mut self) -> Result<(), String> {
2217        self.begin_observation("syncular_status")?;
2218        let batch = ChangeAccumulator {
2219            status: true,
2220            ..ChangeAccumulator::default()
2221        };
2222        self.finish_observation("syncular_status", batch)
2223            .inspect_err(|_| self.rollback_observation("syncular_status"))
2224    }
2225
2226    /// Release core-owned key material as a host tears the client down,
2227    /// WITHOUT recording a quarantine.
2228    ///
2229    /// Shutting an activated client down is not a quarantine event. Persisting
2230    /// the gate here marks every cleanly closed replica as pending, and the
2231    /// next plain `create` is then refused permanently: the reopen path
2232    /// restores the flag from the marker and the create guard rejects it. The
2233    /// in-memory flag still closes the gate for anything still holding this
2234    /// instance, which is all a teardown barrier needs.
2235    pub fn seal_security_on_teardown(&mut self) {
2236        self.cancel_sync_round();
2237        self.security_preflight = true;
2238        self.security_epoch = self.security_epoch.wrapping_add(1);
2239        self.encryption = crate::values::EncryptionConfig::default();
2240        self.sync_intent_queue.clear();
2241    }
2242
2243    /// Install the post-authentication keyring and release the host loop.
2244    pub fn activate_security(
2245        &mut self,
2246        encryption: crate::values::EncryptionConfig,
2247    ) -> Result<(), String> {
2248        if !self.security_preflight {
2249            return Err(
2250                "sync.invalid_request: activateSecurity requires security preflight".to_owned(),
2251            );
2252        }
2253        // §4.8: an interrupted eviction finishes before protected reads open.
2254        self.drain_pending_evictions()?;
2255        self.enqueue_startup_sync_if_needed()?;
2256        self.delete_meta(SECURITY_PREFLIGHT_PENDING_KEY)?;
2257        self.encryption = encryption;
2258        self.security_preflight = false;
2259        self.emit_status_batch()
2260    }
2261
2262    fn clock_now_ms(&self) -> i64 {
2263        self.now_ms.unwrap_or_else(crate::wall_clock_ms)
2264    }
2265
2266    fn create_bookkeeping_tables(&self) -> Result<(), String> {
2267        let exists = |name: &str| {
2268            self.conn
2269                .query_row(
2270                    "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1)",
2271                    [name],
2272                    |row| row.get::<_, bool>(0),
2273                )
2274                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2275        };
2276        let outbox_existed = exists("_syncular_outbox")?;
2277        // Durable client bookkeeping (outbox + units + meta).
2278        self.conn
2279            .execute_batch(
2280                "CREATE TABLE IF NOT EXISTS _syncular_outbox (
2281                   seq INTEGER PRIMARY KEY AUTOINCREMENT,
2282                   commit_id TEXT NOT NULL UNIQUE, ops_json TEXT NOT NULL);
2283                 CREATE TABLE IF NOT EXISTS _syncular_row_deliveries (
2284                   tbl TEXT NOT NULL, id TEXT NOT NULL, commit_seq INTEGER NOT NULL, PRIMARY KEY(tbl,id));
2285                 CREATE TABLE IF NOT EXISTS _syncular_acked_rows (
2286                   commit_id TEXT NOT NULL, idx INTEGER NOT NULL, tbl TEXT NOT NULL, id TEXT NOT NULL,
2287                   commit_seq INTEGER NOT NULL, op_json TEXT NOT NULL, intent_json TEXT,
2288                   PRIMARY KEY(commit_id, idx));
2289                 CREATE INDEX IF NOT EXISTS _syncular_acked_rows_row
2290                   ON _syncular_acked_rows(tbl, id);
2291                 CREATE TABLE IF NOT EXISTS _syncular_failed_commits (
2292                   seq INTEGER PRIMARY KEY AUTOINCREMENT, client_commit_id TEXT NOT NULL UNIQUE,
2293                   operations_json TEXT NOT NULL, initial_json TEXT NOT NULL);
2294                 CREATE TABLE IF NOT EXISTS _syncular_commit_outcomes (
2295                   seq INTEGER PRIMARY KEY AUTOINCREMENT,
2296                   client_commit_id TEXT NOT NULL UNIQUE,
2297                   status TEXT NOT NULL CHECK(status IN ('applied', 'cached', 'conflict', 'rejected')),
2298                   recorded_at_ms INTEGER NOT NULL,
2299                   results_json TEXT NOT NULL,
2300                   operations_json TEXT,
2301                   resolution TEXT NOT NULL DEFAULT 'active'
2302                     CHECK(resolution IN ('active', 'resolved_keep_server', 'superseded', 'dismissed')),
2303                   resolved_at_ms INTEGER,
2304                   replacement_client_commit_id TEXT);
2305                 CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq
2306                   ON _syncular_commit_outcomes(resolution, seq);
2307                 CREATE TABLE IF NOT EXISTS _syncular_units (
2308                   id TEXT PRIMARY KEY, scopes TEXT NOT NULL,
2309                   explicit INTEGER NOT NULL DEFAULT 0,
2310                   status TEXT NOT NULL DEFAULT 'active', reason_code TEXT,
2311                   cursor INTEGER DEFAULT -1, bootstrap_state TEXT,
2312                   seeded TEXT NOT NULL DEFAULT '[]', echo TEXT);
2313                 CREATE TABLE IF NOT EXISTS _syncular_meta (
2314                   key TEXT PRIMARY KEY, value TEXT NOT NULL);
2315                 CREATE TABLE IF NOT EXISTS _syncular_windows (
2316                   base TEXT NOT NULL, unit TEXT NOT NULL, sub_id TEXT NOT NULL,
2317                   PRIMARY KEY (base, unit));
2318                 CREATE INDEX IF NOT EXISTS _syncular_windows_unit ON _syncular_windows(sub_id);
2319                 CREATE TABLE IF NOT EXISTS _syncular_pending_evictions (
2320                   unit_id TEXT NOT NULL, tbl TEXT NOT NULL,
2321                   effective_scopes TEXT NOT NULL, PRIMARY KEY (unit_id, tbl));
2322                 CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
2323                   commit_id TEXT NOT NULL, blob_id TEXT NOT NULL,
2324                   PRIMARY KEY(commit_id, blob_id));
2325                 CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body
2326                   ON _syncular_blob_commit_refs(blob_id);",
2327            )
2328            .map_err(|e| e.to_string())?;
2329        // Migrate an outcome journal created before failed aggregate
2330        // envelopes were retained. Historical rows intentionally stay NULL.
2331        let _ = self
2332            .conn
2333            .execute_batch("ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations_json TEXT");
2334        if self.get_meta(LOCAL_REVISION_KEY)?.is_none() {
2335            self.set_meta(LOCAL_REVISION_KEY, "0")?;
2336        }
2337        // §7.1: `outboxId` names the outbox sequence. A new outbox table starts
2338        // a new sequence, so it replaces the id in the same transaction.
2339        if !outbox_existed || self.get_meta(OUTBOX_ID_KEY)?.is_none() {
2340            self.set_meta(OUTBOX_ID_KEY, &uuid::Uuid::new_v4().to_string())?;
2341        }
2342        // §9: a replica written under wire version 3 keeps its outbox, journal,
2343        // rows and pending evictions and registers its units fresh. Its
2344        // subscriptions, cursors, echoes, resume tokens and window entries go;
2345        // units left from an earlier version 4 life restart.
2346        if exists("_syncular_window_pending_evict")? {
2347            let invalid: bool = self
2348                .conn
2349                .query_row(
2350                    "SELECT EXISTS(SELECT 1 FROM _syncular_window_pending_evict
2351                       WHERE NOT json_valid(effective_scopes)
2352                          OR json_type(effective_scopes) <> 'object'
2353                          OR EXISTS(SELECT 1 FROM json_each(effective_scopes)
2354                               WHERE type <> 'array'
2355                                  OR EXISTS(SELECT 1 FROM json_each(value) AS v
2356                                       WHERE v.type <> 'text')))",
2357                    [],
2358                    |row| row.get(0),
2359                )
2360                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2361            if invalid {
2362                return Err(
2363                    "sync.local_corrupt: a version 3 pending eviction cannot be upgraded"
2364                        .to_owned(),
2365                );
2366            }
2367            self.conn
2368                .execute_batch(
2369                    "INSERT OR REPLACE INTO _syncular_pending_evictions
2370                       SELECT sub_id, tbl, effective_scopes FROM _syncular_window_pending_evict;
2371                     DROP TABLE _syncular_window_pending_evict;
2372                     DROP TABLE IF EXISTS _syncular_subscriptions;
2373                     DELETE FROM _syncular_windows;",
2374                )
2375                .and_then(|()| reset_units(&self.conn))
2376                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2377        }
2378        // §5.9.7 blob cache. Mutable upload state stays off the body row so
2379        // completing a large upload does not rewrite its BLOB record.
2380        if self.schema_has_blobs() {
2381            if exists("_syncular_blobs")? {
2382                let mut statement = self
2383                    .conn
2384                    .prepare("PRAGMA table_info(_syncular_blobs)")
2385                    .map_err(|e| e.to_string())?;
2386                let mut columns = statement
2387                    .query_map([], |row| row.get::<_, String>(1))
2388                    .map_err(|e| e.to_string())?
2389                    .collect::<Result<Vec<_>, _>>()
2390                    .map_err(|e| e.to_string())?;
2391                columns.sort();
2392                let mut expected = vec![
2393                    "blob_id",
2394                    "byte_length",
2395                    "bytes",
2396                    "created_at_ms",
2397                    "media_type",
2398                ];
2399                expected.sort_unstable();
2400                if columns != expected {
2401                    return Err(
2402                        "sync.schema_mismatch: Local blob schema is incompatible".to_owned()
2403                    );
2404                }
2405            } else {
2406                self.conn
2407                    .execute_batch(
2408                        "CREATE TABLE _syncular_blobs(
2409                           blob_id TEXT PRIMARY KEY,
2410                           bytes BLOB NOT NULL,
2411                           byte_length INTEGER NOT NULL,
2412                           media_type TEXT,
2413                           created_at_ms INTEGER NOT NULL);",
2414                    )
2415                    .map_err(|e| e.to_string())?;
2416            }
2417            self.conn
2418                .execute_batch(
2419                    "CREATE TABLE IF NOT EXISTS _syncular_blob_uploads(
2420                       blob_id TEXT PRIMARY KEY,
2421                       media_type TEXT,
2422                       created_at_ms INTEGER NOT NULL);",
2423                )
2424                .map_err(|e| e.to_string())?;
2425        }
2426        Ok(())
2427    }
2428
2429    /// True iff any synced table declares a `blob_ref` column (§5.9).
2430    fn schema_has_blobs(&self) -> bool {
2431        self.schema
2432            .tables
2433            .iter()
2434            .any(|t| t.columns.iter().any(|c| c.ty == ColumnType::BlobRef))
2435    }
2436
2437    // -- meta (§7.4.1 marker, bookkeeping) ------------------------------------
2438
2439    fn get_meta(&self, key: &str) -> Result<Option<String>, String> {
2440        meta_get(&self.conn, key)
2441            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2442    }
2443
2444    // The caller holds the startup/reset transaction. Either both schema
2445    // records persist or the enclosing operation fails and rolls back.
2446    fn persist_schema_version(&self) -> Result<(), String> {
2447        self.conn
2448            .execute(
2449                "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
2450                rusqlite::params![LOCAL_SCHEMA_VERSION_KEY, self.schema.version.to_string()],
2451            )
2452            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2453        set_local_schema_descriptor(&self.conn, &self.schema)
2454            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2455    }
2456
2457    pub(crate) fn set_meta(&self, key: &str, value: &str) -> Result<(), String> {
2458        meta_set(&self.conn, key, value)
2459            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2460    }
2461
2462    fn delete_meta(&self, key: &str) -> Result<(), String> {
2463        meta_delete(&self.conn, key)
2464            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2465    }
2466
2467    /// §7.1: the durable outbox in FIFO order, in schema-agnostic local form.
2468    fn load_outbox(&self) -> Result<Vec<Arc<OutboxCommit>>, String> {
2469        let mut stmt = self
2470            .conn
2471            .prepare("SELECT commit_id, ops_json FROM _syncular_outbox ORDER BY seq ASC")
2472            .map_err(|error| error.to_string())?;
2473        let rows = stmt
2474            .query_map([], |row| {
2475                Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
2476            })
2477            .map_err(|error| error.to_string())?;
2478        let mut commits = Vec::new();
2479        for row in rows {
2480            let (client_commit_id, raw) = row.map_err(|error| error.to_string())?;
2481            let entries: Vec<Value> = serde_json::from_str(&raw).map_err(|error| {
2482                format!("invalid persisted outbox {client_commit_id:?}: {error}")
2483            })?;
2484            let mut ops = Vec::with_capacity(entries.len());
2485            for entry in entries {
2486                let op = entry.get("op").and_then(Value::as_str).unwrap_or("delete");
2487                ops.push(OutboxOp {
2488                    upsert: op == "upsert",
2489                    table: entry
2490                        .get("table")
2491                        .and_then(Value::as_str)
2492                        .ok_or_else(|| "persisted outbox operation missing table".to_owned())?
2493                        .to_owned(),
2494                    row_id: entry
2495                        .get("rowId")
2496                        .and_then(Value::as_str)
2497                        .ok_or_else(|| "persisted outbox operation missing rowId".to_owned())?
2498                        .to_owned(),
2499                    base_version: entry.get("baseVersion").and_then(Value::as_i64),
2500                    // A legacy entry's `changedFields` key is ignored:
2501                    // the values map is the presence set (§6.1).
2502                    values: entry.get("values").and_then(Value::as_object).cloned(),
2503                    insert: entry.get("insert") == Some(&Value::Bool(true)),
2504                });
2505            }
2506            commits.push(Arc::new(OutboxCommit {
2507                client_commit_id,
2508                ops,
2509            }));
2510        }
2511        Ok(commits)
2512    }
2513
2514    fn restore_persisted_state(&mut self) -> Result<(), String> {
2515        self.outbox = self.load_outbox()?.into();
2516
2517        self.prune_commit_outcomes()?;
2518        let active = self.commit_outcomes(CommitOutcomeQuery {
2519            active_only: true,
2520            ..CommitOutcomeQuery::default()
2521        })?;
2522        self.conflicts = active
2523            .iter()
2524            .flat_map(|outcome| outcome.results.iter())
2525            .filter_map(|result| match result {
2526                CommitOperationOutcome::Conflict { conflict } => Some(conflict.clone()),
2527                _ => None,
2528            })
2529            .collect::<Vec<_>>()
2530            .into();
2531        self.rejections = active
2532            .iter()
2533            .flat_map(|outcome| outcome.results.iter())
2534            .filter_map(|result| match result {
2535                CommitOperationOutcome::Error { rejection } => Some(rejection.clone()),
2536                _ => None,
2537            })
2538            .collect::<Vec<_>>()
2539            .into();
2540
2541        self.lease_state = self
2542            .get_meta(LEASE_STATE_KEY)?
2543            .map(|raw| serde_json::from_str(&raw))
2544            .transpose()
2545            .map_err(|error| format!("invalid persisted lease state: {error}"))?;
2546        self.schema_floor = self
2547            .get_meta(SCHEMA_FLOOR_KEY)?
2548            .map(|raw| serde_json::from_str(&raw))
2549            .transpose()
2550            .map_err(|error| format!("invalid persisted schema floor: {error}"))?;
2551        self.stopped = self.schema_floor.is_some();
2552        // A replica left in unactivated preflight reopens gated: the quarantine
2553        // decision persists with the data across handle teardown and restart.
2554        if self.get_meta(SECURITY_PREFLIGHT_PENDING_KEY)?.as_deref() == Some("1") {
2555            self.security_preflight = true;
2556        }
2557        Ok(())
2558    }
2559
2560    fn save_unit_scope_schema(&self) -> Result<(), String> {
2561        let declarations: BTreeMap<_, BTreeMap<_, _>> = self
2562            .schema
2563            .tables
2564            .iter()
2565            .map(|table| {
2566                (
2567                    table.name.clone(),
2568                    table
2569                        .scope_variables
2570                        .iter()
2571                        .map(|scope| {
2572                            (
2573                                scope.variable.clone(),
2574                                [scope.prefix.clone(), scope.column.clone()],
2575                            )
2576                        })
2577                        .collect(),
2578                )
2579            })
2580            .collect();
2581        self.set_meta(
2582            "subscriptionScopeSchema",
2583            &serde_json::to_string(&declarations).expect("scope schema serialization"),
2584        )
2585    }
2586
2587    /// Drop units that cover no table of the running schema, with their window
2588    /// registry rows and pending evictions; never translate scopes. At a bump
2589    /// (§7.4.3) a unit also needs every variable unchanged in prefix and column
2590    /// on every table it covered before.
2591    fn prune_unknown_units(&mut self, bump: bool) -> Result<(), String> {
2592        let previous: Option<BTreeMap<String, BTreeMap<String, [String; 2]>>> = if bump {
2593            self.get_meta("subscriptionScopeSchema")?
2594                .map(|raw| serde_json::from_str(&raw))
2595                .transpose()
2596                .map_err(|_| "sync.local_corrupt: invalid persisted scope schema".to_owned())?
2597        } else {
2598            None
2599        };
2600        // A table keeps the variables' meaning when each has the same prefix
2601        // and column as before. An old binary stored no declaration evidence;
2602        // matching names cannot prove unchanged meaning, so the app registers
2603        // again.
2604        let unchanged = |name: &str, variables: &[&String]| {
2605            let (Some(old), Some(table)) = (
2606                previous.as_ref().and_then(|previous| previous.get(name)),
2607                self.schema.table(name),
2608            ) else {
2609                return false;
2610            };
2611            variables.iter().all(|variable| {
2612                table
2613                    .scope_variables
2614                    .iter()
2615                    .find(|scope| &scope.variable == *variable)
2616                    .is_some_and(|scope| {
2617                        old.get(*variable) == Some(&[scope.prefix.clone(), scope.column.clone()])
2618                    })
2619            })
2620        };
2621        let compatible = |scopes: &UnitScopes| {
2622            if !self.schema.tables.iter().any(|table| covers(table, scopes)) {
2623                return false;
2624            }
2625            if !bump {
2626                return true;
2627            }
2628            let Some(previous) = &previous else {
2629                return false;
2630            };
2631            previous.iter().all(|(name, old)| {
2632                !scopes.keys().all(|variable| old.contains_key(variable))
2633                    || unchanged(name, &scopes.keys().collect::<Vec<_>>())
2634            })
2635        };
2636        let mut stale: BTreeSet<String> = self
2637            .stored(load_units(&self.conn))?
2638            .into_iter()
2639            .filter(|unit| !compatible(&unit.scopes))
2640            .map(|unit| unit.id)
2641            .collect();
2642        // A shrunk window's deferred eviction outlives its unit row and keeps
2643        // its per-table scopes. A table the schema no longer has cannot be
2644        // evicted, and at a bump a table whose scope declarations changed must
2645        // not be evicted by the outdated rule.
2646        for (id, table, effective) in self.load_pending_evictions()? {
2647            if self.schema.table(&table).is_none()
2648                || (bump
2649                    && !unchanged(
2650                        &table,
2651                        &effective
2652                            .iter()
2653                            .map(|(variable, _)| variable)
2654                            .collect::<Vec<_>>(),
2655                    ))
2656            {
2657                stale.insert(id);
2658            }
2659        }
2660        for id in &stale {
2661            for sql in [
2662                "DELETE FROM _syncular_windows WHERE sub_id = ?1",
2663                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
2664                "DELETE FROM _syncular_units WHERE id = ?1",
2665            ] {
2666                self.conn
2667                    .execute(sql, rusqlite::params![id])
2668                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2669            }
2670        }
2671        Ok(())
2672    }
2673
2674    pub fn local_revision(&self) -> Result<u64, String> {
2675        Ok(self
2676            .get_meta(LOCAL_REVISION_KEY)?
2677            .and_then(|value| value.parse().ok())
2678            .unwrap_or(0))
2679    }
2680
2681    /// §7.5: resolve a snapshot read on the mutable owner connection through
2682    /// the same primitive the read-only sidecar uses, so the command surface
2683    /// and the file sidecar return one revision, rows, coverage, catch-up, and
2684    /// delivery shape. The structured [`QueryReadFailure`] is preserved; an
2685    /// `owner` records its failure (and its next success) in diagnostics.
2686    pub fn snapshot_read(
2687        &mut self,
2688        request: &SnapshotReadRequest<'_>,
2689        owner: Option<QueryOwner<'_>>,
2690    ) -> Result<SnapshotRead, QueryReadFailure> {
2691        let result = snapshot_read_connection(&self.conn, request);
2692        if let Some(owner) = owner {
2693            self.record_query_read(owner, result.as_ref().err());
2694        }
2695        result
2696    }
2697
2698    #[must_use]
2699    pub fn status_snapshot(&self) -> SyncStatusSnapshot {
2700        SyncStatusSnapshot {
2701            current_schema_version: self.schema.version,
2702            outbox: self.outbox.len(),
2703            upgrading: self.upgrading,
2704            lease_state: self.lease_state.clone(),
2705            schema_floor: self.schema_floor.clone(),
2706            sync_needed: self.sync_needed,
2707            previous_version_context: self.previous_version_status(),
2708            security_lifecycle: self.security_lifecycle(),
2709        }
2710    }
2711
2712    /// RFC 0005 A2: container presence for a host that must act on it (Diego's
2713    /// rollback precondition), read without creating the file.
2714    fn previous_version_status(&self) -> PreviousVersionStatus {
2715        let Some(replica_path) = self.previous_version_replica_path() else {
2716            return PreviousVersionStatus {
2717                present: false,
2718                created_at_ms: None,
2719            };
2720        };
2721        match crate::previous_version::read_previous_version_record(&replica_path) {
2722            Ok(Some(record)) => PreviousVersionStatus {
2723                present: true,
2724                created_at_ms: Some(record.created_at_ms),
2725            },
2726            _ => PreviousVersionStatus {
2727                present: std::path::Path::new(
2728                    &crate::previous_version::previous_version_container_path(&replica_path),
2729                )
2730                .exists(),
2731                created_at_ms: None,
2732            },
2733        }
2734    }
2735
2736    /// RFC 0005 D7: read captured rows from the previous local schema. `state`
2737    /// is always `previousVersion`; the container never makes
2738    /// `query_snapshot()` coverage complete. Lease stop/expiry, scope
2739    /// revocation, coverage completion and the TTL DISCARD the container and
2740    /// close the read with their own reason.
2741    pub fn previous_version_snapshot(
2742        &self,
2743        spec: &PreviousVersionReadSpec,
2744    ) -> Result<PreviousVersionSnapshot, String> {
2745        let now_ms = self.clock_now_ms();
2746        crate::previous_version::previous_version_snapshot(
2747            &self.conn,
2748            self.previous_version_replica_path().as_deref(),
2749            self.previous_version.as_ref(),
2750            PreviousVersionLifecycle {
2751                lease_inactive: self.previous_version_lease_inactive(now_ms),
2752                scope_revoked: self
2753                    .stored(load_units(&self.conn))?
2754                    .iter()
2755                    .any(|unit| unit.status == UnitStatus::Revoked),
2756                coverage_complete: self.previous_version_coverage_complete()?,
2757            },
2758            now_ms,
2759            self.schema.version,
2760            spec,
2761        )
2762    }
2763
2764    /// RFC 0005 D6: the advisory pre-reset compatibility audit.
2765    pub fn previous_version_audit(
2766        &self,
2767    ) -> Result<Option<crate::previous_version::PreviousVersionAudit>, String> {
2768        crate::previous_version::stored_previous_version_audit(&self.conn)
2769            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2770    }
2771
2772    /// RFC 0005 A2/D9: the executable downgrade step. Drop the container file
2773    /// and both metadata records, and report whether anything was present.
2774    /// Idempotent: absence is a successful no-op.
2775    pub fn previous_version_discard(
2776        &self,
2777    ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2778        self.drop_previous_version()
2779    }
2780
2781    fn drop_previous_version(
2782        &self,
2783    ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2784        let Some(replica_path) = self.previous_version_replica_path() else {
2785            return Ok(crate::previous_version::PreviousVersionDiscardOutcome {
2786                present: false,
2787                discarded: false,
2788            });
2789        };
2790        crate::previous_version::discard_previous_version(&self.conn, &replica_path)
2791    }
2792
2793    /// RFC 0005 D7: `leaseState.errorCode` or an expired lease.
2794    fn previous_version_lease_inactive(&self, now_ms: i64) -> bool {
2795        let Some(lease) = &self.lease_state else {
2796            return false;
2797        };
2798        if lease.error_code.is_some() {
2799            return true;
2800        }
2801        lease.expires_at_ms.is_some_and(|expires| expires <= now_ms)
2802    }
2803
2804    /// RFC 0005 D7: §7.4.5 replacement coverage — no active unit is
2805    /// bootstrapping. An empty active set is not completion (mirrors the TS
2806    /// predicate exactly).
2807    fn previous_version_coverage_complete(&self) -> Result<bool, String> {
2808        let units = self.stored(load_units(&self.conn))?;
2809        let mut active = units
2810            .iter()
2811            .filter(|unit| unit.status == UnitStatus::Active)
2812            .peekable();
2813        Ok(active.peek().is_some() && !active.any(UnitRecord::bootstrapping))
2814    }
2815
2816    /// RFC 0005 D7: lifetime triggers evaluated once per sync round, after the
2817    /// apply. A container that no longer has a reason to exist is discarded so
2818    /// the rows do not outlive the window they were kept for.
2819    fn previous_version_lifetime_check(&self) {
2820        let Some(config) = self.previous_version.filter(|config| config.enabled) else {
2821            return;
2822        };
2823        let now_ms = self.clock_now_ms();
2824        if self.previous_version_lease_inactive(now_ms) {
2825            let _ = self.drop_previous_version();
2826            return;
2827        }
2828        let Some(replica_path) = self.previous_version_replica_path() else {
2829            return;
2830        };
2831        let Ok(Some(record)) = crate::previous_version::read_previous_version_record(&replica_path)
2832        else {
2833            return;
2834        };
2835        let Ok(units) = load_units(&self.conn) else {
2836            return;
2837        };
2838        if units.iter().any(|unit| unit.status == UnitStatus::Revoked) {
2839            let _ = self.drop_previous_version();
2840            return;
2841        }
2842        if now_ms - record.created_at_ms > config.max_age_ms {
2843            let _ = self.drop_previous_version();
2844            return;
2845        }
2846        if self.previous_version_coverage_complete() == Ok(true) {
2847            let _ = self.drop_previous_version();
2848        }
2849    }
2850
2851    pub fn diagnostics_snapshot(&self) -> Result<ClientDiagnosticsSnapshot, String> {
2852        let registered = self.stored(load_units(&self.conn))?;
2853        // Both meta values in one statement: the FFI host recomputes
2854        // diagnostics after every command.
2855        let (local_revision, replica_cursor): (Option<String>, Option<String>) = self.stored(
2856            self.conn
2857                .prepare_cached(
2858                    "SELECT (SELECT value FROM _syncular_meta WHERE key = ?1),
2859                            (SELECT value FROM _syncular_meta WHERE key = ?2)",
2860                )
2861                .and_then(|mut statement| {
2862                    statement.query_row([LOCAL_REVISION_KEY, REPLICA_CURSOR_KEY], |row| {
2863                        Ok((row.get(0)?, row.get(1)?))
2864                    })
2865                }),
2866        )?;
2867        let mut units = DiagnosticUnits::default();
2868        for unit in &registered {
2869            *match unit.status {
2870                UnitStatus::Revoked => &mut units.revoked,
2871                UnitStatus::Failed => &mut units.failed,
2872                UnitStatus::Active if !unit.bootstrapping() => &mut units.complete,
2873                UnitStatus::Active
2874                    if unit.reason_code.as_deref() == Some("sync.cursor_expired") =>
2875                {
2876                    &mut units.reset
2877                }
2878                UnitStatus::Active => &mut units.bootstrapping,
2879            } += 1;
2880        }
2881        units.reason_codes = registered
2882            .iter()
2883            .filter_map(|unit| unit.reason_code.as_deref().map(Self::diagnostic_code))
2884            .collect::<BTreeSet<_>>()
2885            .into_iter()
2886            .collect();
2887        let captured_at_ms = self.clock_now_ms();
2888        let lease = if let Some(error_code) = self
2889            .lease_state
2890            .as_ref()
2891            .and_then(|state| state.error_code.clone())
2892        {
2893            ClientDiagnosticsLease {
2894                state: "stopped".to_owned(),
2895                expires_at_ms: self
2896                    .lease_state
2897                    .as_ref()
2898                    .and_then(|state| state.expires_at_ms),
2899                error_code: Some(Self::diagnostic_code(&error_code)),
2900            }
2901        } else if let Some(expires_at_ms) = self
2902            .lease_state
2903            .as_ref()
2904            .and_then(|state| state.expires_at_ms)
2905        {
2906            ClientDiagnosticsLease {
2907                state: if expires_at_ms <= captured_at_ms {
2908                    "expired".to_owned()
2909                } else {
2910                    "active".to_owned()
2911                },
2912                expires_at_ms: Some(expires_at_ms),
2913                error_code: None,
2914            }
2915        } else {
2916            ClientDiagnosticsLease {
2917                state: "none".to_owned(),
2918                expires_at_ms: None,
2919                error_code: None,
2920            }
2921        };
2922        let connectivity = match self.last_round.as_ref() {
2923            _ if !self.transport_enabled && self.active_round.is_none() => "offline",
2924            Some(round) if round.status == "succeeded" => "online",
2925            Some(round)
2926                if round.status == "failed"
2927                    && matches!(
2928                        round.cause_kind,
2929                        Some(
2930                            crate::TransportCauseKind::Network | crate::TransportCauseKind::Connect
2931                        )
2932                    ) =>
2933            {
2934                "offline"
2935            }
2936            Some(round) if round.status == "failed" && round.http_status.is_some() => "online",
2937            _ => "unknown",
2938        };
2939        Ok(ClientDiagnosticsSnapshot {
2940            version: CLIENT_DIAGNOSTICS_VERSION,
2941            captured_at_ms,
2942            host: ClientDiagnosticsHost {
2943                kind: "direct".to_owned(),
2944                role: "single".to_owned(),
2945                connectivity: connectivity.to_owned(),
2946                realtime: self.realtime_state,
2947                realtime_policy: self.realtime_policy,
2948                realtime_reason_code: self.realtime_reason_code.clone(),
2949                realtime_retry_delay_ms: self.realtime_retry_delay_ms,
2950            },
2951            security_lifecycle: self.security_lifecycle().to_owned(),
2952            schema: ClientDiagnosticsSchema {
2953                current_version: self.schema.version,
2954                upgrading: self.upgrading,
2955                required_version: self
2956                    .schema_floor
2957                    .as_ref()
2958                    .and_then(|floor| floor.required_schema_version),
2959                latest_version: self
2960                    .schema_floor
2961                    .as_ref()
2962                    .and_then(|floor| floor.latest_schema_version),
2963            },
2964            replica: ClientDiagnosticsReplica {
2965                local_revision: local_revision
2966                    .and_then(|value| value.parse::<u64>().ok())
2967                    .unwrap_or(0)
2968                    .to_string(),
2969                sync_needed: self.sync_needed,
2970                pending_outbox: self.outbox.len(),
2971            },
2972            lease,
2973            active_units: registered
2974                .iter()
2975                .filter(|unit| unit.status == UnitStatus::Active)
2976                .count(),
2977            units,
2978            replica_cursor: replica_cursor.map_or(Ok(-1), |raw| {
2979                raw.parse()
2980                    .map_err(|_| "sync.local_corrupt: persisted unit state is invalid".to_owned())
2981            })?,
2982            last_round: self.last_round.clone(),
2983            last_change: self.last_change.clone(),
2984            storage: self.diagnostics_storage(),
2985            query_failures: self.query_failures.clone(),
2986        })
2987    }
2988
2989    fn diagnostics_storage(&self) -> ClientDiagnosticsStorage {
2990        let read = || -> Result<ClientDiagnosticsStorage, rusqlite::Error> {
2991            let page_count: i64 = self
2992                .conn
2993                .query_row("PRAGMA page_count", [], |row| row.get(0))?;
2994            let page_size: i64 = self
2995                .conn
2996                .query_row("PRAGMA page_size", [], |row| row.get(0))?;
2997            // One cached aggregate, since the FFI host recomputes diagnostics
2998            // after every command; every invocation still reads current storage.
2999            let (outbox_bytes, outcome_entries, outcome_bytes): (i64, i64, i64) = self
3000                .conn
3001                .prepare_cached(
3002                    "SELECT (SELECT COALESCE(SUM(LENGTH(ops_json)), 0) FROM _syncular_outbox),
3003                            COUNT(*), COALESCE(SUM(LENGTH(results_json) + COALESCE(LENGTH(operations_json), 0)), 0)
3004                       FROM _syncular_commit_outcomes",
3005                )?
3006                .query_row([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?;
3007            let blob_bytes = if self.schema_has_blobs() {
3008                self.conn
3009                    .prepare_cached("SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs")?
3010                    .query_row([], |row| row.get(0))?
3011            } else {
3012                0
3013            };
3014            let pressure = self
3015                .limits
3016                .blob_cache_max_bytes
3017                .is_some_and(|limit| blob_bytes > limit);
3018            Ok(ClientDiagnosticsStorage {
3019                status: if pressure { "pressure" } else { "healthy" }.to_owned(),
3020                database_bytes_approx: Some(page_count.saturating_mul(page_size).max(0)),
3021                pending_outbox_bytes_approx: Some(outbox_bytes.max(0)),
3022                retained_outcome_bytes_approx: Some(outcome_bytes.max(0)),
3023                retained_outcome_entries: Some(outcome_entries.max(0)),
3024                blob_cache_bytes_approx: Some(blob_bytes.max(0)),
3025                pressure_reason_code: pressure.then(|| "client.blob_cache_over_limit".to_owned()),
3026            })
3027        };
3028        read().unwrap_or_else(|_| ClientDiagnosticsStorage {
3029            status: "unreadable".to_owned(),
3030            database_bytes_approx: None,
3031            pending_outbox_bytes_approx: None,
3032            retained_outcome_bytes_approx: None,
3033            retained_outcome_entries: None,
3034            blob_cache_bytes_approx: None,
3035            pressure_reason_code: None,
3036        })
3037    }
3038
3039    pub fn drain_change_batches(&mut self) -> Vec<ClientChangeBatch> {
3040        self.change_queue.drain(..).collect()
3041    }
3042
3043    pub fn drain_sync_intents(&mut self) -> Vec<SyncIntent> {
3044        let intents = self.sync_intent_queue.drain(..).collect();
3045        if self.transport_enabled {
3046            intents
3047        } else {
3048            vec![SyncIntent::None]
3049        }
3050    }
3051
3052    fn schedule_background_retry(&mut self) -> u64 {
3053        let delay_ms = self.retry_delay_ms;
3054        self.sync_intent_queue
3055            .push_back(SyncIntent::Background { delay_ms });
3056        self.retry_delay_ms = (self.retry_delay_ms * 2).min(30_000);
3057        self.round_retry_delay_ms = Some(delay_ms);
3058        delay_ms
3059    }
3060
3061    fn reset_background_retry(&mut self) {
3062        self.retry_delay_ms = 250;
3063    }
3064
3065    fn retryable_transport_code(code: &str) -> bool {
3066        code == "transport.failed"
3067            || code == "transport.timeout"
3068            || code == "transport.unavailable"
3069            || code == "sync.transport_failed"
3070    }
3071
3072    /// §1.8: the transport reported a refused or unreachable endpoint. The
3073    /// native transport says `connect` (DNS failure, connection refused,
3074    /// reset, or aborted); a browser fetch transport says `network`. Repeating
3075    /// the request on a backoff repairs neither, so no retry is scheduled.
3076    fn unreachable_transport(details: &Option<serde_json::Value>) -> bool {
3077        matches!(
3078            details
3079                .as_ref()
3080                .and_then(|details| details.get("causeKind"))
3081                .and_then(serde_json::Value::as_str),
3082            Some("connect" | "network")
3083        )
3084    }
3085
3086    /// §1.5: a segment fetch that fails inside an otherwise complete round is
3087    /// invisible to the server (the round response arrived whole), so its code
3088    /// rides the following requests like a socket-round failure. A code the
3089    /// frame grammar rejects is not reportable and the previous code stays.
3090    fn segment_fetch_failed(&mut self, error: TransportError) -> SectionError {
3091        if ssp2::model::valid_round_failure_code(&error.code) {
3092            self.round_failure = Some(error.code.clone());
3093        }
3094        SectionError::Transport(error)
3095    }
3096
3097    /// A failed round worth a background retry: a transport failure, or a
3098    /// §10.2 code the catalog marks retryable (clients may hardcode the
3099    /// catalog metadata, §10.1). Matches the TypeScript core, which retries
3100    /// on the server's `retryable` flag.
3101    fn retryable_failure_code(code: &str) -> bool {
3102        Self::retryable_transport_code(code)
3103            || matches!(
3104                code,
3105                "sync.auth_required"
3106                    | "sync.auth_lease_required"
3107                    | "sync.auth_lease_revoked"
3108                    | "sync.internal_error"
3109                    | "sync.idempotency_cache_miss"
3110                    | "sync.schema_not_ready"
3111                    | "sync.segment_expired"
3112                    | "sync.rate_limited"
3113                    | "sync.websocket_connection_limit"
3114            )
3115    }
3116
3117    fn diagnostic_code(code: &str) -> String {
3118        let valid = !code.is_empty()
3119            && code.len() <= 96
3120            && code.contains('.')
3121            && code
3122                .bytes()
3123                .next()
3124                .is_some_and(|byte| byte.is_ascii_lowercase())
3125            && code.bytes().all(|byte| {
3126                byte.is_ascii_lowercase()
3127                    || byte.is_ascii_digit()
3128                    || matches!(byte, b'.' | b'_' | b'-')
3129            });
3130        if valid {
3131            code.to_owned()
3132        } else {
3133            "client.unknown_failure".to_owned()
3134        }
3135    }
3136
3137    fn set_sync_needed(&mut self, value: bool, interactive: bool) {
3138        if self.sync_needed != value {
3139            if self.begin_observation("syncular_status").is_ok() {
3140                self.sync_needed = value;
3141                let batch = ChangeAccumulator {
3142                    status: true,
3143                    ..ChangeAccumulator::default()
3144                };
3145                if self.finish_observation("syncular_status", batch).is_err() {
3146                    self.rollback_observation("syncular_status");
3147                }
3148            } else {
3149                self.sync_needed = value;
3150            }
3151        }
3152        if value && interactive {
3153            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3154        }
3155    }
3156
3157    /// A unit-store result: a row that does not parse is `sync.local_corrupt`;
3158    /// every other SQLite error keeps its storage classification.
3159    fn stored<T>(&self, result: rusqlite::Result<T>) -> Result<T, String> {
3160        result.map_err(|error| match error {
3161            rusqlite::Error::FromSqlConversionFailure(..) => {
3162                "sync.local_corrupt: persisted unit state is invalid".to_owned()
3163            }
3164            error => Self::sqlite_failure(&self.storage_failure, error),
3165        })
3166    }
3167
3168    fn sqlite_failure(
3169        storage_failure: &RefCell<Option<QueryReadFailure>>,
3170        error: rusqlite::Error,
3171    ) -> String {
3172        let message = error.to_string();
3173        let failure = QueryReadFailure::from(error);
3174        let code = failure.code;
3175        if code.is_some() && storage_failure.borrow().is_none() {
3176            *storage_failure.borrow_mut() = Some(failure);
3177        }
3178        match code {
3179            Some(code) => format!("{code}: {message}"),
3180            None => message,
3181        }
3182    }
3183
3184    fn begin_observation(&self, name: &str) -> Result<(), String> {
3185        if let Some(failure) = &self.coalesced_failure {
3186            return Err(failure.clone());
3187        }
3188        // SQLite rolls a whole transaction back on some I/O and capacity
3189        // errors; later frames must not commit on their own after that.
3190        if self.coalesced.is_some() && self.conn.is_autocommit() {
3191            return Err("the coalesced apply transaction was rolled back".to_owned());
3192        }
3193        self.conn
3194            .execute_batch(&format!("SAVEPOINT {name}"))
3195            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3196    }
3197
3198    /// SPEC §1.4 rule 4: open a coalesced apply transaction unless a caller
3199    /// already owns one.
3200    fn begin_coalesced_apply(&mut self) -> Result<(), String> {
3201        if self.coalesced.is_some() || !self.conn.is_autocommit() {
3202            return Ok(());
3203        }
3204        self.conn
3205            .execute_batch("BEGIN")
3206            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3207        self.coalesced = Some(CoalescedApply {
3208            rows: 0,
3209            rollback: self.capture(),
3210        });
3211        Ok(())
3212    }
3213
3214    fn capture(&self) -> Rollback {
3215        Rollback {
3216            outbox: self.outbox.clone(),
3217            failed_commits: self.failed_commits.clone(),
3218            conflicts: self.conflicts.clone(),
3219            rejections: self.rejections.clone(),
3220            schema_floor: self.schema_floor.clone(),
3221            lease_state: self.lease_state.clone(),
3222            stopped: self.stopped,
3223            upgrading: self.upgrading,
3224            sync_needed: self.sync_needed,
3225            active_round: self.active_round,
3226            overlay_dirty: self.overlay_dirty.snapshot(),
3227            change_queue: self.change_queue.len(),
3228            sync_intent_queue: self.sync_intent_queue.len(),
3229            last_change: self.last_change.clone(),
3230        }
3231    }
3232
3233    fn restore(&mut self, rollback: Rollback) {
3234        self.outbox = rollback.outbox;
3235        self.failed_commits = rollback.failed_commits;
3236        self.conflicts = rollback.conflicts;
3237        self.rejections = rollback.rejections;
3238        self.schema_floor = rollback.schema_floor;
3239        self.lease_state = rollback.lease_state;
3240        self.stopped = rollback.stopped;
3241        self.upgrading = rollback.upgrading;
3242        self.sync_needed = rollback.sync_needed;
3243        self.active_round = rollback.active_round;
3244        self.overlay_dirty.restore(rollback.overlay_dirty);
3245        self.change_queue.truncate(rollback.change_queue);
3246        self.sync_intent_queue.truncate(rollback.sync_intent_queue);
3247        self.last_change = rollback.last_change;
3248    }
3249
3250    /// Account the rows of the next frame or block. A unit that would take the
3251    /// coalesced transaction past the bound commits the earlier units first.
3252    fn coalesce_unit(&mut self, rows: usize) -> Result<(), String> {
3253        let Some(open) = &self.coalesced else {
3254            return Ok(());
3255        };
3256        if open.rows > 0 && open.rows + rows > COALESCED_APPLY_ROWS {
3257            self.commit_coalesced_apply()?;
3258            self.begin_coalesced_apply()?;
3259        }
3260        if let Some(open) = &mut self.coalesced {
3261            open.rows += rows;
3262        }
3263        Ok(())
3264    }
3265
3266    /// COMMIT the coalesced transaction. A failed COMMIT rolls every coalesced
3267    /// frame back, restores the in-memory state of its `BEGIN`, drops the
3268    /// change batches and sync intents queued since, and fails the rest of the
3269    /// response.
3270    fn commit_coalesced_apply(&mut self) -> Result<(), String> {
3271        let Some(open) = self.coalesced.take() else {
3272            return Ok(());
3273        };
3274        let committed = if self.conn.is_autocommit() {
3275            Err("the coalesced apply transaction was rolled back".to_owned())
3276        } else {
3277            self.conn
3278                .execute_batch("COMMIT")
3279                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3280        };
3281        let Err(error) = committed else {
3282            return Ok(());
3283        };
3284        if !self.conn.is_autocommit() {
3285            if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3286                let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3287            }
3288        }
3289        self.restore(open.rollback);
3290        self.coalesced_failure = Some(error.clone());
3291        Err(error)
3292    }
3293
3294    /// End the response's coalescing: COMMIT what is open and clear a failure.
3295    fn finish_coalesced_apply(&mut self) -> Result<(), String> {
3296        let committed = self.commit_coalesced_apply();
3297        match self.coalesced_failure.take() {
3298            Some(failure) => Err(failure),
3299            None => committed,
3300        }
3301    }
3302
3303    fn rollback_observation(&self, name: &str) {
3304        if let Err(error) = self
3305            .conn
3306            .execute_batch(&format!("ROLLBACK TO {name}; RELEASE {name}"))
3307        {
3308            if let Some(failure) = self.storage_failure.borrow_mut().as_mut() {
3309                if failure.rollback_failure.is_none() {
3310                    failure.rollback_failure = Some(Box::new(QueryReadFailure::from(error)));
3311                }
3312            }
3313        }
3314    }
3315
3316    fn finish_observation(
3317        &mut self,
3318        name: &str,
3319        mut batch: ChangeAccumulator,
3320    ) -> Result<(), String> {
3321        #[cfg(feature = "bench-internals")]
3322        let _phase = self.benchmark_phases.start(Phase::ObservationCommit);
3323        if self.failed_commits.iter().any(|(commit, _)| {
3324            commit
3325                .ops
3326                .iter()
3327                .any(|operation| batch.tables.contains_key(&operation.table))
3328        }) {
3329            batch.outcomes = true;
3330        }
3331        if !batch.touched() {
3332            self.conn
3333                .execute_batch(&format!("RELEASE {name}"))
3334                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3335            return Ok(());
3336        }
3337        let revision = self
3338            .local_revision()?
3339            .checked_add(1)
3340            .ok_or_else(|| "local revision exhausted u64".to_owned())?;
3341        self.conn
3342            .execute(
3343                "INSERT OR REPLACE INTO _syncular_meta(key, value) VALUES (?1, ?2)",
3344                rusqlite::params![LOCAL_REVISION_KEY, revision.to_string()],
3345            )
3346            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3347        let status = batch.status.then(|| self.status_snapshot());
3348        let event = ClientChangeBatch {
3349            revision: revision.to_string(),
3350            tables: batch
3351                .tables
3352                .into_iter()
3353                .map(|(table, scope_keys)| TableChange {
3354                    table,
3355                    scope_keys: scope_keys.map(|keys| keys.into_iter().collect()),
3356                })
3357                .collect(),
3358            windows: batch
3359                .windows
3360                .into_iter()
3361                .map(|(base_key, units)| WindowChange {
3362                    base_key,
3363                    units: units.into_iter().collect(),
3364                })
3365                .collect(),
3366            status,
3367            conflicts_changed: batch.conflicts,
3368            rejections_changed: batch.rejections,
3369            outcomes_changed: batch.outcomes,
3370            applied_commits: Vec::new(),
3371        };
3372        self.conn
3373            .execute_batch(&format!("RELEASE {name}"))
3374            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3375        let mut diagnostic_tables = event
3376            .tables
3377            .iter()
3378            .map(|entry| entry.table.clone())
3379            .collect::<BTreeSet<_>>()
3380            .into_iter()
3381            .collect::<Vec<_>>();
3382        // §7.6: the selected variables of the changed window bases.
3383        let mut diagnostic_windows = event
3384            .windows
3385            .iter()
3386            .map(|entry| {
3387                entry
3388                    .base_key
3389                    .split('\0')
3390                    .next()
3391                    .unwrap_or_default()
3392                    .to_owned()
3393            })
3394            .collect::<BTreeSet<_>>()
3395            .into_iter()
3396            .collect::<Vec<_>>();
3397        let domains_truncated = diagnostic_tables.len() > MAX_DIAGNOSTIC_DOMAINS
3398            || diagnostic_windows.len() > MAX_DIAGNOSTIC_DOMAINS;
3399        diagnostic_tables.truncate(MAX_DIAGNOSTIC_DOMAINS);
3400        diagnostic_windows.truncate(MAX_DIAGNOSTIC_DOMAINS);
3401        self.last_change = Some(DiagnosticLastChange {
3402            revision: event.revision.clone(),
3403            recorded_at_ms: self.clock_now_ms(),
3404            tables: diagnostic_tables,
3405            windows: diagnostic_windows,
3406            domains_truncated,
3407            status_changed: event.status.is_some(),
3408            conflicts_changed: event.conflicts_changed,
3409            rejections_changed: event.rejections_changed,
3410            outcomes_changed: event.outcomes_changed,
3411        });
3412        self.change_queue.push_back(event);
3413        Ok(())
3414    }
3415
3416    fn record_scope_map(
3417        &self,
3418        batch: &mut ChangeAccumulator,
3419        table_name: &str,
3420        scopes: &[(String, Vec<String>)],
3421    ) {
3422        let Some(table) = self.schema.table(table_name) else {
3423            return;
3424        };
3425        // A bulk scoped delete whose map leaves a declared variable unnamed
3426        // cannot list the deleted rows' keys for it: the change is table-wide.
3427        if table.scope_variables.iter().any(|scope| {
3428            !scopes
3429                .iter()
3430                .any(|(variable, _)| *variable == scope.variable)
3431        }) {
3432            batch.table(table_name);
3433            return;
3434        }
3435        for (variable, values) in scopes {
3436            let Some(scope) = table
3437                .scope_variables
3438                .iter()
3439                .find(|scope| &scope.variable == variable)
3440            else {
3441                continue;
3442            };
3443            for value in values {
3444                batch.scope(table_name, format!("{}:{value}", scope.prefix));
3445            }
3446        }
3447    }
3448
3449    /// Record a row's current scope keys from the base or visible table.
3450    fn record_row_scopes(
3451        &self,
3452        batch: &mut ChangeAccumulator,
3453        table_name: &str,
3454        row_id: &str,
3455        base: bool,
3456    ) -> bool {
3457        let Some(table) = self.schema.table(table_name) else {
3458            return false;
3459        };
3460        if table.scope_variables.is_empty() {
3461            return false;
3462        }
3463        let columns = table
3464            .scope_variables
3465            .iter()
3466            .map(|scope| quote_ident(&scope.column))
3467            .collect::<Vec<_>>()
3468            .join(", ");
3469        let full_table = if base {
3470            base_table(table_name)
3471        } else {
3472            visible_table(table_name)
3473        };
3474        let sql = format!(
3475            "SELECT {columns} FROM {full_table} WHERE {} LIMIT 1",
3476            row_id_predicate(table)
3477        );
3478        let Ok(mut stmt) = self.conn.prepare_cached(&sql) else {
3479            return false;
3480        };
3481        let values = stmt.query_row(rusqlite::params![row_id], |row| {
3482            let mut values = Vec::with_capacity(table.scope_variables.len());
3483            for index in 0..table.scope_variables.len() {
3484                values.push(row.get::<_, Option<String>>(index)?);
3485            }
3486            Ok(values)
3487        });
3488        let Ok(values) = values else {
3489            return false;
3490        };
3491        let mut recorded = false;
3492        for (scope, value) in table.scope_variables.iter().zip(values) {
3493            if let Some(value) = value {
3494                batch.scope(table_name, format!("{}:{value}", scope.prefix));
3495                recorded = true;
3496            }
3497        }
3498        recorded
3499    }
3500
3501    fn record_commit_changes(
3502        &self,
3503        batch: &mut ChangeAccumulator,
3504        tables: &[String],
3505        changes: &[ssp2::model::Change],
3506    ) {
3507        #[cfg(feature = "bench-internals")]
3508        let _phase = self.benchmark_phases.start(Phase::ObservationPrepare);
3509        for change in changes {
3510            let Some(table_name) = tables.get(change.table_index as usize) else {
3511                continue;
3512            };
3513            let mut precise = self.record_row_scopes(batch, table_name, &change.row_id, true);
3514            if let Some(table) = self.schema.table(table_name) {
3515                for (variable, value) in &change.scopes {
3516                    if let Some(scope) = table
3517                        .scope_variables
3518                        .iter()
3519                        .find(|scope| &scope.variable == variable)
3520                    {
3521                        batch.scope(table_name, format!("{}:{value}", scope.prefix));
3522                        precise = true;
3523                    }
3524                }
3525            }
3526            if !precise {
3527                batch.table(table_name);
3528            }
3529        }
3530    }
3531
3532    /// Whether a base or visible row matches the scope predicate; `false`
3533    /// without a local scope-column mapping. A SQLite failure is an error.
3534    fn scoped_rows_exist(
3535        &self,
3536        table_name: &str,
3537        effective: &[(String, Vec<String>)],
3538        owners: &[Vec<(String, Vec<String>)>],
3539    ) -> Result<bool, String> {
3540        let Some(table) = self.schema.table(table_name) else {
3541            return Ok(false);
3542        };
3543        let Ok(Some((predicate, params))) = local_scope_predicate(table, effective, owners) else {
3544            return Ok(false);
3545        };
3546        for source in [base_table(table_name), visible_table(table_name)] {
3547            if self
3548                .conn
3549                .query_row(
3550                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
3551                    rusqlite::params_from_iter(&params),
3552                    |row| row.get::<_, bool>(0),
3553                )
3554                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
3555            {
3556                return Ok(true);
3557            }
3558        }
3559        Ok(false)
3560    }
3561
3562    /// §5.6 first-page clear of `unit_id`'s pair: delete its rows except
3563    /// those another owner covers (§3.3), failing closed without a local
3564    /// scope-column mapping. Owners are read only when a row matches, inside
3565    /// the caller's transaction. Returns whether rows matched.
3566    fn clear_scope(
3567        &mut self,
3568        table: &TableSchema,
3569        effective: &[(String, Vec<String>)],
3570        unit_id: &str,
3571    ) -> Result<bool, SectionError> {
3572        let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
3573        let matched = self
3574            .scoped_rows_exist(&table.name, effective, &[])
3575            .map_err(storage)?;
3576        let owners = if matched {
3577            unit_owners(
3578                &self.stored(load_units(&self.conn)).map_err(storage)?,
3579                table,
3580                unit_id,
3581            )
3582        } else {
3583            Vec::new()
3584        };
3585        let changed = matched
3586            && (owners.is_empty()
3587                || self
3588                    .scoped_rows_exist(&table.name, effective, &owners)
3589                    .map_err(storage)?);
3590        if !self
3591            .purge_scope_rows(&table.name, effective, &owners)
3592            .map_err(storage)?
3593        {
3594            return Err(SectionError::FailClosed);
3595        }
3596        Ok(changed)
3597    }
3598
3599    /// §7.4.5: true while a schema-bump reset + first re-bootstrap runs.
3600    pub fn upgrading(&self) -> bool {
3601        self.upgrading
3602    }
3603
3604    /// §7.4.2 "app ships new code": swap to a NEW generated schema while
3605    /// keeping this client's local database (identity, outbox, tables). The
3606    /// §7.4.1 marker check then fires the wipe/re-bootstrap flow when the
3607    /// version increases. Recreation runs the same marker guard as opening
3608    /// a durable replica, holds the guard and every write it authorizes under
3609    /// one write transaction, and preserves the current client (compiled
3610    /// schema, outbox, tables) on refusal.
3611    pub fn recreate_with_schema(&mut self, schema_json: &Value) -> Result<(), String> {
3612        let new_schema = parse_schema_json(schema_json)?;
3613        validate_authority_reads(&new_schema, &self.limits.authority_reads)?;
3614        self.conn
3615            .execute_batch("BEGIN IMMEDIATE")
3616            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3617        let prior_schema = std::mem::replace(&mut self.schema, new_schema);
3618        // §7.4.3/§7.4.4: a reset inside this transaction mutates in-memory
3619        // state (dropped outbox commits, rejections, upgrade and floor flags,
3620        // overlay dirtiness) and appends change/intent batches. A COMMIT that
3621        // fails after the reset succeeded rolls the database back, so every
3622        // one of those fields is captured here and restored with it.
3623        let rollback = self.capture();
3624        let guarded = (|| -> Result<(), String> {
3625            // §7.4.2: the marker is re-read under the write lock the caller
3626            // holds, so a replica another process upgraded meanwhile refuses
3627            // this recreation instead of having its marker and tables
3628            // downgraded.
3629            let marker = read_local_schema_version(&self.conn, self.schema.version)?;
3630            self.create_bookkeeping_tables()?;
3631            match marker {
3632                Some(version) if version < self.schema.version => self.run_schema_reset()?,
3633                None => {
3634                    self.create_synced_tables()?;
3635                    self.persist_schema_version()?;
3636                }
3637                _ => {}
3638            }
3639            // §7.4.2: recreation IS the boot for the in-memory core, so reload the
3640            // durable outbox the same-version path is about to replay. Only the
3641            // outbox is reloaded: the recovery below reads it, and the caller's
3642            // rollback snapshot already covers this field.
3643            self.outbox = self.load_outbox()?.into();
3644            // §7.1/§7.4.4: recover intrinsically codec-invalid persisted values at
3645            // this guarded boundary once the schema and marker agree. A bump went
3646            // through `run_schema_reset`, which performs the same recovery after
3647            // it creates the new physical tables and before its final replay.
3648            self.drop_unencodable_outbox(false, None)?;
3649            if marker == Some(self.schema.version)
3650                && (!self.outbox.is_empty()
3651                    || !self.failed_commits.is_empty()
3652                    || self.has_acknowledged_rows()?)
3653            {
3654                self.overlay_dirty.set(true);
3655                self.rebuild_overlay()?;
3656            }
3657            self.prune_unknown_units(false)?;
3658            self.save_unit_scope_schema()?;
3659            // The conformance recreate is the in-memory equivalent of reopening
3660            // a durable client. Apply the same startup catch-up contract even
3661            // when the schema itself did not change.
3662            self.enqueue_startup_sync_if_needed()?;
3663            Ok(())
3664        })();
3665        let outcome = match guarded {
3666            Ok(()) => self
3667                .conn
3668                .execute_batch("COMMIT")
3669                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error)),
3670            Err(error) => Err(error),
3671        };
3672        if let Err(error) = outcome {
3673            if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3674                // Keep a failed rollback's typed storage classification.
3675                let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3676            }
3677            self.schema = prior_schema;
3678            self.restore(rollback);
3679            // Prepared insert statements were derived from the reverted schema.
3680            self.insert_sql.borrow_mut().clear();
3681            return Err(error);
3682        }
3683        if !self.security_preflight {
3684            self.drain_pending_evictions()?;
3685        }
3686        Ok(())
3687    }
3688
3689    fn enqueue_startup_sync_if_needed(&mut self) -> Result<(), String> {
3690        let startup_work = !self.stopped
3691            && (!self.outbox.is_empty()
3692                || self.has_acknowledged_rows()?
3693                || !self.load_pending_evictions()?.is_empty()
3694                || self
3695                    .stored(load_units(&self.conn))?
3696                    .iter()
3697                    .any(|unit| unit.status == UnitStatus::Active));
3698        if startup_work {
3699            self.sync_needed = true;
3700            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3701        }
3702        Ok(())
3703    }
3704
3705    /// A native client persists schema-floor stops across process restarts.
3706    /// Once the running app already satisfies that floor, the persisted stop
3707    /// is only stale evidence from an older server round (for example, the
3708    /// server was restarted after catching up to an app that was ahead).
3709    /// Clear it and let the normal startup pull re-negotiate. If the server is
3710    /// still incompatible it will return the floor again in that first round.
3711    fn clear_satisfied_persisted_schema_floor(&mut self) -> Result<(), String> {
3712        let satisfied = self
3713            .schema_floor
3714            .as_ref()
3715            .and_then(|floor| floor.required_schema_version)
3716            .is_some_and(|required| self.schema.version >= required);
3717        if !satisfied {
3718            return Ok(());
3719        }
3720        self.delete_meta(SCHEMA_FLOOR_KEY)?;
3721        self.schema_floor = None;
3722        self.stopped = false;
3723        Ok(())
3724    }
3725
3726    /// RFC 0005 D1: discard an orphan or stale container at boot. The reset
3727    /// path already swept it; this covers a same-version or fresh-install open,
3728    /// which runs no reset and therefore no sweep — plus the D7 TTL, which only
3729    /// an aware binary can apply.
3730    fn reconcile_previous_version_at_boot(&self) -> Result<(), String> {
3731        let Some(replica_path) = self.previous_version_replica_path() else {
3732            return Ok(());
3733        };
3734        let max_age_ms = self
3735            .previous_version
3736            .filter(|config| config.enabled)
3737            .map(|config| config.max_age_ms);
3738        reconcile_previous_version_at_boot(
3739            &self.conn,
3740            &replica_path,
3741            self.schema.version,
3742            max_age_ms,
3743            self.clock_now_ms(),
3744        )
3745    }
3746
3747    /// RFC 0005 D3: the sibling container path, or `None` when the replica has
3748    /// no file — an in-memory replica returns an empty path, and a `file:` URI
3749    /// has no plain sibling path — so the feature resolves as off there.
3750    fn previous_version_replica_path(&self) -> Option<String> {
3751        let path = self.conn.path()?;
3752        if path.is_empty() || path.starts_with("file:") {
3753            return None;
3754        }
3755        Some(path.to_owned())
3756    }
3757
3758    /// §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
3759    /// and leaseState. Drops/recreates every synced table from the new
3760    /// schema, resets unit sync state (keeping registrations), clears
3761    /// the schema-floor stop state, rewrites the marker, drops outbox commits
3762    /// that cannot re-encode (§7.4.4), and replays the survivors on top.
3763    fn run_schema_reset(&mut self) -> Result<(), String> {
3764        self.begin_observation("syncular_schema_reset")?;
3765        let rollback = self.capture();
3766        let mut batch = ChangeAccumulator::default();
3767        let result = self
3768            .run_schema_reset_observed(&mut batch, true)
3769            .and_then(|()| self.finish_observation("syncular_schema_reset", batch));
3770        if let Err(error) = result {
3771            self.rollback_observation("syncular_schema_reset");
3772            self.restore(rollback);
3773            return Err(error);
3774        }
3775        Ok(())
3776    }
3777
3778    fn run_log_epoch_reset(&mut self, log_epoch: &str) -> Result<Vec<String>, String> {
3779        if self.get_meta(LOG_EPOCH_KEY)?.is_none() {
3780            self.begin_observation("syncular_epoch_acquisition")?;
3781            let rollback = self.capture();
3782            if let Err(error) = self.conn.execute(
3783                "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3784                rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3785            ) {
3786                self.rollback_observation("syncular_epoch_acquisition");
3787                return Err(Self::sqlite_failure(&self.storage_failure, error));
3788            }
3789            self.sync_needed = true;
3790            let batch = ChangeAccumulator {
3791                status: true,
3792                ..ChangeAccumulator::default()
3793            };
3794            if let Err(error) = self.finish_observation("syncular_epoch_acquisition", batch) {
3795                self.rollback_observation("syncular_epoch_acquisition");
3796                self.restore(rollback);
3797                return Err(error);
3798            }
3799            self.sync_intent_queue.push_back(SyncIntent::Interactive);
3800            return Ok(Vec::new());
3801        }
3802        let resets = self
3803            .stored(load_units(&self.conn))?
3804            .into_iter()
3805            .map(|unit| unit.id)
3806            .collect();
3807        self.begin_observation("syncular_log_epoch_reset")?;
3808        let rollback = self.capture();
3809        let mut batch = ChangeAccumulator::default();
3810        let result = self
3811            .run_schema_reset_observed(&mut batch, false)
3812            .and_then(|()| {
3813                self.conn
3814                    .execute(
3815                        "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3816                        rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3817                    )
3818                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3819                self.sync_needed = true;
3820                batch.status = true;
3821                self.finish_observation("syncular_log_epoch_reset", batch)
3822            });
3823        if let Err(error) = result {
3824            self.rollback_observation("syncular_log_epoch_reset");
3825            self.restore(rollback);
3826            return Err(error);
3827        }
3828        self.sync_intent_queue.push_back(SyncIntent::Interactive);
3829        Ok(resets)
3830    }
3831
3832    fn run_schema_reset_observed(
3833        &mut self,
3834        batch: &mut ChangeAccumulator,
3835        capture: bool,
3836    ) -> Result<(), String> {
3837        // §7.4.2: the reset is the only path that wipes local tables for a
3838        // version bump, and it rewrites the marker last. Re-read the marker
3839        // under this reset's transaction: a replica another process upgraded
3840        // meanwhile refuses here instead of being reset to this client's
3841        // older schema.
3842        read_local_schema_version(&self.conn, self.schema.version)?;
3843        self.conn
3844            .execute_batch(
3845                "DELETE FROM _syncular_acked_rows; DELETE FROM _syncular_row_deliveries;",
3846            )
3847            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3848        self.cancel_sync_round();
3849        self.upgrading = true;
3850        batch.status = true;
3851        // RFC 0005 D6: classify the pending outbox against the NEW compiled
3852        // schema BEFORE the wipe, and record the advisory audit. This pass
3853        // drops nothing, so the audit sees the original pending intent; the
3854        // §7.4.4 send-time drop and the intrinsic value recovery later in this
3855        // reset are the paths that remove a commit. The classification is
3856        // shared with the send-time drop so the two cannot disagree about what
3857        // is incompatible.
3858        if self.previous_version.is_some_and(|config| config.enabled) {
3859            let previous_version = self
3860                .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
3861                .and_then(|value| value.parse::<i32>().ok())
3862                .unwrap_or(self.schema.version);
3863            let pending = self
3864                .outbox
3865                .iter()
3866                .map(|commit| PendingCommitAudit {
3867                    commit_id: &commit.client_commit_id,
3868                    operations: commit_audit_operations(commit),
3869                })
3870                .collect::<Vec<_>>();
3871            crate::previous_version::write_previous_version_audit(
3872                &self.conn,
3873                &crate::previous_version::build_previous_version_audit(
3874                    &self.schema,
3875                    &pending,
3876                    previous_version,
3877                    self.schema.version,
3878                    self.clock_now_ms(),
3879                ),
3880            )?;
3881        }
3882        // RFC 0005 D5: the container lives in its own FILE, so the reset can
3883        // never reach it. Sweep first (unconditional — also on the log-epoch
3884        // reset, which captures nothing), then capture BEFORE the wipe drops
3885        // any row. A refused capture records its reason and leaves no file.
3886        if let Some(replica_path) = self.previous_version_replica_path() {
3887            sweep_previous_version_container(&self.conn, &replica_path)?;
3888            if capture {
3889                if let Some(config) = self.previous_version.filter(|config| config.enabled) {
3890                    let previous_version = self
3891                        .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
3892                        .and_then(|value| value.parse::<i32>().ok())
3893                        .unwrap_or(self.schema.version);
3894                    capture_previous_version_from_replica(
3895                        &self.conn,
3896                        &replica_path,
3897                        previous_version,
3898                        self.schema.version,
3899                        &config,
3900                        self.clock_now_ms(),
3901                    )?;
3902                }
3903            }
3904        }
3905        for table in &self.schema.tables {
3906            batch.table(&table.name);
3907        }
3908        for (base_key, value) in self.load_window_registry()? {
3909            batch.window(&base_key, &value);
3910        }
3911        if capture {
3912            self.prune_unknown_units(true)?;
3913        }
3914        // The per-table insert SQL is derived from the OLD column lists.
3915        self.insert_sql.borrow_mut().clear();
3916        self.overlay_dirty.set(true);
3917        // Drop every synced table (base + visible) that currently exists —
3918        // discovered from sqlite_master so a bump that adds/removes tables is
3919        // handled. Bookkeeping tables (`_syncular_outbox/_units/_meta`
3920        // and the blob cache) are preserved; base tables are `_syncular_base_*`
3921        // so they are matched explicitly, not by the bookkeeping filter.
3922        // Drop virtual tables first so SQLite removes every FTS shadow table
3923        // atomically instead of the generic discovery tearing it apart.
3924        let virtual_tables: Vec<String> = {
3925            let mut stmt = self
3926                .conn
3927                .prepare(
3928                    "SELECT name FROM sqlite_master WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%'",
3929                )
3930                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3931            let rows = stmt
3932                .query_map([], |row| row.get::<_, String>(0))
3933                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3934            rows.filter_map(Result::ok)
3935                .filter(|name| is_synced_table_name(name))
3936                .collect()
3937        };
3938        for name in virtual_tables {
3939            self.conn
3940                .execute_batch(&format!(
3941                    "DROP TABLE IF EXISTS {}",
3942                    quote_ident(&format!("_syncular_fts_{name}"))
3943                ))
3944                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3945            self.conn
3946                .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
3947                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3948        }
3949        let existing: Vec<String> = {
3950            let mut stmt = self
3951                .conn
3952                .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
3953                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3954            let rows = stmt
3955                .query_map([], |row| row.get::<_, String>(0))
3956                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3957            rows.filter_map(Result::ok)
3958                .filter(|name| is_synced_table_name(name))
3959                .collect()
3960        };
3961        for name in &existing {
3962            if let Some(table) = name.strip_prefix("_syncular_base_") {
3963                batch.table(table);
3964            } else if !name.starts_with("_syncular_") {
3965                batch.table(name);
3966            }
3967        }
3968        for name in existing {
3969            self.conn
3970                .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
3971                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3972        }
3973        // Recreate the synced tables from the NEW schema.
3974        self.create_synced_tables()?;
3975        // Reset every unit's sync state, keeping the registration.
3976        reset_units(&self.conn)
3977            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3978        // The stop state is over: this client now ships a servable schema.
3979        self.stopped = false;
3980        self.schema_floor = None;
3981        self.delete_meta(SCHEMA_FLOOR_KEY)?;
3982        // Rewrite the marker LAST so a crash mid-reset re-runs the reset.
3983        self.persist_schema_version()?;
3984        self.save_unit_scope_schema()?;
3985        // §7.1/§7.4.4: the previous-version capture and audit above saw the
3986        // original pending intent; the synced tables now carry the new schema, so
3987        // recover intrinsically codec-invalid persisted values here, before the
3988        // final replay. A pending upsert that names a column the new schema
3989        // removed stays pending for the send-time `drop_incompatible_outbox`
3990        // prepass. The reset wrapper snapshots and restores the outbox,
3991        // rejections, and change queues, so a failed commit rolls this recovery
3992        // back with the rest of the reset.
3993        // §7.4.4: the enclosing reset observation owns the publication, so the
3994        // recovery contributes its rejection, outcome, and table domains to it.
3995        self.drop_unencodable_outbox(false, Some(batch))?;
3996        // Re-apply the surviving outbox optimistically over the empty tables.
3997        self.rebuild_overlay()?;
3998        Ok(())
3999    }
4000
4001    /// §7.4.4 send-time prepass: a persisted upsert whose values reference a
4002    /// column the current schema lacks (or a removed table) cannot be encoded
4003    /// (`commit_audit_operations` inspects upserts, so a value-free delete stays
4004    /// encodable and is validated by the server), nor can an insert-intent
4005    /// upsert that lacks a non-nullable column (§7.1, the audit's
4006    /// `missing-required-column`). Drop the commit, undo
4007    /// its optimistic projection, and raise a client-local
4008    /// `sync.outbox_incompatible` rejection.
4009    fn drop_incompatible_outbox(&mut self) -> Result<bool, String> {
4010        let incompatible = self
4011            .outbox
4012            .iter()
4013            .filter(|commit| {
4014                first_incompatibility(&self.schema, &commit_audit_operations(commit)).is_some()
4015            })
4016            .cloned()
4017            .collect::<Vec<_>>();
4018        if incompatible.is_empty() {
4019            return Ok(false);
4020        }
4021        self.drop_outbox_commits(
4022            &incompatible,
4023            OUTBOX_INCOMPATIBLE_CODE,
4024            "the persisted commit cannot encode under the current schema",
4025        )?;
4026        Ok(true)
4027    }
4028
4029    /// §7.4.4 incompatible-commit path, also taken by a refused blob upload
4030    /// (§5.9.7) with the server's code: reject every operation of `commits`,
4031    /// remove them from the outbox, and undo their optimistic rows.
4032    fn drop_outbox_commits(
4033        &mut self,
4034        incompatible: &[Arc<OutboxCommit>],
4035        code: &str,
4036        message: &str,
4037    ) -> Result<(), String> {
4038        // §7.4.4: one observation covers the durable outcome writes, the outbox
4039        // removal, the in-memory drop, and the overlay rebuild, so a storage
4040        // fault leaves the replica and the client unchanged and publishes no
4041        // change; a successful drop publishes exactly one batch carrying the
4042        // rejections, outcomes, status, and the tables whose projection changed.
4043        let rollback = self.capture();
4044        let owns_transaction = self.conn.is_autocommit();
4045        self.begin_observation("syncular_outbox_drop")?;
4046        let mut batch = ChangeAccumulator::default();
4047        let dropped = (|| -> Result<(), String> {
4048            let mut rejections = Vec::new();
4049            for commit in incompatible {
4050                let results = commit
4051                    .ops
4052                    .iter()
4053                    .enumerate()
4054                    .map(|(op_index, operation)| {
4055                        let rejection = RejectionRecord {
4056                            client_commit_id: commit.client_commit_id.clone(),
4057                            op_index: op_index as i32,
4058                            code: code.to_owned(),
4059                            message: message.to_owned(),
4060                            retryable: false,
4061                            details: None,
4062                            operation: Some(CommitOperation::from(operation)),
4063                        };
4064                        rejections.push(rejection.clone());
4065                        CommitOperationOutcome::Error { rejection }
4066                    })
4067                    .collect::<Vec<_>>();
4068                self.persist_commit_outcome(
4069                    &commit.client_commit_id,
4070                    CommitOutcomeStatus::Rejected,
4071                    &results,
4072                    Some(&commit.ops),
4073                )?;
4074                self.delete_outbox_persisted(&commit.client_commit_id)?;
4075                // A removed table has no local projection to invalidate; every
4076                // surviving table the dropped commit touched does.
4077                for operation in &commit.ops {
4078                    if self.schema.table(&operation.table).is_some() {
4079                        batch.table(&operation.table);
4080                    }
4081                }
4082            }
4083            self.prune_commit_outcomes()?;
4084            let incompatible_ids = incompatible
4085                .iter()
4086                .map(|commit| commit.client_commit_id.as_str())
4087                .collect::<BTreeSet<_>>();
4088            self.outbox
4089                .retain(|commit| !incompatible_ids.contains(commit.client_commit_id.as_str()));
4090            self.rejections.extend(rejections);
4091            // The dropped commits' purely-optimistic rows are undone: the
4092            // visible projection is re-derived from the surviving base + outbox.
4093            self.overlay_dirty.set(true);
4094            self.rebuild_overlay()?;
4095            batch.status = true;
4096            batch.rejections = true;
4097            batch.outcomes = true;
4098            Ok(())
4099        })();
4100        let result = dropped.and_then(|()| self.finish_observation("syncular_outbox_drop", batch));
4101        if let Err(error) = result {
4102            // An outer RELEASE is the COMMIT. Roll back that transaction
4103            // directly: retrying RELEASE after ROLLBACK TO still needs the
4104            // reader's lock. A nested observation only rolls back its savepoint.
4105            if owns_transaction {
4106                if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
4107                    let mut failure = self.storage_failure.borrow_mut();
4108                    let failure =
4109                        failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
4110                    failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
4111                }
4112            } else {
4113                self.rollback_observation("syncular_outbox_drop");
4114            }
4115            self.restore(rollback);
4116            return Err(error);
4117        }
4118        Ok(())
4119    }
4120
4121    /// §7.4.3: (re)create the base + visible table pair for every synced
4122    /// table in the CURRENT schema (idempotent — `IF NOT EXISTS`).
4123    fn create_synced_tables(&self) -> Result<(), String> {
4124        for table in &self.schema.tables {
4125            // The base half + the visible half form the synced-table pair. An
4126            // index name is global in SQLite, so the base half's indexes are
4127            // name-prefixed (`_syncular_base_<index>`) to stay distinct.
4128            for (full, index_prefix) in [
4129                (base_table(&table.name), "_syncular_base_"),
4130                (visible_table(&table.name), ""),
4131            ] {
4132                let mut cols: Vec<String> =
4133                    table.columns.iter().map(|c| quote_ident(&c.name)).collect();
4134                cols.push("\"_syncular_version\" INTEGER NOT NULL".to_owned());
4135                let sql = format!(
4136                    "CREATE TABLE IF NOT EXISTS {full} ({} , PRIMARY KEY ({}))",
4137                    cols.join(", "),
4138                    quote_ident(&table.primary_key)
4139                );
4140                self.conn
4141                    .execute(&sql, [])
4142                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4143                // Local secondary indexes (CREATE INDEX subset). Created on
4144                // both halves so mirror reads hit an index on either. Runs on
4145                // both the initial create and the §7.4.3 reset recreate path.
4146                for index in &table.indexes {
4147                    let unique = if index.unique { "UNIQUE " } else { "" };
4148                    let index_name = quote_ident(&format!("{index_prefix}{}", index.name));
4149                    let cols_sql = index
4150                        .columns
4151                        .iter()
4152                        .map(|c| quote_ident(c))
4153                        .collect::<Vec<_>>()
4154                        .join(", ");
4155                    let index_sql = format!(
4156                        "CREATE {unique}INDEX IF NOT EXISTS {index_name} ON {full} ({cols_sql})"
4157                    );
4158                    self.conn
4159                        .execute(&index_sql, [])
4160                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4161                }
4162            }
4163        }
4164        // FTS exists only on the visible half. It is a local search
4165        // projection, never a synced/base table or a wire-schema member.
4166        for table in &self.schema.tables {
4167            for index in &table.fts_indexes {
4168                self.create_fts_projection(table, index)?;
4169            }
4170        }
4171        Ok(())
4172    }
4173
4174    fn fts_projection_exists(&self, index: &FtsIndexSchema) -> Result<bool, String> {
4175        let count: i64 = self
4176            .conn
4177            .query_row(
4178                "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?1",
4179                rusqlite::params![index.name],
4180                |row| row.get(0),
4181            )
4182            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4183        Ok(count > 0)
4184    }
4185
4186    fn drop_fts_triggers(&self, index: &FtsIndexSchema) -> Result<(), String> {
4187        for suffix in ["ai", "ad", "au"] {
4188            self.conn
4189                .execute(
4190                    &format!(
4191                        "DROP TRIGGER IF EXISTS {}",
4192                        quote_ident(&format!("{}_{suffix}", index.name))
4193                    ),
4194                    [],
4195                )
4196                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4197        }
4198        Ok(())
4199    }
4200
4201    fn create_fts_triggers(
4202        &self,
4203        table: &TableSchema,
4204        index: &FtsIndexSchema,
4205    ) -> Result<(), String> {
4206        let fts = quote_ident(&index.name);
4207        let source = visible_table(&table.name);
4208        let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4209        let pk = quote_ident(&table.primary_key);
4210        let projection_columns = std::iter::once(source_id.clone())
4211            .chain(index.columns.iter().map(|column| quote_ident(column)))
4212            .collect::<Vec<_>>()
4213            .join(", ");
4214        let new_values = std::iter::once(format!("CAST(new.{pk} AS TEXT)"))
4215            .chain(
4216                index
4217                    .columns
4218                    .iter()
4219                    .map(|column| format!("new.{}", quote_ident(column))),
4220            )
4221            .collect::<Vec<_>>()
4222            .join(", ");
4223        let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4224        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)");
4225        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)");
4226        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})");
4227        let bi = quote_ident(&format!("{}_bi", index.name));
4228        let ai = quote_ident(&format!("{}_ai", index.name));
4229        let ad = quote_ident(&format!("{}_ad", index.name));
4230        let au = quote_ident(&format!("{}_au", index.name));
4231        let replacement_exists = format!("EXISTS (SELECT 1 FROM {source} WHERE {pk} = new.{pk})");
4232        let sql = format!(
4233            "DROP TRIGGER IF EXISTS {bi};
4234             DROP TRIGGER IF EXISTS {ai};
4235             DROP TRIGGER IF EXISTS {ad};
4236             DROP TRIGGER IF EXISTS {au};
4237             CREATE TRIGGER {bi} BEFORE INSERT ON {source} WHEN {replacement_exists} BEGIN {delete_new}; END;
4238             CREATE TRIGGER {ai} AFTER INSERT ON {source} BEGIN {insert_new}; END;
4239             CREATE TRIGGER {ad} AFTER DELETE ON {source} BEGIN {delete_old}; END;
4240             CREATE TRIGGER {au} AFTER UPDATE ON {source} BEGIN {delete_old}; {delete_new}; {insert_new}; END;",
4241        );
4242        self.conn
4243            .execute_batch(&sql)
4244            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4245    }
4246
4247    fn rebuild_fts_projection(
4248        &self,
4249        table: &TableSchema,
4250        index: &FtsIndexSchema,
4251    ) -> Result<(), String> {
4252        let fts = quote_ident(&index.name);
4253        let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4254        let pk = quote_ident(&table.primary_key);
4255        let indexed_columns = index
4256            .columns
4257            .iter()
4258            .map(|column| quote_ident(column))
4259            .collect::<Vec<_>>();
4260        let projection_columns = std::iter::once(source_id.clone())
4261            .chain(indexed_columns.iter().cloned())
4262            .collect::<Vec<_>>()
4263            .join(", ");
4264        let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4265        let sql = format!(
4266            "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};",
4267            columns = indexed_columns.join(", "),
4268            source = visible_table(&table.name),
4269        );
4270        self.conn
4271            .execute_batch(&sql)
4272            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4273    }
4274
4275    fn create_fts_projection(
4276        &self,
4277        table: &TableSchema,
4278        index: &FtsIndexSchema,
4279    ) -> Result<(), String> {
4280        self.begin_observation("syncular_fts_schema")?;
4281        let result = (|| {
4282            let existed = self.fts_projection_exists(index)?;
4283            let tokenizer = index.tokenize.replace('\'', "''");
4284            let columns = index
4285                .columns
4286                .iter()
4287                .map(|column| quote_ident(column))
4288                .collect::<Vec<_>>()
4289                .join(", ");
4290            let sql = format!(
4291            "CREATE VIRTUAL TABLE IF NOT EXISTS {fts} USING fts5({source_id} UNINDEXED, {columns}, tokenize='{tokenizer}')",
4292            fts = quote_ident(&index.name),
4293            source_id = quote_ident(FTS_SOURCE_ID_COLUMN),
4294        );
4295            self.conn.execute(&sql, []).map_err(|error| {
4296                format!(
4297                    "cannot create local FTS5 projection {:?}: {error}",
4298                    index.name
4299                )
4300            })?;
4301            let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4302            let mapped: bool = self
4303                .conn
4304                .query_row(
4305                    "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1)",
4306                    [format!("_syncular_fts_{}", index.name)],
4307                    |row| row.get(0),
4308                )
4309                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4310            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))?;
4311            if !mapped && existed {
4312                self.conn
4313                    .execute_batch(&format!(
4314                        "INSERT INTO {mapping}(id, source_id) SELECT rowid, {} FROM {}",
4315                        quote_ident(FTS_SOURCE_ID_COLUMN),
4316                        quote_ident(&index.name)
4317                    ))
4318                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4319            }
4320            self.create_fts_triggers(table, index)?;
4321            if !existed {
4322                self.rebuild_fts_projection(table, index)?;
4323            }
4324            Ok(())
4325        })();
4326        if let Err(error) = result {
4327            self.rollback_observation("syncular_fts_schema");
4328            return Err(error);
4329        }
4330        if let Err(error) = self.conn.execute_batch("RELEASE syncular_fts_schema") {
4331            self.rollback_observation("syncular_fts_schema");
4332            return Err(error.to_string());
4333        }
4334        Ok(())
4335    }
4336
4337    // -- persistence write-through --------------------------------------------
4338
4339    fn persist_outbox_insert(&self, commit: &OutboxCommit) -> Result<(), String> {
4340        let ops: Vec<Value> = commit
4341            .ops
4342            .iter()
4343            .map(|op| {
4344                let mut entry = serde_json::json!({
4345                    "op": if op.upsert { "upsert" } else { "delete" },
4346                    "table": op.table,
4347                    "rowId": op.row_id,
4348                    "baseVersion": op.base_version,
4349                    "values": op.values.clone().map(Value::Object),
4350                });
4351                if op.insert {
4352                    entry["insert"] = Value::Bool(true);
4353                }
4354                entry
4355            })
4356            .collect();
4357        self.conn
4358            .execute(
4359                "INSERT OR REPLACE INTO _syncular_outbox (commit_id, ops_json) VALUES (?1, ?2)",
4360                rusqlite::params![commit.client_commit_id, Value::Array(ops).to_string()],
4361            )
4362            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4363        for operation in &commit.ops {
4364            let Some(values) = &operation.values else {
4365                continue;
4366            };
4367            let Some(table) = self.schema.table(&operation.table) else {
4368                continue;
4369            };
4370            for column in table
4371                .columns
4372                .iter()
4373                .filter(|column| column.ty == ColumnType::BlobRef)
4374            {
4375                let Some(Value::String(raw)) = values.get(&column.name) else {
4376                    continue;
4377                };
4378                let Ok(blob_ref) = serde_json::from_str::<Value>(raw) else {
4379                    continue;
4380                };
4381                let Some(blob_id) = blob_ref.get("blobId").and_then(Value::as_str) else {
4382                    continue;
4383                };
4384                self.conn
4385                    .execute(
4386                        "INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id, blob_id)
4387                         SELECT ?1, ?2 WHERE EXISTS (SELECT 1 FROM _syncular_blobs WHERE blob_id = ?2)",
4388                        rusqlite::params![commit.client_commit_id, blob_id],
4389                    )
4390                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4391            }
4392        }
4393        Ok(())
4394    }
4395
4396    fn delete_outbox_persisted(&self, client_commit_id: &str) -> Result<(), String> {
4397        self.conn
4398            .execute(
4399                "DELETE FROM _syncular_blob_commit_refs WHERE commit_id = ?1",
4400                rusqlite::params![client_commit_id],
4401            )
4402            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4403        self.conn
4404            .execute(
4405                "DELETE FROM _syncular_outbox WHERE commit_id = ?1",
4406                rusqlite::params![client_commit_id],
4407            )
4408            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4409        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)", [])
4410            .map(|_| ())
4411            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4412    }
4413
4414    fn outcome_status_name(status: CommitOutcomeStatus) -> &'static str {
4415        match status {
4416            CommitOutcomeStatus::Applied => "applied",
4417            CommitOutcomeStatus::Cached => "cached",
4418            CommitOutcomeStatus::Conflict => "conflict",
4419            CommitOutcomeStatus::Rejected => "rejected",
4420        }
4421    }
4422
4423    fn outcome_resolution_name(resolution: CommitOutcomeResolution) -> &'static str {
4424        match resolution {
4425            CommitOutcomeResolution::Active => "active",
4426            CommitOutcomeResolution::ResolvedKeepServer => "resolved_keep_server",
4427            CommitOutcomeResolution::Superseded => "superseded",
4428            CommitOutcomeResolution::Dismissed => "dismissed",
4429        }
4430    }
4431
4432    fn parse_outcome_status(value: &str) -> Result<CommitOutcomeStatus, String> {
4433        match value {
4434            "applied" => Ok(CommitOutcomeStatus::Applied),
4435            "cached" => Ok(CommitOutcomeStatus::Cached),
4436            "conflict" => Ok(CommitOutcomeStatus::Conflict),
4437            "rejected" => Ok(CommitOutcomeStatus::Rejected),
4438            _ => Err(format!("invalid persisted commit outcome status {value:?}")),
4439        }
4440    }
4441
4442    fn parse_outcome_resolution(value: &str) -> Result<CommitOutcomeResolution, String> {
4443        match value {
4444            "active" => Ok(CommitOutcomeResolution::Active),
4445            "resolved_keep_server" => Ok(CommitOutcomeResolution::ResolvedKeepServer),
4446            "superseded" => Ok(CommitOutcomeResolution::Superseded),
4447            "dismissed" => Ok(CommitOutcomeResolution::Dismissed),
4448            _ => Err(format!(
4449                "invalid persisted commit outcome resolution {value:?}"
4450            )),
4451        }
4452    }
4453
4454    fn persist_commit_outcome(
4455        &self,
4456        client_commit_id: &str,
4457        status: CommitOutcomeStatus,
4458        results: &[CommitOperationOutcome],
4459        operations: Option<&[OutboxOp]>,
4460    ) -> Result<(), String> {
4461        let results_json = serde_json::to_string(results).map_err(|error| error.to_string())?;
4462        let operations_json = operations
4463            .map(|items| {
4464                serde_json::to_string(&items.iter().map(CommitOperation::from).collect::<Vec<_>>())
4465            })
4466            .transpose()
4467            .map_err(|error| error.to_string())?;
4468        self.conn
4469            .execute(
4470                "INSERT INTO _syncular_commit_outcomes (
4471                   client_commit_id, status, recorded_at_ms, results_json,
4472                   operations_json, resolution
4473                 ) VALUES (?1, ?2, ?3, ?4, ?5, 'active')",
4474                rusqlite::params![
4475                    client_commit_id,
4476                    Self::outcome_status_name(status),
4477                    self.clock_now_ms(),
4478                    results_json,
4479                    operations_json
4480                ],
4481            )
4482            .map(|_| ())
4483            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4484    }
4485
4486    /// §7.2: the journal holds a stored cell only in its canonical shape. A cell
4487    /// the byte-envelope rule refuses cannot be journaled verbatim.
4488    fn stored_cell_is_representable(cell: &Value) -> bool {
4489        cell.is_null()
4490            || cell.is_string()
4491            || cell.is_boolean()
4492            || cell.is_number()
4493            || is_canonical_bytes_envelope(cell)
4494    }
4495
4496    fn stored_row_is_representable(value: &Value) -> bool {
4497        value
4498            .as_object()
4499            .is_some_and(|row| row.values().all(Self::stored_cell_is_representable))
4500    }
4501
4502    fn stored_operation_is_representable(value: &Value) -> bool {
4503        value.get("table").is_some_and(Value::is_string)
4504            && value.get("rowId").is_some_and(Value::is_string)
4505            && value.get("baseVersion").is_none_or(|v| {
4506                v.as_i64()
4507                    .is_some_and(|n| n.unsigned_abs() <= MAX_JS_SAFE_INTEGER)
4508            })
4509            && match value.get("op").and_then(Value::as_str) {
4510                Some("upsert") => {
4511                    value
4512                        .get("values")
4513                        .is_some_and(Self::stored_row_is_representable)
4514                        && value
4515                            .get("insert")
4516                            .is_none_or(|insert| *insert == Value::Bool(true))
4517                }
4518                Some("delete") => value.get("values").is_none() && value.get("insert").is_none(),
4519                _ => false,
4520            }
4521    }
4522
4523    /// §7.2/§7.4.4: a dropped commit keeps its operation envelope in the journal
4524    /// only when the journal reader accepts the serialized operation, which is the
4525    /// rule `outcome_from_row` applies to this same row later.
4526    fn outbox_op_is_journalable(operation: &OutboxOp) -> bool {
4527        serde_json::to_value(CommitOperation::from(operation))
4528            .is_ok_and(|value| Self::stored_operation_is_representable(&value))
4529    }
4530
4531    fn outcome_from_row(row: StoredCommitOutcomeRow) -> Result<CommitOutcome, String> {
4532        let StoredCommitOutcomeRow {
4533            sequence,
4534            client_commit_id,
4535            status,
4536            recorded_at_ms,
4537            results_json,
4538            operations_json,
4539            resolution,
4540            resolved_at_ms,
4541            replacement_client_commit_id,
4542        } = row;
4543        if sequence.unsigned_abs() > MAX_JS_SAFE_INTEGER
4544            || recorded_at_ms.unsigned_abs() > MAX_JS_SAFE_INTEGER
4545            || resolved_at_ms.is_some_and(|value| value.unsigned_abs() > MAX_JS_SAFE_INTEGER)
4546        {
4547            return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned());
4548        }
4549        let invalid = || "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
4550        let stored: Vec<Value> = serde_json::from_str(&results_json).map_err(|_| invalid())?;
4551        for result in &stored {
4552            let nested = match result.get("status").and_then(Value::as_str) {
4553                Some("conflict") => result.get("conflict"),
4554                Some("error") => result.get("rejection"),
4555                _ => None,
4556            };
4557            if nested
4558                .and_then(|record| record.get("operation"))
4559                .is_some_and(|op| !Self::stored_operation_is_representable(op))
4560                || (result.get("status").and_then(Value::as_str) == Some("conflict")
4561                    && nested
4562                        .and_then(|record| record.get("serverRow"))
4563                        .is_some_and(|row| !Self::stored_row_is_representable(row)))
4564            {
4565                return Err(invalid());
4566            }
4567        }
4568        let results: Vec<CommitOperationOutcome> =
4569            serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())?;
4570        let has_conflict = results
4571            .iter()
4572            .any(|result| matches!(result, CommitOperationOutcome::Conflict { .. }));
4573        let has_error = results
4574            .iter()
4575            .any(|result| matches!(result, CommitOperationOutcome::Error { .. }));
4576        let status = Self::parse_outcome_status(&status).map_err(|_| invalid())?;
4577        let redacted = results.is_empty() && operations_json.is_none();
4578        if match status {
4579            CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => has_conflict || has_error,
4580            CommitOutcomeStatus::Conflict => !(has_conflict || redacted),
4581            CommitOutcomeStatus::Rejected => has_conflict || !(has_error || redacted),
4582        } {
4583            return Err(invalid());
4584        }
4585        let operations: Option<Vec<CommitOperation>> = operations_json
4586            .map(|raw| {
4587                let stored: Vec<Value> = serde_json::from_str(&raw).map_err(|_| invalid())?;
4588                if !stored.iter().all(Self::stored_operation_is_representable) {
4589                    return Err(invalid());
4590                }
4591                serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())
4592            })
4593            .transpose()?;
4594        for result in &results {
4595            match result {
4596                CommitOperationOutcome::Conflict { conflict }
4597                    if conflict.server_version.unsigned_abs() > MAX_JS_SAFE_INTEGER =>
4598                {
4599                    return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned())
4600                }
4601                CommitOperationOutcome::Error { rejection } => {
4602                    if let Some(details) = &rejection.details {
4603                        let encoded = serde_json::to_string(details).map_err(|_| {
4604                            "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4605                        })?;
4606                        RejectionDetails::parse(&encoded).map_err(|_| {
4607                            "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4608                        })?;
4609                    }
4610                }
4611                _ => {}
4612            }
4613        }
4614        Ok(CommitOutcome {
4615            sequence,
4616            client_commit_id,
4617            status,
4618            recorded_at_ms,
4619            results,
4620            operations,
4621            retained_rows: None,
4622            resolution: Self::parse_outcome_resolution(&resolution)?,
4623            resolved_at_ms,
4624            replacement_client_commit_id,
4625        })
4626    }
4627
4628    /// Resolve declared unique keys through SQLite, including affinity and NULL semantics.
4629    fn unique_conflicts(
4630        &self,
4631        table: &TableSchema,
4632        values: &Map<String, Value>,
4633        base: bool,
4634    ) -> Result<Vec<RetainedUniqueConflict>, String> {
4635        let source = if base {
4636            base_table(&table.name)
4637        } else {
4638            visible_table(&table.name)
4639        };
4640        let mut conflicts = Vec::new();
4641        for index in table.indexes.iter().filter(|index| index.unique) {
4642            let mut params = vec![json_param_to_sql(
4643                values.get(&table.primary_key).ok_or("sync.local_corrupt")?,
4644            )?];
4645            for name in &index.columns {
4646                let column = table
4647                    .columns
4648                    .iter()
4649                    .find(|column| column.name == *name)
4650                    .ok_or("sync.local_corrupt")?;
4651                let cell = json_to_column_value(column, values.get(name))?;
4652                params.push(owned_sql_value(RowParam::Cell(&cell))?);
4653            }
4654            let sql = format!(
4655                "SELECT * FROM {source} WHERE {} != ? AND {}",
4656                quote_ident(&table.primary_key),
4657                index
4658                    .columns
4659                    .iter()
4660                    .map(|column| format!("{} = ?", quote_ident(column)))
4661                    .collect::<Vec<_>>()
4662                    .join(" AND ")
4663            );
4664            let mut statement = self
4665                .conn
4666                .prepare_cached(&sql)
4667                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4668            let records = statement
4669                .query_map(rusqlite::params_from_iter(params), |record| {
4670                    let values = table
4671                        .columns
4672                        .iter()
4673                        .enumerate()
4674                        .map(|(index, column)| {
4675                            let value = sql_ref_to_json(column, record.get_ref(index)?);
4676                            json_to_column_value(column, Some(&value)).map_err(|message| {
4677                                rusqlite::Error::ToSqlConversionFailure(message.into())
4678                            })
4679                        })
4680                        .collect::<Result<Row, _>>()?;
4681                    Ok((values, record.get::<_, i64>(table.columns.len())?))
4682                })
4683                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4684            for record in records {
4685                let (row, version) =
4686                    record.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4687                let row_id = render_row_id_json(Some(&column_value_to_json(&row[table.pk_index])))?;
4688                conflicts.push(RetainedUniqueConflict {
4689                    index: index.name.clone(),
4690                    columns: index.columns.clone(),
4691                    row_id,
4692                    server_row: table
4693                        .columns
4694                        .iter()
4695                        .zip(&row)
4696                        .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
4697                        .collect(),
4698                    server_version: version,
4699                });
4700            }
4701        }
4702        Ok(conflicts)
4703    }
4704
4705    fn attach_retained_rows(&self, mut outcome: CommitOutcome) -> Result<CommitOutcome, String> {
4706        if let Some((commit, initial)) = self
4707            .failed_commits
4708            .iter()
4709            .find(|(commit, _)| commit.client_commit_id == outcome.client_commit_id)
4710        {
4711            let mut rows = Vec::new();
4712            for operation in &commit.ops {
4713                // A table the current schema removed has no rows to retain.
4714                let Some(table) = self.schema.table(&operation.table) else {
4715                    continue;
4716                };
4717                let key =
4718                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
4719                        .map_err(|_| "sync.local_corrupt".to_owned())?;
4720                let base = self.stored_row(table, &operation.row_id, true)?;
4721                rows.push(RetainedCommitRow {
4722                    table: operation.table.clone(),
4723                    row_id: operation.row_id.clone(),
4724                    unique_conflicts: if operation.upsert {
4725                        self.unique_conflicts(
4726                            table,
4727                            initial
4728                                .get(&key)
4729                                .and_then(Value::as_object)
4730                                .or(operation.values.as_ref())
4731                                .ok_or("sync.local_corrupt")?,
4732                            true,
4733                        )?
4734                    } else {
4735                        Vec::new()
4736                    },
4737                    local_row: if operation.upsert {
4738                        initial
4739                            .get(&key)
4740                            .and_then(Value::as_object)
4741                            .cloned()
4742                            .or_else(|| operation.values.clone())
4743                    } else {
4744                        None
4745                    },
4746                    server_row: base.as_ref().map(|(values, _)| {
4747                        table
4748                            .columns
4749                            .iter()
4750                            .zip(values)
4751                            .map(|(column, value)| {
4752                                (column.name.clone(), column_value_to_json(value))
4753                            })
4754                            .collect()
4755                    }),
4756                    server_version: base.map(|(_, version)| version),
4757                });
4758            }
4759            outcome.retained_rows = Some(rows);
4760        }
4761        Ok(outcome)
4762    }
4763
4764    pub fn commit_outcome(&self, client_commit_id: &str) -> Result<Option<CommitOutcome>, String> {
4765        let row = self
4766            .conn
4767            .query_row(
4768                "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
4769                        resolution, resolved_at_ms, replacement_client_commit_id
4770                   FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
4771                rusqlite::params![client_commit_id],
4772                |row| {
4773                    Ok(StoredCommitOutcomeRow {
4774                        sequence: row.get(0)?,
4775                        client_commit_id: row.get(1)?,
4776                        status: row.get(2)?,
4777                        recorded_at_ms: row.get(3)?,
4778                        results_json: row.get(4)?,
4779                        operations_json: row.get(5)?,
4780                        resolution: row.get(6)?,
4781                        resolved_at_ms: row.get(7)?,
4782                        replacement_client_commit_id: row.get(8)?,
4783                    })
4784                },
4785            )
4786            .optional()
4787            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4788        row.map(|row| self.attach_retained_rows(Self::outcome_from_row(row)?))
4789            .transpose()
4790    }
4791
4792    /// Internal host step. The host must run its idle drive before finishing.
4793    #[doc(hidden)]
4794    pub fn prepare_current_base(
4795        &self,
4796        client_commit_id: &str,
4797        sequence: i64,
4798    ) -> Result<CurrentBasePreparation, CurrentBaseProof> {
4799        let outcome = self
4800            .commit_outcome(client_commit_id)
4801            .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?;
4802        let valid = outcome.as_ref().is_some_and(|outcome| {
4803            outcome.sequence == sequence
4804                && outcome.resolution == CommitOutcomeResolution::Active
4805                && matches!(
4806                    outcome.status,
4807                    CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
4808                )
4809                && outcome
4810                    .operations
4811                    .as_ref()
4812                    .zip(outcome.retained_rows.as_ref())
4813                    .is_some_and(|(operations, rows)| {
4814                        !rows.is_empty() && operations.len() == rows.len()
4815                    })
4816        });
4817        if !valid {
4818            return Err(CurrentBaseProof::failure(
4819                CurrentBaseProofReason::OutcomeUnavailable,
4820            ));
4821        }
4822        if !self.transport_enabled {
4823            return Err(CurrentBaseProof::failure(CurrentBaseProofReason::Offline));
4824        }
4825        Ok(CurrentBasePreparation {
4826            client_commit_id: client_commit_id.to_owned(),
4827            sequence,
4828            units: load_units(&self.conn)
4829                .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?,
4830            transport_epoch: self.transport_epoch,
4831            registration_epoch: self.registration_epoch,
4832            security_epoch: self.security_epoch,
4833        })
4834    }
4835
4836    /// Internal host step after the completed post-rejection idle drive.
4837    #[doc(hidden)]
4838    pub fn finish_current_base(
4839        &mut self,
4840        prepared: CurrentBasePreparation,
4841        drive: SyncOutcome,
4842    ) -> CurrentBaseProof {
4843        if !self.transport_enabled || self.transport_epoch != prepared.transport_epoch {
4844            return CurrentBaseProof::failure(CurrentBaseProofReason::Offline);
4845        }
4846        if self.registration_epoch != prepared.registration_epoch {
4847            return CurrentBaseProof::failure(CurrentBaseProofReason::MissingCoverage);
4848        }
4849        if self.security_preflight || self.security_epoch != prepared.security_epoch {
4850            return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed);
4851        }
4852        let report = match drive {
4853            SyncOutcome::Ok(report) => report,
4854            SyncOutcome::BudgetExhausted(_) => {
4855                return CurrentBaseProof::failure(CurrentBaseProofReason::BudgetExhausted)
4856            }
4857            _ => return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed),
4858        };
4859        if report.schema_floor.is_some() {
4860            return CurrentBaseProof::failure(CurrentBaseProofReason::SchemaFloor);
4861        }
4862        if self
4863            .conn
4864            .execute_batch("SAVEPOINT syncular_base_proof")
4865            .is_err()
4866        {
4867            return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
4868        }
4869        let proof = (|| {
4870            let snapshot = snapshot_read_connection(
4871                &self.conn,
4872                &SnapshotReadRequest {
4873                    units: prepared.units.iter().map(|unit| unit.id.clone()).collect(),
4874                    commit_ids: vec![prepared.client_commit_id.clone()],
4875                    ..Default::default()
4876                },
4877            )
4878            .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4879            let current = self
4880                .commit_outcome(&prepared.client_commit_id)
4881                .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4882            let unavailable = if report.revoked.is_empty() {
4883                CurrentBaseProofReason::OutcomeUnavailable
4884            } else {
4885                CurrentBaseProofReason::Revoked
4886            };
4887            let Some(outcome) = current else {
4888                return Err(unavailable);
4889            };
4890            if !matches!(
4891                snapshot.deliveries.first(),
4892                Some(CommitDelivery::Known { .. })
4893            ) || outcome.sequence != prepared.sequence
4894                || outcome.resolution != CommitOutcomeResolution::Active
4895                || !matches!(
4896                    outcome.status,
4897                    CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
4898                )
4899            {
4900                return Err(unavailable);
4901            }
4902            let (Some(operations), Some(rows)) = (outcome.operations, outcome.retained_rows) else {
4903                return Err(unavailable);
4904            };
4905            if rows.is_empty() || operations.len() != rows.len() {
4906                return Err(unavailable);
4907            }
4908            let after =
4909                load_units(&self.conn).map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4910            let complete: HashSet<&str> = snapshot
4911                .units
4912                .iter()
4913                .filter_map(|unit| match unit {
4914                    UnitCatchup::Known {
4915                        id,
4916                        bootstrap_complete: true,
4917                        ..
4918                    } => Some(id.as_str()),
4919                    _ => None,
4920                })
4921                .collect();
4922            // A unit id names one scope map (§4.1), so the same id before and
4923            // after the drive is the same registration.
4924            let candidates: Vec<&UnitRecord> = after
4925                .iter()
4926                .filter(|unit| {
4927                    complete.contains(unit.id.as_str())
4928                        && prepared.units.iter().any(|before| before.id == unit.id)
4929                })
4930                .collect();
4931            let covered = |table_name: &str, row: &Map<String, Value>| {
4932                let Some(table) = self.schema.table(table_name) else {
4933                    return false;
4934                };
4935                candidates.iter().any(|unit| {
4936                    covers(table, &unit.scopes)
4937                        && pair_scopes(&unit.scopes, table_name, unit.echo.as_deref()).is_some_and(
4938                            |scopes| {
4939                                scopes.iter().all(|(variable, allowed)| {
4940                                    table
4941                                        .scope_column(variable)
4942                                        .and_then(|column| match row.get(column) {
4943                                            Some(Value::String(value)) => Some(value.clone()),
4944                                            Some(Value::Bool(value)) => Some(value.to_string()),
4945                                            Some(Value::Number(value)) => {
4946                                                value.as_f64().map(|number| {
4947                                                    ryu_js::Buffer::new()
4948                                                        .format_finite(number)
4949                                                        .to_owned()
4950                                                })
4951                                            }
4952                                            _ => None,
4953                                        })
4954                                        .is_some_and(|value| {
4955                                            !value.is_empty() && allowed.contains(&value)
4956                                        })
4957                                })
4958                            },
4959                        )
4960                })
4961            };
4962            for row in &rows {
4963                let Some(base) = row.server_row.as_ref().or(row.local_row.as_ref()) else {
4964                    return Err(if report.revoked.is_empty() {
4965                        CurrentBaseProofReason::MissingCoverage
4966                    } else {
4967                        CurrentBaseProofReason::Revoked
4968                    });
4969                };
4970                if !covered(&row.table, base)
4971                    || row
4972                        .unique_conflicts
4973                        .iter()
4974                        .any(|conflict| !covered(&row.table, &conflict.server_row))
4975                {
4976                    return Err(if report.revoked.is_empty() {
4977                        CurrentBaseProofReason::MissingCoverage
4978                    } else {
4979                        CurrentBaseProofReason::Revoked
4980                    });
4981                }
4982            }
4983            Ok(rows)
4984        })();
4985        if self
4986            .conn
4987            .execute_batch("RELEASE syncular_base_proof")
4988            .is_err()
4989        {
4990            return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
4991        }
4992        match proof {
4993            Ok(rows) => CurrentBaseProof {
4994                proven: true,
4995                rows: Some(rows),
4996                reason: None,
4997            },
4998            Err(reason) => CurrentBaseProof::failure(reason),
4999        }
5000    }
5001
5002    pub fn prove_current_base(
5003        &mut self,
5004        transport: &mut dyn Transport,
5005        client_commit_id: &str,
5006        sequence: i64,
5007        max_rounds: Option<u32>,
5008    ) -> CurrentBaseProof {
5009        let prepared = match self.prepare_current_base(client_commit_id, sequence) {
5010            Ok(prepared) => prepared,
5011            Err(proof) => return proof,
5012        };
5013        let drive = self.sync_until_idle(transport, max_rounds);
5014        self.finish_current_base(prepared, drive)
5015    }
5016
5017    pub fn commit_outcomes(&self, query: CommitOutcomeQuery) -> Result<Vec<CommitOutcome>, String> {
5018        if query.limit == Some(0) {
5019            return Err("sync.invalid_request: commit outcome limit must be positive".to_owned());
5020        }
5021        let mut sql = String::from(
5022            "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
5023                    resolution, resolved_at_ms, replacement_client_commit_id
5024               FROM _syncular_commit_outcomes",
5025        );
5026        if query.active_only {
5027            sql.push_str(" WHERE resolution = 'active' AND status IN ('conflict', 'rejected')");
5028        }
5029        sql.push_str(" ORDER BY seq DESC");
5030        if let Some(limit) = query.limit {
5031            sql.push_str(&format!(" LIMIT {limit}"));
5032        }
5033        let mut stmt = self
5034            .conn
5035            .prepare(&sql)
5036            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5037        let rows = stmt
5038            .query_map([], |row| {
5039                Ok(StoredCommitOutcomeRow {
5040                    sequence: row.get(0)?,
5041                    client_commit_id: row.get(1)?,
5042                    status: row.get(2)?,
5043                    recorded_at_ms: row.get(3)?,
5044                    results_json: row.get(4)?,
5045                    operations_json: row.get(5)?,
5046                    resolution: row.get(6)?,
5047                    resolved_at_ms: row.get(7)?,
5048                    replacement_client_commit_id: row.get(8)?,
5049                })
5050            })
5051            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5052        let mut outcomes = Vec::new();
5053        for row in rows {
5054            outcomes.push(self.attach_retained_rows(Self::outcome_from_row(
5055                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
5056            )?)?);
5057        }
5058        Ok(outcomes)
5059    }
5060
5061    fn prune_commit_outcomes(&self) -> Result<(), String> {
5062        #[cfg(test)]
5063        self.outcome_prune_count
5064            .set(self.outcome_prune_count.get() + 1);
5065        let max_entries = self.limits.outcome_retention_max_entries.unwrap_or(1_000);
5066        let count = self
5067            .conn
5068            .query_row(
5069                "SELECT COUNT(*) FROM _syncular_commit_outcomes",
5070                [],
5071                |row| row.get::<_, i64>(0),
5072            )
5073            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5074            as usize;
5075        let excess = count.saturating_sub(max_entries);
5076        if excess == 0 {
5077            return Ok(());
5078        }
5079        let mut stmt = self
5080            .conn
5081            .prepare(
5082                "SELECT seq FROM _syncular_commit_outcomes
5083                  WHERE status IN ('applied', 'cached') OR resolution != 'active'
5084                  ORDER BY seq ASC LIMIT ?1",
5085            )
5086            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5087        let rows = stmt
5088            .query_map(rusqlite::params![excess as i64], |row| row.get::<_, i64>(0))
5089            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5090        let sequences = rows
5091            .collect::<Result<Vec<_>, _>>()
5092            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5093        drop(stmt);
5094        for sequence in sequences {
5095            self.conn
5096                .execute(
5097                    "DELETE FROM _syncular_commit_outcomes WHERE seq = ?1",
5098                    rusqlite::params![sequence],
5099                )
5100                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5101        }
5102        Ok(())
5103    }
5104
5105    // -- units (§4.1) ------------------------------------------------------------
5106
5107    /// Every registered unit in registration order (§4.1).
5108    pub fn units(&self) -> Result<Vec<UnitRecord>, String> {
5109        self.stored(load_units(&self.conn))
5110    }
5111
5112    pub fn unit(&self, id: &str) -> Result<Option<UnitRecord>, String> {
5113        self.stored(get_unit(&self.conn, id))
5114    }
5115
5116    /// Register one unit (§4.1) and return its id.
5117    pub fn subscribe(&mut self, scopes: UnitScopes) -> Result<String, String> {
5118        Ok(self.subscribe_many(vec![scopes])?.remove(0))
5119    }
5120
5121    /// Register several units in one local transaction and return their ids:
5122    /// one commit for all of them (on OPFS a commit costs milliseconds, so a
5123    /// cold start with hundreds of units pays it once). An error rolls back
5124    /// every registration of the call. Registering an active unit again
5125    /// changes nothing; a revoked unit re-arms (§3.3). A call that registers or
5126    /// re-arms a unit raises sync-needed with an interactive intent.
5127    pub fn subscribe_many(&mut self, units: Vec<UnitScopes>) -> Result<Vec<String>, String> {
5128        self.begin_observation("syncular_subscribe")?;
5129        let mut changed = false;
5130        let registered = (|| {
5131            let mut ids = Vec::with_capacity(units.len());
5132            for scopes in units {
5133                let (id, held) = self.hold_unit(scopes, true)?;
5134                changed |= held;
5135                ids.push(id);
5136            }
5137            self.conn
5138                .execute_batch("RELEASE syncular_subscribe")
5139                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5140            Ok(ids)
5141        })();
5142        let ids = match registered {
5143            Ok(ids) => ids,
5144            Err(error) => {
5145                self.rollback_observation("syncular_subscribe");
5146                return Err(error);
5147            }
5148        };
5149        if changed {
5150            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5151            self.set_sync_needed(true, true);
5152        }
5153        Ok(ids)
5154    }
5155
5156    /// Release the explicit reference to a unit. The unit leaves the
5157    /// registration list when no window base holds it (§4.1); its rows stay.
5158    pub fn unsubscribe(&mut self, id: &str) -> Result<(), String> {
5159        let Some(unit) = self.stored(get_unit(&self.conn, id))? else {
5160            return Ok(());
5161        };
5162        if !unit.explicit {
5163            return Ok(());
5164        }
5165        if !self.stored(window_refs(&self.conn, id))?.is_empty() {
5166            return self.stored(save_unit(
5167                &self.conn,
5168                &UnitRecord {
5169                    explicit: false,
5170                    ..unit
5171                },
5172            ));
5173        }
5174        self.conn
5175            .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5176            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5177        self.registration_epoch = self.registration_epoch.wrapping_add(1);
5178        if unit.status == UnitStatus::Active {
5179            self.set_sync_needed(true, true);
5180        }
5181        Ok(())
5182    }
5183
5184    /// Take one reference on a unit (§4.1): validate the scope map, register a
5185    /// new unit catching up with cursor `-1`, re-arm a revoked one (§3.3).
5186    /// Returns the id and whether the registration list changed.
5187    fn hold_unit(&mut self, scopes: UnitScopes, explicit: bool) -> Result<(String, bool), String> {
5188        if scopes.is_empty()
5189            || scopes.values().any(|value| value == "*")
5190            || !self
5191                .schema
5192                .tables
5193                .iter()
5194                .any(|table| covers(table, &scopes))
5195        {
5196            return Err("sync.invalid_subscription: a unit names one non-wildcard value per variable and covers a table".to_owned());
5197        }
5198        let id = ssp2::registration::unit_id(&scope_pairs(&scopes));
5199        let existing = self.stored(get_unit(&self.conn, &id))?;
5200        if let Some(existing) = existing
5201            .as_ref()
5202            .filter(|unit| unit.status != UnitStatus::Revoked)
5203        {
5204            if explicit && !existing.explicit {
5205                self.stored(save_unit(
5206                    &self.conn,
5207                    &UnitRecord {
5208                        explicit,
5209                        ..existing.clone()
5210                    },
5211                ))?;
5212            }
5213            return Ok((id, false));
5214        }
5215        self.delete_pending_evict(&id)?;
5216        self.stored(save_unit(
5217            &self.conn,
5218            &UnitRecord {
5219                id: id.clone(),
5220                scopes,
5221                explicit: explicit || existing.is_some_and(|unit| unit.explicit),
5222                status: UnitStatus::Active,
5223                reason_code: None,
5224                cursor: Some(-1),
5225                bootstrap_state: None,
5226                seeded: Vec::new(),
5227                echo: None,
5228            },
5229        ))?;
5230        Ok((id, true))
5231    }
5232
5233    // -- windows (§4.8) -----------------------------------------------------------
5234
5235    /// §4.8: set the windowed-in values of a base, one unit per value. Added
5236    /// values take a reference on their unit (a new unit bootstraps on the
5237    /// next sync); removed values release theirs, and a unit no reference
5238    /// holds leaves the registration list fused with its first eviction chunk
5239    /// (E1–E4). Idempotent; re-entry cancels a deferred eviction.
5240    pub fn set_window(
5241        &mut self,
5242        base: &WindowBase,
5243        units: &[String],
5244    ) -> Result<CommandEffects, String> {
5245        let base_key = window_base_key(base);
5246        let live = self.load_window_units(&base_key)?;
5247        let mut changed = false;
5248        for value in units {
5249            if live.iter().any(|(held, _)| held == value) {
5250                continue;
5251            }
5252            let rollback = self.capture();
5253            self.begin_observation("syncular_window")?;
5254            let widened = (|| {
5255                let (id, registered) = self.hold_unit(window_unit_scopes(base, value), false)?;
5256                self.sync_needed |= registered;
5257                self.conn
5258                    .execute(
5259                        "INSERT OR REPLACE INTO _syncular_windows(base, unit, sub_id) VALUES (?1, ?2, ?3)",
5260                        rusqlite::params![base_key, value, id],
5261                    )
5262                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5263                let mut batch = ChangeAccumulator::default();
5264                batch.window(&base_key, value);
5265                batch.status = true;
5266                self.finish_observation("syncular_window", batch)
5267            })();
5268            if let Err(error) = widened {
5269                self.rollback_observation("syncular_window");
5270                self.restore(rollback);
5271                return Err(error);
5272            }
5273            changed = true;
5274            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5275        }
5276        for (value, id) in live {
5277            if units.contains(&value) {
5278                continue;
5279            }
5280            self.rebuild_overlay_if_dirty()?;
5281            let rollback = self.capture();
5282            self.begin_observation("syncular_window")?;
5283            let remaining = self.release_window_unit(&base_key, &value, &id);
5284            let remaining = match remaining {
5285                Ok(remaining) => remaining,
5286                Err(error) => {
5287                    self.rollback_observation("syncular_window");
5288                    self.restore(rollback);
5289                    return Err(error);
5290                }
5291            };
5292            changed = true;
5293            self.registration_epoch = self.registration_epoch.wrapping_add(1);
5294            if remaining {
5295                self.drain_pending_evictions()?;
5296            }
5297        }
5298        Ok(if changed && self.transport_enabled {
5299            CommandEffects::interactive()
5300        } else {
5301            CommandEffects::none()
5302        })
5303    }
5304
5305    /// §4.8 completeness oracle: the windowed-in values of a base and those
5306    /// whose unit is not complete. A value is complete once its unit is active
5307    /// and no longer bootstrapping; registration alone is not completeness.
5308    pub fn window_state(&self, base: &WindowBase) -> Result<WindowState, String> {
5309        persisted_window_state(&self.conn, base).map_err(|failure| failure.message)
5310    }
5311
5312    /// Registry rows for a base, ordered by value: (value, unit id).
5313    fn load_window_units(&self, base_key: &str) -> Result<Vec<(String, String)>, String> {
5314        let mut statement = self
5315            .conn
5316            .prepare_cached(
5317                "SELECT unit, sub_id FROM _syncular_windows WHERE base = ?1 ORDER BY unit ASC",
5318            )
5319            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5320        let rows = statement
5321            .query_map([base_key], |row| Ok((row.get(0)?, row.get(1)?)))
5322            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5323        rows.collect::<Result<_, _>>()
5324            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5325    }
5326
5327    /// Every window registry row: (base key, value).
5328    fn load_window_registry(&self) -> Result<Vec<(String, String)>, String> {
5329        let mut statement = self
5330            .conn
5331            .prepare_cached("SELECT base, unit FROM _syncular_windows ORDER BY base, unit")
5332            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5333        let rows = statement
5334            .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
5335            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5336        rows.collect::<Result<_, _>>()
5337            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5338    }
5339
5340    /// §4.8: release a window value's reference inside the caller's
5341    /// observation. When no reference holds the unit, unregister it fused with
5342    /// its first eviction chunk (E3): delete the rows of every covered table
5343    /// matching the persisted echo, except rows pinned by the outbox (E1) or
5344    /// owned by another unit (§3.3), and park the per-table scopes of what
5345    /// remains in the pending-eviction registry. Fails closed without a local
5346    /// scope-column mapping. Returns whether unpinned rows remain.
5347    fn release_window_unit(
5348        &mut self,
5349        base_key: &str,
5350        value: &str,
5351        id: &str,
5352    ) -> Result<bool, String> {
5353        self.conn
5354            .execute(
5355                "DELETE FROM _syncular_windows WHERE base = ?1 AND unit = ?2",
5356                rusqlite::params![base_key, value],
5357            )
5358            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5359        let mut batch = ChangeAccumulator::default();
5360        batch.window(base_key, value);
5361        batch.status = true;
5362        let unit = self.stored(get_unit(&self.conn, id))?;
5363        let mut remaining = false;
5364        if let Some(unit) = unit.filter(|unit| !unit.explicit) {
5365            if self.stored(window_refs(&self.conn, id))?.is_empty() {
5366                let units = self.stored(load_units(&self.conn))?;
5367                self.conn
5368                    .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5369                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5370                self.sync_needed = true;
5371                for table in self.schema.tables.clone() {
5372                    let Some(effective) = unit
5373                        .echo
5374                        .as_deref()
5375                        .filter(|_| covers(&table, &unit.scopes))
5376                        .and_then(|echo| pair_scopes(&unit.scopes, &table.name, Some(echo)))
5377                    else {
5378                        continue;
5379                    };
5380                    let pinned = self.pinned_row_ids(&table.name);
5381                    let owners = unit_owners(&units, &table, id);
5382                    let (more, deferred) =
5383                        self.evict_scope_rows(&table.name, &effective, &owners, &pinned)?;
5384                    remaining |= more;
5385                    if deferred {
5386                        self.save_pending_evict(id, &table.name, &effective)?;
5387                    }
5388                    self.record_scope_map(&mut batch, &table.name, &effective);
5389                }
5390            }
5391        }
5392        self.finish_observation("syncular_window", batch)?;
5393        Ok(remaining)
5394    }
5395
5396    /// §4.8 E1: delete base rows owned by the effective scopes
5397    /// ([`local_scope_predicate`]) EXCEPT pinned primary keys. Returns (more
5398    /// unpinned work, any scoped rows remain). A missing scope-column mapping
5399    /// fails without deleting rows.
5400    fn evict_scope_rows(
5401        &self,
5402        table_name: &str,
5403        effective: &[(String, Vec<String>)],
5404        owners: &[Vec<(String, Vec<String>)>],
5405        pinned: &std::collections::HashSet<String>,
5406    ) -> Result<(bool, bool), String> {
5407        let table = self.schema.table(table_name).ok_or("sync.unknown_table")?;
5408        let Some((scope, mut params)) = local_scope_predicate(table, effective, owners)
5409            .map_err(|()| "sync.scope_revoked".to_owned())?
5410        else {
5411            return Ok((false, false));
5412        };
5413        let scope_params = params.len();
5414        let pk = quote_ident(&table.primary_key);
5415        // Pinned ids are rowId text; the text form matches every key type.
5416        let predicate = if pinned.is_empty() {
5417            scope.clone()
5418        } else {
5419            params.extend(pinned.iter().cloned().map(SqlValue::Text));
5420            let holes = vec!["?"; pinned.len()].join(", ");
5421            format!("{scope} AND CAST({pk} AS TEXT) NOT IN ({holes})")
5422        };
5423        let base = base_table(table_name);
5424        let visible = visible_table(table_name);
5425        let mut ids: Vec<SqlValue> = Vec::new();
5426        for source in [&base, &visible] {
5427            let mut stmt = self
5428                .conn
5429                .prepare_cached(&format!(
5430                    "SELECT {pk} FROM {source} WHERE {predicate} LIMIT 1024"
5431                ))
5432                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5433            ids = stmt
5434                .query_map(rusqlite::params_from_iter(&params), |row| row.get(0))
5435                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5436                .collect::<Result<_, _>>()
5437                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5438            if !ids.is_empty() {
5439                break;
5440            }
5441        }
5442        if !ids.is_empty() {
5443            for id in &ids {
5444                self.conn
5445                    .execute(
5446                        "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2",
5447                        rusqlite::params![table_name, id],
5448                    )
5449                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5450            }
5451            let holes = vec!["?"; ids.len()].join(", ");
5452            for source in [&base, &visible] {
5453                self.conn
5454                    .execute(
5455                        &format!("DELETE FROM {source} WHERE {pk} IN ({holes})"),
5456                        rusqlite::params_from_iter(&ids),
5457                    )
5458                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5459            }
5460        }
5461        let mut remaining = false;
5462        let mut deferred = false;
5463        for source in [&base, &visible] {
5464            remaining |= self
5465                .conn
5466                .query_row(
5467                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
5468                    rusqlite::params_from_iter(&params),
5469                    |row| row.get::<_, bool>(0),
5470                )
5471                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5472            deferred |= self
5473                .conn
5474                .query_row(
5475                    &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {scope})"),
5476                    rusqlite::params_from_iter(&params[..scope_params]),
5477                    |row| row.get::<_, bool>(0),
5478                )
5479                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5480        }
5481        Ok((remaining, deferred))
5482    }
5483
5484    /// §4.8 E1: continue deferred evictions after the outbox drains or between
5485    /// chunks, retaining outbox pins and their durable marker. A unit that
5486    /// re-entered the window has no pending entry left.
5487    fn drain_pending_evictions(&mut self) -> Result<(), String> {
5488        let pending = self.load_pending_evictions()?;
5489        if pending.is_empty() {
5490            return Ok(());
5491        }
5492        self.rebuild_overlay_if_dirty()?;
5493        for (unit_id, table_name, effective) in pending {
5494            let Some(table) = self.schema.table(&table_name).cloned() else {
5495                self.delete_pending_evict_table(&unit_id, &table_name)?;
5496                continue;
5497            };
5498            loop {
5499                std::thread::yield_now();
5500                self.begin_observation("syncular_evict")?;
5501                let chunk = (|| {
5502                    let pinned = self.pinned_row_ids(&table_name);
5503                    let owners =
5504                        unit_owners(&self.stored(load_units(&self.conn))?, &table, &unit_id);
5505                    let (remaining, deferred) =
5506                        self.evict_scope_rows(&table_name, &effective, &owners, &pinned)?;
5507                    if !deferred {
5508                        self.delete_pending_evict_table(&unit_id, &table_name)?;
5509                    }
5510                    let mut batch = ChangeAccumulator::default();
5511                    self.record_scope_map(&mut batch, &table_name, &effective);
5512                    self.finish_observation("syncular_evict", batch)?;
5513                    Ok(remaining)
5514                })();
5515                match chunk {
5516                    Ok(true) => {}
5517                    Ok(false) => break,
5518                    Err(error) => {
5519                        self.rollback_observation("syncular_evict");
5520                        return Err(error);
5521                    }
5522                }
5523            }
5524        }
5525        Ok(())
5526    }
5527
5528    /// §4.8 E1: primary keys of `table` referenced by a pending outbox
5529    /// commit — rows that MUST NOT be evicted until the commit drains.
5530    fn pinned_row_ids(&self, table: &str) -> std::collections::HashSet<String> {
5531        let mut pinned = std::collections::HashSet::new();
5532        for commit in self
5533            .outbox
5534            .iter()
5535            .map(|commit| &**commit)
5536            .chain(self.failed_commits.iter().map(|(commit, _)| commit))
5537        {
5538            for op in &commit.ops {
5539                if op.table == table {
5540                    pinned.insert(op.row_id.clone());
5541                }
5542            }
5543        }
5544        pinned
5545    }
5546
5547    fn save_pending_evict(
5548        &self,
5549        unit_id: &str,
5550        table: &str,
5551        effective: &[(String, Vec<String>)],
5552    ) -> Result<(), String> {
5553        self.conn.execute(
5554            "INSERT OR REPLACE INTO _syncular_pending_evictions(unit_id, tbl, effective_scopes) VALUES (?1, ?2, ?3)",
5555            rusqlite::params![unit_id, table, scope_map_to_json(effective).to_string()],
5556        ).map(|_| ()).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5557    }
5558
5559    /// Re-entry cancels every pending eviction of the unit.
5560    fn delete_pending_evict(&self, unit_id: &str) -> Result<(), String> {
5561        self.conn
5562            .execute(
5563                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
5564                [unit_id],
5565            )
5566            .map(|_| ())
5567            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5568    }
5569
5570    fn delete_pending_evict_table(&self, unit_id: &str, table: &str) -> Result<(), String> {
5571        self.conn
5572            .execute(
5573                "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1 AND tbl = ?2",
5574                [unit_id, table],
5575            )
5576            .map(|_| ())
5577            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5578    }
5579
5580    fn load_pending_evictions(&self) -> Result<Vec<PendingEvict>, String> {
5581        let mut stmt = self
5582            .conn
5583            .prepare("SELECT unit_id, tbl, effective_scopes FROM _syncular_pending_evictions")
5584            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5585        let rows = stmt
5586            .query_map([], |row| {
5587                Ok((
5588                    row.get::<_, String>(0)?,
5589                    row.get::<_, String>(1)?,
5590                    row.get::<_, String>(2)?,
5591                ))
5592            })
5593            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5594        rows.map(|row| {
5595            let (unit_id, table, json) =
5596                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5597            let value: Value = serde_json::from_str(&json)
5598                .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5599            let effective = json_to_scope_map(&value)
5600                .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5601            Ok((unit_id, table, effective))
5602        })
5603        .collect()
5604    }
5605
5606    /// Select failed-intent retention; reload durable retained aggregates.
5607    pub fn set_retain_failed_commits(&mut self, enabled: bool) -> Result<(), String> {
5608        self.retain_failed_commits = enabled;
5609        for (commit, _) in self.failed_commits.iter() {
5610            for operation in &commit.ops {
5611                self.overlay_dirty.table(&operation.table);
5612            }
5613        }
5614        self.failed_commits = self.load_failed_commits()?.into();
5615        for (commit, _) in self.failed_commits.iter() {
5616            for operation in &commit.ops {
5617                self.overlay_dirty.table(&operation.table);
5618            }
5619        }
5620        Ok(())
5621    }
5622
5623    fn load_failed_commits(&self) -> Result<Vec<FailedCommit>, String> {
5624        let mut statement = self.conn.prepare("SELECT client_commit_id, operations_json, initial_json FROM _syncular_failed_commits ORDER BY seq")
5625            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5626        let rows = statement
5627            .query_map([], |row| {
5628                Ok((
5629                    row.get::<_, String>(0)?,
5630                    row.get::<_, String>(1)?,
5631                    row.get::<_, String>(2)?,
5632                ))
5633            })
5634            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5635        rows.map(|row| {
5636            let (id, operations, initial) =
5637                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5638            let operations: Vec<CommitOperation> =
5639                serde_json::from_str(&operations).map_err(|_| "sync.local_corrupt".to_owned())?;
5640            let initial =
5641                serde_json::from_str(&initial).map_err(|_| "sync.local_corrupt".to_owned())?;
5642            Ok((
5643                OutboxCommit {
5644                    client_commit_id: id,
5645                    ops: operations
5646                        .into_iter()
5647                        .map(|op| OutboxOp {
5648                            upsert: op.op == "upsert",
5649                            table: op.table,
5650                            row_id: op.row_id,
5651                            base_version: op.base_version,
5652                            values: op.values,
5653                            insert: op.insert,
5654                        })
5655                        .collect(),
5656                },
5657                initial,
5658            ))
5659        })
5660        .collect()
5661    }
5662
5663    fn retain_failed_commit(&mut self, id: &str, operations: &[OutboxOp]) -> Result<(), String> {
5664        let mut initial = Map::new();
5665        for operation in operations {
5666            // A table the current schema removed has no rows to retain.
5667            let Some(table) = self.schema.table(&operation.table) else {
5668                continue;
5669            };
5670            let initial_row = match self.stored_row(table, &operation.row_id, true)? {
5671                Some(row) => Some(row),
5672                None => self.visible_row(table, &operation.row_id)?,
5673            };
5674            if let Some((values, _)) = initial_row {
5675                let mut intended: Map<String, Value> = table
5676                    .columns
5677                    .iter()
5678                    .zip(values.iter())
5679                    .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
5680                    .collect();
5681                if let Some(patch) = &operation.values {
5682                    intended.extend(patch.clone());
5683                }
5684                initial.insert(
5685                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5686                        .map_err(|_| "sync.local_corrupt".to_owned())?,
5687                    Value::Object(intended),
5688                );
5689            }
5690        }
5691        self.conn.execute("INSERT INTO _syncular_failed_commits(client_commit_id, operations_json, initial_json) VALUES (?1, ?2, ?3)", rusqlite::params![id,
5692            serde_json::to_string(&operations.iter().map(CommitOperation::from).collect::<Vec<_>>()).map_err(|_| "sync.local_corrupt".to_owned())?,
5693            serde_json::to_string(&initial).map_err(|_| "sync.local_corrupt".to_owned())?])
5694            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5695        self.failed_commits.push((
5696            OutboxCommit {
5697                client_commit_id: id.to_owned(),
5698                ops: operations.to_vec(),
5699            },
5700            initial,
5701        ));
5702        Ok(())
5703    }
5704
5705    fn drop_failed_commits(
5706        &mut self,
5707        matches: impl Fn(&str, &Map<String, Value>) -> bool,
5708    ) -> Result<Vec<OutboxCommit>, String> {
5709        let mut doomed = self.drop_acknowledged_rows(&matches)?;
5710        for (commit, initial) in self.failed_commits.iter() {
5711            for operation in &commit.ops {
5712                let key =
5713                    serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5714                        .map_err(|_| "sync.local_corrupt".to_owned())?;
5715                if initial
5716                    .get(&key)
5717                    .and_then(Value::as_object)
5718                    .is_some_and(|values| matches(&operation.table, values))
5719                {
5720                    doomed.push(commit.clone());
5721                    break;
5722                }
5723            }
5724        }
5725        for commit in &doomed {
5726            self.conn
5727                .execute(
5728                    "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
5729                    rusqlite::params![commit.client_commit_id],
5730                )
5731                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5732        }
5733        for commit in &doomed {
5734            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))?;
5735        }
5736        self.conflicts.retain(|record| {
5737            !doomed
5738                .iter()
5739                .any(|commit| commit.client_commit_id == record.client_commit_id)
5740        });
5741        self.rejections.retain(|record| {
5742            !doomed
5743                .iter()
5744                .any(|commit| commit.client_commit_id == record.client_commit_id)
5745        });
5746        self.failed_commits.retain(|(commit, _)| {
5747            !doomed
5748                .iter()
5749                .any(|dropped| dropped.client_commit_id == commit.client_commit_id)
5750        });
5751        for commit in &doomed {
5752            for operation in &commit.ops {
5753                self.overlay_dirty.table(&operation.table);
5754            }
5755        }
5756        Ok(doomed)
5757    }
5758
5759    /// Record one commit of local mutations. The returned commit ID is the
5760    /// §2.3 idempotency key. Failures are structured so callers read
5761    /// `code`/`message`/`details` instead of parsing a string prefix.
5762    pub fn mutate(&mut self, mutations: Vec<Mutation>) -> Result<String, ClientError> {
5763        self.mutate_with_commit_id(mutations, None)
5764    }
5765
5766    /// [`Self::mutate`] under a caller-supplied `clientCommitId` (§7.1), so an
5767    /// app that loses the reply knows its commit. The ID is non-empty (§6.1);
5768    /// one this replica still holds fails with `client.commit_id_reused`.
5769    pub fn mutate_with_commit_id(
5770        &mut self,
5771        mutations: Vec<Mutation>,
5772        client_commit_id: Option<String>,
5773    ) -> Result<String, ClientError> {
5774        let prior = self.storage_failure.borrow_mut().take();
5775        if let Some(id) = &client_commit_id {
5776            let held = if id.is_empty() {
5777                Err("sync.invalid_request: clientCommitId is empty".to_owned())
5778            } else {
5779                self.conn
5780                    .query_row(
5781                        "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id=?1 UNION ALL SELECT 1 FROM _syncular_commit_outcomes WHERE client_commit_id=?1)",
5782                        [id],
5783                        |row| row.get(0),
5784                    )
5785                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5786            };
5787            match held {
5788                Ok(false) => {}
5789                Ok(true) => {
5790                    return self.finish_authoring(
5791                        prior,
5792                        Err(ClientError {
5793                            code: "client.commit_id_reused".to_owned(),
5794                            message: "clientCommitId is held".to_owned(),
5795                            details: Some(json!({ "clientCommitId": id })),
5796                            retryable: false,
5797                        }),
5798                    )
5799                }
5800                Err(message) => return self.finish_authoring(prior, Err(message.into())),
5801            }
5802        }
5803        let outcome = (|| -> Result<String, ClientError> {
5804            if mutations.is_empty() {
5805                return Err(
5806                    "sync.invalid_request: a commit must contain at least one operation (§6.1)"
5807                        .to_owned()
5808                        .into(),
5809                );
5810            }
5811            let mut ops = Vec::with_capacity(mutations.len());
5812            for mutation in mutations {
5813                match mutation {
5814                    Mutation::Patch {
5815                        table,
5816                        values,
5817                        base_version,
5818                    } => {
5819                        let schema_table = self
5820                            .schema
5821                            .table(&table)
5822                            .ok_or_else(|| "sync.unknown_table".to_owned())?;
5823                        let values = normalize_values_casing(schema_table, values)?;
5824                        let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
5825                        ops.push(self.prepare_patch(&table, &row_id, values, base_version)?);
5826                    }
5827                    Mutation::Upsert {
5828                        table,
5829                        values,
5830                        base_version,
5831                    } => {
5832                        let schema_table = self.schema.table(&table).ok_or_else(|| {
5833                            format!("sync.unknown_table: unknown table {table:?}")
5834                        })?;
5835                        // §5: value keys are accepted in snake_case AND the
5836                        // generated row types' camelCase; normalize to SQL truth
5837                        // before the pk lookup / codec see them.
5838                        let values = normalize_values_casing(schema_table, values)?;
5839                        let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
5840                        // §6.7 `mutate` marks every column present: fill missing
5841                        // nullable columns with NULL before the payload is built.
5842                        let values = full_row_values(schema_table, values)?;
5843                        // §5.11: validate the payload encodes with the current
5844                        // codec. A key-selection or unknown-key failure is a
5845                        // durable rejection at the push seam (§10.3), never an
5846                        // author-time error. Full-row `mutate` presents every
5847                        // column, so no stored fallback is needed.
5848                        self.validate_author_encode(schema_table, &row_id, &values)?;
5849                        // §7.1 insert intent: the row is absent from the
5850                        // visible replica at call time, before this batch
5851                        // applies anything.
5852                        let insert = !self.visible_row_exists(schema_table, &row_id)?;
5853                        ops.push(OutboxOp {
5854                            upsert: true,
5855                            table,
5856                            row_id,
5857                            base_version,
5858                            values: Some(values),
5859                            insert,
5860                        });
5861                    }
5862                    Mutation::Delete {
5863                        table,
5864                        row_id,
5865                        base_version,
5866                    } => {
5867                        if self.schema.table(&table).is_none() {
5868                            return Err(
5869                                format!("sync.unknown_table: unknown table {table:?}").into()
5870                            );
5871                        }
5872                        // §2.4: the server rejects a rowId holding U+0000.
5873                        if row_id.contains('\0') {
5874                            return Err("sync.invalid_request: rowId holds U+0000 (§2.4)"
5875                                .to_owned()
5876                                .into());
5877                        }
5878                        ops.push(OutboxOp {
5879                            upsert: false,
5880                            table,
5881                            row_id,
5882                            base_version,
5883                            values: None,
5884                            insert: false,
5885                        });
5886                    }
5887                }
5888            }
5889            Ok(self.record_outbox_commit(ops, client_commit_id)?)
5890        })();
5891        self.finish_authoring(prior, outcome)
5892    }
5893
5894    /// Scope the retained `storage_failure` diagnostic to this call so an
5895    /// earlier operation's failure cannot classify a new one, and surface the
5896    /// call's own classified failure with its details. A fresh classified
5897    /// failure replaces the retained diagnostic; otherwise the earlier one is
5898    /// kept for the next sync.
5899    fn finish_authoring(
5900        &self,
5901        prior: Option<QueryReadFailure>,
5902        outcome: Result<String, ClientError>,
5903    ) -> Result<String, ClientError> {
5904        let fresh = self.storage_failure.borrow_mut().take();
5905        *self.storage_failure.borrow_mut() = fresh.clone().or(prior);
5906        outcome.map_err(|error| fresh.map(ClientError::from).unwrap_or(error))
5907    }
5908
5909    fn record_outbox_commit(
5910        &mut self,
5911        ops: Vec<OutboxOp>,
5912        client_commit_id: Option<String>,
5913    ) -> Result<String, String> {
5914        let commit = OutboxCommit {
5915            client_commit_id: client_commit_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
5916            ops,
5917        };
5918        self.begin_observation("syncular_mutation")?;
5919        let mut batch = ChangeAccumulator::default();
5920        for op in &commit.ops {
5921            let mut precise = self.record_row_scopes(&mut batch, &op.table, &op.row_id, false);
5922            if let Some(values) = &op.values {
5923                if let Some(table) = self.schema.table(&op.table) {
5924                    for scope in &table.scope_variables {
5925                        if let Some(Value::String(value)) = values.get(&scope.column) {
5926                            batch.scope(&op.table, format!("{}:{value}", scope.prefix));
5927                            precise = true;
5928                        }
5929                    }
5930                }
5931            }
5932            if !precise {
5933                batch.table(&op.table);
5934            }
5935        }
5936        if let Err(error) = self.persist_outbox_insert(&commit) {
5937            self.rollback_observation("syncular_mutation");
5938            return Err(error);
5939        }
5940        // A clean overlay contains the FIFO fold of every previous commit, so
5941        // the new commit applies over it. §7.1: an operation that does not
5942        // apply (a secondary unique collision) fails the whole commit; the
5943        // savepoint rollback removes the outbox entry and every visible write.
5944        // The append undoes itself: a rollback capture would copy the outbox.
5945        let was_dirty = self.overlay_dirty.snapshot();
5946        let id = commit.client_commit_id.clone();
5947        let appended = self.rebuild_overlay_if_dirty().and_then(|()| {
5948            commit
5949                .ops
5950                .iter()
5951                .try_for_each(|op| self.apply_outbox_op(op))?;
5952            self.outbox.push(Arc::new(commit));
5953            batch.status = true;
5954            self.finish_observation("syncular_mutation", batch)
5955                .inspect_err(|_| drop(self.outbox.pop()))
5956        });
5957        if let Err(error) = appended {
5958            self.rollback_observation("syncular_mutation");
5959            self.overlay_dirty.restore(was_dirty);
5960            return Err(error);
5961        }
5962        Ok(id)
5963    }
5964
5965    /// Record one §6.1 sparse upsert: the primary key plus the supplied
5966    /// non-scope columns are present; every other column is absent and stays
5967    /// untouched on the server and in the local overlay. An absent local base
5968    /// refuses the whole batch with sync.row_missing before enqueueing (§7.1).
5969    /// Failures are structured so callers read `code`/`message`/`details`.
5970    pub fn patch(
5971        &mut self,
5972        table: &str,
5973        row_id: &str,
5974        partial: Map<String, Value>,
5975        base_version: Option<i64>,
5976    ) -> Result<String, ClientError> {
5977        let prior = self.storage_failure.borrow_mut().take();
5978        let outcome = self.perform_patch(table, row_id, partial, base_version);
5979        self.finish_authoring(prior, outcome)
5980    }
5981
5982    /// The unscoped patch body. Public authoring entry points scope
5983    /// `storage_failure` around the whole operation, including any pre-read.
5984    fn perform_patch(
5985        &mut self,
5986        table: &str,
5987        row_id: &str,
5988        partial: Map<String, Value>,
5989        base_version: Option<i64>,
5990    ) -> Result<String, ClientError> {
5991        let operation = self.prepare_patch(table, row_id, partial, base_version)?;
5992        Ok(self.record_outbox_commit(vec![operation], None)?)
5993    }
5994
5995    fn prepare_patch(
5996        &self,
5997        table: &str,
5998        row_id: &str,
5999        partial: Map<String, Value>,
6000        base_version: Option<i64>,
6001    ) -> Result<OutboxOp, ClientError> {
6002        let schema_table = self
6003            .schema
6004            .table(table)
6005            .ok_or_else(|| format!("sync.unknown_table: unknown table {table:?}"))?;
6006        let partial = normalize_values_casing(schema_table, partial)?;
6007        if let Some(pk) = partial.get(&schema_table.primary_key) {
6008            if render_row_id_json(Some(pk)).ok().as_deref() != Some(row_id) {
6009                return Err(invalid_authoring(
6010                    "patch cannot change the primary key",
6011                    json!({ "table": table }),
6012                ));
6013            }
6014        }
6015        if !self.visible_row_exists(schema_table, row_id)? {
6016            return Err("sync.row_missing: a sparse patch requires a local row"
6017                .to_owned()
6018                .into());
6019        }
6020        // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
6021        // server accepts a present scope column whose value equals the
6022        // stored row and applies it as a no-op, so a decoded envelope
6023        // round-trips. The local row is the only value the client can prove
6024        // equality against; when the row is absent locally the client cannot
6025        // prove equality against the server's stored row and fails closed.
6026        // A primary key that is also a scope column needs no stored-row
6027        // read: the primary key in a sparse payload is by construction the
6028        // row id being patched (§6.1), so its value is proven equal already.
6029        for scope in &schema_table.scope_variables {
6030            if !partial.contains_key(&scope.column) || scope.column == schema_table.primary_key {
6031                continue;
6032            }
6033            let Some(column) = schema_table
6034                .columns
6035                .iter()
6036                .find(|column| column.name == scope.column)
6037            else {
6038                continue;
6039            };
6040            let stored = self
6041                .conn
6042                .query_row(
6043                    &format!(
6044                        "SELECT {} FROM {} WHERE {}",
6045                        quote_ident(&scope.column),
6046                        visible_table(&schema_table.name),
6047                        row_id_predicate(schema_table)
6048                    ),
6049                    rusqlite::params![row_id],
6050                    |row| Ok(sql_ref_to_json(column, row.get_ref(0)?)),
6051                )
6052                .optional()
6053                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6054            // Decode the supplied value through the same column-type path the
6055            // rest of the patch encoding uses, so a value that only equals
6056            // the stored one in another number representation still compares
6057            // equal.
6058            let incoming = json_to_column_value(column, partial.get(&scope.column))
6059                .ok()
6060                .map(|value| column_value_to_json(&value));
6061            // A stored blob never equals a patch value, matching the server's
6062            // scope-column comparison (§3.4): bytes are unstorable as scope
6063            // values.
6064            let equal = stored.as_ref().is_some_and(|stored| {
6065                stored.get("$bytes").is_none() && incoming.as_ref() == Some(stored)
6066            });
6067            if !equal {
6068                return Err(invalid_authoring(
6069                    "patch cannot write a scope column (§3.4)",
6070                    json!({ "table": table, "column": scope.column }),
6071                ));
6072            }
6073        }
6074        let mut values = partial;
6075        // Presence-set semantics: a proven-equal scope column is dropped, so
6076        // the patch leaves the stored value untouched (§6.2).
6077        for scope in &schema_table.scope_variables {
6078            values.remove(&scope.column);
6079        }
6080        let pk_value = match schema_table.columns[schema_table.pk_index].ty {
6081            // §2.4: the rowId of an integer key is its canonical decimal form.
6082            ColumnType::Integer => match row_id.parse::<i64>() {
6083                Ok(v)
6084                    if v.to_string() == row_id
6085                        && (-ssp2::primitives::I64_SAFE_MAX..=ssp2::primitives::I64_SAFE_MAX)
6086                            .contains(&v) =>
6087                {
6088                    Value::from(v)
6089                }
6090                _ => {
6091                    return Err(format!(
6092                    "sync.invalid_request: table {table:?}: invalid integer primary key {row_id:?}"
6093                )
6094                    .into())
6095                }
6096            },
6097            ColumnType::Boolean => match row_id {
6098                "true" => Value::Bool(true),
6099                "false" => Value::Bool(false),
6100                _ => {
6101                    return Err(format!(
6102                    "sync.invalid_request: table {table:?}: invalid boolean primary key {row_id:?}"
6103                )
6104                    .into())
6105                }
6106            },
6107            _ => Value::from(row_id.to_owned()),
6108        };
6109        values.insert(schema_table.primary_key.clone(), pk_value);
6110        // §6.1: a patch cannot null a non-nullable column.
6111        if let Some(column) = schema_table
6112            .columns
6113            .iter()
6114            .find(|column| !column.nullable && values.get(&column.name) == Some(&Value::Null))
6115        {
6116            return Err(invalid_authoring(
6117                "a non-nullable column is null (§6.1)",
6118                json!({ "table": table, "column": column.name }),
6119            ));
6120        }
6121        // §5.11: structural validation only; an absent key-id selector is
6122        // resolved at the push seam from the stored local row, and a
6123        // key-selection or unknown-key failure becomes a durable
6124        // `client.encrypt_failed` rejection there (§10.3), never an
6125        // author-time error.
6126        self.validate_author_encode(schema_table, row_id, &values)?;
6127        Ok(OutboxOp {
6128            upsert: true,
6129            table: table.to_owned(),
6130            row_id: row_id.to_owned(),
6131            base_version,
6132            values: Some(values),
6133            insert: false,
6134        })
6135    }
6136
6137    /// §5.11 key-id fallback: the stored local row's selector value as a
6138    /// positional row (only the selector slot filled). Returns None when no
6139    /// selector is configured, the row is locally absent, or the stored
6140    /// value is not a usable key id. A failed storage read is an error.
6141    fn stored_key_fallback(
6142        &self,
6143        table: &TableSchema,
6144        row_id: &str,
6145    ) -> Result<Option<Row>, String> {
6146        let Some(selector) = self.encryption.key_id_columns.get(&table.name) else {
6147            return Ok(None);
6148        };
6149        let Some(index) = table
6150            .columns
6151            .iter()
6152            .position(|column| &column.name == selector)
6153        else {
6154            return Ok(None);
6155        };
6156        let sql = format!(
6157            "SELECT {} FROM {} WHERE {}",
6158            quote_ident(selector),
6159            visible_table(&table.name),
6160            row_id_predicate(table)
6161        );
6162        let key = self
6163            .conn
6164            .query_row(&sql, rusqlite::params![row_id], |row| {
6165                row.get::<_, Option<String>>(0)
6166            })
6167            .optional()
6168            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6169            .flatten()
6170            .filter(|key| !key.is_empty());
6171        let Some(key) = key else {
6172            return Ok(None);
6173        };
6174        let mut fallback: Row = vec![None; table.columns.len()];
6175        fallback[index] = Some(ColumnValue::String(key));
6176        Ok(Some(fallback))
6177    }
6178
6179    /// §5.11/§10.3 author-time encode check: a structural failure (a
6180    /// non-nullable NULL, a value the codec rejects) is an author-time
6181    /// error; a key-selection or unknown-key failure is deferred to the push
6182    /// seam, where it becomes a durable `client.encrypt_failed` rejection.
6183    fn validate_author_encode(
6184        &self,
6185        table: &TableSchema,
6186        row_id: &str,
6187        values: &Map<String, Value>,
6188    ) -> Result<(), String> {
6189        match encode_sparse_row_json(table, row_id, values, &self.encryption, None) {
6190            Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => Ok(()),
6191            result => result.map(|_| ()),
6192        }
6193    }
6194
6195    /// §5.11/§10.3: drop every pending commit whose push encode fails with
6196    /// `client.encrypt_failed` (an unresolvable key id or an unknown key) and
6197    /// raise one durable rejection per commit. `sync()` never aborts for an
6198    /// encode failure. Mirrors §7.4.4's `drop_incompatible_outbox`, including
6199    /// undoing the dropped commit's purely-optimistic rows.
6200    /// §7.1/§7.4.4: drop pending commits whose values the current codec refuses
6201    /// (an envelope or a type an earlier version accepted). `with_encryption`
6202    /// additionally drops commits whose §5.11 encryption cannot resolve a key;
6203    /// the startup boundary leaves those to the send seam, where hosts configure
6204    /// keys after open.
6205    /// Recovery runs as one observation. An enclosing observation (the guarded
6206    /// schema reset) passes its `batch`, so the rejection, outcome, and table
6207    /// domains join that change event instead of publishing a second one.
6208    fn drop_unencodable_outbox(
6209        &mut self,
6210        with_encryption: bool,
6211        batch: Option<&mut ChangeAccumulator>,
6212    ) -> Result<bool, String> {
6213        let mut failures = Vec::new();
6214        for commit in self.outbox.iter() {
6215            for op in &commit.ops {
6216                let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6217                    continue;
6218                };
6219                // An insert lacking a non-nullable column is left to
6220                // `drop_incompatible_outbox` (§7.4.4).
6221                let Some(values) = op.presented_values(table) else {
6222                    continue;
6223                };
6224                let fallback = self.stored_key_fallback(table, &op.row_id)?;
6225                let failure = match encode_sparse_row_json(
6226                    table,
6227                    &op.row_id,
6228                    &values,
6229                    &self.encryption,
6230                    fallback.as_ref(),
6231                ) {
6232                    Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => {
6233                        with_encryption.then_some((error, ENCRYPT_FAILED_CODE))
6234                    }
6235                    // §7.1/§7.4.4: a value the current codec refuses was
6236                    // persisted by a version that accepted it; it leaves
6237                    // through the incompatible-outbox path, so the FIFO
6238                    // queue never wedges.
6239                    Err(error) if error.starts_with(INVALID_REQUEST_CODE) => Some((
6240                        LEGACY_VALUE_REFUSAL_MESSAGE.to_owned(),
6241                        OUTBOX_INCOMPATIBLE_CODE,
6242                    )),
6243                    _ => None,
6244                };
6245                if let Some((error, code)) = failure {
6246                    failures.push((commit.clone(), error, code));
6247                    break;
6248                }
6249            }
6250        }
6251        if failures.is_empty() {
6252            return Ok(false);
6253        }
6254        // §7.4.4: one observation covers the durable outcome writes, the outbox
6255        // removal, the in-memory drop, and the overlay rebuild, so a storage fault
6256        // leaves the replica and the client unchanged, a successful recovery
6257        // publishes one batch with the rejection, outcome, and table domains, and
6258        // an ordinary open with nothing to recover publishes nothing.
6259        let rollback = self.capture();
6260        let owns_observation = batch.is_none();
6261        let owns_transaction = self.conn.is_autocommit();
6262        let mut domains = ChangeAccumulator::default();
6263        if owns_observation {
6264            self.begin_observation("syncular_value_recovery")?;
6265        }
6266        let dropped = (|| -> Result<(), String> {
6267            for (commit, message, code) in failures {
6268                if self.retain_failed_commits && code == ENCRYPT_FAILED_CODE {
6269                    self.retain_failed_commit(&commit.client_commit_id, &commit.ops)?;
6270                }
6271                let representable = commit.ops.iter().all(Self::outbox_op_is_journalable);
6272                let rejection = RejectionRecord {
6273                    client_commit_id: commit.client_commit_id.clone(),
6274                    op_index: 0,
6275                    code: code.to_owned(),
6276                    message,
6277                    retryable: false,
6278                    details: (code == OUTBOX_INCOMPATIBLE_CODE).then(|| RejectionDetails {
6279                        field_paths: None,
6280                        reason: Some(INVALID_STORED_VALUES_REASON.to_owned()),
6281                        required_action: None,
6282                        references: None,
6283                    }),
6284                    operation: representable
6285                        .then(|| commit.ops.first())
6286                        .flatten()
6287                        .map(CommitOperation::from),
6288                };
6289                self.persist_commit_outcome(
6290                    &commit.client_commit_id,
6291                    CommitOutcomeStatus::Rejected,
6292                    &[CommitOperationOutcome::Error {
6293                        rejection: rejection.clone(),
6294                    }],
6295                    representable.then_some(commit.ops.as_slice()),
6296                )?;
6297                self.delete_outbox_persisted(&commit.client_commit_id)?;
6298                self.outbox
6299                    .retain(|candidate| candidate.client_commit_id != commit.client_commit_id);
6300                self.rejections.push(rejection);
6301                for operation in &commit.ops {
6302                    domains.table(operation.table.as_str());
6303                }
6304            }
6305            domains.status = true;
6306            domains.rejections = true;
6307            domains.outcomes = true;
6308            self.prune_commit_outcomes()?;
6309            // The visible projection is re-derived from the surviving base + outbox.
6310            self.overlay_dirty.set(true);
6311            self.rebuild_overlay()?;
6312            Ok(())
6313        })();
6314        let result = match batch {
6315            Some(batch) => {
6316                if dropped.is_ok() {
6317                    for table in domains.tables.keys() {
6318                        batch.table(table.as_str());
6319                    }
6320                    batch.status |= domains.status;
6321                    batch.rejections |= domains.rejections;
6322                    batch.outcomes |= domains.outcomes;
6323                }
6324                dropped
6325            }
6326            None => {
6327                dropped.and_then(|()| self.finish_observation("syncular_value_recovery", domains))
6328            }
6329        };
6330        if let Err(error) = result {
6331            if owns_observation {
6332                if owns_transaction {
6333                    if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
6334                        let mut failure = self.storage_failure.borrow_mut();
6335                        let failure =
6336                            failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
6337                        failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
6338                    }
6339                } else {
6340                    self.rollback_observation("syncular_value_recovery");
6341                }
6342            }
6343            self.restore(rollback);
6344            return Err(error);
6345        }
6346        Ok(true)
6347    }
6348
6349    pub fn pending_commit_ids(&self) -> Vec<String> {
6350        self.outbox
6351            .iter()
6352            .map(|c| c.client_commit_id.clone())
6353            .collect()
6354    }
6355
6356    /// §6.1: the sparse push payload bytes of every pending upsert operation,
6357    /// FIFO — exactly what the next push round would put on the wire. Used by
6358    /// conformance B.21(h) to pin cross-core byte identity.
6359    pub fn pending_payloads(&self) -> Result<Vec<Vec<u8>>, String> {
6360        let mut payloads = Vec::new();
6361        for commit in self.outbox.iter() {
6362            for op in &commit.ops {
6363                let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6364                    continue;
6365                };
6366                let Some(values) = op.presented_values(table) else {
6367                    continue;
6368                };
6369                let fallback = self.stored_key_fallback(table, &op.row_id)?;
6370                if let Ok(payload) = encode_sparse_row_json(
6371                    table,
6372                    &op.row_id,
6373                    &values,
6374                    &self.encryption,
6375                    fallback.as_ref(),
6376                ) {
6377                    payloads.push(payload);
6378                }
6379            }
6380        }
6381        Ok(payloads)
6382    }
6383
6384    pub fn conflicts(&self) -> &[ConflictRecord] {
6385        &self.conflicts
6386    }
6387
6388    pub fn rejections(&self) -> &[RejectionRecord] {
6389        &self.rejections
6390    }
6391
6392    pub fn resolve_commit_outcome(
6393        &mut self,
6394        input: ResolveCommitOutcomeInput,
6395    ) -> Result<CommitOutcome, String> {
6396        let current = self
6397            .commit_outcome(&input.client_commit_id)?
6398            .ok_or_else(|| {
6399                format!(
6400                    "sync.outcome_not_found: no durable outcome exists for {:?}",
6401                    input.client_commit_id
6402                )
6403            })?;
6404        if current.resolution != CommitOutcomeResolution::Active {
6405            return Ok(current);
6406        }
6407        if input.resolution == CommitOutcomeResolution::Active {
6408            return Err("sync.invalid_request: resolution must leave active state".to_owned());
6409        }
6410        match input.resolution {
6411            CommitOutcomeResolution::Superseded => {
6412                let replacement = input
6413                    .replacement_client_commit_id
6414                    .as_deref()
6415                    .filter(|value| !value.is_empty() && *value != input.client_commit_id)
6416                    .ok_or_else(|| {
6417                        "sync.invalid_request: superseded outcomes require a distinct replacementClientCommitId"
6418                            .to_owned()
6419                    })?;
6420                let _ = replacement;
6421            }
6422            _ if input.replacement_client_commit_id.is_some() => {
6423                return Err(
6424                    "sync.invalid_request: replacementClientCommitId is valid only for superseded outcomes"
6425                        .to_owned(),
6426                );
6427            }
6428            _ => {}
6429        }
6430        let allowed = match current.status {
6431            CommitOutcomeStatus::Conflict => matches!(
6432                input.resolution,
6433                CommitOutcomeResolution::ResolvedKeepServer | CommitOutcomeResolution::Superseded
6434            ),
6435            CommitOutcomeStatus::Rejected => {
6436                matches!(
6437                    input.resolution,
6438                    CommitOutcomeResolution::Superseded
6439                        | CommitOutcomeResolution::ResolvedKeepServer
6440                )
6441            }
6442            CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => {
6443                input.resolution == CommitOutcomeResolution::Dismissed
6444            }
6445        };
6446        if !allowed {
6447            return Err(format!(
6448                "sync.invalid_request: resolution {:?} is invalid for {:?} outcome",
6449                input.resolution, current.status
6450            ));
6451        }
6452
6453        let rollback = self.capture();
6454        self.begin_observation("syncular_outcome_resolution")?;
6455        let result = (|| {
6456            self.conn
6457                .execute(
6458                    "UPDATE _syncular_commit_outcomes
6459                        SET resolution = ?1, resolved_at_ms = ?2,
6460                            replacement_client_commit_id = ?3
6461                      WHERE client_commit_id = ?4 AND resolution = 'active'",
6462                    rusqlite::params![
6463                        Self::outcome_resolution_name(input.resolution),
6464                        self.clock_now_ms(),
6465                        input.replacement_client_commit_id,
6466                        input.client_commit_id
6467                    ],
6468                )
6469                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6470            let resolved = self
6471                .commit_outcome(&current.client_commit_id)?
6472                .ok_or_else(|| "sync.outcome_not_found: outcome disappeared".to_owned())?;
6473            self.conn
6474                .execute(
6475                    "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
6476                    rusqlite::params![input.client_commit_id],
6477                )
6478                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6479            for (commit, _) in self.failed_commits.iter() {
6480                if commit.client_commit_id == input.client_commit_id {
6481                    for operation in &commit.ops {
6482                        self.overlay_dirty.table(&operation.table);
6483                    }
6484                }
6485            }
6486            self.failed_commits
6487                .retain(|(commit, _)| commit.client_commit_id != input.client_commit_id);
6488            self.prune_commit_outcomes()?;
6489            Ok(resolved)
6490        })();
6491        let resolved = match result {
6492            Ok(outcome) => outcome,
6493            Err(error) => {
6494                self.rollback_observation("syncular_outcome_resolution");
6495                self.restore(rollback);
6496                return Err(error);
6497            }
6498        };
6499        self.conflicts
6500            .retain(|record| record.client_commit_id != current.client_commit_id);
6501        self.rejections
6502            .retain(|record| record.client_commit_id != current.client_commit_id);
6503        let mut batch = ChangeAccumulator {
6504            conflicts: current.status == CommitOutcomeStatus::Conflict,
6505            rejections: current.status == CommitOutcomeStatus::Rejected,
6506            outcomes: true,
6507            ..ChangeAccumulator::default()
6508        };
6509        if let Some(operations) = &current.operations {
6510            for operation in operations {
6511                batch.table(&operation.table);
6512            }
6513        }
6514        if let Err(error) = self
6515            .rebuild_overlay_if_dirty()
6516            .and_then(|()| self.finish_observation("syncular_outcome_resolution", batch))
6517        {
6518            self.rollback_observation("syncular_outcome_resolution");
6519            self.restore(rollback);
6520            return Err(error);
6521        }
6522        Ok(resolved)
6523    }
6524
6525    pub fn schema_floor(&self) -> Option<&SchemaFloor> {
6526        self.schema_floor.as_ref()
6527    }
6528
6529    /// §7.3.5: the client's opaque auth-lease state, if any.
6530    pub fn lease_state(&self) -> Option<&LeaseState> {
6531        self.lease_state.as_ref()
6532    }
6533
6534    /// §7.3.5: record a request-level lease error (stop-and-surface). Only
6535    /// the two lease codes set it; other errors leave leaseState untouched.
6536    fn record_lease_error(&mut self, code: &str) -> Result<(), String> {
6537        if code != "sync.auth_lease_required" && code != "sync.auth_lease_revoked" {
6538            return Ok(());
6539        }
6540        let mut next = self.lease_state.clone().unwrap_or_default();
6541        next.error_code = Some(code.to_owned());
6542        self.set_lease_state(Some(next))
6543    }
6544
6545    fn set_lease_state(&mut self, next: Option<LeaseState>) -> Result<(), String> {
6546        if self.lease_state == next {
6547            return Ok(());
6548        }
6549        self.begin_observation("syncular_lease")?;
6550        let rollback = self.capture();
6551        self.lease_state = next;
6552        let persisted = match &self.lease_state {
6553            Some(lease) => serde_json::to_string(lease)
6554                .map_err(|error| error.to_string())
6555                .and_then(|json| self.set_meta(LEASE_STATE_KEY, &json)),
6556            None => self.delete_meta(LEASE_STATE_KEY),
6557        };
6558        let batch = ChangeAccumulator {
6559            status: true,
6560            ..ChangeAccumulator::default()
6561        };
6562        if let Err(error) =
6563            persisted.and_then(|()| self.finish_observation("syncular_lease", batch))
6564        {
6565            self.rollback_observation("syncular_lease");
6566            self.restore(rollback);
6567            return Err(error);
6568        }
6569        Ok(())
6570    }
6571
6572    fn set_schema_floor(&mut self, next: Option<SchemaFloor>) -> Result<(), String> {
6573        if self.schema_floor == next {
6574            return Ok(());
6575        }
6576        self.begin_observation("syncular_schema_floor")?;
6577        let rollback = self.capture();
6578        self.stopped = next.is_some();
6579        self.schema_floor = next;
6580        let persisted = match &self.schema_floor {
6581            Some(floor) => serde_json::to_string(floor)
6582                .map_err(|error| error.to_string())
6583                .and_then(|json| self.set_meta(SCHEMA_FLOOR_KEY, &json)),
6584            None => self.delete_meta(SCHEMA_FLOOR_KEY),
6585        };
6586        let batch = ChangeAccumulator {
6587            status: true,
6588            ..ChangeAccumulator::default()
6589        };
6590        if let Err(error) =
6591            persisted.and_then(|()| self.finish_observation("syncular_schema_floor", batch))
6592        {
6593            self.rollback_observation("syncular_schema_floor");
6594            self.restore(rollback);
6595            return Err(error);
6596        }
6597        Ok(())
6598    }
6599
6600    fn set_upgrading(&mut self, value: bool) {
6601        if self.upgrading == value {
6602            return;
6603        }
6604        if self.begin_observation("syncular_upgrading").is_err() {
6605            return;
6606        }
6607        self.upgrading = value;
6608        let batch = ChangeAccumulator {
6609            status: true,
6610            ..ChangeAccumulator::default()
6611        };
6612        if self
6613            .finish_observation("syncular_upgrading", batch)
6614            .is_err()
6615        {
6616            self.rollback_observation("syncular_upgrading");
6617        }
6618    }
6619
6620    pub fn sync_needed(&self) -> bool {
6621        self.sync_needed
6622    }
6623
6624    pub fn read_rows(&self, table: &str) -> Result<Vec<RowState>, String> {
6625        let schema_table = self
6626            .schema
6627            .table(table)
6628            .ok_or_else(|| format!("unknown table {table:?}"))?;
6629        let sql = format!(
6630            "SELECT * FROM {} ORDER BY {} ASC",
6631            visible_table(table),
6632            quote_ident(&schema_table.primary_key)
6633        );
6634        let mut stmt = self
6635            .conn
6636            .prepare(&sql)
6637            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6638        let mut rows = stmt
6639            .query([])
6640            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6641        let mut out = Vec::new();
6642        while let Some(row) = rows
6643            .next()
6644            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6645        {
6646            let mut values = Map::new();
6647            for (i, column) in schema_table.columns.iter().enumerate() {
6648                let value = row
6649                    .get_ref(i)
6650                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6651                values.insert(column.name.clone(), sql_ref_to_json(column, value));
6652            }
6653            let version: i64 = row
6654                .get(schema_table.columns.len())
6655                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6656            let row_id = match values.get(&schema_table.primary_key) {
6657                Some(Value::String(s)) => s.clone(),
6658                Some(Value::Number(n)) => n.to_string(),
6659                Some(Value::Bool(b)) => b.to_string(),
6660                other => format!("{}", other.cloned().unwrap_or(Value::Null)),
6661            };
6662            out.push(RowState {
6663                row_id,
6664                version,
6665                values,
6666            });
6667        }
6668        Ok(out)
6669    }
6670
6671    // -- §5.10.5 native CRDT (the `crdt-yjs` feature) --------------------------
6672    //
6673    // The Rust face of the §5.10.4 client model: a local crdt edit loads the
6674    // current stored (server-merged ⊕ pending-overlay) column bytes, applies
6675    // the op with `yrs`, re-encodes the whole doc state, and records a
6676    // baseVersion-less sparse upsert carrying only the primary key and the
6677    // crdt column (§5.10.3, §6.6). No local merge — merging is server-side;
6678    // the overlay re-materializes the edit immediately (optimistic apply,
6679    // §7.1) and the server-merged bytes arrive on the next pull, idempotently.
6680    // Byte-compatible with `@syncular/crdt-yjs`.
6681
6682    /// The current stored value of a `crdt` column for one row — the visible
6683    /// (optimistic) bytes, or `None` when the row is absent or the column is
6684    /// NULL (the empty document, §5.10.1). Errors if the column is not a
6685    /// `crdt` column (guards the app against a typo'd column name).
6686    #[cfg(feature = "crdt-yjs")]
6687    fn crdt_column_bytes(
6688        &self,
6689        table: &str,
6690        row_id: &str,
6691        column: &str,
6692    ) -> Result<Option<Vec<u8>>, String> {
6693        let schema_table = self
6694            .schema
6695            .table(table)
6696            .ok_or_else(|| format!("unknown table {table:?}"))?;
6697        let col = schema_table
6698            .columns
6699            .iter()
6700            .find(|c| c.name == column)
6701            .ok_or_else(|| format!("table {table:?} has no column {column:?}"))?;
6702        if col.ty != ColumnType::Crdt {
6703            return Err(format!("column {column:?} is not a crdt column (§5.10.1)"));
6704        }
6705        let sql = format!(
6706            "SELECT {} FROM {} WHERE {}",
6707            quote_ident(column),
6708            visible_table(table),
6709            row_id_predicate(schema_table)
6710        );
6711        let bytes: Option<Vec<u8>> = self
6712            .conn
6713            .prepare_cached(&sql)
6714            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6715            .query_row(rusqlite::params![row_id], |row| {
6716                row.get::<_, Option<Vec<u8>>>(0)
6717            })
6718            .map_err(|e| match e {
6719                rusqlite::Error::QueryReturnedNoRows => "no such row".to_owned(),
6720                other => Self::sqlite_failure(&self.storage_failure, other),
6721            })?;
6722        Ok(bytes)
6723    }
6724
6725    /// §5.10.4 materialize: the collaborative text of a `crdt` column, decoded
6726    /// from the stored bytes with `yrs` — `YjsColumn.text(name).toString()`.
6727    /// An absent row / NULL column is the empty document (empty string).
6728    #[cfg(feature = "crdt-yjs")]
6729    pub fn crdt_text(
6730        &self,
6731        table: &str,
6732        row_id: &str,
6733        column: &str,
6734        name: &str,
6735    ) -> Result<String, String> {
6736        let bytes = self
6737            .crdt_column_bytes(table, row_id, column)?
6738            .unwrap_or_default();
6739        crate::crdt::text(&bytes, name)
6740    }
6741
6742    /// §5.10.4 push-an-update: apply a text insert to a `crdt` column and
6743    /// record the resulting crdt-only sparse operation. Returns the enqueued
6744    /// `clientCommitId`.
6745    #[cfg(feature = "crdt-yjs")]
6746    pub fn crdt_insert_text(
6747        &mut self,
6748        table: &str,
6749        row_id: &str,
6750        column: &str,
6751        name: &str,
6752        index: u32,
6753        value: &str,
6754    ) -> Result<String, ClientError> {
6755        let prior = self.storage_failure.borrow_mut().take();
6756        let outcome = (|| -> Result<String, ClientError> {
6757            let current = self
6758                .crdt_column_bytes(table, row_id, column)?
6759                .unwrap_or_default();
6760            let update = crate::crdt::insert_text(&current, name, index, value)?;
6761            self.perform_crdt_push_update(table, row_id, column, &update)
6762        })();
6763        self.finish_authoring(prior, outcome)
6764    }
6765
6766    /// §5.10.4 push-an-update: apply a text delete to a `crdt` column and
6767    /// record the resulting crdt-only sparse operation. Returns the enqueued
6768    /// `clientCommitId`.
6769    #[cfg(feature = "crdt-yjs")]
6770    pub fn crdt_delete_text(
6771        &mut self,
6772        table: &str,
6773        row_id: &str,
6774        column: &str,
6775        name: &str,
6776        index: u32,
6777        len: u32,
6778    ) -> Result<String, ClientError> {
6779        let prior = self.storage_failure.borrow_mut().take();
6780        let outcome = (|| -> Result<String, ClientError> {
6781            let current = self
6782                .crdt_column_bytes(table, row_id, column)?
6783                .unwrap_or_default();
6784            let update = crate::crdt::delete_text(&current, name, index, len)?;
6785            self.perform_crdt_push_update(table, row_id, column, &update)
6786        })();
6787        self.finish_authoring(prior, outcome)
6788    }
6789
6790    /// §5.10.4 generic escape hatch: apply an arbitrary Yjs update onto a
6791    /// `crdt` column's current state and record the resulting crdt-only sparse
6792    /// operation. The app authored the update with its own `yrs` model.
6793    /// Returns the enqueued `clientCommitId`.
6794    #[cfg(feature = "crdt-yjs")]
6795    pub fn crdt_apply_update(
6796        &mut self,
6797        table: &str,
6798        row_id: &str,
6799        column: &str,
6800        update: &[u8],
6801    ) -> Result<String, ClientError> {
6802        let prior = self.storage_failure.borrow_mut().take();
6803        let outcome = (|| -> Result<String, ClientError> {
6804            let current = self
6805                .crdt_column_bytes(table, row_id, column)?
6806                .unwrap_or_default();
6807            let next = crate::crdt::apply_update(&current, update)?;
6808            self.perform_crdt_push_update(table, row_id, column, &next)
6809        })();
6810        self.finish_authoring(prior, outcome)
6811    }
6812
6813    /// Shared tail of the crdt edit methods: record a §6.1 sparse crdt-only
6814    /// upsert — the primary key plus the crdt column, no `baseVersion` — and
6815    /// enqueue it. The server merges the crdt column and leaves every other
6816    /// column untouched (§5.10.3), so a baseVersion-less crdt edit cannot
6817    /// clobber a concurrent edit to another column. A locally absent row
6818    /// records the same partial operation; the server answers per §6.2.
6819    #[cfg(feature = "crdt-yjs")]
6820    fn perform_crdt_push_update(
6821        &mut self,
6822        table: &str,
6823        row_id: &str,
6824        column: &str,
6825        crdt_bytes: &[u8],
6826    ) -> Result<String, ClientError> {
6827        let mut bytes_obj = Map::new();
6828        bytes_obj.insert("$bytes".to_owned(), Value::from(bytes_to_hex(crdt_bytes)));
6829        let mut partial = Map::new();
6830        partial.insert(column.to_owned(), Value::Object(bytes_obj));
6831        self.perform_patch(table, row_id, partial, None)
6832    }
6833
6834    /// Run an arbitrary read-only SQL query against the local database and
6835    /// return each row as a `column-name → JSON value` map. This is the seam
6836    /// the React `useSyncQuery` live-query API needs (it takes app-authored
6837    /// SQL over the visible tables/views, not a fixed table read like
6838    /// [`read_rows`]).
6839    ///
6840    /// Bound `params` are the driver value forms: JSON strings/numbers/bools/
6841    /// null bind directly; a `{"$bytes": hex}` object binds as a BLOB — the
6842    /// same envelope the command surface uses everywhere else. Output BLOB
6843    /// columns come back as `{"$bytes": hex}` to round-trip cleanly.
6844    ///
6845    /// The result column typing is dynamic (SQLite's stored affinity), because
6846    /// arbitrary SQL can alias, join, and compute — there is no schema column
6847    /// to consult per output cell, unlike [`read_rows`].
6848    pub fn query(&self, sql: &str, params: &[QueryValue]) -> Result<Vec<QueryRow>, String> {
6849        query_connection(&self.conn, sql, params).map_err(|failure| failure.to_string())
6850    }
6851
6852    /// Repository benchmark and conformance access, present only with `bench-internals`.
6853    #[cfg(feature = "bench-internals")]
6854    #[doc(hidden)]
6855    pub fn benchmark_connection(&mut self) -> &mut Connection {
6856        &mut self.conn
6857    }
6858
6859    /// Private benchmark intervals; absent from ordinary builds and diagnostics.
6860    #[cfg(feature = "bench-internals")]
6861    #[doc(hidden)]
6862    pub fn benchmark_phases(
6863        &self,
6864        enabled: Option<bool>,
6865        reset: bool,
6866    ) -> Result<Option<Value>, String> {
6867        self.benchmark_phases.configure(enabled, reset)?;
6868        Ok(self.benchmark_phases.snapshot())
6869    }
6870
6871    /// One serialized, read-only authority observation, including durable coverage.
6872    pub fn authority_snapshot(&self) -> Result<Value, String> {
6873        validate_authority_reads(&self.schema, &self.limits.authority_reads)?;
6874        if self.limits.authority_reads.is_empty() {
6875            return Err("client.authority_read_forbidden: no authority reads were declared at client creation".into());
6876        }
6877        self.conn
6878            .execute_batch("SAVEPOINT authority_snapshot")
6879            .map_err(|e| e.to_string())?;
6880        let result = (|| {
6881            let revision = self
6882                .get_meta(LOCAL_REVISION_KEY)?
6883                .ok_or("sync.local_corrupt: authority revision is missing")?;
6884            let parsed_revision = revision
6885                .parse::<u64>()
6886                .map_err(|_| "sync.local_corrupt: authority revision is invalid")?;
6887            if parsed_revision.to_string() != revision {
6888                return Err("sync.local_corrupt: authority revision is invalid".into());
6889            }
6890            let mut tables = Vec::new();
6891            for read in &self.limits.authority_reads {
6892                let table = self
6893                    .schema
6894                    .table(&read.table)
6895                    .ok_or("client.authority_read_forbidden: authority table is not declared")?;
6896                let scalar = |column: &str, value: &Value| -> Result<String, String> {
6897                    let ty = table
6898                        .columns
6899                        .iter()
6900                        .find(|c| c.name == column)
6901                        .expect("validated authority column")
6902                        .ty;
6903                    if ty == ColumnType::Boolean {
6904                        if let Some(value) = value.as_bool() {
6905                            return Ok(value.to_string());
6906                        }
6907                        return match value.as_i64() {
6908                            Some(0) => Ok("false".into()),
6909                            Some(1) => Ok("true".into()),
6910                            _ => Err("sync.local_corrupt: authority boolean is invalid".into()),
6911                        };
6912                    }
6913                    match value {
6914                        Value::String(s) => Ok(s.clone()),
6915                        Value::Number(n) => Ok(n.to_string()),
6916                        Value::Object(o) if ty == ColumnType::Integer && o.len() == 1 => o
6917                            .get("$bigint")
6918                            .and_then(Value::as_str)
6919                            .map(str::to_owned)
6920                            .ok_or("sync.local_corrupt: authority integer is invalid".into()),
6921                        _ => {
6922                            Err("sync.local_corrupt: authority scalar is missing or invalid".into())
6923                        }
6924                    }
6925                };
6926                let matches = |row: &QueryRow| -> Result<bool, String> {
6927                    for (variable, values) in &read.scopes {
6928                        let column = table
6929                            .scope_column(variable)
6930                            .expect("validated authority scope");
6931                        let value = row
6932                            .get(column)
6933                            .ok_or("sync.local_corrupt: authority scope column is missing")?;
6934                        if value.is_null() || !values.contains(&scalar(column, value)?) {
6935                            return Ok(false);
6936                        }
6937                    }
6938                    Ok(true)
6939                };
6940                let selected = read
6941                    .columns
6942                    .iter()
6943                    .map(|c| quote_ident(c))
6944                    .collect::<Vec<_>>()
6945                    .join(",");
6946                let mut intent = BTreeSet::new();
6947                let mut relevant = BTreeSet::new();
6948                for row in query_connection(&self.conn,
6949                    "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=?",
6950                    &[Value::String(read.table.clone())]).map_err(|e| e.to_string())? {
6951                    let id = row.get("id").and_then(Value::as_str).ok_or("sync.local_corrupt: authority intent id is invalid")?.to_owned();
6952                    intent.insert(id.clone());
6953                    if let Some(raw) = row.get("values_json").and_then(Value::as_str) {
6954                        let values: QueryRow = serde_json::from_str(raw).map_err(|_| "sync.local_corrupt: authority intent values are invalid")?;
6955                        if read.scopes.keys().all(|v| values.contains_key(table.scope_column(v).expect("validated scope"))) && matches(&values)? {relevant.insert(id);}
6956                    }
6957                }
6958                let mut rows = BTreeMap::new();
6959                for full in [base_table(&read.table), visible_table(&read.table)] {
6960                    for mut values in query_connection(
6961                        &self.conn,
6962                        &format!(
6963                            "SELECT {selected},_syncular_version AS authority_version FROM {full}"
6964                        ),
6965                        &[],
6966                    )
6967                    .map_err(|e| e.to_string())?
6968                    {
6969                        if !matches(&values)? {
6970                            continue;
6971                        }
6972                        let id = scalar(
6973                            &table.primary_key,
6974                            values
6975                                .get(&table.primary_key)
6976                                .expect("selected primary key"),
6977                        )?;
6978                        relevant.insert(id.clone());
6979                        if full == base_table(&read.table) {
6980                            let version = values
6981                                .remove("authority_version")
6982                                .expect("selected version");
6983                            let version = version
6984                                .as_i64()
6985                                .ok_or("sync.local_corrupt: authority server version is invalid")?;
6986                            if version >= 0 {
6987                                rows.insert(id.clone(), json!({"values": values, "version": version, "hasLocalIntent": intent.contains(&id)}));
6988                            }
6989                        }
6990                    }
6991                }
6992                intent.retain(|id| relevant.contains(id));
6993                let rows = rows.into_values().collect::<Vec<_>>();
6994                // Every unit covering the table, as its (unit, table) pair (§4.4).
6995                let replica = self.stored(replica_cursor(&self.conn))?;
6996                let persisted = self
6997                    .stored(load_units(&self.conn))?
6998                    .into_iter()
6999                    .filter(|unit| covers(table, &unit.scopes))
7000                    .map(|unit| {
7001                        let effective = unit.echo.as_deref().and_then(|echo| {
7002                            pair_scopes(&unit.scopes, &read.table, Some(echo))
7003                        });
7004                        let requested = read
7005                            .scopes
7006                            .keys()
7007                            .map(|v| (v.clone(), json!(unit.scopes.get(v).into_iter().collect::<Vec<_>>())))
7008                            .collect::<Map<_, _>>();
7009                        let complete = effective
7010                            .as_ref()
7011                            .is_some_and(|scopes| scopes.len() == read.scopes.len())
7012                            && unit.status == UnitStatus::Active
7013                            && !unit.bootstrapping();
7014                        let exposed = effective.map(|scopes| {
7015                            read.scopes
7016                                .keys()
7017                                .map(|v| {
7018                                    let held = scopes.iter().find(|(variable, _)| variable == v);
7019                                    (v.clone(), json!(held.map_or(&Vec::new(), |(_, values)| values)))
7020                                })
7021                                .collect::<Map<_, _>>()
7022                        });
7023                        json!({"requestedScopes": requested, "status": unit.status, "cursor": unit.cursor.unwrap_or(replica), "effectiveScopes": exposed, "complete": complete})
7024                    })
7025                    .collect::<Vec<_>>();
7026                fn covered(selectors: &[(&String, &Vec<String>)], candidates: &[&Value]) -> bool {
7027                    match selectors.split_first() {
7028                        None => !candidates.is_empty(),
7029                        Some(((variable, values), rest)) => values.iter().all(|value| {
7030                            covered(
7031                                rest,
7032                                &candidates
7033                                    .iter()
7034                                    .copied()
7035                                    .filter(|p| {
7036                                        p["effectiveScopes"][variable.as_str()]
7037                                            .as_array()
7038                                            .is_some_and(|held| {
7039                                                held.contains(&Value::String(value.clone()))
7040                                                    || held.contains(&Value::String("*".into()))
7041                                            })
7042                                    })
7043                                    .collect::<Vec<_>>(),
7044                            )
7045                        }),
7046                    }
7047                }
7048                let coverage = if covered(
7049                    &read.scopes.iter().collect::<Vec<_>>(),
7050                    &persisted
7051                        .iter()
7052                        .filter(|p| p["complete"] == true)
7053                        .collect::<Vec<_>>(),
7054                ) {
7055                    "complete"
7056                } else if persisted.iter().any(|p| {
7057                    p["status"] == "active"
7058                        && read.scopes.iter().all(|(v, values)| {
7059                            values.iter().any(|value| {
7060                                p["requestedScopes"][v].as_array().is_some_and(|held| {
7061                                    held.contains(&Value::String(value.clone()))
7062                                })
7063                            })
7064                        })
7065                }) {
7066                    "pending"
7067                } else {
7068                    "missing"
7069                };
7070                tables.push(json!({"table": read.table, "rows": rows, "localIntentRowIds": intent, "scopes": read.scopes, "coverage": coverage, "persisted": persisted}));
7071            }
7072            Ok(
7073                json!({"revision": revision, "complete": tables.iter().all(|t| t["coverage"] == "complete"), "tables": tables}),
7074            )
7075        })();
7076        match result {
7077            Ok(snapshot) => {
7078                self.conn
7079                    .execute_batch("RELEASE authority_snapshot")
7080                    .map_err(|e| e.to_string())?;
7081                Ok(snapshot)
7082            }
7083            Err(error) => {
7084                self.conn
7085                    .execute_batch("ROLLBACK TO authority_snapshot; RELEASE authority_snapshot")
7086                    .map_err(|e| format!("{error}; rollback failed: {e}"))?;
7087                Err(error)
7088            }
7089        }
7090    }
7091
7092    /// Rows, coverage, and local revision from one SQLite read snapshot.
7093    /// §7.5 atomic snapshot read. An `owner` records a failure in
7094    /// `diagnostics_snapshot().query_failures` until its next successful read.
7095    pub fn query_snapshot(
7096        &mut self,
7097        sql: &str,
7098        params: &[QueryValue],
7099        coverage: &[WindowCoverage],
7100        owner: Option<QueryOwner<'_>>,
7101    ) -> Result<QuerySnapshot, String> {
7102        let result = snapshot_connection(&self.conn, sql, params, coverage);
7103        if let Some(owner) = owner {
7104            self.record_query_read(owner, result.as_ref().err());
7105        }
7106        result.map_err(|failure| failure.to_string())
7107    }
7108
7109    /// §7.6: record the outcome of one owned snapshot read, including reads a
7110    /// host ran on a separate connection. A success removes the owner's entry;
7111    /// an identical failure leaves it unchanged; a changed failure moves last.
7112    pub fn record_query_read(&mut self, owner: QueryOwner<'_>, failure: Option<&QueryReadFailure>) {
7113        let position = self
7114            .query_failures
7115            .iter()
7116            .position(|entry| entry.id == owner.id);
7117        let Some(failure) = failure else {
7118            if let Some(index) = position {
7119                self.query_failures.remove(index);
7120            }
7121            return;
7122        };
7123        let tables: Vec<String> = BTreeSet::from_iter(owner.tables.iter().copied())
7124            .into_iter()
7125            .map(str::to_owned)
7126            .collect();
7127        let code = failure.code.unwrap_or("client.query_failed").to_owned();
7128        if position.is_some_and(|index| {
7129            let entry = &self.query_failures[index];
7130            entry.tables == tables && entry.code == code && entry.sqlite_code == failure.sqlite_code
7131        }) {
7132            return;
7133        }
7134        if let Some(index) = position {
7135            self.query_failures.remove(index);
7136        }
7137        self.query_failures.push(DiagnosticQueryFailure {
7138            id: owner.id.to_owned(),
7139            tables,
7140            code,
7141            sqlite_code: failure.sqlite_code,
7142            at_ms: self.clock_now_ms(),
7143        });
7144        if self.query_failures.len() > MAX_DIAGNOSTIC_QUERY_FAILURES {
7145            self.query_failures.remove(0);
7146        }
7147    }
7148
7149    // -- request building ---------------------------------------------------------
7150
7151    fn build_request(&self, url_capable: bool) -> Result<(Message, RequestMeta), Box<SyncOutcome>> {
7152        #[cfg(feature = "bench-internals")]
7153        let _phase = self.benchmark_phases.start(Phase::RequestPrepare);
7154        let log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7155            Box::new(SyncOutcome::Failed {
7156                error_code: "storage.failed".into(),
7157                message,
7158                details: None,
7159                recommended_action: None,
7160            })
7161        })?;
7162        let max_commits = self.limits.max_push_commits_per_request;
7163        let max_ops = self
7164            .limits
7165            .max_push_operations_per_request
7166            .unwrap_or(PUSH_OPS_PER_REQUEST);
7167        let byte_cap = self.limits.max_push_request_bytes;
7168        // §4.2/§5.4: bit 3 is advertised iff the transport can fetch a
7169        // bare URL — capability negotiation, decided per transport.
7170        let accept = self.limits.accept.unwrap_or(if url_capable {
7171            DEFAULT_ACCEPT | ACCEPT_SIGNED_URLS
7172        } else {
7173            DEFAULT_ACCEPT
7174        });
7175        let storage_failed = |message: String| {
7176            Box::new(SyncOutcome::Failed {
7177                error_code: "storage.failed".into(),
7178                message,
7179                details: None,
7180                recommended_action: None,
7181            })
7182        };
7183        let header = Frame::ReqHeader {
7184            client_id: self.client_id.clone(),
7185            schema_version: self.schema.version,
7186            log_epoch: log_epoch.clone(),
7187            outbox_id: self.get_meta(OUTBOX_ID_KEY).map_err(storage_failed)?,
7188        };
7189        // §1.5: the lead frames are REQ_HEADER plus the optional ROUND_FAILURE,
7190        // which stays ahead of every push, pull, unit and progress frame; the
7191        // byte-capacity probes below measure this exact sequence.
7192        let mut lead = vec![header];
7193        lead.extend(
7194            self.round_failure
7195                .iter()
7196                .map(|code| Frame::RoundFailure { code: code.clone() }),
7197        );
7198        let registered: Vec<UnitRecord> = self
7199            .stored(load_units(&self.conn))
7200            .map_err(storage_failed)?
7201            .into_iter()
7202            .filter(|unit| unit.status == UnitStatus::Active)
7203            .collect();
7204        let registration_digest = ssp2::registration::registration_digest(
7205            registered
7206                .iter()
7207                .map(|unit| scope_pairs(&unit.scopes))
7208                .collect::<Vec<_>>()
7209                .iter()
7210                .map(Vec::as_slice),
7211        );
7212        let echo_digest = self
7213            .get_meta(ECHO_DIGEST_KEY)
7214            .map_err(storage_failed)?
7215            .filter(|hex| !hex.is_empty())
7216            .map(|hex| {
7217                crate::values::hex_to_bytes(&hex)
7218                    .ok()
7219                    .and_then(|bytes| <[u8; 32]>::try_from(bytes).ok())
7220                    .ok_or_else(|| {
7221                        "sync.local_corrupt: persisted echo digest is invalid".to_owned()
7222                    })
7223            })
7224            .transpose()
7225            .map_err(storage_failed)?;
7226        let pull = Frame::PullHeader {
7227            limit_commits: self.limits.limit_commits.unwrap_or(0),
7228            limit_snapshot_rows: self.limits.limit_snapshot_rows.unwrap_or(0),
7229            max_snapshot_pages: self.limits.max_snapshot_pages.unwrap_or(0),
7230            accept,
7231            cursor: self
7232                .stored(replica_cursor(&self.conn))
7233                .map_err(storage_failed)?,
7234            registration_digest,
7235            echo_digest,
7236        };
7237        let registration_digest = bytes_to_hex(&registration_digest);
7238        // §4.1: the list travels when it changed since the server stored it,
7239        // after `unregistered` and after a reset (both clear the stored digest).
7240        let travels = self
7241            .get_meta(REGISTERED_DIGEST_KEY)
7242            .map_err(storage_failed)?
7243            .as_deref()
7244            != Some(registration_digest.as_str());
7245        let mut sub_frames: Vec<Frame> = Vec::new();
7246        if travels {
7247            sub_frames.extend(registered.iter().map(|unit| Frame::Unit {
7248                scopes: scope_pairs(&unit.scopes),
7249            }));
7250        }
7251        // §4.3: one PROGRESS per catching-up unit, in registration order.
7252        sub_frames.extend(registered.iter().filter_map(|unit| {
7253            Some(Frame::Progress {
7254                id: unit.id.clone(),
7255                cursor: unit.cursor?,
7256                bootstrap_state: unit.bootstrap_state.clone().map(RawJson),
7257            })
7258        }));
7259        // The fixed frames (order-independent size) and the header+pull probe
7260        // both encode canonically, so the byte budget is the exact wire size.
7261        let fixed_bytes = match byte_cap {
7262            Some(_) => {
7263                let mut frames = lead.clone();
7264                frames.push(pull.clone());
7265                frames.extend(sub_frames.iter().cloned());
7266                encode_message(&Message {
7267                    wire_version: WIRE_VERSION,
7268                    msg_kind: MsgKind::Request,
7269                    frames,
7270                })
7271                .len()
7272            }
7273            None => 0,
7274        };
7275        if let Some(cap) = byte_cap {
7276            if fixed_bytes > cap {
7277                return Err(Self::push_capacity_outcome("bytes", cap, fixed_bytes, None));
7278            }
7279        }
7280        let base_bytes = match byte_cap {
7281            Some(_) => {
7282                let mut frames = lead.clone();
7283                frames.push(pull.clone());
7284                encode_message(&Message {
7285                    wire_version: WIRE_VERSION,
7286                    msg_kind: MsgKind::Request,
7287                    frames,
7288                })
7289                .len()
7290            }
7291            None => 0,
7292        };
7293        let total_outbox = if log_epoch.is_some() {
7294            self.outbox.len()
7295        } else {
7296            0
7297        };
7298        let mut push_frames: Vec<Frame> = Vec::new();
7299        let mut pushed_ids = Vec::new();
7300        let mut ops_in_request = 0usize;
7301        let mut bytes_in_request = 0usize;
7302        let mut deferred_commits = 0usize;
7303        #[cfg(feature = "bench-internals")]
7304        let outbox_phase = self.benchmark_phases.start(Phase::OutboxEncode);
7305        for (index, commit) in self.outbox.iter().take(total_outbox).enumerate() {
7306            // §6.1/§7.1: the commit-count and operation caps are hard. A
7307            // first commit over the operation cap is a typed capacity error
7308            // and stays queued; a later one defers with the complete suffix.
7309            if max_commits.is_some_and(|cap| push_frames.len() >= cap) {
7310                deferred_commits = total_outbox - index;
7311                break;
7312            }
7313            if ops_in_request + commit.ops.len() > max_ops {
7314                if push_frames.is_empty() {
7315                    return Err(Self::push_capacity_outcome(
7316                        "operations",
7317                        max_ops,
7318                        commit.ops.len(),
7319                        Some(commit.client_commit_id.as_str()),
7320                    ));
7321                }
7322                deferred_commits = total_outbox - index;
7323                break;
7324            }
7325            // §7.1 chained base: the commit waits for the change of the commit
7326            // it chains on, which supplies its rebased version.
7327            if self.outbox[..index]
7328                .iter()
7329                .flat_map(|earlier| &earlier.ops)
7330                .any(|earlier| commit.ops.iter().any(|op| chains_on(earlier, op)))
7331            {
7332                deferred_commits = total_outbox - index;
7333                break;
7334            }
7335            let operations = commit
7336                .ops
7337                .iter()
7338                .map(|op| {
7339                    let payload = match self
7340                        .schema
7341                        .table(&op.table)
7342                        .and_then(|table| Some((table, op.presented_values(table)?)))
7343                    {
7344                        Some((table, values)) => {
7345                            // §0: outbox entries encode at send time with the
7346                            // current codec (validated at mutate()). §6.1: the
7347                            // values map's keys are the sparse presence set; an
7348                            // insert-intent operation presents every column (§7.1).
7349                            // §5.11: encrypted columns are encrypted here, with
7350                            // an absent key-id selector read from the stored row.
7351                            // `sync_inner` runs `drop_unencodable_outbox` first,
7352                            // so an encrypt failure cannot reach this encode; the
7353                            // author seam validated every other failure.
7354                            let fallback =
7355                                self.stored_key_fallback(table, &op.row_id)
7356                                    .map_err(|message| {
7357                                        Box::new(SyncOutcome::Failed {
7358                                            error_code: "storage.failed".into(),
7359                                            message,
7360                                            details: None,
7361                                            recommended_action: None,
7362                                        })
7363                                    })?;
7364                            encode_sparse_row_json(
7365                                table,
7366                                &op.row_id,
7367                                &values,
7368                                &self.encryption,
7369                                fallback.as_ref(),
7370                            )
7371                            .ok()
7372                        }
7373                        None => None,
7374                    };
7375                    Ok(ssp2::model::Operation {
7376                        table: op.table.clone(),
7377                        row_id: op.row_id.clone(),
7378                        op: if op.upsert { Op::Upsert } else { Op::Delete },
7379                        base_version: op.base_version,
7380                        payload,
7381                    })
7382                })
7383                .collect::<Result<Vec<_>, Box<SyncOutcome>>>()?;
7384            // §6.3.2, §7.1: the commit's outbox sequence.
7385            let client_seq = self
7386                .conn
7387                .prepare_cached("SELECT seq FROM _syncular_outbox WHERE commit_id = ?1")
7388                .and_then(|mut statement| {
7389                    statement.query_row([&commit.client_commit_id], |row| row.get(0))
7390                })
7391                .map_err(|error| {
7392                    storage_failed(Self::sqlite_failure(&self.storage_failure, error))
7393                })?;
7394            let frame = Frame::PushCommit {
7395                client_commit_id: commit.client_commit_id.clone(),
7396                client_seq,
7397                operations,
7398            };
7399            let frame_bytes = match byte_cap {
7400                Some(_) => {
7401                    let mut frames = lead.clone();
7402                    frames.push(frame.clone());
7403                    frames.push(pull.clone());
7404                    encode_message(&Message {
7405                        wire_version: WIRE_VERSION,
7406                        msg_kind: MsgKind::Request,
7407                        frames,
7408                    })
7409                    .len()
7410                        - base_bytes
7411                }
7412                None => 0,
7413            };
7414            // The head is always encoded so the caller can report the full
7415            // projected request size; a later commit defers once it no longer
7416            // fits.
7417            if let Some(cap) = byte_cap {
7418                if !push_frames.is_empty() && fixed_bytes + bytes_in_request + frame_bytes > cap {
7419                    deferred_commits = total_outbox - index;
7420                    break;
7421                }
7422            }
7423            push_frames.push(frame);
7424            pushed_ids.push(commit.client_commit_id.clone());
7425            ops_in_request += commit.ops.len();
7426            bytes_in_request += frame_bytes;
7427        }
7428        #[cfg(feature = "bench-internals")]
7429        drop(outbox_phase);
7430        if let Some(cap) = byte_cap {
7431            if fixed_bytes + bytes_in_request > cap {
7432                // The head alone does not fit this budget; the commit stays
7433                // queued and no transport round is attempted.
7434                let blocked = if push_frames.is_empty() {
7435                    None
7436                } else {
7437                    self.outbox.first().map(|c| c.client_commit_id.as_str())
7438                };
7439                return Err(Self::push_capacity_outcome(
7440                    "bytes",
7441                    cap,
7442                    fixed_bytes + bytes_in_request,
7443                    blocked,
7444                ));
7445            }
7446        }
7447        let mut frames = lead;
7448        frames.extend(push_frames);
7449        frames.push(pull);
7450        frames.extend(sub_frames);
7451        let message = Message {
7452            wire_version: WIRE_VERSION,
7453            msg_kind: MsgKind::Request,
7454            frames,
7455        };
7456        Ok((
7457            message,
7458            RequestMeta {
7459                pushed_ids,
7460                registration_digest,
7461                accept,
7462                deferred_commits,
7463            },
7464        ))
7465    }
7466
7467    /// §7.1: a configured push capacity limit cannot carry this request.
7468    fn push_capacity_outcome(
7469        kind: &str,
7470        limit: usize,
7471        size: usize,
7472        client_commit_id: Option<&str>,
7473    ) -> Box<SyncOutcome> {
7474        let mut details = Map::new();
7475        details.insert("kind".to_owned(), Value::from(kind));
7476        details.insert("limit".to_owned(), Value::from(limit as u64));
7477        details.insert("size".to_owned(), Value::from(size as u64));
7478        if let Some(id) = client_commit_id {
7479            details.insert("clientCommitId".to_owned(), Value::from(id));
7480        }
7481        Box::new(SyncOutcome::Failed {
7482            error_code: "client.push_request_too_large".into(),
7483            message: "the push request exceeds a configured capacity limit".into(),
7484            details: Some(Value::Object(details)),
7485            recommended_action: None,
7486        })
7487    }
7488
7489    // -- sync -------------------------------------------------------------------
7490
7491    /// Cloneable observation handle; no client lock is needed to read it.
7492    pub fn progress(&self) -> ProgressObserver {
7493        self.progress.clone()
7494    }
7495
7496    pub fn sync(&mut self, transport: &mut dyn Transport) -> SyncOutcome {
7497        let prepared = match self.prepare_sync_round(transport.supports_url_fetch()) {
7498            Ok(prepared) => prepared,
7499            Err(outcome) => return *outcome,
7500        };
7501        // The round's network deadline rides `PreparedSyncRound` and is scoped
7502        // to each exchange, so uploads, continuations, the main request, and
7503        // every segment fetch share one monotonic anchor without leaving
7504        // deadline state on a reused transport.
7505        let mut next = prepared;
7506        loop {
7507            match self.apply_sync_round(next.exchange(transport)) {
7508                crate::AppliedSyncRound::Continue(prepared) => next = prepared,
7509                crate::AppliedSyncRound::Complete {
7510                    outcome, controls, ..
7511                } => {
7512                    if self.transport_enabled {
7513                        for text in controls {
7514                            let _ = transport.realtime_send(&text);
7515                        }
7516                    } else {
7517                        self.disconnect_realtime(transport);
7518                    }
7519                    return outcome;
7520                }
7521            }
7522        }
7523    }
7524
7525    fn finish_sync_round(&mut self, started_at_ms: i64, mut outcome: SyncOutcome) -> SyncOutcome {
7526        if let SyncOutcome::Failed {
7527            error_code,
7528            message,
7529            details,
7530            ..
7531        } = &mut outcome
7532        {
7533            if let Some((failure, code)) = self
7534                .storage_failure
7535                .borrow()
7536                .as_ref()
7537                .and_then(|failure| failure.code.map(|code| (failure, code)))
7538            {
7539                *error_code = code.to_owned();
7540                *message = match code {
7541                    "client.storage_busy" => "local SQLite storage is busy",
7542                    "client.storage_full" => "local SQLite storage is full",
7543                    "client.storage_io" => "local SQLite storage I/O failed",
7544                    "client.storage_corrupt" => "local SQLite storage is corrupt",
7545                    _ => unreachable!("unrecognized classified storage failure"),
7546                }
7547                .to_owned();
7548                *details = failure.details();
7549            }
7550        }
7551        let details = match &outcome {
7552            SyncOutcome::Failed { details, .. } => details.as_ref(),
7553            _ => None,
7554        };
7555        let cause_kind = details
7556            .and_then(|details| details.get("causeKind"))
7557            .and_then(Value::as_str)
7558            .and_then(|cause| match cause {
7559                "network" => Some(crate::TransportCauseKind::Network),
7560                "connect" => Some(crate::TransportCauseKind::Connect),
7561                "tls" => Some(crate::TransportCauseKind::Tls),
7562                "io" => Some(crate::TransportCauseKind::Io),
7563                "request" => Some(crate::TransportCauseKind::Request),
7564                "protocol" => Some(crate::TransportCauseKind::Protocol),
7565                "timeout" => Some(crate::TransportCauseKind::Timeout),
7566                "round_deadline" => Some(crate::TransportCauseKind::RoundDeadline),
7567                "aborted" => Some(crate::TransportCauseKind::Aborted),
7568                "body" => Some(crate::TransportCauseKind::Body),
7569                "status" => Some(crate::TransportCauseKind::Status),
7570                "redirect" => Some(crate::TransportCauseKind::Redirect),
7571                "unknown" => Some(crate::TransportCauseKind::Unknown),
7572                _ => None,
7573            });
7574        let http_status = if matches!(
7575            cause_kind,
7576            Some(
7577                crate::TransportCauseKind::Status
7578                    | crate::TransportCauseKind::Body
7579                    | crate::TransportCauseKind::Redirect
7580            )
7581        ) {
7582            details
7583                .and_then(|details| details.get("httpStatus"))
7584                .and_then(Value::as_f64)
7585                .filter(|status| status.fract() == 0.0 && (100.0..=599.0).contains(status))
7586                .map(|status| status as u16)
7587        } else {
7588            None
7589        };
7590        let retry_delay_ms = self.round_retry_delay_ms;
7591        self.progress.update(|p| match &outcome {
7592            SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report)
7593                if report.failed.is_empty() =>
7594            {
7595                p.state = ProgressState::Complete
7596            }
7597            SyncOutcome::Ok(_) | SyncOutcome::BudgetExhausted(_) => {
7598                p.state = ProgressState::Failed;
7599                p.error_code = Some("sync.scope_revoked".into());
7600            }
7601            SyncOutcome::Failed { error_code, .. } => {
7602                p.state = ProgressState::Failed;
7603                p.error_code = Some(Self::diagnostic_code(error_code));
7604                p.cause_kind = cause_kind;
7605                p.http_status = http_status;
7606                p.retry_delay_ms = retry_delay_ms;
7607            }
7608            SyncOutcome::RealtimeUnavailable { .. } => {
7609                p.state = ProgressState::Failed;
7610                p.error_code = Some(REALTIME_UNAVAILABLE_CODE.to_owned());
7611                p.retry_delay_ms = retry_delay_ms;
7612            }
7613        });
7614        let completed_at_ms = self.clock_now_ms();
7615        self.last_round = Some(match &outcome {
7616            SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report) => DiagnosticLastRound {
7617                status: "succeeded".to_owned(),
7618                started_at_ms,
7619                completed_at_ms,
7620                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7621                counters: Some(DiagnosticRoundCounters {
7622                    pushed: report.pushed,
7623                    applied: report.applied.len(),
7624                    rejected: report.rejected.len(),
7625                    retryable: report.retryable.len(),
7626                    conflicts: report.conflicts,
7627                    commits_applied: report.commits_applied,
7628                    segment_rows_applied: report.segment_rows_applied,
7629                    bootstrapping: report.bootstrapping.len(),
7630                    resets: report.resets.len(),
7631                    revoked: report.revoked.len(),
7632                    failed: report.failed.len(),
7633                    deferred_commits: report.deferred_commits,
7634                }),
7635                error_code: None,
7636                cause_kind: None,
7637                http_status: None,
7638            },
7639            SyncOutcome::Failed { error_code, .. } => DiagnosticLastRound {
7640                status: "failed".to_owned(),
7641                started_at_ms,
7642                completed_at_ms,
7643                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7644                counters: None,
7645                error_code: Some(Self::diagnostic_code(error_code)),
7646                cause_kind,
7647                http_status,
7648            },
7649            SyncOutcome::RealtimeUnavailable { .. } => DiagnosticLastRound {
7650                status: "failed".to_owned(),
7651                started_at_ms,
7652                completed_at_ms,
7653                duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7654                counters: None,
7655                error_code: Some(REALTIME_UNAVAILABLE_CODE.to_owned()),
7656                cause_kind: None,
7657                http_status: None,
7658            },
7659        });
7660        outcome
7661    }
7662
7663    /// Capture one request on the client owner. Mutations made after this
7664    /// call remain in the outbox for a later round; no network I/O occurs here.
7665    pub fn prepare_sync_round(
7666        &mut self,
7667        url_capable: bool,
7668    ) -> Result<crate::PreparedSyncRound, Box<SyncOutcome>> {
7669        if !self.transport_enabled {
7670            return Err(Box::new(SyncOutcome::Failed {
7671                error_code: "sync.offline".into(),
7672                message: "transport gate is closed".into(),
7673                details: None,
7674                recommended_action: None,
7675            }));
7676        }
7677        if self.active_round.is_some() {
7678            return Err(Box::new(SyncOutcome::Failed {
7679                error_code: "client.round_in_progress".into(),
7680                message: "a sync round is already in flight".into(),
7681                details: None,
7682                recommended_action: None,
7683            }));
7684        }
7685        self.storage_failure.borrow_mut().take();
7686        self.progress.start();
7687        self.round_retry_delay_ms = None;
7688        let started_at_ms = self.clock_now_ms();
7689        let prepared = (|| {
7690            if self.stopped {
7691                return Err(Box::new(SyncOutcome::Ok(SyncReport {
7692                    schema_floor: self.schema_floor.clone(),
7693                    ..SyncReport::default()
7694                })));
7695            }
7696            if self.security_preflight {
7697                return Err(Box::new(SyncOutcome::Failed {
7698                    error_code: SECURITY_PREFLIGHT_REQUIRED_CODE.into(),
7699                    message: "security preflight must complete before syncing".into(),
7700                    details: None,
7701                    recommended_action: None,
7702                }));
7703            }
7704            self.set_sync_needed(false, false);
7705            self.drain_pending_evictions()
7706                .and_then(|_| self.drop_incompatible_outbox())
7707                .and_then(|_| self.drop_unencodable_outbox(true, None))
7708                .map_err(|message| {
7709                    Box::new(SyncOutcome::Failed {
7710                        error_code: "storage.failed".into(),
7711                        message,
7712                        details: None,
7713                        recommended_action: None,
7714                    })
7715                })?;
7716            let has_log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7717                Box::new(SyncOutcome::Failed {
7718                    error_code: "storage.failed".into(),
7719                    message,
7720                    details: None,
7721                    recommended_action: None,
7722                })
7723            })?;
7724            let uploads = if has_log_epoch.is_some() && self.schema_has_blobs() {
7725                self.pending_blob_uploads().map_err(|e| {
7726                    Box::new(SyncOutcome::Failed {
7727                        error_code: e.code,
7728                        message: e.message,
7729                        details: e.details,
7730                        recommended_action: None,
7731                    })
7732                })?
7733            } else {
7734                Vec::new()
7735            };
7736            if self.realtime_state != RealtimeState::Connected
7737                && self.realtime_policy == RealtimePolicy::Required
7738            {
7739                let retry_delay_ms = self.schedule_background_retry();
7740                self.realtime_retry_delay_ms = Some(retry_delay_ms);
7741                return Err(Box::new(SyncOutcome::RealtimeUnavailable {
7742                    state: self.realtime_state,
7743                    reason_code: self.realtime_reason_code.clone(),
7744                    retry_delay_ms,
7745                }));
7746            }
7747            let (message, meta) = self.build_request(url_capable)?;
7748            let id = uuid::Uuid::new_v4();
7749            self.active_round = Some(id);
7750            let phase = if uploads.is_empty() {
7751                crate::round::RoundPhase::Sync
7752            } else {
7753                crate::round::RoundPhase::UploadGrant
7754            };
7755            Ok(crate::PreparedSyncRound {
7756                id,
7757                started_at_ms,
7758                message,
7759                meta,
7760                uploads: uploads.into(),
7761                phase,
7762                encoded: None,
7763                continuation: None,
7764                completed: None,
7765                realtime: self.realtime_state == RealtimeState::Connected,
7766                // §5.5: the owning unit's scope map, each value a one-element list.
7767                scopes: self
7768                    .stored(load_units(&self.conn))
7769                    .map_err(|message| {
7770                        Box::new(SyncOutcome::Failed {
7771                            error_code: "storage.failed".into(),
7772                            message,
7773                            details: None,
7774                            recommended_action: None,
7775                        })
7776                    })?
7777                    .into_iter()
7778                    .map(|unit| {
7779                        (
7780                            unit.id,
7781                            canonical_scope_json(&unit_scope_lists(&unit.scopes)),
7782                        )
7783                    })
7784                    .collect(),
7785                #[cfg(feature = "bench-internals")]
7786                benchmark_phases: self.benchmark_phases.clone(),
7787                progress: self.progress.clone(),
7788                fixed_now: self.now_ms,
7789                round_deadline_at: None,
7790            })
7791        })();
7792        prepared.map_err(|outcome| Box::new(self.finish_sync_round(started_at_ms, *outcome)))
7793    }
7794
7795    /// Discard the reply of an old authorization or registration context. Its
7796    /// submitted commits stay durable and can be retried with the same ids.
7797    pub fn cancel_sync_round(&mut self) {
7798        self.active_round = None;
7799    }
7800
7801    /// Apply captured network results on the owner, preserving all normal
7802    /// version, schema, content-address and cursor checks. No network I/O.
7803    pub fn apply_sync_round(
7804        &mut self,
7805        completed: crate::CompletedSyncRound,
7806    ) -> crate::AppliedSyncRound {
7807        let mut prepared = completed.prepared;
7808        if self.active_round != Some(prepared.id) || self.security_preflight {
7809            return crate::AppliedSyncRound::Complete {
7810                outcome: SyncOutcome::Failed {
7811                    error_code: "client.round_cancelled".into(),
7812                    message: "sync round belongs to a released client context".into(),
7813                    details: None,
7814                    recommended_action: None,
7815                },
7816                controls: Vec::new(),
7817                more: false,
7818                bootstrap_advanced: false,
7819            };
7820        }
7821        self.storage_failure.borrow_mut().take();
7822        let (response, mut downloads, transport_failed) = match completed.exchange {
7823            crate::round::ExchangeResult::Upload { id, result } => {
7824                let result = match result {
7825                    // §5.9.7: a non-retryable server refusal (`blob.too_large`)
7826                    // is the body's final outcome. The commits naming it take
7827                    // the incompatible-commit path with the server's code and
7828                    // leave this round's request; the round continues.
7829                    Err(error)
7830                        if error
7831                            .details
7832                            .as_ref()
7833                            .and_then(|details| details.get("retryable"))
7834                            == Some(&Value::Bool(false)) =>
7835                    {
7836                        self.conn
7837                            .prepare(
7838                                "SELECT commit_id FROM _syncular_blob_commit_refs WHERE blob_id = ?",
7839                            )
7840                            .and_then(|mut statement| {
7841                                statement
7842                                    .query_map(rusqlite::params![id], |row| row.get::<_, String>(0))?
7843                                    .collect::<Result<HashSet<_>, _>>()
7844                            })
7845                            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
7846                            .and_then(|refused| {
7847                                let commits = self
7848                                    .outbox
7849                                    .iter()
7850                                    .filter(|commit| refused.contains(&commit.client_commit_id))
7851                                    .cloned()
7852                                    .collect::<Vec<_>>();
7853                                if !commits.is_empty() {
7854                                    self.drop_outbox_commits(&commits, &error.code, &error.message)?;
7855                                }
7856                                prepared.message.frames.retain(|frame| {
7857                                    !matches!(frame, Frame::PushCommit { client_commit_id, .. }
7858                                        if refused.contains(client_commit_id))
7859                                });
7860                                prepared.meta.pushed_ids.retain(|id| !refused.contains(id));
7861                                prepared.continuation = Some(crate::round::RoundPhase::UploadGrant);
7862                                Ok(())
7863                            })
7864                            .map_err(|message| TransportError::new("client.failed", message))
7865                    }
7866                    result => result,
7867                };
7868                let result = result.and_then(|()| {
7869                    self.conn
7870                        .execute(
7871                            "DELETE FROM _syncular_blob_uploads WHERE blob_id = ?",
7872                            rusqlite::params![id],
7873                        )
7874                        .map(|_| ())
7875                        .map_err(|error| {
7876                            TransportError::new(
7877                                "client.failed",
7878                                Self::sqlite_failure(&self.storage_failure, error),
7879                            )
7880                        })
7881                });
7882                match result {
7883                    Ok(()) => return crate::AppliedSyncRound::Continue(prepared),
7884                    Err(TransportError {
7885                        code,
7886                        message,
7887                        details,
7888                    }) => {
7889                        self.active_round = None;
7890                        if Self::unreachable_transport(&details) {
7891                            // The round's work is still owed; the host's
7892                            // connectivity resume runs it.
7893                            self.set_sync_needed(true, false);
7894                        } else if Self::retryable_failure_code(&code) {
7895                            self.schedule_background_retry();
7896                        }
7897                        let recommended_action = recommended_action_of(&details);
7898                        let outcome = self.finish_sync_round(
7899                            prepared.started_at_ms,
7900                            SyncOutcome::Failed {
7901                                error_code: code,
7902                                message,
7903                                details,
7904                                recommended_action,
7905                            },
7906                        );
7907                        return crate::AppliedSyncRound::Complete {
7908                            outcome,
7909                            controls: Vec::new(),
7910                            more: false,
7911                            bootstrap_advanced: false,
7912                        };
7913                    }
7914                }
7915            }
7916            crate::round::ExchangeResult::Reply {
7917                response,
7918                downloads,
7919                transport_failed,
7920            } => (response, downloads, transport_failed),
7921        };
7922        self.active_round = None;
7923        let before = self.resume_tokens();
7924        let outcome = (|| {
7925            let response = match response {
7926                Ok(response) => {
7927                    // §1.5: a complete, decodable response ends the report, an
7928                    // in-band ERROR included (the server already recorded it).
7929                    self.round_failure = None;
7930                    response
7931                }
7932                Err(TransportError {
7933                    code,
7934                    message,
7935                    details,
7936                }) => {
7937                    // §1.5: the server cannot see a round whose transport
7938                    // failed or whose response never decoded, so its code rides
7939                    // the following requests. A code the frame grammar rejects
7940                    // is not reportable, and the previous code stays.
7941                    if ssp2::model::valid_round_failure_code(&code) {
7942                        self.round_failure = Some(code.clone());
7943                    }
7944                    if transport_failed {
7945                        if prepared.realtime {
7946                            self.set_realtime_state(RealtimeState::Lost, Some(&code));
7947                        }
7948                        if let Err(message) = self.record_lease_error(&code) {
7949                            return SyncOutcome::Failed {
7950                                error_code: "storage.failed".to_owned(),
7951                                message,
7952                                details: None,
7953                                recommended_action: None,
7954                            };
7955                        }
7956                    }
7957                    if Self::retryable_failure_code(&code) && !Self::unreachable_transport(&details)
7958                    {
7959                        let delay = self.schedule_background_retry();
7960                        if prepared.realtime && transport_failed {
7961                            self.realtime_retry_delay_ms = Some(delay);
7962                        }
7963                    }
7964                    let recommended_action = recommended_action_of(&details);
7965                    return SyncOutcome::Failed {
7966                        error_code: code,
7967                        message,
7968                        details,
7969                        recommended_action,
7970                    };
7971                }
7972            };
7973            let mut outcome = self.process_response(&mut downloads, response, &prepared.meta);
7974            if let SyncOutcome::Ok(report) = &mut outcome {
7975                report.deferred_commits = prepared.meta.deferred_commits;
7976            }
7977            match &outcome {
7978                SyncOutcome::Ok(_) => self.reset_background_retry(),
7979                SyncOutcome::Failed {
7980                    error_code,
7981                    details,
7982                    ..
7983                } if Self::retryable_failure_code(error_code)
7984                    && !Self::unreachable_transport(details) =>
7985                {
7986                    self.schedule_background_retry();
7987                }
7988                _ => {}
7989            }
7990            if prepared.meta.deferred_commits > 0 {
7991                self.set_sync_needed(true, true);
7992            }
7993            self.previous_version_lifetime_check();
7994            outcome
7995        })();
7996        match &outcome {
7997            // §7.1: a unit still catching up needs another round, also when the
7998            // drive that started it ends early.
7999            SyncOutcome::Ok(report) if !report.bootstrapping.is_empty() => {
8000                self.set_sync_needed(true, false)
8001            }
8002            // The round's work is still owed; the host's connectivity resume
8003            // runs it.
8004            SyncOutcome::Failed { details, .. } if Self::unreachable_transport(details) => {
8005                self.set_sync_needed(true, false)
8006            }
8007            _ => {}
8008        }
8009        let more = self.transport_enabled
8010            && matches!(&outcome, SyncOutcome::Ok(report)
8011                if report.schema_floor.is_none()
8012                    && (!report.bootstrapping.is_empty()
8013                        || report.commits_applied > 0
8014                        || report.segment_rows_applied > 0
8015                        || !report.resets.is_empty()
8016                        || report.deferred_commits > 0
8017                        || self.sync_needed));
8018        let bootstrap_advanced = matches!(&outcome, SyncOutcome::Ok(report) if report.segment_rows_applied > 0 && !report.bootstrapping.is_empty())
8019            && before != self.resume_tokens();
8020        crate::AppliedSyncRound::Complete {
8021            outcome: self.finish_sync_round(prepared.started_at_ms, outcome),
8022            controls: if self.transport_enabled {
8023                downloads.controls
8024            } else {
8025                Vec::new()
8026            },
8027            more,
8028            bootstrap_advanced,
8029        }
8030    }
8031
8032    /// Every unit's resume token: a bootstrap that advanced changes one (§4.7).
8033    fn resume_tokens(&self) -> Option<Vec<(String, Option<String>)>> {
8034        load_units(&self.conn).ok().map(|units| {
8035            units
8036                .into_iter()
8037                .map(|unit| (unit.id, unit.bootstrap_state))
8038                .collect()
8039        })
8040    }
8041
8042    /// §7.8: one idle drive's default total deadline, the TS client's value.
8043    pub const SYNC_IDLE_TIMEOUT_MS: u64 = 60_000;
8044
8045    pub fn sync_until_idle(
8046        &mut self,
8047        transport: &mut dyn Transport,
8048        max_rounds: Option<u32>,
8049    ) -> SyncOutcome {
8050        self.sync_until_idle_with_deadline(transport, max_rounds, Some(Self::SYNC_IDLE_TIMEOUT_MS))
8051    }
8052
8053    /// As [`SyncClient::sync_until_idle`], with an explicit total deadline in
8054    /// milliseconds (`None` disables it). The deadline is checked between
8055    /// rounds; one blocking transport call is bounded by the transport's own
8056    /// whole-round deadline (§1.8).
8057    pub fn sync_until_idle_with_deadline(
8058        &mut self,
8059        transport: &mut dyn Transport,
8060        max_rounds: Option<u32>,
8061        timeout_ms: Option<u64>,
8062    ) -> SyncOutcome {
8063        // §7.8: an explicit budget is a strict positive round count. Zero is a
8064        // caller error, not an exhaustion.
8065        if max_rounds == Some(0) {
8066            return SyncOutcome::Failed {
8067                details: None,
8068                error_code: "sync.invalid_request".into(),
8069                message: "maxRounds must be a positive integer".into(),
8070                recommended_action: None,
8071            };
8072        }
8073        if timeout_ms.is_some_and(|ms| ms == 0 || i64::try_from(ms).is_err()) {
8074            return SyncOutcome::Failed {
8075                details: None,
8076                error_code: "sync.invalid_request".into(),
8077                message: "timeoutMs must be a positive integer".into(),
8078                recommended_action: None,
8079            };
8080        }
8081        let started_at_ms = self.clock_now_ms();
8082        let deadline_ms = timeout_ms.map(|ms| started_at_ms.saturating_add(ms as i64));
8083        self.sync_until_idle_bounded(transport, max_rounds, started_at_ms, deadline_ms)
8084    }
8085
8086    fn sync_until_idle_bounded(
8087        &mut self,
8088        transport: &mut dyn Transport,
8089        max_rounds: Option<u32>,
8090        started_at_ms: i64,
8091        deadline_ms: Option<i64>,
8092    ) -> SyncOutcome {
8093        let rounds = max_rounds.unwrap_or(20);
8094        let mut aggregate = SyncReport::default();
8095        let mut spent = 0;
8096        while spent < rounds {
8097            if let Some(deadline_ms) = deadline_ms {
8098                if self.clock_now_ms() >= deadline_ms {
8099                    return SyncOutcome::Failed {
8100                        error_code: "sync.idle_timeout".into(),
8101                        message: "sync_until_idle exceeded its deadline".into(),
8102                        details: Some(serde_json::json!({
8103                            "timeoutMs": deadline_ms
8104                                .saturating_sub(started_at_ms) as u64,
8105                            "rounds": spent,
8106                        })),
8107                        recommended_action: Some("retryLater".into()),
8108                    };
8109                }
8110            }
8111            spent += 1;
8112            let before = self.resume_tokens();
8113            match self.sync(transport) {
8114                SyncOutcome::Failed {
8115                    error_code,
8116                    message,
8117                    details,
8118                    recommended_action,
8119                } => {
8120                    return SyncOutcome::Failed {
8121                        details,
8122                        error_code,
8123                        message,
8124                        recommended_action,
8125                    };
8126                }
8127                outcome @ SyncOutcome::RealtimeUnavailable { .. } => return outcome,
8128                SyncOutcome::BudgetExhausted(_) => {
8129                    unreachable!("sync() never exhausts a round budget")
8130                }
8131                SyncOutcome::Ok(report) => {
8132                    if max_rounds.is_none()
8133                        && report.segment_rows_applied > 0
8134                        && !report.bootstrapping.is_empty()
8135                        && before != self.resume_tokens()
8136                    {
8137                        spent = 0;
8138                    }
8139                    // TS parity: a disabled transport or a schema floor ends
8140                    // the loop. The latest round still merges first.
8141                    let stop = !self.transport_enabled() || report.schema_floor.is_some();
8142                    aggregate.merge(&report);
8143                    if stop {
8144                        return SyncOutcome::Ok(aggregate);
8145                    }
8146                    // §4.5: pull again whenever the response contained
8147                    // commits or segments; resets re-bootstrap; a pending
8148                    // resume token continues paging (§4.7); deferred outbox
8149                    // commits and a raised sync-needed signal push on the next
8150                    // round.
8151                    let more = !report.bootstrapping.is_empty()
8152                        || report.commits_applied > 0
8153                        || report.segment_rows_applied > 0
8154                        || !report.resets.is_empty()
8155                        || report.deferred_commits > 0
8156                        || self.sync_needed;
8157                    if !more {
8158                        return SyncOutcome::Ok(aggregate);
8159                    }
8160                }
8161            }
8162        }
8163        // §7.8: partial success. The aggregate report is retained and the run
8164        // is explicitly not idle.
8165        SyncOutcome::BudgetExhausted(aggregate)
8166    }
8167
8168    fn process_response(
8169        &mut self,
8170        transport: &mut dyn Transport,
8171        response: Message,
8172        meta: &RequestMeta,
8173    ) -> SyncOutcome {
8174        #[cfg(feature = "bench-internals")]
8175        let _phase = self.benchmark_phases.start(Phase::ResponseApply);
8176        let mut report = SyncReport {
8177            pushed: meta.pushed_ids.len() as u32,
8178            ..SyncReport::default()
8179        };
8180        let mut rejection_details_by_commit: HashMap<String, BTreeMap<i32, RejectionDetails>> =
8181            HashMap::new();
8182        let pushed_ids = meta
8183            .pushed_ids
8184            .iter()
8185            .map(String::as_str)
8186            .collect::<HashSet<_>>();
8187        let mut last_final_push_result_id: Option<String> = None;
8188        for frame in &response.frames {
8189            match frame {
8190                Frame::PushResultDetails {
8191                    client_commit_id,
8192                    entries,
8193                } => {
8194                    let details = rejection_details_by_commit
8195                        .entry(client_commit_id.clone())
8196                        .or_default();
8197                    for entry in entries {
8198                        let parsed = match RejectionDetails::parse(&entry.details.0) {
8199                            Ok(value) => value,
8200                            Err(message) => {
8201                                return SyncOutcome::Failed {
8202                                    details: None,
8203                                    error_code: "sync.invalid_request".to_owned(),
8204                                    message,
8205                                    recommended_action: None,
8206                                };
8207                            }
8208                        };
8209                        details.insert(entry.op_index, parsed);
8210                    }
8211                }
8212                Frame::PushResult {
8213                    client_commit_id,
8214                    status,
8215                    results,
8216                    ..
8217                } if pushed_ids.contains(client_commit_id.as_str())
8218                    && Self::push_result_is_final(*status, results) =>
8219                {
8220                    last_final_push_result_id = Some(client_commit_id.clone());
8221                }
8222                _ => {}
8223            }
8224        }
8225        let mut frames = response.frames.into_iter().peekable();
8226        match frames.next() {
8227            Some(Frame::RespHeader {
8228                required_schema_version,
8229                latest_schema_version,
8230                log_epoch,
8231                reset_required,
8232            }) => {
8233                if let Some(required) = required_schema_version {
8234                    // §1.6 schema-floor response: nothing else is processed;
8235                    // stop syncing and surface the upgrade requirement.
8236                    let floor = SchemaFloor {
8237                        required_schema_version: Some(required),
8238                        latest_schema_version,
8239                    };
8240                    if let Err(message) = self.set_schema_floor(Some(floor.clone())) {
8241                        return SyncOutcome::Failed {
8242                            details: None,
8243                            error_code: "storage.failed".to_owned(),
8244                            message,
8245                            recommended_action: None,
8246                        };
8247                    }
8248                    report.schema_floor = Some(floor);
8249                    return SyncOutcome::Ok(report);
8250                }
8251                if reset_required {
8252                    if frames.next().is_some() {
8253                        return SyncOutcome::Failed {
8254                            details: None,
8255                            error_code: "client.invalid_host_response".to_owned(),
8256                            message: "log-epoch reset response contains body frames".to_owned(),
8257                            recommended_action: None,
8258                        };
8259                    }
8260                    match self.run_log_epoch_reset(&log_epoch) {
8261                        Ok(resets) => {
8262                            report.resets = resets;
8263                            return SyncOutcome::Ok(report);
8264                        }
8265                        Err(message) => {
8266                            return SyncOutcome::Failed {
8267                                details: None,
8268                                error_code: "sync.local_corrupt".to_owned(),
8269                                message,
8270                                recommended_action: None,
8271                            };
8272                        }
8273                    }
8274                }
8275                let stored_epoch = match self.get_meta(LOG_EPOCH_KEY) {
8276                    Ok(stored) => stored,
8277                    Err(message) => {
8278                        return SyncOutcome::Failed {
8279                            details: None,
8280                            error_code: "storage.failed".to_owned(),
8281                            message,
8282                            recommended_action: None,
8283                        };
8284                    }
8285                };
8286                if stored_epoch.as_deref() != Some(log_epoch.as_str()) {
8287                    return SyncOutcome::Failed {
8288                        details: None,
8289                        error_code: "client.invalid_host_response".to_owned(),
8290                        message: "server changed logEpoch without requiring a reset".to_owned(),
8291                        recommended_action: None,
8292                    };
8293                }
8294            }
8295            _ => {
8296                return SyncOutcome::Failed {
8297                    details: None,
8298                    error_code: "sync.invalid_request".to_owned(),
8299                    message: "response does not start with RESP_HEADER".to_owned(),
8300                    recommended_action: None,
8301                };
8302            }
8303        }
8304
8305        if let Err(message) = self.begin_coalesced_apply() {
8306            return SyncOutcome::Failed {
8307                details: None,
8308                error_code: "storage.failed".into(),
8309                message,
8310                recommended_action: None,
8311            };
8312        }
8313        let mut failure: Option<(String, String, Option<String>, Option<Value>)> = None;
8314        // §4.5 client application: the units whose persisted echo a live
8315        // change must match, fixed at LIVE_START after every SUB_END persisted.
8316        let mut live: Option<(LiveStatus, String, Vec<UnitRecord>)> = None;
8317        let mut live_ended = false;
8318        while let Some(frame) = frames.next() {
8319            match frame {
8320                frame @ Frame::PushResult { .. } => {
8321                    let successful = matches!(
8322                        &frame,
8323                        Frame::PushResult {
8324                            status: PushStatus::Applied | PushStatus::Cached,
8325                            ..
8326                        }
8327                    );
8328                    let mut results = vec![frame];
8329                    if successful {
8330                        while matches!(
8331                            frames.peek(),
8332                            Some(Frame::PushResult {
8333                                status: PushStatus::Applied | PushStatus::Cached,
8334                                ..
8335                            })
8336                        ) {
8337                            if let Some(next) = frames.next() {
8338                                results.push(next);
8339                            }
8340                        }
8341                    }
8342                    if self
8343                        .handle_push_results(
8344                            &results,
8345                            &pushed_ids,
8346                            &rejection_details_by_commit,
8347                            &mut report,
8348                            last_final_push_result_id.as_deref(),
8349                        )
8350                        .is_err()
8351                    {
8352                        failure = Some((
8353                            "client.outcome_persistence_failed".to_owned(),
8354                            "local commit outcome could not be persisted".to_owned(),
8355                            None,
8356                            None,
8357                        ));
8358                        break;
8359                    }
8360                }
8361                Frame::PushResultDetails { .. } => {}
8362                Frame::SubStart {
8363                    id,
8364                    status,
8365                    reason_code,
8366                    bootstrap,
8367                    fenced,
8368                } => {
8369                    // §1.4 rule 5: an ERROR closes the section; its body still
8370                    // applied, its SUB_END values are never persisted.
8371                    let mut body = Vec::new();
8372                    let mut sub_end: Option<(i64, Option<String>)> = None;
8373                    let mut error: Option<Frame> = None;
8374                    for inner in frames.by_ref() {
8375                        match inner {
8376                            Frame::SubEnd {
8377                                next_cursor,
8378                                bootstrap_state,
8379                            } => {
8380                                sub_end = Some((next_cursor, bootstrap_state.map(|r| r.0)));
8381                                break;
8382                            }
8383                            inner @ Frame::Error { .. } => {
8384                                error = Some(inner);
8385                                break;
8386                            }
8387                            Frame::Unknown { .. } => {}
8388                            other => body.push(other),
8389                        }
8390                    }
8391                    let ended = sub_end.is_some();
8392                    let section = SectionStart {
8393                        id,
8394                        status,
8395                        reason_code,
8396                        bootstrap,
8397                        fenced,
8398                    };
8399                    match self.process_section(
8400                        transport,
8401                        &section,
8402                        body,
8403                        sub_end,
8404                        meta,
8405                        &mut report,
8406                    ) {
8407                        Err(SectionError::Abort(code, message)) => {
8408                            failure = Some((code, message, None, None));
8409                            break;
8410                        }
8411                        Err(SectionError::Transport(error)) => {
8412                            failure = Some((error.code, error.message, None, error.details));
8413                            break;
8414                        }
8415                        _ => {}
8416                    }
8417                    if ended {
8418                        // The counters stay: `complete` and `failed` report them.
8419                        self.progress.update(|p| {
8420                            p.unit_id = None;
8421                            p.table = None;
8422                            p.segment_id = None;
8423                        });
8424                    }
8425                    match error {
8426                        Some(Frame::Error {
8427                            code,
8428                            message,
8429                            recommended_action,
8430                            details,
8431                            ..
8432                        }) => {
8433                            failure = Some(Self::error_frame_failure(
8434                                code,
8435                                message,
8436                                recommended_action,
8437                                details,
8438                            ));
8439                            break;
8440                        }
8441                        Some(_) => unreachable!("only an ERROR closes a section early"),
8442                        None if !ended => {
8443                            failure = Some((
8444                                "sync.invalid_request".to_owned(),
8445                                "unit section without SUB_END".to_owned(),
8446                                None,
8447                                None,
8448                            ));
8449                            break;
8450                        }
8451                        None => {}
8452                    }
8453                }
8454                Frame::LiveStart {
8455                    status,
8456                    reason_code,
8457                } => {
8458                    let receivers = match self.stored(load_units(&self.conn)) {
8459                        Ok(units) => units
8460                            .into_iter()
8461                            .filter(|unit| {
8462                                unit.status == UnitStatus::Active
8463                                    && unit.echo.is_some()
8464                                    && !unit.bootstrapping()
8465                            })
8466                            .collect(),
8467                        Err(message) => {
8468                            failure = Some(("storage.failed".to_owned(), message, None, None));
8469                            break;
8470                        }
8471                    };
8472                    live = Some((status, reason_code, receivers));
8473                }
8474                Frame::Commit {
8475                    commit_seq,
8476                    tables,
8477                    changes,
8478                    ..
8479                } => {
8480                    let Some((LiveStatus::Active, _, receivers)) = &live else {
8481                        continue;
8482                    };
8483                    let receivers = receivers.clone();
8484                    match self.apply_live_commit(
8485                        &receivers,
8486                        &tables,
8487                        changes,
8488                        commit_seq,
8489                        AppliedServerCommitSource::Pull,
8490                    ) {
8491                        Ok(applied) => report.commits_applied += u32::from(applied),
8492                        Err(error) => {
8493                            failure = Some((error.code, error.message, None, error.details));
8494                            break;
8495                        }
8496                    }
8497                }
8498                Frame::LiveEnd {
8499                    through_seq,
8500                    echo_digest,
8501                } => {
8502                    let Some((status, reason_code, _)) = live.take() else {
8503                        continue;
8504                    };
8505                    live_ended = true;
8506                    live = Some((status, String::new(), Vec::new()));
8507                    if let Err(message) = self.finish_live_section(
8508                        status,
8509                        &reason_code,
8510                        through_seq,
8511                        echo_digest,
8512                        &meta.registration_digest,
8513                        &mut report,
8514                    ) {
8515                        failure = Some(("storage.failed".to_owned(), message, None, None));
8516                        break;
8517                    }
8518                }
8519                Frame::Lease {
8520                    lease_id,
8521                    expires_at_ms,
8522                } => {
8523                    // §7.3.5: persist the opaque lease; a fresh lease clears
8524                    // any prior lease error (the outage/revocation is over).
8525                    if let Err(message) = self.set_lease_state(Some(LeaseState {
8526                        lease_id: Some(lease_id),
8527                        expires_at_ms: Some(expires_at_ms),
8528                        error_code: None,
8529                    })) {
8530                        failure = Some(("storage.failed".to_owned(), message, None, None));
8531                        break;
8532                    }
8533                }
8534                Frame::Error {
8535                    code,
8536                    message,
8537                    recommended_action,
8538                    details,
8539                    ..
8540                } => {
8541                    // §1.6: the whole request failed; already-completed
8542                    // units keep their applied data and cursors.
8543                    failure = Some(Self::error_frame_failure(
8544                        code,
8545                        message,
8546                        recommended_action,
8547                        details,
8548                    ));
8549                    break;
8550                }
8551                Frame::Unknown { .. } => {}
8552                _ => {
8553                    failure = Some((
8554                        "sync.invalid_request".to_owned(),
8555                        "unexpected frame in response".to_owned(),
8556                        None,
8557                        None,
8558                    ));
8559                    break;
8560                }
8561            }
8562        }
8563
8564        let applied = match failure {
8565            Some(failure) => Err(failure),
8566            // Local apply boundaries already reconciled their affected overlay.
8567            // Refuse round success if any remaining dirty work fails to
8568            // reconcile. §4.8 E1: the push half may have drained commits that
8569            // pinned rows of a shrunk window unit, so retry deferred evictions.
8570            None => self
8571                .rebuild_overlay_if_dirty()
8572                .and_then(|()| self.drain_pending_evictions())
8573                .map_err(|message| ("storage.failed".to_owned(), message, None, None)),
8574        };
8575        // §1.4 rule 4: frames completed before a failure stay committed; a
8576        // failed COMMIT of the coalesced transaction fails the round.
8577        if let Err(message) = self.finish_coalesced_apply() {
8578            return SyncOutcome::Failed {
8579                details: None,
8580                error_code: "storage.failed".into(),
8581                message,
8582                recommended_action: None,
8583            };
8584        }
8585        if let Err((error_code, message, recommended_action, details)) = applied {
8586            return SyncOutcome::Failed {
8587                details,
8588                error_code,
8589                message,
8590                recommended_action,
8591            };
8592        }
8593        let catching_up = match self.stored(load_units(&self.conn)) {
8594            Ok(units) => units
8595                .into_iter()
8596                .filter(|unit| unit.status == UnitStatus::Active && unit.cursor.is_some())
8597                .map(|unit| unit.id)
8598                .collect::<Vec<_>>(),
8599            Err(message) => {
8600                return SyncOutcome::Failed {
8601                    details: None,
8602                    error_code: "storage.failed".into(),
8603                    message,
8604                    recommended_action: None,
8605                }
8606            }
8607        };
8608        // §7.1: a response without LIVE_END, one answered `unregistered` or
8609        // `reset`, or a unit still catching up leaves sync-needed raised;
8610        // after `unregistered` the next round starts at once.
8611        let status = live.map(|(status, _, _)| status);
8612        if !live_ended || status != Some(LiveStatus::Active) || !catching_up.is_empty() {
8613            self.set_sync_needed(true, status == Some(LiveStatus::Unregistered));
8614        }
8615        self.ack_after_pull(transport);
8616        // §7.4.5: the reset is over once the first post-reset pull round
8617        // leaves no unit catching up: the tables are rebuilt and current.
8618        if self.upgrading && catching_up.is_empty() {
8619            self.set_upgrading(false);
8620        }
8621        report.bootstrapping = catching_up;
8622        SyncOutcome::Ok(report)
8623    }
8624
8625    /// §1.6 / §10.1: the failure an in-band `ERROR` frame reports.
8626    fn error_frame_failure(
8627        code: String,
8628        message: String,
8629        recommended_action: String,
8630        details: Option<RawJson>,
8631    ) -> (String, String, Option<String>, Option<Value>) {
8632        let recommended_action = (!recommended_action.is_empty()).then_some(recommended_action);
8633        let details = details
8634            .and_then(|details| serde_json::from_str::<Value>(&details.0).ok())
8635            .filter(Value::is_object);
8636        (code, message, recommended_action, details)
8637    }
8638
8639    /// §4.5 at `LIVE_END` of a pull: join rule J for an `active` section, the
8640    /// §4.6 replica reset for `reset`, nothing for `unregistered`; then the
8641    /// replica cursor, the echo digest and the digest of the list the server
8642    /// now stores.
8643    fn finish_live_section(
8644        &mut self,
8645        status: LiveStatus,
8646        reason_code: &str,
8647        through_seq: i64,
8648        echo_digest: Option<[u8; 32]>,
8649        registration_digest: &str,
8650        report: &mut SyncReport,
8651    ) -> Result<(), String> {
8652        let rollback = self.capture();
8653        let resets = report.resets.len();
8654        self.begin_observation("syncular_live_end")?;
8655        let finished = (|| {
8656            let mut batch = ChangeAccumulator::default();
8657            let before = self.stored(replica_cursor(&self.conn))?;
8658            let mut cursor = if status == LiveStatus::Unregistered {
8659                before
8660            } else {
8661                -1
8662            };
8663            let joined = before.max(through_seq);
8664            for unit in self.stored(load_units(&self.conn))? {
8665                if unit.status != UnitStatus::Active || unit.bootstrapping() {
8666                    continue;
8667                }
8668                match status {
8669                    // §4.6 replica reset: every live unit bootstraps again;
8670                    // post-bootstrap units keep their cursors.
8671                    LiveStatus::Reset if unit.cursor.is_none() => {
8672                        for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
8673                            batch.window(&base_key, &value);
8674                        }
8675                        report.resets.push(unit.id.clone());
8676                        self.stored(save_unit(
8677                            &self.conn,
8678                            &UnitRecord {
8679                                reason_code: Some(reason_code.to_owned()),
8680                                cursor: Some(-1),
8681                                seeded: Vec::new(),
8682                                ..unit
8683                            },
8684                        ))?;
8685                    }
8686                    // §4.5 join rule J.
8687                    LiveStatus::Active => {
8688                        let next = unit.cursor.unwrap_or(joined).max(through_seq);
8689                        if next >= joined {
8690                            cursor = joined;
8691                        }
8692                        if unit.cursor.is_some() {
8693                            self.stored(save_unit(
8694                                &self.conn,
8695                                &UnitRecord {
8696                                    cursor: (next < joined).then_some(next),
8697                                    ..unit
8698                                },
8699                            ))?;
8700                        }
8701                    }
8702                    _ => {}
8703                }
8704            }
8705            self.set_meta(REPLICA_CURSOR_KEY, &cursor.to_string())?;
8706            self.set_meta(
8707                ECHO_DIGEST_KEY,
8708                &echo_digest
8709                    .map(|digest| bytes_to_hex(&digest))
8710                    .unwrap_or_default(),
8711            )?;
8712            if status == LiveStatus::Unregistered {
8713                self.delete_meta(REGISTERED_DIGEST_KEY)?;
8714            } else {
8715                self.set_meta(REGISTERED_DIGEST_KEY, registration_digest)?;
8716            }
8717            self.finish_observation("syncular_live_end", batch)
8718        })();
8719        if finished.is_err() {
8720            self.rollback_observation("syncular_live_end");
8721            self.restore(rollback);
8722            report.resets.truncate(resets);
8723        }
8724        finished
8725    }
8726
8727    // -- push results (§6.3, §7.2) ------------------------------------------------
8728
8729    fn handle_push_results(
8730        &mut self,
8731        frames: &[Frame],
8732        pushed_ids: &HashSet<&str>,
8733        rejection_details_by_commit: &HashMap<String, BTreeMap<i32, RejectionDetails>>,
8734        report: &mut SyncReport,
8735        last_final_push_result_id: Option<&str>,
8736    ) -> Result<(), String> {
8737        self.begin_observation("syncular_push_results")?;
8738        let rollback = self.capture();
8739        let conflict_count = self.conflicts.len();
8740        let applied_count = report.applied.len();
8741        let rejected_count = report.rejected.len();
8742        let retryable_count = report.retryable.len();
8743        let mut drained = Vec::new();
8744        let mut batch = ChangeAccumulator::default();
8745        let persisted = (|| {
8746            for frame in frames {
8747                let Frame::PushResult {
8748                    client_commit_id,
8749                    status,
8750                    results,
8751                    commit_seq,
8752                } = frame
8753                else {
8754                    return Err("unexpected acknowledgement frame".to_owned());
8755                };
8756                if !pushed_ids.contains(client_commit_id.as_str()) {
8757                    continue;
8758                }
8759                let Some(index) = self
8760                    .outbox
8761                    .iter()
8762                    .position(|commit| commit.client_commit_id == *client_commit_id)
8763                else {
8764                    continue;
8765                };
8766                let status = *status;
8767                let rejection_details = rejection_details_by_commit.get(client_commit_id);
8768                let operations = self.outbox[index].ops.clone();
8769                match status {
8770                    PushStatus::Applied | PushStatus::Cached => {
8771                        // §7.2: a lost ack replays as `cached` — proceed as if the
8772                        // ack had arrived.
8773                        let sequence =
8774                            commit_seq.ok_or_else(|| "ACK lacks a commit sequence".to_owned())?;
8775                        let affected: HashSet<_> = operations
8776                            .iter()
8777                            .map(|op| (op.table.as_str(), op.row_id.as_str()))
8778                            .collect();
8779                        let prior = self.acknowledged_operations(Some(&affected), None)?;
8780                        for (op_index, operation) in operations.iter().enumerate() {
8781                            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))
8782                                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
8783                            if delivered {
8784                                continue;
8785                            }
8786                            let table = self
8787                                .schema
8788                                .table(&operation.table)
8789                                .ok_or_else(|| "sync.unknown_table".to_owned())?;
8790                            let mut intended: Map<String, Value> = self
8791                                .stored_row(table, &operation.row_id, true)?
8792                                .map(|(row, _)| {
8793                                    table
8794                                        .columns
8795                                        .iter()
8796                                        .zip(&row)
8797                                        .map(|(column, value)| {
8798                                            (column.name.clone(), column_value_to_json(value))
8799                                        })
8800                                        .collect()
8801                                })
8802                                .unwrap_or_default();
8803                            let mut scope_image = intended.clone();
8804                            for op in prior
8805                                .iter()
8806                                .chain(
8807                                    self.failed_commits
8808                                        .iter()
8809                                        .flat_map(|(commit, _)| &commit.ops),
8810                                )
8811                                .chain(
8812                                    self.outbox
8813                                        .iter()
8814                                        .take(index)
8815                                        .flat_map(|commit| &commit.ops),
8816                                )
8817                                .chain(operations.iter().take(op_index + 1))
8818                            {
8819                                if op.table != operation.table || op.row_id != operation.row_id {
8820                                    continue;
8821                                }
8822                                if let Some(values) = &op.values {
8823                                    intended.extend(values.clone());
8824                                } else {
8825                                    scope_image = intended.clone();
8826                                    intended.clear();
8827                                }
8828                            }
8829                            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)",
8830                                rusqlite::params![client_commit_id, op_index as i64, operation.table, operation.row_id, sequence,
8831                                    serde_json::to_string(&CommitOperation::from(operation)).map_err(|_| "sync.local_corrupt".to_owned())?,
8832                                    serde_json::to_string(if operation.upsert { &intended } else { &scope_image }).map_err(|_| "sync.local_corrupt".to_owned())?])
8833                                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
8834                        }
8835                        let journal_results = results
8836                            .iter()
8837                            .map(|result| {
8838                                let op_index = match result {
8839                                    OpResult::Applied { op_index }
8840                                    | OpResult::Conflict { op_index, .. }
8841                                    | OpResult::Error { op_index, .. } => *op_index,
8842                                };
8843                                CommitOperationOutcome::Applied { op_index }
8844                            })
8845                            .collect::<Vec<_>>();
8846                        let outcome_status = if status == PushStatus::Applied {
8847                            CommitOutcomeStatus::Applied
8848                        } else {
8849                            CommitOutcomeStatus::Cached
8850                        };
8851                        let persisted = self
8852                            .persist_commit_outcome(
8853                                client_commit_id,
8854                                outcome_status,
8855                                &journal_results,
8856                                None,
8857                            )
8858                            .and_then(|()| self.delete_outbox_persisted(client_commit_id));
8859                        persisted?;
8860                        self.sync_needed = true;
8861                        batch.status = true;
8862                        batch.outcomes = true;
8863                    }
8864                    PushStatus::Rejected => {
8865                        if results.iter().any(|result| {
8866                            matches!(
8867                                result,
8868                                OpResult::Error {
8869                                    code,
8870                                    retryable: true,
8871                                    ..
8872                                } if code == "sync.idempotency_cache_miss"
8873                            )
8874                        }) {
8875                            // §6.3/§7.2: a serving failure, not an outcome — keep the
8876                            // exact commit queued for an identical retry.
8877                            report.retryable.push(client_commit_id.to_owned());
8878                            continue;
8879                        }
8880
8881                        let mut journal_results = Vec::with_capacity(results.len());
8882                        let mut conflicts = Vec::new();
8883                        let mut rejections = Vec::new();
8884                        for result in results {
8885                            match result {
8886                                OpResult::Applied { op_index } => {
8887                                    journal_results.push(CommitOperationOutcome::Applied {
8888                                        op_index: *op_index,
8889                                    });
8890                                }
8891                                OpResult::Conflict {
8892                                    op_index,
8893                                    code,
8894                                    message,
8895                                    server_version,
8896                                    server_row,
8897                                    conflict_columns: conflict_columns_bitmap,
8898                                } => {
8899                                    let operation = operations
8900                                        .get(*op_index as usize)
8901                                        .map(CommitOperation::from);
8902                                    let (table, row_id) = operation
8903                                        .as_ref()
8904                                        .map(|op| (op.table.clone(), op.row_id.clone()))
8905                                        .unwrap_or_default();
8906                                    let server_row_json = self
8907                                        .schema
8908                                        .table(&table)
8909                                        .and_then(|t| {
8910                                            decode_row_bytes(t, server_row, &self.encryption)
8911                                                .ok()
8912                                                .map(|row| (t, row))
8913                                        })
8914                                        .map(|(t, row)| {
8915                                            let mut map = Map::new();
8916                                            for (i, column) in t.columns.iter().enumerate() {
8917                                                map.insert(
8918                                                    column.name.clone(),
8919                                                    column_value_to_json(
8920                                                        row.get(i).unwrap_or(&None),
8921                                                    ),
8922                                                );
8923                                            }
8924                                            map
8925                                        })
8926                                        .unwrap_or_default();
8927                                    // §6.3: decode the presence-layout bitmap
8928                                    // into the marked column names.
8929                                    let conflict_columns = self
8930                                        .schema
8931                                        .table(&table)
8932                                        .map(|t| {
8933                                            t.columns
8934                                                .iter()
8935                                                .enumerate()
8936                                                .filter(|(index, _)| {
8937                                                    conflict_columns_bitmap
8938                                                        .get(index / 8)
8939                                                        .is_some_and(|byte| {
8940                                                            byte & (1 << (index % 8)) != 0
8941                                                        })
8942                                                })
8943                                                .map(|(_, column)| column.name.clone())
8944                                                .collect::<Vec<_>>()
8945                                        })
8946                                        .unwrap_or_default();
8947                                    let conflict = ConflictRecord {
8948                                        client_commit_id: client_commit_id.to_owned(),
8949                                        op_index: *op_index,
8950                                        table,
8951                                        row_id,
8952                                        code: code.clone(),
8953                                        message: message.clone(),
8954                                        server_version: *server_version,
8955                                        server_row: server_row_json,
8956                                        conflict_columns,
8957                                        operation,
8958                                    };
8959                                    journal_results.push(CommitOperationOutcome::Conflict {
8960                                        conflict: conflict.clone(),
8961                                    });
8962                                    conflicts.push(conflict);
8963                                }
8964                                OpResult::Error {
8965                                    op_index,
8966                                    code,
8967                                    message,
8968                                    retryable,
8969                                } => {
8970                                    let rejection = RejectionRecord {
8971                                        client_commit_id: client_commit_id.to_owned(),
8972                                        op_index: *op_index,
8973                                        code: code.clone(),
8974                                        message: message.clone(),
8975                                        retryable: *retryable,
8976                                        details: rejection_details
8977                                            .and_then(|details| details.get(op_index))
8978                                            .cloned(),
8979                                        operation: operations
8980                                            .get(*op_index as usize)
8981                                            .map(CommitOperation::from),
8982                                    };
8983                                    journal_results.push(CommitOperationOutcome::Error {
8984                                        rejection: rejection.clone(),
8985                                    });
8986                                    rejections.push(rejection);
8987                                }
8988                            }
8989                        }
8990                        if self.retain_failed_commits {
8991                            self.retain_failed_commit(client_commit_id, &operations)?;
8992                        }
8993                        let outcome_status = if conflicts.is_empty() {
8994                            CommitOutcomeStatus::Rejected
8995                        } else {
8996                            CommitOutcomeStatus::Conflict
8997                        };
8998                        let persisted = self
8999                            .persist_commit_outcome(
9000                                client_commit_id,
9001                                outcome_status,
9002                                &journal_results,
9003                                Some(&operations),
9004                            )
9005                            .and_then(|()| self.delete_outbox_persisted(client_commit_id));
9006                        persisted?;
9007                        batch.conflicts = !conflicts.is_empty();
9008                        batch.rejections = !rejections.is_empty();
9009                        batch.status = true;
9010                        batch.outcomes = true;
9011                        self.conflicts.extend(conflicts);
9012                        self.rejections.extend(rejections);
9013                    }
9014                }
9015                drained.push(self.outbox.remove(index));
9016                if batch.status {
9017                    for operation in &operations {
9018                        if !self.record_row_scopes(
9019                            &mut batch,
9020                            &operation.table,
9021                            &operation.row_id,
9022                            false,
9023                        ) {
9024                            batch.table(&operation.table);
9025                        }
9026                    }
9027                }
9028                match status {
9029                    PushStatus::Applied | PushStatus::Cached => {
9030                        report.applied.push(client_commit_id.to_owned())
9031                    }
9032                    PushStatus::Rejected => report.rejected.push(client_commit_id.to_owned()),
9033                }
9034            }
9035            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)) {
9036                self.prune_commit_outcomes()?;
9037            }
9038            self.reconcile_rows(&drained)?;
9039            self.rebuild_overlay_if_dirty()?;
9040            self.finish_observation("syncular_push_results", batch)
9041        })();
9042        if let Err(error) = persisted {
9043            self.rollback_observation("syncular_push_results");
9044            self.restore(rollback);
9045            report.applied.truncate(applied_count);
9046            report.rejected.truncate(rejected_count);
9047            report.retryable.truncate(retryable_count);
9048            return Err(error);
9049        }
9050        if !rollback.sync_needed && self.sync_needed {
9051            self.sync_intent_queue.push_back(SyncIntent::Interactive);
9052        }
9053        report.conflicts += (self.conflicts.len() - conflict_count) as u32;
9054        Ok(())
9055    }
9056
9057    fn push_result_is_final(status: PushStatus, results: &[OpResult]) -> bool {
9058        status != PushStatus::Rejected
9059            || !results.iter().any(|result| {
9060                matches!(
9061                    result,
9062                    OpResult::Error {
9063                        code,
9064                        retryable: true,
9065                        ..
9066                    } if code == "sync.idempotency_cache_miss"
9067                )
9068            })
9069    }
9070
9071    // -- unit sections and the live section ------------------------------------------
9072
9073    /// One unit section (§4.4): apply its segments, then persist its
9074    /// `SUB_END` (§4.6 reset, §3.3 revocation and purge, the echo, cursor and
9075    /// resume token). A section of a unit the app released while the round was
9076    /// in flight is skipped; a fail-closed first page fails the unit and skips
9077    /// the rest of its section (§5.6).
9078    fn process_section(
9079        &mut self,
9080        transport: &mut dyn Transport,
9081        start: &SectionStart,
9082        body: Vec<Frame>,
9083        sub_end: Option<(i64, Option<String>)>,
9084        meta: &RequestMeta,
9085        report: &mut SyncReport,
9086    ) -> Result<(), SectionError> {
9087        let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
9088        let unit = self
9089            .stored(get_unit(&self.conn, &start.id))
9090            .map_err(storage)?
9091            .filter(|unit| unit.status == UnitStatus::Active);
9092        // §7.7: a section boundary ends the previous payload.
9093        self.progress.update(|p| {
9094            p.phase = ProgressPhase::Import;
9095            p.unit_id = unit.as_ref().map(|unit| unit.id.clone());
9096            p.table = None;
9097            p.segment_id = None;
9098            p.bytes_received = 0;
9099            p.bytes_total = None;
9100            p.rows_processed = 0;
9101            p.rows_total = None;
9102            p.import_write_ms = None;
9103            p.import_commit_ms = None;
9104        });
9105        let Some(unit) = unit else {
9106            return Ok(());
9107        };
9108        let echo: Vec<EchoRecord> = start
9109            .fenced
9110            .iter()
9111            .map(|record| EchoRecord {
9112                table: record.table.clone(),
9113                status: record.status.name().to_owned(),
9114                scopes: record.scopes.iter().cloned().collect(),
9115            })
9116            .collect();
9117        // §5.6: a resumed bootstrap keeps the tables it already seeded.
9118        let mut seeded: BTreeSet<String> = if unit.bootstrap_state.is_none() {
9119            BTreeSet::new()
9120        } else {
9121            unit.seeded.iter().cloned().collect()
9122        };
9123        let applied = (|| {
9124            for frame in body {
9125                match frame {
9126                    Frame::SegmentInline { payload } => {
9127                        let segment = decode_rows_segment(&payload).map_err(|e| {
9128                            SectionError::Abort(e.code.as_str().to_owned(), e.detail)
9129                        })?;
9130                        self.progress.update(|p| {
9131                            p.phase = ProgressPhase::Import;
9132                            p.unit_id = Some(unit.id.clone());
9133                            p.table = Some(segment.table.clone());
9134                            p.segment_id = None;
9135                            p.bytes_received = payload.len() as u64;
9136                            p.bytes_total = Some(payload.len() as u64);
9137                            p.rows_processed = 0;
9138                            p.rows_total =
9139                                Some(segment.blocks.iter().map(|block| block.len() as u64).sum());
9140                            p.import_write_ms = None;
9141                            p.import_commit_ms = None;
9142                        });
9143                        let (pair, clear, effective) =
9144                            self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
9145                        report.segment_rows_applied +=
9146                            self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
9147                        seeded.insert(segment.table);
9148                    }
9149                    Frame::SegmentRef {
9150                        segment_id,
9151                        byte_length,
9152                        media_type,
9153                        table,
9154                        row_count,
9155                        as_of_commit_seq,
9156                        scope_digest,
9157                        row_cursor,
9158                        next_row_cursor,
9159                        url,
9160                        url_expires_at_ms,
9161                        ..
9162                    } => {
9163                        // §4.2: reject a descriptor whose mediaType was not
9164                        // advertised — never skip or guess.
9165                        let advertised = match media_type {
9166                            MediaType::Rows => {
9167                                meta.accept & ACCEPT_EXTERNAL_ROWS != 0
9168                                    || meta.accept & ACCEPT_INLINE_ROWS != 0
9169                            }
9170                            MediaType::Sqlite => meta.accept & ACCEPT_SQLITE != 0,
9171                        };
9172                        if !advertised {
9173                            return Err(SectionError::Abort(
9174                                "sync.invalid_request".to_owned(),
9175                                format!(
9176                                    "SEGMENT_REF mediaType {} was not advertised in accept (§4.2)",
9177                                    media_type.name()
9178                                ),
9179                            ));
9180                        }
9181                        self.progress.update(|p| {
9182                            p.phase = ProgressPhase::Download;
9183                            p.unit_id = Some(unit.id.clone());
9184                            p.table = Some(table.clone());
9185                            p.segment_id = Some(segment_id.clone());
9186                            p.bytes_received = 0;
9187                            p.bytes_total = u64::try_from(byte_length).ok();
9188                            p.rows_processed = 0;
9189                            p.rows_total = u64::try_from(row_count).ok();
9190                            p.import_write_ms = None;
9191                            p.import_commit_ms = None;
9192                        });
9193                        let observer = self.progress.clone();
9194                        let mut on_progress = |bytes| observer.update(|p| p.bytes_received = bytes);
9195                        let bytes = if let Some(url) = url {
9196                            // §5.4: a url-carrying descriptor MUST be fetched
9197                            // from that URL; failure invalidates the whole
9198                            // descriptor (no fall-through to §5.5 — re-pull
9199                            // recovers, §1.4 rule 5).
9200                            if meta.accept & ACCEPT_SIGNED_URLS == 0 {
9201                                return Err(SectionError::Abort(
9202                                    "sync.invalid_request".to_owned(),
9203                                    "SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)"
9204                                        .to_owned(),
9205                                ));
9206                            }
9207                            // §5.4: MUST NOT start a fetch at/past expiry.
9208                            if url_expires_at_ms.is_some_and(|exp| {
9209                                exp <= transport
9210                                    .segment_fetch_started_at(&url)
9211                                    .unwrap_or_else(|| self.clock_now_ms())
9212                            }) {
9213                                return Err(SectionError::Abort(
9214                                    "sync.segment_expired".to_owned(),
9215                                    format!(
9216                                        "signed URL for segment {segment_id} expired before fetch — re-pull mints fresh descriptors (§5.4)"
9217                                    ),
9218                                ));
9219                            }
9220                            transport
9221                                .fetch_url(
9222                                    &url,
9223                                    u64::try_from(byte_length).unwrap_or(0),
9224                                    &mut on_progress,
9225                                )
9226                                .map_err(|e| self.segment_fetch_failed(e))?
9227                        } else {
9228                            // §5.5: the owning unit's scope map, each value a one-element list.
9229                            let requested_scopes_json =
9230                                canonical_scope_json(&unit_scope_lists(&unit.scopes));
9231                            transport
9232                                .download_segment(
9233                                    &SegmentRequest {
9234                                        segment_id: segment_id.clone(),
9235                                        table: table.clone(),
9236                                        requested_scopes_json,
9237                                        byte_length: u64::try_from(byte_length).unwrap_or(0),
9238                                    },
9239                                    &mut on_progress,
9240                                )
9241                                .map_err(|e| {
9242                                    // §5.5: access changed since the response;
9243                                    // the next round's SUB_START settles the unit.
9244                                    if e.code == "sync.forbidden" {
9245                                        SectionError::Refused
9246                                    } else {
9247                                        self.segment_fetch_failed(e)
9248                                    }
9249                                })?
9250                        };
9251                        // §5.4: the descriptor's byteLength caps the body before
9252                        // §5.1 verifies the content address; the client discards
9253                        // the segment and re-pulls on either failure.
9254                        if bytes.len() as i64 > byte_length {
9255                            self.schedule_background_retry();
9256                            return Err(SectionError::Abort(
9257                                "sync.invalid_request".to_owned(),
9258                                "segment exceeds its byteLength".to_owned(),
9259                            ));
9260                        }
9261                        on_progress(bytes.len() as u64);
9262                        let digest = Sha256::digest(&bytes);
9263                        let expected = segment_id
9264                            .strip_prefix("sha256:")
9265                            .unwrap_or(segment_id.as_str());
9266                        if bytes_to_hex(&digest) != expected {
9267                            // §5.1: the client discards the segment and re-pulls.
9268                            self.schedule_background_retry();
9269                            return Err(SectionError::Abort(
9270                                "sync.invalid_request".to_owned(),
9271                                "segment bytes do not match the content address (§5.1)".to_owned(),
9272                            ));
9273                        }
9274                        self.progress.update(|p| p.phase = ProgressPhase::Import);
9275                        if media_type == MediaType::Sqlite {
9276                            // §5.3: images are whole-table — a paged sqlite
9277                            // descriptor is invalid.
9278                            if row_cursor.is_some() || next_row_cursor.is_some() {
9279                                return Err(SectionError::Abort(
9280                                    "sync.invalid_request".to_owned(),
9281                                    "sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)"
9282                                        .to_owned(),
9283                                ));
9284                            }
9285                            let (pair, clear, effective) =
9286                                self.segment_pair(&unit, &echo, &seeded, &table)?;
9287                            report.segment_rows_applied += self.apply_sqlite_segment(
9288                                &pair,
9289                                &bytes,
9290                                clear,
9291                                &effective,
9292                                &unit.id,
9293                                row_count,
9294                                as_of_commit_seq,
9295                                &scope_digest,
9296                            )?;
9297                            seeded.insert(table);
9298                        } else {
9299                            let segment = decode_rows_segment(&bytes).map_err(|e| {
9300                                SectionError::Abort(e.code.as_str().to_owned(), e.detail)
9301                            })?;
9302                            let (pair, clear, effective) =
9303                                self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
9304                            report.segment_rows_applied +=
9305                                self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
9306                            seeded.insert(segment.table);
9307                        }
9308                    }
9309                    _ => {
9310                        return Err(SectionError::Abort(
9311                            "sync.invalid_request".to_owned(),
9312                            "unexpected frame inside a unit section".to_owned(),
9313                        ));
9314                    }
9315                }
9316            }
9317            Ok(())
9318        })();
9319        match applied {
9320            Ok(()) => {}
9321            // The unit keeps catching up with its cursor unpersisted.
9322            Err(SectionError::Refused) => return Ok(()),
9323            Err(SectionError::FailClosed) => {
9324                // §5.6: the failure is unit-local; the rest of the response
9325                // still applies and the failed unit leaves the list.
9326                self.begin_observation("syncular_section_failure")
9327                    .map_err(storage)?;
9328                let failed = (|| {
9329                    let mut batch = ChangeAccumulator::default();
9330                    for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9331                        batch.window(&base_key, &value);
9332                    }
9333                    batch.status = true;
9334                    self.stored(save_unit(
9335                        &self.conn,
9336                        &UnitRecord {
9337                            status: UnitStatus::Failed,
9338                            reason_code: Some("sync.scope_revoked".to_owned()),
9339                            ..unit.clone()
9340                        },
9341                    ))?;
9342                    self.finish_observation("syncular_section_failure", batch)
9343                })();
9344                if let Err(message) = failed {
9345                    self.rollback_observation("syncular_section_failure");
9346                    return Err(storage(message));
9347                }
9348                report.failed.push(unit.id);
9349                return Ok(());
9350            }
9351            Err(error) => return Err(error),
9352        }
9353        let Some((next_cursor, bootstrap_state)) = sub_end else {
9354            return Ok(());
9355        };
9356        let rollback = self.capture();
9357        let counts = (
9358            report.resets.len(),
9359            report.revoked.len(),
9360            report.failed.len(),
9361        );
9362        self.begin_observation("syncular_sub_end")
9363            .map_err(storage)?;
9364        let finished = self
9365            .finish_section(start, echo, next_cursor, bootstrap_state, seeded, report)
9366            .and_then(|batch| {
9367                self.rebuild_overlay_if_dirty()?;
9368                self.finish_observation("syncular_sub_end", batch)
9369            });
9370        if let Err(message) = finished {
9371            self.rollback_observation("syncular_sub_end");
9372            self.restore(rollback);
9373            report.resets.truncate(counts.0);
9374            report.revoked.truncate(counts.1);
9375            report.failed.truncate(counts.2);
9376            return Err(storage(message));
9377        }
9378        Ok(())
9379    }
9380
9381    /// §5.6: the table, first-page flag and effective scopes of one segment
9382    /// of `unit`'s section.
9383    #[allow(clippy::type_complexity)]
9384    fn segment_pair(
9385        &self,
9386        unit: &UnitRecord,
9387        echo: &[EchoRecord],
9388        seeded: &BTreeSet<String>,
9389        name: &str,
9390    ) -> Result<(TableSchema, bool, Vec<(String, Vec<String>)>), SectionError> {
9391        let table = self.schema.table(name).cloned().ok_or_else(|| {
9392            SectionError::Abort(
9393                "sync.schema_mismatch".to_owned(),
9394                format!("segment table {name:?} is not in the client schema"),
9395            )
9396        })?;
9397        let effective = covers(&table, &unit.scopes)
9398            .then(|| pair_scopes(&unit.scopes, name, Some(echo)))
9399            .flatten()
9400            .ok_or_else(|| {
9401                SectionError::Abort(
9402                    "sync.invalid_request".to_owned(),
9403                    "a segment names no active pair of its unit".to_owned(),
9404                )
9405            })?;
9406        Ok((table, !seeded.contains(name), effective))
9407    }
9408
9409    /// §4.4 `SUB_END` of an active, revoked or reset section, inside the
9410    /// caller's observation: a reset discards cursor, resume token and
9411    /// first-page record and keeps the echo; a revoked pair purges by its last
9412    /// echo (§3.3); otherwise the echo replaces the persisted one, a revoked
9413    /// fenced record that turns active again re-bootstraps the unit, and a
9414    /// bootstrap section persists its pin, resume token and seeded tables.
9415    fn finish_section(
9416        &mut self,
9417        start: &SectionStart,
9418        echo: Vec<EchoRecord>,
9419        next_cursor: i64,
9420        bootstrap_state: Option<String>,
9421        seeded: BTreeSet<String>,
9422        report: &mut SyncReport,
9423    ) -> Result<ChangeAccumulator, String> {
9424        #[cfg(feature = "bench-internals")]
9425        let _phase = self.benchmark_phases.start(Phase::CursorPersist);
9426        let mut batch = ChangeAccumulator::default();
9427        // §4.4: SUB_END writes only into a unit that is still registered.
9428        let Some(unit) = self
9429            .stored(get_unit(&self.conn, &start.id))?
9430            .filter(|unit| unit.status == UnitStatus::Active)
9431        else {
9432            return Ok(batch);
9433        };
9434        for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9435            batch.window(&base_key, &value);
9436        }
9437        if start.status == SubStatus::Reset {
9438            // §4.6: staleness, never a purge; the rows stay until the
9439            // bootstrap replaces them.
9440            report.resets.push(unit.id.clone());
9441            self.stored(save_unit(
9442                &self.conn,
9443                &UnitRecord {
9444                    reason_code: Some(start.reason_code.clone()),
9445                    cursor: Some(-1),
9446                    bootstrap_state: None,
9447                    seeded: Vec::new(),
9448                    ..unit
9449                },
9450            ))?;
9451            return Ok(batch);
9452        }
9453        let revoked = start.status == SubStatus::Revoked;
9454        let mut units = None;
9455        let mut failed = false;
9456        let mut rearmed = false;
9457        for table in self.schema.tables.clone() {
9458            if !covers(&table, &unit.scopes) {
9459                continue;
9460            }
9461            let last = unit
9462                .echo
9463                .as_deref()
9464                .and_then(|last| pair_scopes(&unit.scopes, &table.name, Some(last)));
9465            let next = (!revoked)
9466                .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
9467                .flatten();
9468            // §3.3: a revoked fenced record that turns active again re-bootstraps.
9469            rearmed |= unit.echo.is_some() && last.is_none() && next.is_some();
9470            // §3.3: purge a pair the response revokes, keyed on the echo the
9471            // client persisted while the pair was active.
9472            if let (Some(last), None) = (&last, &next) {
9473                let units = match units {
9474                    Some(ref units) => units,
9475                    None => units.insert(self.stored(load_units(&self.conn))?),
9476                };
9477                let owners = unit_owners(units, &table, &unit.id);
9478                failed |= !self.purge_pair(&mut batch, &table, last, &owners)?;
9479            }
9480        }
9481        if revoked || failed {
9482            if revoked {
9483                report.revoked.push(unit.id.clone());
9484            }
9485            if failed {
9486                report.failed.push(unit.id.clone());
9487            }
9488            batch.status = true;
9489            self.stored(save_unit(
9490                &self.conn,
9491                &UnitRecord {
9492                    status: if failed {
9493                        UnitStatus::Failed
9494                    } else {
9495                        UnitStatus::Revoked
9496                    },
9497                    reason_code: Some(if failed {
9498                        "sync.scope_revoked".to_owned()
9499                    } else {
9500                        start.reason_code.clone()
9501                    }),
9502                    cursor: Some(-1),
9503                    bootstrap_state: None,
9504                    seeded: Vec::new(),
9505                    echo: None,
9506                    ..unit
9507                },
9508            ))?;
9509            return Ok(batch);
9510        }
9511        let completed = start.bootstrap && !rearmed && bootstrap_state.is_none();
9512        let (cursor, bootstrap_state, seeded) = if rearmed {
9513            (Some(-1), None, Vec::new())
9514        } else if start.bootstrap {
9515            let seeded = if bootstrap_state.is_none() {
9516                Vec::new()
9517            } else {
9518                seeded.into_iter().collect()
9519            };
9520            (Some(next_cursor), bootstrap_state, seeded)
9521        } else {
9522            (
9523                unit.cursor,
9524                unit.bootstrap_state.clone(),
9525                unit.seeded.clone(),
9526            )
9527        };
9528        self.stored(save_unit(
9529            &self.conn,
9530            &UnitRecord {
9531                reason_code: None,
9532                echo: Some(echo.clone()),
9533                cursor,
9534                bootstrap_state,
9535                seeded,
9536                ..unit.clone()
9537            },
9538        ))?;
9539        if !completed {
9540            return Ok(batch);
9541        }
9542        // §7.1: a completed bootstrap covers acknowledged intent of its pairs
9543        // at or below its pin.
9544        for table in self.schema.tables.clone() {
9545            let Some(effective) = covers(&table, &unit.scopes)
9546                .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
9547                .flatten()
9548            else {
9549                continue;
9550            };
9551            let mut statement = self
9552                .conn
9553                .prepare("SELECT id,intent_json FROM _syncular_acked_rows WHERE tbl=?1 AND commit_seq<=?2")
9554                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9555            let rows = statement
9556                .query_map(rusqlite::params![table.name, next_cursor], |row| {
9557                    Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
9558                })
9559                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9560            let mut covered = HashSet::new();
9561            for row in rows {
9562                let (id, intent) =
9563                    row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9564                let values: Map<String, Value> =
9565                    serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
9566                if owns_local_row(&table, &effective, &[], &values) {
9567                    covered.insert(id);
9568                }
9569            }
9570            drop(statement);
9571            for id in covered {
9572                self.conn
9573                    .execute(
9574                        "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3",
9575                        rusqlite::params![table.name, id, next_cursor],
9576                    )
9577                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9578                self.overlay_dirty.table(&table.name);
9579                batch.table(&table.name);
9580            }
9581        }
9582        Ok(batch)
9583    }
9584
9585    /// §3.3: purge one revoked pair inside the caller's observation: delete
9586    /// the rows matching its last effective scopes that no owner holds, drop
9587    /// the retained intent and every pending commit that provably writes into
9588    /// them, and delete now-unauthorized blob bodies. `Ok(false)` when the
9589    /// table has no local scope-column mapping (fail closed: nothing deleted).
9590    fn purge_pair(
9591        &mut self,
9592        batch: &mut ChangeAccumulator,
9593        table: &TableSchema,
9594        last: &[(String, Vec<String>)],
9595        owners: &[Vec<(String, Vec<String>)>],
9596    ) -> Result<bool, String> {
9597        if local_scope_predicate(table, last, owners).is_err() {
9598            return Ok(false);
9599        }
9600        for commit in self.drop_failed_commits(|name, values| {
9601            name == table.name && owns_local_row(table, last, owners, values)
9602        })? {
9603            batch.conflicts = true;
9604            batch.rejections = true;
9605            batch.outcomes = true;
9606            for operation in commit.ops {
9607                batch.table(&operation.table);
9608            }
9609        }
9610        if !self.purge_scope_rows(&table.name, last, owners)? {
9611            return Err("storage.failed: the revoked scope purge failed".to_owned());
9612        }
9613        self.record_scope_map(batch, &table.name, last);
9614        if self.drop_doomed_outbox(table, last, owners)? {
9615            batch.status = true;
9616            batch.rejections = true;
9617            batch.outcomes = true;
9618        }
9619        // §5.9.7 B2: revocation deletes now-unauthorized blob bodies.
9620        self.delete_unreferenced_cached_blobs()?;
9621        Ok(true)
9622    }
9623
9624    /// §4.5 client application: apply one live-section or delta `COMMIT`
9625    /// with only the changes that match the persisted echo of a receiving
9626    /// unit; every applied change then goes through the version guard.
9627    /// Returns whether any change of the frame applied.
9628    fn apply_live_commit(
9629        &mut self,
9630        receivers: &[UnitRecord],
9631        tables: &[String],
9632        changes: Vec<ssp2::model::Change>,
9633        commit_seq: i64,
9634        source: AppliedServerCommitSource,
9635    ) -> Result<bool, TransportError> {
9636        let changes: Vec<ssp2::model::Change> = changes
9637            .into_iter()
9638            .filter(|change| {
9639                // An unknown table fails loud in the apply below.
9640                let Some(table) = tables
9641                    .get(change.table_index as usize)
9642                    .and_then(|name| self.schema.table(name))
9643                else {
9644                    return true;
9645                };
9646                receivers.iter().any(|unit| {
9647                    covers(table, &unit.scopes)
9648                        && pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()).is_some_and(
9649                            |scopes| {
9650                                scopes.iter().all(|(variable, values)| {
9651                                    change
9652                                        .scopes
9653                                        .iter()
9654                                        .find(|(key, _)| key == variable)
9655                                        .is_some_and(|(_, value)| values.contains(value))
9656                                })
9657                            },
9658                        )
9659                })
9660            })
9661            .collect();
9662        if changes.is_empty() {
9663            return Ok(false);
9664        }
9665        let affected_tables = changes
9666            .iter()
9667            .filter_map(|change| tables.get(change.table_index as usize))
9668            .cloned()
9669            .collect::<BTreeSet<_>>();
9670        let previous_batches = self.change_queue.len();
9671        self.apply_commit_frame(tables, &changes, commit_seq)?;
9672        if self.change_queue.len() > previous_batches {
9673            if let Some(batch) = self.change_queue.back_mut() {
9674                batch
9675                    .applied_commits
9676                    .extend(
9677                        affected_tables
9678                            .into_iter()
9679                            .map(|table| AppliedServerCommit {
9680                                table,
9681                                commit_seq,
9682                                source,
9683                            }),
9684                    );
9685            }
9686        }
9687        Ok(true)
9688    }
9689
9690    // Both pull and realtime frames use the same durable observation boundary.
9691    fn apply_commit_frame(
9692        &mut self,
9693        tables: &[String],
9694        changes: &[ssp2::model::Change],
9695        sequence: i64,
9696    ) -> Result<(), TransportError> {
9697        #[cfg(feature = "bench-internals")]
9698        let _phase = self.benchmark_phases.start(Phase::CommitApply);
9699        let rollback = self.capture();
9700        self.coalesce_unit(changes.len())
9701            .and_then(|()| self.begin_observation("syncular_commit"))
9702            .map_err(|message| TransportError::new("storage.failed", message))?;
9703        let applied = (|| {
9704            let mut batch = ChangeAccumulator::default();
9705            self.record_commit_changes(&mut batch, tables, changes);
9706            // §7.1 chained base: a change names the version an acknowledged own
9707            // commit wrote; pending upserts chained on it move to that version.
9708            for change in changes {
9709                let Some(table) = tables.get(change.table_index as usize) else {
9710                    continue;
9711                };
9712                let acknowledged = self
9713                    .conn
9714                    .prepare_cached("SELECT op_json FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq=?3")
9715                    .and_then(|mut statement| {
9716                        statement
9717                            .query_map(rusqlite::params![table, change.row_id, sequence], |row| row.get::<_, String>(0))?
9718                            .collect::<Result<Vec<_>, _>>()
9719                    })
9720                    .map_err(|error| TransportError::new("storage.failed", Self::sqlite_failure(&self.storage_failure, error)))?
9721                    .iter()
9722                    .map(|op| serde_json::from_str::<CommitOperation>(op).map(OutboxOp::from))
9723                    .collect::<Result<Vec<_>, _>>()
9724                    .map_err(|_| TransportError::new("storage.failed", "sync.local_corrupt: invalid acknowledged operation".to_owned()))?;
9725                for index in 0..self.outbox.len() {
9726                    if !self.outbox[index]
9727                        .ops
9728                        .iter()
9729                        .any(|op| acknowledged.iter().any(|earlier| chains_on(earlier, op)))
9730                    {
9731                        continue;
9732                    }
9733                    let commit = Arc::make_mut(&mut self.outbox[index]);
9734                    for op in &mut commit.ops {
9735                        if acknowledged.iter().any(|earlier| chains_on(earlier, op)) {
9736                            op.base_version = Some(change.row_version);
9737                        }
9738                    }
9739                    let ops = serde_json::to_string(
9740                        &commit
9741                            .ops
9742                            .iter()
9743                            .map(CommitOperation::from)
9744                            .collect::<Vec<_>>(),
9745                    )
9746                    .map_err(|_| {
9747                        TransportError::new(
9748                            "storage.failed",
9749                            "sync.local_corrupt: unencodable outbox".to_owned(),
9750                        )
9751                    })?;
9752                    let id = commit.client_commit_id.clone();
9753                    self.conn
9754                        .execute(
9755                            "UPDATE _syncular_outbox SET ops_json=?1 WHERE commit_id=?2",
9756                            rusqlite::params![ops, id],
9757                        )
9758                        .map_err(|error| {
9759                            TransportError::new(
9760                                "storage.failed",
9761                                Self::sqlite_failure(&self.storage_failure, error),
9762                            )
9763                        })?;
9764                }
9765            }
9766            {
9767                let storage_failed = |error| {
9768                    TransportError::new(
9769                        "storage.failed",
9770                        Self::sqlite_failure(&self.storage_failure, error),
9771                    )
9772                };
9773                let pinned: HashSet<(&str, &str)> = self
9774                    .outbox
9775                    .iter()
9776                    .flat_map(|commit| &commit.ops)
9777                    .map(|op| (op.table.as_str(), op.row_id.as_str()))
9778                    .collect();
9779                for change in changes {
9780                    let table = tables.get(change.table_index as usize).ok_or_else(|| {
9781                        TransportError::new(
9782                            "sync.invalid_request",
9783                            "change tableIndex out of range".to_owned(),
9784                        )
9785                    })?;
9786                    if pinned.contains(&(table.as_str(), change.row_id.as_str())) {
9787                        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)")
9788                            .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
9789                            .map_err(storage_failed)?;
9790                    }
9791                    self.conn.prepare_cached("DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3")
9792                        .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
9793                        .map_err(storage_failed)?;
9794                }
9795            }
9796            self.apply_commit_changes(tables, changes)?;
9797            self.rebuild_overlay_if_dirty()
9798                .map_err(|message| TransportError::new("storage.failed", message))?;
9799            self.finish_observation("syncular_commit", batch)
9800                .map_err(|message| TransportError::new("storage.failed", message))
9801        })();
9802        if applied.is_err() {
9803            self.rollback_observation("syncular_commit");
9804            self.restore(rollback);
9805        }
9806        applied
9807    }
9808
9809    fn apply_commit_changes(
9810        &mut self,
9811        tables: &[String],
9812        changes: &[ssp2::model::Change],
9813    ) -> Result<(), TransportError> {
9814        // A clean overlay can reconcile changed primary keys independently
9815        // when their tables have no secondary unique constraints. Such a
9816        // constraint can change whether another row's write succeeds, so a
9817        // table with one and any local intent takes the table rebuild.
9818        let changed_tables: BTreeSet<&str> = changes
9819            .iter()
9820            .filter_map(|change| tables.get(change.table_index as usize))
9821            .map(String::as_str)
9822            .collect();
9823        let mut mirror_visible = !self.overlay_dirty.get();
9824        for name in &changed_tables {
9825            if mirror_visible
9826                && self
9827                    .schema
9828                    .table(name)
9829                    .is_some_and(|table| table.indexes.iter().any(|index| index.unique))
9830            {
9831                let (pending, protected) = self
9832                    .table_intent(name)
9833                    .map_err(|message| TransportError::new("storage.failed", message))?;
9834                mirror_visible = !pending && !protected;
9835            }
9836        }
9837        for change in changes {
9838            let table_name = tables.get(change.table_index as usize).ok_or_else(|| {
9839                TransportError::new(
9840                    "sync.invalid_request",
9841                    "change tableIndex out of range".to_owned(),
9842                )
9843            })?;
9844            let table = self.schema.table(table_name).ok_or_else(|| {
9845                TransportError::new(
9846                    "sync.schema_mismatch",
9847                    format!("change targets unknown table {table_name:?}"),
9848                )
9849            })?;
9850            let landed = match change.op {
9851                Op::Upsert => {
9852                    let payload = change.row.as_ref().ok_or_else(|| {
9853                        TransportError::new(
9854                            "sync.invalid_request",
9855                            "upsert change without row payload".to_owned(),
9856                        )
9857                    })?;
9858                    // §5.11: decrypt encrypted columns on apply.
9859                    let row = {
9860                        #[cfg(feature = "bench-internals")]
9861                        let _phase = self.benchmark_phases.start(Phase::RowDecode);
9862                        // §5.11: a decrypt failure keeps its own identity.
9863                        decode_row_bytes(table, payload, &self.encryption)?
9864                    };
9865                    let table_name = table.name.clone();
9866                    // §4.5 version guard: only a newer upsert lands.
9867                    let landed = self
9868                        .write_base_row(&table_name, &row, change.row_version)
9869                        .map_err(|m| TransportError::new("sync.invalid_request", m))?;
9870                    if mirror_visible && landed {
9871                        self.write_row(
9872                            &visible_table(&table_name),
9873                            &table_name,
9874                            &row,
9875                            change.row_version,
9876                        )
9877                        .map_err(|m| TransportError::new("sync.invalid_request", m))?;
9878                    }
9879                    landed
9880                }
9881                // §4.5 version guard: a delete at or below the local version
9882                // is skipped, a delete of an absent row is a no-op.
9883                Op::Delete => self
9884                    .delete_base_row(table_name, &change.row_id, change.row_version)
9885                    .map_err(|m| TransportError::new("sync.invalid_request", m))?,
9886            };
9887            // The change dropped the row's acknowledged intent either way
9888            // (§7.1), so the overlay of a skipped change rebuilds from the
9889            // unchanged base.
9890            self.overlay_dirty.table(table_name);
9891            if mirror_visible && !(landed && change.op == Op::Upsert) {
9892                let predicate = row_id_predicate(table);
9893                let visible = visible_table(table_name);
9894                let mut statements = vec![format!("DELETE FROM {visible} WHERE {predicate}")];
9895                if !landed {
9896                    statements.push(format!(
9897                        "INSERT INTO {visible} SELECT * FROM {} WHERE {predicate}",
9898                        base_table(table_name)
9899                    ));
9900                }
9901                for statement in &statements {
9902                    self.conn
9903                        .prepare_cached(statement)
9904                        .and_then(|mut statement| {
9905                            statement.execute(rusqlite::params![change.row_id])
9906                        })
9907                        .map_err(|error| {
9908                            TransportError::new("sync.invalid_request", error.to_string())
9909                        })?;
9910                }
9911            }
9912        }
9913        if mirror_visible {
9914            let changed_rows: HashSet<(&str, &str)> = changes
9915                .iter()
9916                .map(|change| {
9917                    (
9918                        tables[change.table_index as usize].as_str(),
9919                        change.row_id.as_str(),
9920                    )
9921                })
9922                .collect();
9923            self.replay_overlay(&changed_tables, Some(&changed_rows))
9924                .map_err(|message| TransportError::new("storage.failed", message))?;
9925            self.overlay_dirty.set(false);
9926        }
9927        Ok(())
9928    }
9929
9930    /// §5.6 segment application: validate against the generated schema,
9931    /// clear the pair's scope on the table's first page (fail closed
9932    /// without a mapping), then upsert each row with its segment-carried
9933    /// server version under the §4.5 version guard (§5.2).
9934    fn apply_segment(
9935        &mut self,
9936        table: &TableSchema,
9937        segment: &RowsSegment,
9938        first_page: bool,
9939        effective: &[(String, Vec<String>)],
9940        unit_id: &str,
9941    ) -> Result<u32, SectionError> {
9942        // §5.2: the column table validates against the generated schema —
9943        // order, names, types, nullability; mismatch is fatal. §5.11: the
9944        // server sends the WIRE types (bytes for an encrypted column), so
9945        // validate against wire_columns.
9946        let column = if segment.columns.len() != table.wire_columns.len() {
9947            Some(Value::from("count"))
9948        } else {
9949            segment
9950                .columns
9951                .iter()
9952                .zip(table.wire_columns.iter())
9953                .position(|(a, b)| a.name != b.name || a.ty != b.ty || a.nullable != b.nullable)
9954                .map(Value::from)
9955        };
9956        if segment.table != table.name
9957            || segment.schema_version != self.schema.version
9958            || column.is_some()
9959        {
9960            let mut details = Map::new();
9961            details.insert("table".to_owned(), Value::from(table.name.as_str()));
9962            if let Some(column) = column {
9963                details.insert("column".to_owned(), column);
9964            }
9965            return Err(SectionError::Transport(TransportError {
9966                code: "sync.schema_mismatch".to_owned(),
9967                message: "rows segment columns do not match the generated schema (§5.2)".to_owned(),
9968                details: Some(Value::Object(details)),
9969            }));
9970        }
9971        let mut applied = 0u32;
9972        let empty = Vec::new();
9973        let blocks = if segment.blocks.is_empty() {
9974            std::slice::from_ref(&empty)
9975        } else {
9976            &segment.blocks
9977        };
9978        for (index, block) in blocks.iter().enumerate() {
9979            let clear = first_page && index == 0;
9980            if !clear && block.is_empty() {
9981                continue;
9982            }
9983            let rollback = self.capture();
9984            let (pending, protected) = self
9985                .table_intent(&table.name)
9986                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9987            let reconcile_pending =
9988                !protected && pending && table.indexes.iter().any(|index| index.unique);
9989            let mirror_visible = !protected && !reconcile_pending;
9990            self.coalesce_unit(block.len())
9991                .and_then(|()| self.begin_observation("syncular_segment_block"))
9992                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9993            let outcome = (|| {
9994                self.rebuild_overlay_if_dirty()
9995                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9996                let mut changed_keys = Vec::new();
9997                let mut batch = ChangeAccumulator::default();
9998                if clear && self.clear_scope(table, effective, unit_id)? || !block.is_empty() {
9999                    batch.table(&table.name);
10000                }
10001                for (row_index, row) in block.iter().enumerate() {
10002                    let decrypted;
10003                    let values = if table.has_encrypted_columns() {
10004                        let mut values = row.values.clone();
10005                        crate::values::decrypt_segment_row(table, &mut values, &self.encryption)
10006                            .map_err(SectionError::Transport)?;
10007                        decrypted = values;
10008                        &decrypted
10009                    } else {
10010                        &row.values
10011                    };
10012                    if !self
10013                        .write_base_row(&table.name, values, row.server_version)
10014                        .map_err(|message| {
10015                            SectionError::Abort("sync.invalid_request".into(), message)
10016                        })?
10017                    {
10018                        continue;
10019                    }
10020                    if reconcile_pending {
10021                        changed_keys.push(
10022                            owned_sql_value(RowParam::Cell(&values[table.pk_index])).map_err(
10023                                |message| SectionError::Abort("storage.failed".into(), message),
10024                            )?,
10025                        );
10026                    }
10027                    if mirror_visible {
10028                        self.write_row(
10029                            &visible_table(&table.name),
10030                            &table.name,
10031                            values,
10032                            row.server_version,
10033                        )
10034                        .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10035                    }
10036                    let processed = u64::from(applied) + row_index as u64 + 1;
10037                    if processed.is_multiple_of(1024) {
10038                        self.progress.update(|p| p.rows_processed = processed);
10039                    }
10040                }
10041                self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
10042                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10043                self.finish_observation("syncular_segment_block", batch)
10044                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))
10045            })();
10046            if let Err(error) = outcome {
10047                self.rollback_observation("syncular_segment_block");
10048                self.restore(rollback);
10049                return Err(error);
10050            }
10051            applied += block.len() as u32;
10052            self.progress
10053                .update(|p| p.rows_processed = u64::from(applied));
10054            std::thread::yield_now();
10055        }
10056        self.progress
10057            .update(|p| p.rows_processed = u64::from(applied));
10058        Ok(applied)
10059    }
10060
10061    /// §5.3 sqlite-image application: validate the in-file metadata
10062    /// against the descriptor, validate column names/order against the
10063    /// generated schema, run the §5.6 first-page clear when fresh, then
10064    /// replace-or-upsert every image row with its `_syncular_version`.
10065    /// Mechanics: the image lands in a temp file read through a second
10066    /// rusqlite connection, equivalent to ATTACH + INSERT…SELECT.
10067    /// Each image chunk commits its writes and revision before readers continue.
10068    #[allow(clippy::too_many_arguments)]
10069    fn apply_sqlite_segment(
10070        &mut self,
10071        table: &TableSchema,
10072        bytes: &[u8],
10073        first_page: bool,
10074        effective: &[(String, Vec<String>)],
10075        unit_id: &str,
10076        row_count: i64,
10077        as_of_commit_seq: i64,
10078        scope_digest: &str,
10079    ) -> Result<u32, SectionError> {
10080        let invalid = |detail: &str| {
10081            SectionError::Abort(
10082                "sync.invalid_request".to_owned(),
10083                format!("sqlite segment rejected: {detail} (§5.3)"),
10084            )
10085        };
10086        // §5.11: an image bypasses the decrypt seam, so a server cannot serve
10087        // one for a table with encrypted columns.
10088        if table.has_encrypted_columns() {
10089            return Err(invalid("table has encrypted columns"));
10090        }
10091
10092        // The image lands beside the replica so it shares the replica's
10093        // directory permissions and volume; an in-memory replica has no
10094        // directory and uses the system temp dir. The file is owner-only.
10095        let directory = self
10096            .previous_version_replica_path()
10097            .and_then(|replica| std::path::Path::new(&replica).parent().map(Into::into))
10098            .unwrap_or_else(std::env::temp_dir);
10099        let path = directory.join(format!(".syncular-image-{}.tmp", uuid::Uuid::new_v4()));
10100        let outcome = (|| {
10101            let mut options = std::fs::OpenOptions::new();
10102            options.write(true).create_new(true);
10103            #[cfg(unix)]
10104            std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);
10105            std::io::Write::write_all(
10106                &mut options
10107                    .open(&path)
10108                    .map_err(|_| invalid("image temp file write failed"))?,
10109                bytes,
10110            )
10111            .map_err(|_| invalid("image temp file write failed"))?;
10112            let img = rusqlite::Connection::open_with_flags(
10113                &path,
10114                rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
10115            )
10116            .map_err(|_| invalid("bytes do not open as a SQLite database"))?;
10117            self.apply_sqlite_image(
10118                &img,
10119                table,
10120                first_page,
10121                effective,
10122                unit_id,
10123                row_count,
10124                as_of_commit_seq,
10125                scope_digest,
10126            )
10127        })();
10128        let _ = std::fs::remove_file(&path);
10129        outcome
10130    }
10131
10132    #[allow(clippy::too_many_arguments)]
10133    fn apply_sqlite_image(
10134        &mut self,
10135        img: &rusqlite::Connection,
10136        table: &crate::schema::TableSchema,
10137        first_fresh_page: bool,
10138        effective: &[(String, Vec<String>)],
10139        unit_id: &str,
10140        row_count: i64,
10141        as_of_commit_seq: i64,
10142        scope_digest: &str,
10143    ) -> Result<u32, SectionError> {
10144        let invalid = |detail: String| {
10145            SectionError::Abort(
10146                "sync.invalid_request".to_owned(),
10147                format!("sqlite segment rejected: {detail} (§5.3)"),
10148            )
10149        };
10150
10151        // 1. Metadata vs descriptor + client state (§5.3 rule 2; exactly
10152        //    one row).
10153        type MetaRow = (i64, String, i64, i64, String, i64, i64);
10154        let meta: MetaRow = img
10155            .query_row(
10156                "SELECT format, \"table\", \"schemaVersion\", \"asOfCommitSeq\",
10157                        \"scopeDigest\", \"rowCount\",
10158                        (SELECT count(*) FROM _syncular_segment)
10159                 FROM _syncular_segment",
10160                [],
10161                |row| {
10162                    Ok((
10163                        row.get(0)?,
10164                        row.get(1)?,
10165                        row.get(2)?,
10166                        row.get(3)?,
10167                        row.get(4)?,
10168                        row.get(5)?,
10169                        row.get(6)?,
10170                    ))
10171                },
10172            )
10173            .map_err(|_| invalid("missing or unreadable _syncular_segment metadata".to_owned()))?;
10174        let (format, meta_table, schema_version, pin, digest, meta_rows, meta_count) = meta;
10175        if meta_count != 1 {
10176            return Err(invalid(format!(
10177                "_syncular_segment must contain exactly one row, found {meta_count}"
10178            )));
10179        }
10180        if format != 1 {
10181            return Err(invalid(format!("format {format}")));
10182        }
10183        if meta_table != table.name {
10184            return Err(invalid(format!("image table {meta_table:?}")));
10185        }
10186        if schema_version != i64::from(self.schema.version) {
10187            return Err(invalid(format!("schemaVersion {schema_version}")));
10188        }
10189        if pin != as_of_commit_seq {
10190            return Err(invalid(format!("asOfCommitSeq {pin}")));
10191        }
10192        if digest != scope_digest {
10193            return Err(invalid("scopeDigest mismatch".to_owned()));
10194        }
10195        if meta_rows != row_count {
10196            return Err(invalid(format!("rowCount {meta_rows}")));
10197        }
10198
10199        // 2. Column names and order vs the generated schema (§5.3 rule 3).
10200        let mut names: Vec<String> = Vec::new();
10201        let mut primary_keys: Vec<String> = Vec::new();
10202        {
10203            let mut stmt = img
10204                .prepare(&format!("PRAGMA table_info({})", quote_ident(&table.name)))
10205                .map_err(|_| invalid("image data table missing".to_owned()))?;
10206            let mut rows = stmt
10207                .query([])
10208                .map_err(|_| invalid("image data table unreadable".to_owned()))?;
10209            while let Some(row) = rows
10210                .next()
10211                .map_err(|_| invalid("image data table unreadable".to_owned()))?
10212            {
10213                if row
10214                    .get::<_, i64>(5)
10215                    .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?
10216                    > 0
10217                {
10218                    primary_keys.push(row.get(1).map_err(|error| {
10219                        invalid(Self::sqlite_failure(&self.storage_failure, error))
10220                    })?);
10221                }
10222                names.push(
10223                    row.get::<_, String>(1)
10224                        .map_err(|_| invalid("image data table unreadable".to_owned()))?,
10225                );
10226            }
10227        }
10228        let mut expected: Vec<&str> = table.columns.iter().map(|c| c.name.as_str()).collect();
10229        expected.push("_syncular_version");
10230        if names.len() != expected.len() || names.iter().zip(expected.iter()).any(|(a, b)| a != b) {
10231            return Err(SectionError::Transport(TransportError {
10232                code: "sync.schema_mismatch".to_owned(),
10233                message: "sqlite segment columns do not match the generated schema (§5.3)"
10234                    .to_owned(),
10235                details: Some(serde_json::json!({ "table": table.name })),
10236            }));
10237        }
10238
10239        if primary_keys != vec![table.primary_key.clone()] {
10240            return Err(invalid(
10241                "image primary key does not match generated schema".into(),
10242            ));
10243        }
10244        let actual_count: i64 = img
10245            .query_row(
10246                &format!("SELECT count(*) FROM {}", quote_ident(&table.name)),
10247                [],
10248                |row| row.get(0),
10249            )
10250            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10251        if actual_count != row_count {
10252            return Err(invalid("image row count does not match descriptor".into()));
10253        }
10254        let insert = self.insert_row_sql(&base_table(&table.name), table);
10255        let visible_insert = self.insert_row_sql(&visible_table(&table.name), table);
10256        let column_list = names
10257            .iter()
10258            .map(|n| quote_ident(n))
10259            .collect::<Vec<_>>()
10260            .join(", ");
10261        let mut stmt = img
10262            .prepare(&format!(
10263                "SELECT {column_list} FROM {} ORDER BY {}",
10264                quote_ident(&table.name),
10265                quote_ident(&table.primary_key)
10266            ))
10267            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10268        let mut rows = stmt
10269            .query([])
10270            .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10271        let mut applied = 0u32;
10272        let mut limit = 1024u32;
10273        let (mut write, mut commit) = (std::time::Duration::ZERO, std::time::Duration::ZERO);
10274        loop {
10275            let clear = applied == 0 && first_fresh_page;
10276            let rollback = self.capture();
10277            let (pending, protected) = self
10278                .table_intent(&table.name)
10279                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10280            let reconcile_pending =
10281                !protected && pending && table.indexes.iter().any(|index| index.unique);
10282            let mirror_visible = !protected && !reconcile_pending;
10283            // §5.3: a chunk holds 1,024 rows at first and doubles after each
10284            // commit up to 65,536; a chunk that replays local writes holds 1,024.
10285            let chunk = if pending || protected { 1024 } else { limit };
10286            self.coalesce_unit(chunk as usize)
10287                .and_then(|()| self.begin_observation("syncular_image_chunk"))
10288                .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10289            let started = std::time::Instant::now();
10290            let result = (|| {
10291                self.rebuild_overlay_if_dirty()
10292                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10293                let mut changed_keys = Vec::new();
10294                let mut batch = ChangeAccumulator::default();
10295                if clear && self.clear_scope(table, effective, unit_id)? {
10296                    batch.table(&table.name);
10297                }
10298                let mut processed = 0u32;
10299                {
10300                    let mut ins = self.conn.prepare_cached(&insert).map_err(|error| {
10301                        invalid(Self::sqlite_failure(&self.storage_failure, error))
10302                    })?;
10303                    let mut mirror = if mirror_visible {
10304                        Some(self.conn.prepare_cached(&visible_insert).map_err(|error| {
10305                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10306                        })?)
10307                    } else {
10308                        None
10309                    };
10310                    for _ in 0..chunk {
10311                        let Some(row) = rows.next().map_err(|error| {
10312                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10313                        })?
10314                        else {
10315                            break;
10316                        };
10317                        for (i, column) in table.columns.iter().enumerate() {
10318                            let cell = row.get_ref(i).map_err(|error| {
10319                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10320                            })?;
10321                            let param = image_cell_param(column, cell).map_err(invalid)?;
10322                            ins.raw_bind_parameter(i + 1, &param).map_err(|error| {
10323                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10324                            })?;
10325                            if let Some(mirror) = &mut mirror {
10326                                mirror.raw_bind_parameter(i + 1, &param).map_err(|error| {
10327                                    invalid(Self::sqlite_failure(&self.storage_failure, error))
10328                                })?;
10329                            }
10330                        }
10331                        let version_index = table.columns.len();
10332                        let version: i64 = row.get(version_index).map_err(|error| {
10333                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10334                        })?;
10335                        if version < 1 {
10336                            return Err(invalid("image row version must be positive".into()));
10337                        }
10338                        ins.raw_bind_parameter(version_index + 1, version)
10339                            .map_err(|error| {
10340                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10341                            })?;
10342                        // §4.5 version guard: the base upsert decides.
10343                        let landed = ins.raw_execute().map_err(|error| {
10344                            invalid(Self::sqlite_failure(&self.storage_failure, error))
10345                        })? > 0;
10346                        processed += 1;
10347                        if processed.is_multiple_of(1024) && processed < chunk {
10348                            self.progress
10349                                .update(|p| p.rows_processed = u64::from(applied + processed));
10350                        }
10351                        if !landed {
10352                            continue;
10353                        }
10354                        if let Some(mirror) = &mut mirror {
10355                            mirror
10356                                .raw_bind_parameter(version_index + 1, version)
10357                                .map_err(|error| {
10358                                    invalid(Self::sqlite_failure(&self.storage_failure, error))
10359                                })?;
10360                            mirror.raw_execute().map_err(|error| {
10361                                invalid(Self::sqlite_failure(&self.storage_failure, error))
10362                            })?;
10363                        }
10364                        if reconcile_pending {
10365                            changed_keys.push(row.get::<_, SqlValue>(table.pk_index).map_err(
10366                                |error| invalid(Self::sqlite_failure(&self.storage_failure, error)),
10367                            )?);
10368                        }
10369                    }
10370                }
10371                if processed > 0 {
10372                    batch.table(&table.name);
10373                    self.overlay_dirty.table(&table.name);
10374                }
10375                self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
10376                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10377                let written = std::time::Instant::now();
10378                self.finish_observation("syncular_image_chunk", batch)
10379                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10380                Ok((processed, written))
10381            })();
10382            let (processed, written) = match result {
10383                Ok(done) => done,
10384                Err(error) => {
10385                    self.rollback_observation("syncular_image_chunk");
10386                    self.restore(rollback);
10387                    return Err(error);
10388                }
10389            };
10390            // The chunk commits before the yield, also inside a coalesced apply.
10391            let coalesced = self.coalesced.is_some();
10392            if coalesced {
10393                self.commit_coalesced_apply()
10394                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10395            }
10396            write += written - started;
10397            commit += written.elapsed();
10398            applied += processed;
10399            let last = processed < chunk || i64::from(applied) == actual_count;
10400            // A file replica's WAL keeps its high-water size until truncated.
10401            if last && self.conn.is_autocommit() {
10402                self.conn
10403                    .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
10404                    .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10405            }
10406            if coalesced {
10407                self.begin_coalesced_apply()
10408                    .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10409            }
10410            self.progress.update(|p| {
10411                p.rows_processed = u64::from(applied);
10412                p.import_write_ms = u64::try_from(write.as_millis()).ok();
10413                p.import_commit_ms = u64::try_from(commit.as_millis()).ok();
10414            });
10415            std::thread::yield_now();
10416            if last {
10417                break;
10418            }
10419            limit = (limit * 2).min(65_536);
10420        }
10421        if i64::from(applied) != actual_count {
10422            return Err(invalid(format!(
10423                "image yielded {applied} rows, expected {actual_count}"
10424            )));
10425        }
10426        Ok(applied)
10427    }
10428
10429    /// §7.1 keyed reconciliation of the rows `drained` commits touch: restore
10430    /// them from the base and replay their remaining intent. A table with a
10431    /// secondary unique index restores and replays every row with intent,
10432    /// since one row's value can admit or defer another row's write.
10433    fn reconcile_rows(&self, drained: &[Arc<OutboxCommit>]) -> Result<(), String> {
10434        let names: BTreeSet<&str> = drained
10435            .iter()
10436            .flat_map(|commit| &commit.ops)
10437            .map(|op| op.table.as_str())
10438            .collect();
10439        for name in names {
10440            let Some(table) = self.schema.table(name) else {
10441                continue;
10442            };
10443            let ops = drained.iter().flat_map(|commit| &commit.ops);
10444            let tables = BTreeSet::from([name]);
10445            let rows: HashSet<_> = ops
10446                .clone()
10447                .map(|op| (op.table.as_str(), op.row_id.as_str()))
10448                .collect();
10449            let unique = table.indexes.iter().any(|index| index.unique);
10450            let acknowledged = if unique {
10451                self.acknowledged_operations(None, Some(&tables))?
10452            } else {
10453                Vec::new()
10454            };
10455            let peers = acknowledged
10456                .iter()
10457                .chain(
10458                    self.failed_commits
10459                        .iter()
10460                        .flat_map(|(commit, _)| &commit.ops),
10461                )
10462                .chain(self.outbox.iter().flat_map(|commit| &commit.ops))
10463                .filter(|_| unique);
10464            self.restore_base_rows(table, &mut Vec::new(), peers.chain(ops.clone()))?;
10465            self.replay_overlay(&tables, (!unique).then_some(&rows))?;
10466        }
10467        Ok(())
10468    }
10469
10470    /// Whether `table` has pending outbox intent, and whether it has protected
10471    /// (acknowledged or retained failed) intent.
10472    fn table_intent(&self, table: &str) -> Result<(bool, bool), String> {
10473        let touches = |op: &OutboxOp| op.table == table;
10474        Ok((
10475            self.outbox
10476                .iter()
10477                .flat_map(|commit| &commit.ops)
10478                .any(touches),
10479            self.failed_commits
10480                .iter()
10481                .flat_map(|(commit, _)| &commit.ops)
10482                .any(touches)
10483                || self
10484                    .conn
10485                    .query_row(
10486                        "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows WHERE tbl=?1)",
10487                        [table],
10488                        |row| row.get(0),
10489                    )
10490                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10491        ))
10492    }
10493
10494    /// §7.1 reconciliation after an import block or chunk. Keyed replay covers
10495    /// only pending intent, so a table with protected intent rebuilds; a
10496    /// `restore` restores the imported `keys` and every pending row first.
10497    fn reconcile_import(
10498        &mut self,
10499        table: &TableSchema,
10500        keys: &mut Vec<SqlValue>,
10501        protected: bool,
10502        restore: bool,
10503    ) -> Result<(), String> {
10504        if protected {
10505            return self.rebuild_overlay_if_dirty();
10506        }
10507        let pending = self.outbox.iter().flat_map(|commit| &commit.ops);
10508        if restore {
10509            self.restore_base_rows(table, keys, pending.clone())?;
10510        }
10511        self.apply_outbox_ops(pending.filter(|op| op.table == table.name))?;
10512        self.overlay_dirty.set(false);
10513        Ok(())
10514    }
10515
10516    /// Restore the visible rows of `keys` and of the rows `ops` touch in
10517    /// `table` from the base before the caller replays their intent. The
10518    /// caller owns the transaction and publishes its revision after replay.
10519    fn restore_base_rows<'a>(
10520        &self,
10521        table: &TableSchema,
10522        keys: &mut Vec<SqlValue>,
10523        ops: impl IntoIterator<Item = &'a OutboxOp>,
10524    ) -> Result<(), String> {
10525        let visible = visible_table(&table.name);
10526        let base = base_table(&table.name);
10527        let pk = quote_ident(&table.primary_key);
10528        let predicate = row_id_predicate(table);
10529        let mut lookup = self.conn.prepare_cached(&format!(
10530            "SELECT {pk} FROM {base} WHERE {predicate} UNION SELECT {pk} FROM {visible} WHERE {predicate}"
10531        )).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10532        let mut deleted = HashSet::new();
10533        for op in ops.into_iter().filter(|op| op.table == table.name) {
10534            if op.upsert {
10535                if let Some(values) = &op.values {
10536                    let key = json_to_column_value(
10537                        &table.columns[table.pk_index],
10538                        values.get(&table.primary_key),
10539                    )?;
10540                    keys.push(owned_sql_value(RowParam::Cell(&key))?);
10541                }
10542            } else if deleted.insert(&op.row_id) {
10543                keys.extend(
10544                    lookup
10545                        .query_map([&op.row_id], |row| row.get::<_, SqlValue>(0))
10546                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
10547                        .collect::<Result<Vec<_>, _>>()
10548                        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10549                );
10550            }
10551        }
10552        // Delete the complete affected set before restoring any base value, so
10553        // old optimistic unique values cannot collide with the new server rows.
10554        for chunk in keys.chunks(400) {
10555            let holes = vec!["?"; chunk.len()].join(",");
10556            self.conn
10557                .prepare_cached(&format!("DELETE FROM {visible} WHERE {pk} IN ({holes})"))
10558                .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
10559                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10560        }
10561        let updates = table
10562            .columns
10563            .iter()
10564            .map(|column| column.name.as_str())
10565            .chain(std::iter::once("_syncular_version"))
10566            .filter(|name| *name != table.primary_key)
10567            .map(|name| {
10568                let name = quote_ident(name);
10569                format!("{name}=excluded.{name}")
10570            })
10571            .collect::<Vec<_>>()
10572            .join(",");
10573        for chunk in keys.chunks(400) {
10574            let holes = vec!["?"; chunk.len()].join(",");
10575            self.conn.prepare_cached(&format!("INSERT INTO {visible} SELECT * FROM {base} WHERE {pk} IN ({holes}) ON CONFLICT ({pk}) DO UPDATE SET {updates}"))
10576                .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
10577                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10578        }
10579        Ok(())
10580    }
10581
10582    // -- application-authorized local purge ---------------------------------------
10583
10584    fn compile_local_data_purge(
10585        &self,
10586        input: &LocalDataPurgeInput,
10587    ) -> Result<(Vec<CompiledLocalDataPurgeTarget>, String), String> {
10588        let invalid = |message: String| format!("sync.invalid_request: {message}");
10589        if input.purge_id.is_empty()
10590            || input.purge_id.len() > 128
10591            || !is_local_operation_code_like(&input.purge_id)
10592        {
10593            return Err(invalid(
10594                "local purge purgeId must be a 1–128 character code-like identifier".to_owned(),
10595            ));
10596        }
10597        if input.targets.is_empty() || input.targets.len() > MAX_LOCAL_PURGE_TARGETS {
10598            return Err(invalid(format!(
10599                "local purge needs between 1 and {MAX_LOCAL_PURGE_TARGETS} targets"
10600            )));
10601        }
10602
10603        let mut deduplicated: BTreeMap<
10604            String,
10605            (CompiledLocalDataPurgeTarget, LocalDataPurgeTarget),
10606        > = BTreeMap::new();
10607        for target in &input.targets {
10608            let table = self.schema.table(&target.table).ok_or_else(|| {
10609                invalid(format!(
10610                    "local purge names unknown table {:?}",
10611                    target.table
10612                ))
10613            })?;
10614            if target.selectors.is_empty() || target.selectors.len() > MAX_LOCAL_PURGE_SELECTORS {
10615                return Err(invalid(format!(
10616                    "local purge target {:?} needs between 1 and {MAX_LOCAL_PURGE_SELECTORS} selectors",
10617                    target.table
10618                )));
10619            }
10620            let mut selectors = Vec::with_capacity(target.selectors.len());
10621            let mut canonical_selectors = BTreeMap::new();
10622            for (column_name, raw_values) in &target.selectors {
10623                let Some((column_index, column)) = table
10624                    .columns
10625                    .iter()
10626                    .enumerate()
10627                    .find(|(_, column)| column.name == *column_name)
10628                else {
10629                    return Err(invalid(format!(
10630                        "local purge target {:?} names unknown column {:?}",
10631                        target.table, column_name
10632                    )));
10633                };
10634                let encrypted = table
10635                    .encrypted_columns
10636                    .iter()
10637                    .any(|candidate| candidate.index == column_index);
10638                if column.ty != ColumnType::String || encrypted {
10639                    return Err(invalid(format!(
10640                        "local purge selector {:?}.{:?} must be a plaintext string column",
10641                        target.table, column_name
10642                    )));
10643                }
10644                if raw_values.is_empty() || raw_values.len() > MAX_LOCAL_PURGE_VALUES {
10645                    return Err(invalid(format!(
10646                        "local purge selector {:?}.{:?} needs between 1 and {MAX_LOCAL_PURGE_VALUES} values",
10647                        target.table, column_name
10648                    )));
10649                }
10650                let mut values = raw_values.clone();
10651                values.sort();
10652                values.dedup();
10653                if values.iter().any(|value| {
10654                    value.is_empty()
10655                        || value.len() > MAX_LOCAL_PURGE_VALUE_LENGTH
10656                        || !is_local_operation_code_like(value)
10657                }) {
10658                    return Err(invalid(format!(
10659                        "local purge selector values must be 1–{MAX_LOCAL_PURGE_VALUE_LENGTH} character code-like identifiers"
10660                    )));
10661                }
10662                selectors.push((column_name.clone(), values.clone()));
10663                canonical_selectors.insert(column_name.clone(), values);
10664            }
10665            let canonical = LocalDataPurgeTarget {
10666                table: target.table.clone(),
10667                selectors: canonical_selectors,
10668            };
10669            let key = serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
10670            deduplicated.insert(
10671                key,
10672                (
10673                    CompiledLocalDataPurgeTarget {
10674                        table: target.table.clone(),
10675                        selectors,
10676                    },
10677                    canonical,
10678                ),
10679            );
10680        }
10681        let targets = deduplicated
10682            .values()
10683            .map(|(compiled, _)| compiled.clone())
10684            .collect::<Vec<_>>();
10685        let canonical = deduplicated
10686            .values()
10687            .map(|(_, target)| target.clone())
10688            .collect::<Vec<_>>();
10689        let canonical_plan =
10690            serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
10691        Ok((targets, canonical_plan))
10692    }
10693
10694    fn local_purge_base_row_ids(
10695        &self,
10696        targets: &[CompiledLocalDataPurgeTarget],
10697    ) -> Result<BTreeMap<String, BTreeSet<String>>, String> {
10698        let mut by_table: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
10699        for target in targets {
10700            let table = self
10701                .schema
10702                .table(&target.table)
10703                .ok_or_else(|| format!("sync.invalid_request: unknown table {:?}", target.table))?;
10704            let mut clauses = Vec::with_capacity(target.selectors.len());
10705            let mut params = Vec::new();
10706            for (column, values) in &target.selectors {
10707                clauses.push(format!(
10708                    "{} IN ({})",
10709                    quote_ident(column),
10710                    values.iter().map(|_| "?").collect::<Vec<_>>().join(", ")
10711                ));
10712                params.extend(values.iter().cloned().map(SqlValue::Text));
10713            }
10714            let sql = format!(
10715                "SELECT CAST({} AS TEXT) FROM {} WHERE {}",
10716                quote_ident(&table.primary_key),
10717                base_table(&target.table),
10718                clauses.join(" AND ")
10719            );
10720            let mut statement = self
10721                .conn
10722                .prepare(&sql)
10723                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10724            let rows = statement
10725                .query_map(rusqlite::params_from_iter(params), |row| {
10726                    let value = sql_ref_to_json(&table.columns[table.pk_index], row.get_ref(0)?);
10727                    render_row_id_json(Some(&value))
10728                        .map_err(|message| rusqlite::Error::ToSqlConversionFailure(message.into()))
10729                })
10730                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10731            let ids = by_table.entry(target.table.clone()).or_default();
10732            for row in rows {
10733                ids.insert(
10734                    row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10735                );
10736            }
10737        }
10738        Ok(by_table)
10739    }
10740
10741    fn local_purge_values_match(
10742        target: &CompiledLocalDataPurgeTarget,
10743        values: &Map<String, Value>,
10744    ) -> bool {
10745        target.selectors.iter().all(|(column, allowed)| {
10746            values
10747                .get(column)
10748                .and_then(Value::as_str)
10749                .is_some_and(|value| allowed.iter().any(|candidate| candidate == value))
10750        })
10751    }
10752
10753    /// Apply one host-authorized local security purge. The host MUST gate the
10754    /// corresponding subscriptions first; this primitive owns local SQLite
10755    /// cleanup and never grants/revokes server authority by itself.
10756    pub fn purge_local_data(
10757        &mut self,
10758        input: &LocalDataPurgeInput,
10759    ) -> Result<LocalDataPurgeResult, String> {
10760        let (targets, canonical_plan) = self.compile_local_data_purge(input)?;
10761        let meta_key = format!("localPurge:{}", input.purge_id);
10762        let applied_plan = self
10763            .conn
10764            .query_row(
10765                "SELECT value FROM _syncular_meta WHERE key = ?1",
10766                rusqlite::params![meta_key],
10767                |row| row.get::<_, String>(0),
10768            )
10769            .optional()
10770            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10771        if let Some(applied_plan) = applied_plan {
10772            if applied_plan != canonical_plan {
10773                return Err(format!(
10774                    "sync.invalid_request: local purge id {:?} was already used with a different plan",
10775                    input.purge_id
10776                ));
10777            }
10778            // A retry after a failed rewrite finishes it.
10779            self.erase_purged_pages()?;
10780            return Ok(LocalDataPurgeResult {
10781                already_applied: true,
10782                purged_rows: 0,
10783                dropped_commits: 0,
10784            });
10785        }
10786
10787        // RFC 0005 D7: the container file cannot be a purge target (its name is
10788        // not in the running schema), so purge drops it as a fixed step, before
10789        // any mirror row is touched and unconditionally.
10790        let _ = self.drop_previous_version();
10791
10792        let rollback = self.capture();
10793        self.begin_observation("syncular_local_purge")?;
10794        let applied = (|| -> Result<(ChangeAccumulator, LocalDataPurgeResult), String> {
10795            let row_ids = self.local_purge_base_row_ids(&targets)?;
10796            let retained_dropped = self.drop_failed_commits(|table, values| {
10797                targets.iter().any(|target| {
10798                    target.table == table && Self::local_purge_values_match(target, values)
10799                })
10800            })?;
10801            let doomed = self
10802                .outbox
10803                .iter()
10804                .filter(|commit| {
10805                    commit.ops.iter().any(|operation| {
10806                        let matching_targets = targets
10807                            .iter()
10808                            .filter(|target| target.table == operation.table)
10809                            .collect::<Vec<_>>();
10810                        if matching_targets.is_empty() {
10811                            return false;
10812                        }
10813                        if row_ids
10814                            .get(&operation.table)
10815                            .is_some_and(|ids| ids.contains(&operation.row_id))
10816                        {
10817                            return true;
10818                        }
10819                        operation.values.as_ref().is_some_and(|values| {
10820                            matching_targets
10821                                .iter()
10822                                .any(|target| Self::local_purge_values_match(target, values))
10823                        })
10824                    })
10825                })
10826                .cloned()
10827                .collect::<Vec<_>>();
10828            let doomed_ids = doomed
10829                .iter()
10830                .map(|commit| commit.client_commit_id.clone())
10831                .collect::<BTreeSet<_>>();
10832            let mut batch = ChangeAccumulator::default();
10833            for commit in &retained_dropped {
10834                batch.conflicts = true;
10835                batch.rejections = true;
10836                batch.outcomes = true;
10837                for operation in &commit.ops {
10838                    batch.table(&operation.table);
10839                }
10840            }
10841            let mut rejections = Vec::new();
10842            // §5.11 purge erasure: the journal keeps a dropped commit's identity and
10843            // codes, never its operations, so no purged value survives in it.
10844            for commit in &doomed {
10845                for operation in &commit.ops {
10846                    batch.table(&operation.table);
10847                    self.overlay_dirty.table(&operation.table);
10848                }
10849                let results = (0..commit.ops.len())
10850                    .map(|op_index| {
10851                        let rejection = RejectionRecord {
10852                            client_commit_id: commit.client_commit_id.clone(),
10853                            op_index: op_index as i32,
10854                            code: "client.local_data_purged".to_owned(),
10855                            message: "the commit was dropped by an application-authorized local data purge".to_owned(),
10856                            retryable: false,
10857                            details: None,
10858                            operation: None,
10859                        };
10860                        rejections.push(rejection.clone());
10861                        CommitOperationOutcome::Error { rejection }
10862                    })
10863                    .collect::<Vec<_>>();
10864                self.persist_commit_outcome(
10865                    &commit.client_commit_id,
10866                    CommitOutcomeStatus::Rejected,
10867                    &results,
10868                    None,
10869                )?;
10870                self.delete_outbox_persisted(&commit.client_commit_id)?;
10871            }
10872            if !doomed.is_empty() {
10873                self.outbox
10874                    .retain(|commit| !doomed_ids.contains(&commit.client_commit_id));
10875                self.rejections.extend(rejections);
10876                self.prune_commit_outcomes()?;
10877                batch.status = true;
10878                batch.rejections = true;
10879                batch.outcomes = true;
10880            }
10881
10882            let mut purged_rows = 0usize;
10883            for (table, ids) in &row_ids {
10884                if ids.is_empty() {
10885                    continue;
10886                }
10887                batch.table(table);
10888                self.overlay_dirty.table(table);
10889                for row_id in ids {
10890                    self.delete_base_row(table, row_id, i64::MAX)?;
10891                    purged_rows += 1;
10892                }
10893            }
10894            // §5.11 purge erasure: a journaled outcome with an operation or
10895            // conflict row the purge reaches keeps its identity, status, ids
10896            // and codes only.
10897            let touches = |table: &str, row_id: &str, values: Option<&Map<String, Value>>| {
10898                targets.iter().any(|target| {
10899                    target.table == table
10900                        && (row_ids.get(table).is_some_and(|ids| ids.contains(row_id))
10901                            || values.is_some_and(|values| {
10902                                Self::local_purge_values_match(target, values)
10903                            }))
10904                })
10905            };
10906            let entries = self
10907                .conn
10908                .prepare("SELECT client_commit_id, results_json, operations_json FROM _syncular_commit_outcomes")
10909                .and_then(|mut statement| {
10910                    statement
10911                        .query_map([], |row| {
10912                            Ok((
10913                                row.get::<_, String>(0)?,
10914                                row.get::<_, String>(1)?,
10915                                row.get::<_, Option<String>>(2)?,
10916                            ))
10917                        })?
10918                        .collect::<Result<Vec<_>, _>>()
10919                })
10920                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10921            for (client_commit_id, results_json, operations_json) in entries {
10922                let corrupt = |_| "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
10923                let mut results: Vec<CommitOperationOutcome> =
10924                    serde_json::from_str(&results_json).map_err(corrupt)?;
10925                let operations: Vec<CommitOperation> = operations_json
10926                    .map(|json| serde_json::from_str(&json))
10927                    .transpose()
10928                    .map_err(corrupt)?
10929                    .unwrap_or_default();
10930                let named = operations
10931                    .iter()
10932                    .chain(results.iter().filter_map(|result| match result {
10933                        CommitOperationOutcome::Conflict { conflict } => conflict.operation.as_ref(),
10934                        CommitOperationOutcome::Error { rejection } => rejection.operation.as_ref(),
10935                        CommitOperationOutcome::Applied { .. } => None,
10936                    }))
10937                    .any(|operation| touches(&operation.table, &operation.row_id, operation.values.as_ref()))
10938                    || results.iter().any(|result| {
10939                        matches!(result, CommitOperationOutcome::Conflict { conflict }
10940                            if touches(&conflict.table, &conflict.row_id, Some(&conflict.server_row)))
10941                    });
10942                if !named {
10943                    continue;
10944                }
10945                for result in &mut results {
10946                    match result {
10947                        CommitOperationOutcome::Conflict { conflict } => {
10948                            conflict.server_row = Map::new();
10949                            conflict.conflict_columns.clear();
10950                            conflict.operation = None;
10951                        }
10952                        CommitOperationOutcome::Error { rejection } => {
10953                            rejection.details = None;
10954                            rejection.operation = None;
10955                        }
10956                        CommitOperationOutcome::Applied { .. } => {}
10957                    }
10958                }
10959                let results_json = serde_json::to_string(&results).map_err(|error| error.to_string())?;
10960                self.conn
10961                    .execute(
10962                        "UPDATE _syncular_commit_outcomes SET results_json = ?1, operations_json = NULL WHERE client_commit_id = ?2",
10963                        rusqlite::params![results_json, client_commit_id],
10964                    )
10965                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10966                batch.outcomes = true;
10967            }
10968            self.rebuild_overlay_if_dirty()?;
10969            self.delete_unreferenced_cached_blobs()?;
10970            self.conn
10971                .execute(
10972                    "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
10973                    rusqlite::params![meta_key, canonical_plan],
10974                )
10975                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10976            Ok((
10977                batch,
10978                LocalDataPurgeResult {
10979                    already_applied: false,
10980                    purged_rows,
10981                    dropped_commits: doomed.len(),
10982                },
10983            ))
10984        })()
10985        .and_then(|(batch, result)| {
10986            self.finish_observation("syncular_local_purge", batch)
10987                .map(|()| result)
10988        });
10989        let result = match applied {
10990            Ok(result) => result,
10991            Err(error) => {
10992                self.rollback_observation("syncular_local_purge");
10993                self.restore(rollback);
10994                return Err(error);
10995            }
10996        };
10997        self.cancel_sync_round();
10998        self.erase_purged_pages()?;
10999        Ok(result)
11000    }
11001
11002    /// §5.11 purge erasure: SQLite leaves a deleted value in the freed pages of the
11003    /// database file, and the WAL keeps the frames written before the purge,
11004    /// until either is rewritten. VACUUM rebuilds the file from the remaining
11005    /// rows, and the checkpoint truncates the WAL.
11006    fn erase_purged_pages(&self) -> Result<(), String> {
11007        let erased = self
11008            .conn
11009            .execute_batch("PRAGMA secure_delete = ON; VACUUM;")
11010            .and_then(|()| {
11011                self.conn
11012                    .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
11013            });
11014        let reset = self.conn.execute_batch("PRAGMA secure_delete = OFF");
11015        erased
11016            .and(reset)
11017            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11018    }
11019
11020    /// Application-authorized recovery of the replicated projection. Unlike a
11021    /// local security purge, this retains the entire outbox, device identity,
11022    /// lease, outcomes, unit registrations, and protected bookkeeping.
11023    /// The projection reset, unit rewind, optimistic replay, and
11024    /// idempotency marker share one savepoint for interruption safety.
11025    pub fn rebootstrap_local_data(
11026        &mut self,
11027        input: &LocalDataRebootstrapInput,
11028    ) -> Result<LocalDataRebootstrapResult, String> {
11029        if input.rebootstrap_id.is_empty()
11030            || input.rebootstrap_id.len() > 128
11031            || !is_local_operation_code_like(&input.rebootstrap_id)
11032        {
11033            return Err(
11034                "sync.invalid_request: local rebootstrap rebootstrapId must be a 1–128 character code-like identifier"
11035                    .to_owned(),
11036            );
11037        }
11038        let meta_key = format!("localRebootstrap:{}", input.rebootstrap_id);
11039        if let Some(persisted) = meta_get(&self.conn, &meta_key).map_err(|_| {
11040            "sync.local_corrupt: persisted local rebootstrap receipt is unreadable".to_owned()
11041        })? {
11042            let (retained_commits, reset_subscriptions) =
11043                decode_local_rebootstrap_receipt(&persisted)?;
11044            return Ok(LocalDataRebootstrapResult {
11045                already_applied: true,
11046                retained_commits,
11047                reset_subscriptions,
11048            });
11049        }
11050        if self.stopped || self.schema_floor.is_some() {
11051            return Err(
11052                "sync.invalid_request: local rebootstrap cannot bypass an active schema-floor stop; update the application first"
11053                    .to_owned(),
11054            );
11055        }
11056
11057        let retained_commits = self.outbox.len();
11058        let reset_subscriptions = self.stored(load_units(&self.conn))?.len();
11059        let receipt = encode_local_rebootstrap_receipt(retained_commits, reset_subscriptions)?;
11060        let rollback = self.capture();
11061        self.begin_observation("syncular_local_rebootstrap")?;
11062        let mut batch = ChangeAccumulator::default();
11063        let applied = (|| -> Result<(), String> {
11064            self.run_schema_reset_observed(&mut batch, false)?;
11065            self.conn
11066                .execute(
11067                    "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
11068                    rusqlite::params![meta_key, receipt],
11069                )
11070                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11071            self.sync_needed = true;
11072            self.sync_intent_queue.push_back(SyncIntent::Interactive);
11073            batch.status = true;
11074            Ok(())
11075        })()
11076        .and_then(|()| self.finish_observation("syncular_local_rebootstrap", batch));
11077        if let Err(error) = applied {
11078            self.rollback_observation("syncular_local_rebootstrap");
11079            self.restore(rollback);
11080            return Err(error);
11081        }
11082
11083        Ok(LocalDataRebootstrapResult {
11084            already_applied: false,
11085            retained_commits,
11086            reset_subscriptions,
11087        })
11088    }
11089
11090    // -- scope purge + doomed outbox (§3.3) ----------------------------------------
11091
11092    /// Delete base and visible rows owned by the effective scopes
11093    /// ([`local_scope_predicate`]); `Ok(false)` = no local scope-column
11094    /// mapping for a key (the fail-closed case). A SQLite failure is an error.
11095    fn purge_scope_rows(
11096        &mut self,
11097        table_name: &str,
11098        effective: &[(String, Vec<String>)],
11099        owners: &[Vec<(String, Vec<String>)>],
11100    ) -> Result<bool, String> {
11101        let Some(table) = self.schema.table(table_name) else {
11102            return Ok(false);
11103        };
11104        let Ok(predicate) = local_scope_predicate(table, effective, owners) else {
11105            return Ok(false);
11106        };
11107        let Some((predicate, params)) = predicate else {
11108            return Ok(true);
11109        };
11110        self.overlay_dirty.table(table_name);
11111        for source in [base_table(table_name), visible_table(table_name)] {
11112            self.conn
11113                .execute(
11114                    &format!("DELETE FROM {source} WHERE {predicate}"),
11115                    rusqlite::params_from_iter(&params),
11116                )
11117                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11118        }
11119        Ok(true)
11120    }
11121
11122    /// §3.3: drop pending commits whose upserts provably land in the
11123    /// revoked effective scopes and no other owner covers (row ownership)
11124    /// — whole-commit, never per-operation.
11125    fn drop_doomed_outbox(
11126        &mut self,
11127        table: &TableSchema,
11128        effective: &[(String, Vec<String>)],
11129        owners: &[Vec<(String, Vec<String>)>],
11130    ) -> Result<bool, String> {
11131        let doomed: Vec<_> =
11132            self.outbox
11133                .iter()
11134                .filter(|commit| {
11135                    commit.ops.iter().any(|op| {
11136                        op.upsert
11137                            && op.table == table.name
11138                            && op.values.as_ref().is_some_and(|values| {
11139                                owns_local_row(table, effective, owners, values)
11140                            })
11141                    })
11142                })
11143                .cloned()
11144                .collect();
11145        if doomed.is_empty() {
11146            return Ok(false);
11147        }
11148        let mut rejections = Vec::new();
11149        for commit in &doomed {
11150            let results = commit
11151                .ops
11152                .iter()
11153                .enumerate()
11154                .map(|(op_index, operation)| {
11155                    self.overlay_dirty.table(&operation.table);
11156                    let rejection = RejectionRecord {
11157                        client_commit_id: commit.client_commit_id.clone(),
11158                        op_index: op_index as i32,
11159                        code: "sync.scope_revoked".to_owned(),
11160                        message: "the commit was dropped because its effective scope was revoked"
11161                            .to_owned(),
11162                        retryable: false,
11163                        details: None,
11164                        operation: Some(CommitOperation::from(operation)),
11165                    };
11166                    rejections.push(rejection.clone());
11167                    CommitOperationOutcome::Error { rejection }
11168                })
11169                .collect::<Vec<_>>();
11170            self.persist_commit_outcome(
11171                &commit.client_commit_id,
11172                CommitOutcomeStatus::Rejected,
11173                &results,
11174                Some(&commit.ops),
11175            )?;
11176            self.delete_outbox_persisted(&commit.client_commit_id)?;
11177        }
11178        self.prune_commit_outcomes()?;
11179        let doomed_ids = doomed
11180            .iter()
11181            .map(|commit| commit.client_commit_id.as_str())
11182            .collect::<BTreeSet<_>>();
11183        self.outbox
11184            .retain(|commit| !doomed_ids.contains(commit.client_commit_id.as_str()));
11185        self.rejections.extend(rejections);
11186        Ok(true)
11187    }
11188
11189    // -- blobs (§5.9) ----------------------------------------------------------------
11190
11191    /// §5.9.7: hash bytes into the content address, cache them, queue the
11192    /// upload (flushed before the next push, B4). Returns the canonical
11193    /// BlobRef JSON `{blobId, byteLength, mediaType?}` for a `blob_ref`
11194    /// column value.
11195    pub fn upload_blob(
11196        &mut self,
11197        bytes: &[u8],
11198        media_type: Option<String>,
11199        name: Option<String>,
11200    ) -> Result<Value, String> {
11201        let blob_id = blob_id_for(bytes);
11202        let now = self.clock_now_ms();
11203        let tx = self
11204            .conn
11205            .transaction()
11206            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11207        tx.execute(
11208            "INSERT INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,?,?)
11209             ON CONFLICT(blob_id) DO NOTHING",
11210            rusqlite::params![blob_id, bytes, bytes.len() as i64, media_type, now],
11211        )
11212        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11213        tx.execute(
11214            "INSERT OR IGNORE INTO _syncular_blob_uploads(blob_id, media_type, created_at_ms) VALUES (?,?,?)",
11215            rusqlite::params![blob_id, media_type, now],
11216        )
11217        .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11218        tx.commit()
11219            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11220        self.enforce_blob_cache_cap();
11221        let mut obj = Map::new();
11222        obj.insert("blobId".to_owned(), Value::from(blob_id));
11223        obj.insert("byteLength".to_owned(), Value::from(bytes.len() as i64));
11224        if let Some(mt) = media_type {
11225            obj.insert("mediaType".to_owned(), Value::from(mt));
11226        }
11227        if let Some(n) = name {
11228            obj.insert("name".to_owned(), Value::from(n));
11229        }
11230        Ok(Value::Object(obj))
11231    }
11232
11233    /// §5.9.7: resolve an owned blob body without driver encoding. A
11234    /// content-addressed cache hit serves with no fetch (B1); a miss downloads
11235    /// (§5.9.5), verifies the address, caches the bytes, and returns them.
11236    pub fn fetch_blob_bytes(
11237        &mut self,
11238        transport: &mut dyn Transport,
11239        blob_id_or_ref: &str,
11240    ) -> Result<FetchedBlob, (String, String)> {
11241        let simple = |m: String| ("client.failed".to_owned(), m);
11242        // A BlobRef declares the size that caps the download (§5.9.5); a bare
11243        // blobId declares none.
11244        let (blob_id, byte_length) = if blob_id_or_ref.starts_with("sha256:") {
11245            (blob_id_or_ref.to_owned(), None)
11246        } else {
11247            let value: Value = serde_json::from_str(blob_id_or_ref)
11248                .map_err(|_| simple("blob ref is not JSON".to_owned()))?;
11249            (
11250                value
11251                    .get("blobId")
11252                    .and_then(Value::as_str)
11253                    .ok_or_else(|| simple("blob ref has no blobId".to_owned()))?
11254                    .to_owned(),
11255                value.get("byteLength").and_then(Value::as_u64),
11256            )
11257        };
11258        if let Some(cached) = self.get_cached_blob_bytes(&blob_id).map_err(simple)? {
11259            return Ok(cached);
11260        }
11261        if !self.transport_enabled {
11262            return Err(("sync.offline".into(), "transport gate is closed".into()));
11263        }
11264        // §5.9.5: propagate the server's blob.* code (blob.forbidden /
11265        // blob.not_found) verbatim so the harness can assert on it. The
11266        // authorized endpoint serves bytes inline OR (always-issue, presign
11267        // configured) a signed url the client fetches directly — no host auth,
11268        // no fall-through: failure => re-request (the caller's next fetch_blob_bytes).
11269        #[cfg(feature = "bench-internals")]
11270        let download_phase = self.benchmark_phases.start(Phase::BlobDownload);
11271        let bytes = match transport
11272            .blob_download(&blob_id, byte_length)
11273            .map_err(|e| (e.code, e.message))?
11274        {
11275            BlobDownload::Bytes(bytes) => bytes,
11276            BlobDownload::Url {
11277                url,
11278                url_expires_at_ms,
11279            } => {
11280                // §5.9.5: MUST NOT start a fetch at/past expiry.
11281                if url_expires_at_ms.is_some_and(|exp| exp <= self.clock_now_ms()) {
11282                    return Err((
11283                        "sync.segment_expired".to_owned(),
11284                        format!(
11285                            "blob url for {blob_id} expired before fetch — re-request mints a fresh url (§5.9.5)"
11286                        ),
11287                    ));
11288                }
11289                transport
11290                    .fetch_blob_url(&url, byte_length)
11291                    .map_err(|e| (e.code, e.message))?
11292            }
11293        };
11294        #[cfg(feature = "bench-internals")]
11295        drop(download_phase);
11296        #[cfg(feature = "bench-internals")]
11297        let validate_phase = self.benchmark_phases.start(Phase::BlobValidate);
11298        // §5.9.5 inherits §5.1: the declared size caps the body before the
11299        // content address is verified.
11300        if byte_length.is_some_and(|cap| bytes.len() as u64 > cap) {
11301            return Err((
11302                "sync.invalid_request".to_owned(),
11303                "blob exceeds its byteLength".to_owned(),
11304            ));
11305        }
11306        if blob_id_for(&bytes) != blob_id {
11307            return Err(simple(format!(
11308                "blob content address mismatch for {blob_id}"
11309            )));
11310        }
11311        #[cfg(feature = "bench-internals")]
11312        drop(validate_phase);
11313        #[cfg(feature = "bench-internals")]
11314        let insert_phase = self.benchmark_phases.start(Phase::BlobCacheInsert);
11315        let now = self.clock_now_ms();
11316        self.conn
11317            .execute(
11318                "INSERT OR IGNORE INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,NULL,?)",
11319                rusqlite::params![blob_id, bytes, bytes.len() as i64, now],
11320            )
11321            .map_err(|e| simple(e.to_string()))?;
11322        self.conn
11323            .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
11324            .map_err(|e| simple(e.to_string()))?;
11325        self.enforce_blob_cache_cap();
11326        #[cfg(feature = "bench-internals")]
11327        drop(insert_phase);
11328        self.get_cached_blob_bytes(&blob_id)
11329            .map_err(simple)?
11330            .ok_or_else(|| simple("blob cache write failed".to_owned()))
11331    }
11332
11333    fn get_cached_blob_bytes(&self, blob_id: &str) -> Result<Option<FetchedBlob>, String> {
11334        #[cfg(feature = "bench-internals")]
11335        let _phase = self.benchmark_phases.start(Phase::BlobCacheRead);
11336        let mut stmt = self
11337            .conn
11338            .prepare("SELECT bytes, byte_length, media_type FROM _syncular_blobs WHERE blob_id = ?")
11339            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11340        let mut rows = stmt
11341            .query(rusqlite::params![blob_id])
11342            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11343        if let Some(row) = rows
11344            .next()
11345            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11346        {
11347            let bytes: Vec<u8> = row
11348                .get(0)
11349                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11350            let byte_length: i64 = row
11351                .get(1)
11352                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11353            let media_type: Option<String> = row
11354                .get(2)
11355                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11356            return Ok(Some(FetchedBlob {
11357                blob_id: blob_id.to_owned(),
11358                byte_length,
11359                bytes,
11360                media_type,
11361            }));
11362        }
11363        Ok(None)
11364    }
11365
11366    /// §5.9.7 B4: upload every queued blob before push.
11367    fn pending_blob_uploads(&self) -> Result<Vec<crate::round::PendingUpload>, TransportError> {
11368        let pending: Vec<(String, Option<String>)> = {
11369            let mut stmt = self
11370                .conn
11371                .prepare(
11372                    "SELECT blob_id, media_type FROM (
11373                      SELECT blob_id, media_type, created_at_ms FROM _syncular_blob_uploads
11374                      UNION ALL
11375                      SELECT DISTINCT r.blob_id, b.media_type, 9223372036854775807 AS created_at_ms
11376                      FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id = r.blob_id
11377                      WHERE NOT EXISTS (SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id = r.blob_id)
11378                    ) ORDER BY created_at_ms, blob_id",
11379                )
11380                .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11381            let rows = stmt
11382                .query_map([], |row| {
11383                    Ok((row.get::<_, String>(0)?, row.get::<_, Option<String>>(1)?))
11384                })
11385                .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11386            rows.collect::<Result<_, _>>()
11387                .map_err(|error| match error {
11388                    rusqlite::Error::InvalidColumnType(..)
11389                    | rusqlite::Error::FromSqlConversionFailure(..) => TransportError::new(
11390                        "sync.local_corrupt",
11391                        "Pending blob upload metadata is invalid",
11392                    ),
11393                    _ => TransportError::new("client.failed", error.to_string()),
11394                })?
11395        };
11396        let mut uploads = Vec::new();
11397        for (blob_id, media_type) in pending {
11398            let bytes = (|| {
11399                let stored: Option<(SqlValue, SqlValue)> = self
11400                    .conn
11401                    .query_row(
11402                        "SELECT bytes, byte_length FROM _syncular_blobs WHERE blob_id = ?",
11403                        rusqlite::params![blob_id],
11404                        |row| Ok((row.get(0)?, row.get(1)?)),
11405                    )
11406                    .optional()
11407                    .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11408                let Some((SqlValue::Blob(bytes), SqlValue::Integer(byte_length))) = stored else {
11409                    return Err(TransportError::new(
11410                        "sync.local_corrupt",
11411                        "Pending blob upload body is missing or corrupt",
11412                    ));
11413                };
11414                if byte_length != bytes.len() as i64 || blob_id_for(&bytes) != blob_id {
11415                    return Err(TransportError::new(
11416                        "sync.local_corrupt",
11417                        "Pending blob upload body is missing or corrupt",
11418                    ));
11419                }
11420                Ok(bytes)
11421            })();
11422            let failed = bytes.is_err();
11423            uploads.push(crate::round::PendingUpload {
11424                id: blob_id,
11425                bytes,
11426                media_type,
11427            });
11428            if failed {
11429                break;
11430            }
11431        }
11432        Ok(uploads)
11433    }
11434
11435    fn visible_blob_ids_sql(&self) -> String {
11436        let mut selects = Vec::new();
11437        for table in &self.schema.tables {
11438            for column in table
11439                .columns
11440                .iter()
11441                .filter(|column| column.ty == ColumnType::BlobRef)
11442            {
11443                let identifier = quote_ident(&column.name);
11444                selects.push(format!(
11445                    "SELECT json_extract({identifier}, '$.blobId') AS blob_id FROM {} \
11446                     WHERE typeof({identifier}) = 'text' AND json_valid({identifier}) \
11447                     AND json_type({identifier}, '$.blobId') = 'text'",
11448                    quote_ident(&table.name),
11449                ));
11450            }
11451        }
11452        if selects.is_empty() {
11453            "SELECT NULL AS blob_id WHERE 0".to_owned()
11454        } else {
11455            selects.join(" UNION ")
11456        }
11457    }
11458
11459    /// §5.9.7 B1 size cap. Visible rows, pending commits, and
11460    /// staged uploads pin bodies directly; no derived refcount is stored.
11461    fn enforce_blob_cache_cap(&self) {
11462        let Some(max_bytes) = self.limits.blob_cache_max_bytes else {
11463            return;
11464        };
11465        let mut total: i64 = self
11466            .conn
11467            .query_row(
11468                "SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs",
11469                [],
11470                |row| row.get(0),
11471            )
11472            .unwrap_or(0);
11473        if total <= max_bytes {
11474            return;
11475        }
11476        let query = format!(
11477            "SELECT blob_id, byte_length FROM _syncular_blobs
11478             WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
11479               AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
11480               AND blob_id NOT IN ({})
11481             ORDER BY created_at_ms ASC, blob_id ASC",
11482            self.visible_blob_ids_sql(),
11483        );
11484        let candidates: Vec<(String, i64)> = {
11485            let Ok(mut stmt) = self.conn.prepare(&query) else {
11486                return;
11487            };
11488            let Ok(rows) = stmt.query_map([], |row| {
11489                Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
11490            }) else {
11491                return;
11492            };
11493            rows.filter_map(Result::ok).collect()
11494        };
11495        for (blob_id, byte_length) in candidates {
11496            if total <= max_bytes {
11497                break;
11498            }
11499            let _ = self.conn.execute(
11500                "DELETE FROM _syncular_blobs WHERE blob_id = ?",
11501                rusqlite::params![blob_id],
11502            );
11503            total -= byte_length;
11504        }
11505    }
11506
11507    fn delete_unreferenced_cached_blobs(&mut self) -> Result<(), String> {
11508        #[cfg(feature = "bench-internals")]
11509        let _phase = self.benchmark_phases.start(Phase::BlobRetention);
11510        if !self.schema_has_blobs() {
11511            return Ok(());
11512        }
11513        self.rebuild_overlay_if_dirty()?;
11514        self.conn
11515            .execute(
11516                &format!(
11517                    "DELETE FROM _syncular_blobs
11518                 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
11519                   AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
11520                   AND blob_id NOT IN ({})",
11521                    self.visible_blob_ids_sql(),
11522                ),
11523                [],
11524            )
11525            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11526        Ok(())
11527    }
11528
11529    // -- local row storage ----------------------------------------------------------
11530
11531    /// The cached per-table primary-key upsert SQL for `full_table` (see
11532    /// the `insert_sql` field: built once, reused per row).
11533    fn insert_row_sql(&self, full_table: &str, table: &crate::schema::TableSchema) -> String {
11534        if let Some(sql) = self.insert_sql.borrow().get(full_table) {
11535            return sql.clone();
11536        }
11537        let mut columns: Vec<String> = table.columns.iter().map(|c| quote_ident(&c.name)).collect();
11538        columns.push(quote_ident("_syncular_version"));
11539        let placeholders: Vec<&str> = columns.iter().map(|_| "?").collect();
11540        let primary_key = quote_ident(&table.primary_key);
11541        let updates = columns
11542            .iter()
11543            .filter(|column| **column != primary_key)
11544            .map(|column| format!("{column}=excluded.{column}"))
11545            .collect::<Vec<_>>()
11546            .join(", ");
11547        // §4.5 version guard: server state lands in the base table only above
11548        // the stored version; the visible overlay takes every write.
11549        let guard = if full_table == base_table(&table.name) {
11550            format!(" WHERE excluded._syncular_version > {full_table}._syncular_version")
11551        } else {
11552            String::new()
11553        };
11554        let sql = format!(
11555            "INSERT INTO {full_table} ({}) VALUES ({}) ON CONFLICT ({primary_key}) DO UPDATE SET {updates}{guard}",
11556            columns.join(", "),
11557            placeholders.join(", ")
11558        );
11559        self.insert_sql
11560            .borrow_mut()
11561            .insert(full_table.to_owned(), sql.clone());
11562        sql
11563    }
11564
11565    /// §4.5: write a server row under the version guard; returns whether it
11566    /// landed.
11567    fn write_base_row(&self, table_name: &str, row: &Row, version: i64) -> Result<bool, String> {
11568        let landed = self.write_row(&base_table(table_name), table_name, row, version)?;
11569        if landed {
11570            self.overlay_dirty.table(table_name);
11571        }
11572        Ok(landed)
11573    }
11574
11575    fn write_row(
11576        &self,
11577        full_table: &str,
11578        table_name: &str,
11579        row: &Row,
11580        version: i64,
11581    ) -> Result<bool, String> {
11582        #[cfg(feature = "bench-internals")]
11583        let _phase = self.benchmark_phases.start(Phase::RowWrite);
11584        let table = self
11585            .schema
11586            .table(table_name)
11587            .ok_or_else(|| format!("unknown table {table_name:?}"))?;
11588        let sql = self.insert_row_sql(full_table, table);
11589        let mut stmt = self
11590            .conn
11591            .prepare_cached(&sql)
11592            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11593        let params = row
11594            .iter()
11595            .map(RowParam::Cell)
11596            .chain(std::iter::once(RowParam::Version(version)));
11597        stmt.execute(rusqlite::params_from_iter(params))
11598            .map(|changed| changed > 0)
11599            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11600    }
11601
11602    /// §4.5: delete a server row whose stored version lies below `version`;
11603    /// returns whether a row left.
11604    fn delete_base_row(
11605        &self,
11606        table_name: &str,
11607        row_id: &str,
11608        version: i64,
11609    ) -> Result<bool, String> {
11610        let table = self
11611            .schema
11612            .table(table_name)
11613            .ok_or_else(|| format!("unknown table {table_name:?}"))?;
11614        let sql = format!(
11615            "DELETE FROM {} WHERE {} AND _syncular_version < ?2",
11616            base_table(table_name),
11617            row_id_predicate(table)
11618        );
11619        let mut stmt = self
11620            .conn
11621            .prepare_cached(&sql)
11622            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11623        let landed = stmt
11624            .execute(rusqlite::params![row_id, version])
11625            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11626            > 0;
11627        if landed {
11628            self.overlay_dirty.table(table_name);
11629        }
11630        Ok(landed)
11631    }
11632
11633    fn has_acknowledged_rows(&self) -> Result<bool, String> {
11634        self.conn
11635            .query_row(
11636                "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows)",
11637                [],
11638                |row| row.get(0),
11639            )
11640            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11641    }
11642
11643    fn acknowledged_operations(
11644        &self,
11645        rows: Option<&HashSet<(&str, &str)>>,
11646        tables: Option<&BTreeSet<&str>>,
11647    ) -> Result<Vec<OutboxOp>, String> {
11648        let keys = rows.map(|rows| serde_json::to_string(&rows).expect("row keys"));
11649        let mut statement = self
11650            .conn
11651            .prepare_cached(if keys.is_some() {
11652                ACKED_ROWS_BY_ROW
11653            } else {
11654                "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"
11655            })
11656            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11657        let rows = statement
11658            .query_map(
11659                rusqlite::params![
11660                    keys,
11661                    tables.map(|tables| serde_json::to_string(tables).expect("table keys"))
11662                ],
11663                |row| {
11664                    #[cfg(test)]
11665                    self.acknowledged_replay_count
11666                        .set(self.acknowledged_replay_count.get() + 1);
11667                    Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
11668                },
11669            )
11670            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11671        rows.map(|row| {
11672            let (op, intent) =
11673                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11674            let op: CommitOperation =
11675                serde_json::from_str(&op).map_err(|_| "sync.local_corrupt".to_owned())?;
11676            let table = self
11677                .schema
11678                .table(&op.table)
11679                .ok_or_else(|| "sync.unknown_table".to_owned())?;
11680            let values = if op.op == "upsert" && self.visible_row(table, &op.row_id)?.is_none() {
11681                Some(serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?)
11682            } else {
11683                op.values.clone()
11684            };
11685            Ok(OutboxOp {
11686                values,
11687                ..op.into()
11688            })
11689        })
11690        .collect()
11691    }
11692
11693    fn drop_acknowledged_rows(
11694        &self,
11695        matches: impl Fn(&str, &Map<String, Value>) -> bool,
11696    ) -> Result<Vec<OutboxCommit>, String> {
11697        let mut statement = self
11698            .conn
11699            .prepare("SELECT commit_id,tbl,intent_json,id FROM _syncular_acked_rows")
11700            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11701        let rows = statement
11702            .query_map([], |row| {
11703                Ok((
11704                    row.get::<_, String>(0)?,
11705                    row.get::<_, String>(1)?,
11706                    row.get::<_, String>(2)?,
11707                    row.get::<_, String>(3)?,
11708                ))
11709            })
11710            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11711        let mut doomed = HashSet::new();
11712        for row in rows {
11713            let (id, table, intent, row_id) =
11714                row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11715            let values =
11716                serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
11717            let base_matches = self
11718                .schema
11719                .table(&table)
11720                .map(|schema| self.stored_row(schema, &row_id, true))
11721                .transpose()?
11722                .flatten()
11723                .is_some_and(|(base, _)| {
11724                    let schema = self.schema.table(&table).expect("acknowledged table");
11725                    let values = schema
11726                        .columns
11727                        .iter()
11728                        .zip(base.iter())
11729                        .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
11730                        .collect();
11731                    matches(&table, &values)
11732                });
11733            if matches(&table, &values) || base_matches {
11734                doomed.insert(id);
11735            }
11736        }
11737        let mut dropped = Vec::new();
11738        for id in doomed {
11739            let mut statement = self
11740                .conn
11741                .prepare("SELECT op_json FROM _syncular_acked_rows WHERE commit_id=?1 ORDER BY idx")
11742                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11743            let operations = statement
11744                .query_map([&id], |row| row.get::<_, String>(0))
11745                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11746            let mut ops = Vec::new();
11747            for operation in operations {
11748                let json = operation
11749                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11750                let op: CommitOperation =
11751                    serde_json::from_str(&json).map_err(|_| "sync.local_corrupt".to_owned())?;
11752                self.overlay_dirty.table(&op.table);
11753                ops.push(OutboxOp {
11754                    table: op.table,
11755                    row_id: op.row_id,
11756                    upsert: op.op == "upsert",
11757                    base_version: op.base_version,
11758                    values: op.values,
11759                    insert: op.insert,
11760                });
11761            }
11762            dropped.push(OutboxCommit {
11763                client_commit_id: id.clone(),
11764                ops,
11765            });
11766            self.conn
11767                .execute("DELETE FROM _syncular_acked_rows WHERE commit_id=?1", [id])
11768                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11769        }
11770        Ok(dropped)
11771    }
11772
11773    /// [`Self::rebuild_overlay`], skipped when neither the base tables nor
11774    /// the outbox changed since the last rebuild (the no-op sync round).
11775    fn rebuild_overlay_if_dirty(&mut self) -> Result<(), String> {
11776        if self.overlay_dirty.get() {
11777            self.rebuild_overlay()?;
11778        }
11779        Ok(())
11780    }
11781
11782    /// §7.1: local reads see outbox state applied optimistically — rebuild
11783    /// every visible table as (base server state) + (pending outbox replay
11784    /// on top). Optimistic rows carry version `-1`.
11785    fn rebuild_overlay(&mut self) -> Result<(), String> {
11786        #[cfg(feature = "bench-internals")]
11787        let _phase = self.benchmark_phases.start(Phase::OverlayRebuild);
11788        #[cfg(test)]
11789        self.overlay_rebuild_count
11790            .set(self.overlay_rebuild_count.get() + 1);
11791        let dirty = self.overlay_dirty.snapshot();
11792        let tables: Vec<_> = self
11793            .schema
11794            .tables
11795            .iter()
11796            .filter(|table| {
11797                dirty
11798                    .as_ref()
11799                    .is_none_or(|names| names.is_empty() || names.contains(&table.name))
11800            })
11801            .cloned()
11802            .collect();
11803        let names: BTreeSet<_> = tables.iter().map(|table| table.name.as_str()).collect();
11804        self.begin_observation("syncular_overlay")?;
11805        let rebuilt = (|| {
11806            for table in &tables {
11807                for index in &table.fts_indexes {
11808                    self.drop_fts_triggers(index)?;
11809                }
11810                let visible = visible_table(&table.name);
11811                let base = base_table(&table.name);
11812                self.conn
11813                    .execute_batch(&format!(
11814                        "DELETE FROM {visible}; INSERT INTO {visible} SELECT * FROM {base}"
11815                    ))
11816                    .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11817            }
11818            self.replay_overlay(&names, None)?;
11819            for table in &tables {
11820                for index in &table.fts_indexes {
11821                    self.rebuild_fts_projection(table, index)?;
11822                    self.create_fts_triggers(table, index)?;
11823                }
11824            }
11825            self.conn
11826                .execute_batch("RELEASE syncular_overlay")
11827                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11828            Ok(())
11829        })();
11830        if rebuilt.is_err() {
11831            self.conn
11832                .execute_batch("ROLLBACK TO syncular_overlay; RELEASE syncular_overlay")
11833                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11834        } else {
11835            self.overlay_dirty.set(false);
11836        }
11837        rebuilt
11838    }
11839
11840    /// §7.1 replay of acknowledged, retained failed and pending intent, in
11841    /// that order, for the operations of `tables` on `rows` (every row for
11842    /// `None`) over their current visible state.
11843    fn replay_overlay(
11844        &self,
11845        tables: &BTreeSet<&str>,
11846        rows: Option<&HashSet<(&str, &str)>>,
11847    ) -> Result<(), String> {
11848        let replays = |op: &&OutboxOp| {
11849            tables.contains(op.table.as_str())
11850                && rows.is_none_or(|rows| rows.contains(&(op.table.as_str(), op.row_id.as_str())))
11851        };
11852        self.apply_outbox_ops(&self.acknowledged_operations(rows, Some(tables))?)?;
11853        for (commit, initial) in self.failed_commits.iter() {
11854            for operation in commit.ops.iter().filter(replays) {
11855                let Some(table) = self.schema.table(&operation.table) else {
11856                    continue;
11857                };
11858                if operation.upsert
11859                    && self.visible_row(table, &operation.row_id)?.is_none()
11860                    && operation.presented_values(table).is_some_and(|values| {
11861                        table
11862                            .columns
11863                            .iter()
11864                            .all(|column| values.contains_key(&column.name))
11865                    })
11866                {
11867                    let key = serde_json::to_string(&(&operation.table, &operation.row_id))
11868                        .expect("row key serialization");
11869                    if let Some(Value::Object(values)) = initial.get(&key) {
11870                        self.apply_outbox_ops(&[OutboxOp {
11871                            values: Some(values.clone()),
11872                            ..operation.clone()
11873                        }])?;
11874                    }
11875                }
11876            }
11877            self.apply_outbox_ops(commit.ops.iter().filter(replays))?;
11878        }
11879        self.apply_outbox_ops(
11880            self.outbox
11881                .iter()
11882                .flat_map(|commit| &commit.ops)
11883                .filter(replays),
11884        )
11885    }
11886
11887    /// §7.1 replay: every operation is applied over the current visible
11888    /// state. An operation that no longer applies (a server row now holds its
11889    /// unique value) stays pending and invisible until a later replay admits
11890    /// it or the server answers its push.
11891    fn apply_outbox_ops<'a>(
11892        &self,
11893        ops: impl IntoIterator<Item = &'a OutboxOp>,
11894    ) -> Result<(), String> {
11895        #[cfg(feature = "bench-internals")]
11896        let mut phase = self.benchmark_phases.start(Phase::PendingReplay);
11897        for op in ops {
11898            #[cfg(feature = "bench-internals")]
11899            if let Some(phase) = &mut phase {
11900                phase.unit();
11901            }
11902            if op.upsert {
11903                if let Some((table, values)) = self
11904                    .schema
11905                    .table(&op.table)
11906                    .filter(|table| table.indexes.iter().any(|index| index.unique))
11907                    .and_then(|table| Some((table, op.presented_values(table)?)))
11908                {
11909                    let mut intended: Map<String, Value> = self
11910                        .visible_row(table, &op.row_id)?
11911                        .map(|(row, _)| {
11912                            table
11913                                .columns
11914                                .iter()
11915                                .zip(&row)
11916                                .map(|(column, value)| {
11917                                    (column.name.clone(), column_value_to_json(value))
11918                                })
11919                                .collect()
11920                        })
11921                        .unwrap_or_default();
11922                    intended.extend(values.into_owned());
11923                    if !self.unique_conflicts(table, &intended, false)?.is_empty() {
11924                        continue;
11925                    }
11926                }
11927            }
11928            self.apply_outbox_op(op)?;
11929        }
11930        Ok(())
11931    }
11932
11933    fn apply_outbox_op(&self, op: &OutboxOp) -> Result<(), String> {
11934        let Some(table) = self.schema.table(&op.table) else {
11935            return Ok(());
11936        };
11937        let visible = visible_table(&table.name);
11938        if !op.upsert {
11939            let sql = format!("DELETE FROM {visible} WHERE {}", row_id_predicate(table));
11940            self.conn
11941                .prepare_cached(&sql)
11942                .and_then(|mut statement| statement.execute(rusqlite::params![op.row_id]))
11943                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11944            return Ok(());
11945        }
11946        // §7.1: an insert-intent operation that lacks a non-nullable column
11947        // cannot encode; it stays invisible until the send-time prepass drops
11948        // it as sync.outbox_incompatible (§7.4.4).
11949        let Some(values) = op.presented_values(table) else {
11950            return Ok(());
11951        };
11952        // §7.1: the overlay applies the operation's PRESENT columns
11953        // over the current local row. A partial operation over an
11954        // absent local row leaves it absent — the server answers it
11955        // with sync.row_deleted or sync.row_missing (§6.2). An
11956        // insert-intent operation presents every column.
11957        let full = table
11958            .columns
11959            .iter()
11960            .all(|column| values.contains_key(&column.name));
11961        let local = self.visible_row(table, &op.row_id)?;
11962        if local.is_none() && !full {
11963            return Ok(());
11964        }
11965        let mut row: Row = Vec::with_capacity(table.columns.len());
11966        for (index, column) in table.columns.iter().enumerate() {
11967            let incoming = match values.get(&column.name) {
11968                Some(raw) => json_to_column_value(
11969                    if raw.get("$bytes").is_some()
11970                        && table
11971                            .encrypted_columns
11972                            .iter()
11973                            .any(|encrypted| encrypted.index == index)
11974                    {
11975                        &table.wire_columns[index]
11976                    } else {
11977                        column
11978                    },
11979                    Some(raw),
11980                ),
11981                None => Ok(local
11982                    .as_ref()
11983                    .and_then(|(values, _)| values.get(index).cloned())
11984                    .flatten()),
11985            };
11986            row.push(incoming.map_err(|_| {
11987                "sync.local_corrupt: persisted optimistic row value is invalid".to_owned()
11988            })?);
11989        }
11990        let version = local.as_ref().map_or(-1, |(_, version)| *version);
11991        self.write_row(&visible, &table.name, &row, version)
11992            .map(|_| ())
11993            .map_err(|error| {
11994                if error.starts_with("UNIQUE constraint failed:") {
11995                    "sync.constraint_violation: local write violates a unique constraint".to_owned()
11996                } else {
11997                    error
11998                }
11999            })
12000    }
12001
12002    /// Whether the row is present in the overlay. Existence reads only the
12003    /// key: locked encrypted values stay opaque, and decoding the complete row
12004    /// would reject a valid plain write.
12005    fn visible_row_exists(&self, table: &TableSchema, row_id: &str) -> Result<bool, String> {
12006        self.conn
12007            .query_row(
12008                &format!(
12009                    "SELECT EXISTS(SELECT 1 FROM {} WHERE {})",
12010                    visible_table(&table.name),
12011                    row_id_predicate(table)
12012                ),
12013                rusqlite::params![row_id],
12014                |row| row.get(0),
12015            )
12016            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
12017    }
12018
12019    /// The visible (optimistic) row's values plus version, or `None` when the
12020    /// row is absent from the overlay.
12021    fn visible_row(&self, table: &TableSchema, row_id: &str) -> Result<Option<(Row, i64)>, String> {
12022        self.stored_row(table, row_id, false)
12023    }
12024
12025    fn stored_row(
12026        &self,
12027        table: &TableSchema,
12028        row_id: &str,
12029        base: bool,
12030    ) -> Result<Option<(Row, i64)>, String> {
12031        let sql = format!(
12032            "SELECT * FROM {} WHERE {}",
12033            if base {
12034                base_table(&table.name)
12035            } else {
12036                visible_table(&table.name)
12037            },
12038            row_id_predicate(table)
12039        );
12040        let mut stmt = self
12041            .conn
12042            .prepare_cached(&sql)
12043            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12044        let mut rows = stmt
12045            .query(rusqlite::params![row_id])
12046            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12047        let Some(row) = rows
12048            .next()
12049            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
12050        else {
12051            return Ok(None);
12052        };
12053        let mut values = Vec::with_capacity(table.columns.len());
12054        for (index, column) in table.columns.iter().enumerate() {
12055            let raw = row
12056                .get_ref(index)
12057                .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12058            if let rusqlite::types::ValueRef::Blob(bytes) = raw {
12059                if table
12060                    .encrypted_columns
12061                    .iter()
12062                    .any(|encrypted| encrypted.index == index)
12063                {
12064                    values.push(Some(ColumnValue::Bytes(bytes.to_vec())));
12065                    continue;
12066                }
12067            }
12068            let json = sql_ref_to_json(column, raw);
12069            values.push(json_to_column_value(column, Some(&json)).map_err(|_| {
12070                "sync.local_corrupt: persisted local row value is invalid".to_owned()
12071            })?);
12072        }
12073        let version: i64 = row
12074            .get(table.columns.len())
12075            .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12076        Ok(Some((values, version)))
12077    }
12078
12079    // -- realtime (§8) ---------------------------------------------------------------
12080
12081    /// §8.8: the configured realtime policy.
12082    #[must_use]
12083    pub fn realtime_policy(&self) -> RealtimePolicy {
12084        self.realtime_policy
12085    }
12086
12087    /// §8.8: the explicit realtime availability state.
12088    #[must_use]
12089    pub fn realtime_state(&self) -> RealtimeState {
12090        self.realtime_state
12091    }
12092
12093    /// §8.8: set the realtime policy. Refused while the socket is connected:
12094    /// a policy change never silently re-routes an ownership state.
12095    pub fn set_realtime_policy(&mut self, policy: RealtimePolicy) -> Result<(), String> {
12096        if self.realtime_state == RealtimeState::Connected && policy != self.realtime_policy {
12097            return Err(
12098                "sync.invalid_request: disconnect realtime before changing the realtime policy"
12099                    .to_owned(),
12100            );
12101        }
12102        self.realtime_policy = policy;
12103        match policy {
12104            RealtimePolicy::Off => self.set_realtime_state(RealtimeState::Disabled, None),
12105            RealtimePolicy::Required | RealtimePolicy::Optional
12106                if self.realtime_state == RealtimeState::Disabled =>
12107            {
12108                self.set_realtime_state(RealtimeState::Disconnected, None);
12109            }
12110            RealtimePolicy::Required | RealtimePolicy::Optional => {}
12111        }
12112        Ok(())
12113    }
12114
12115    /// Record an availability transition, keeping the reason code bounded and
12116    /// code-like (§7.6) and clearing it where it cannot apply.
12117    fn set_realtime_state(&mut self, state: RealtimeState, reason_code: Option<&str>) {
12118        self.realtime_state = state;
12119        self.realtime_reason_code = reason_code.map(Self::diagnostic_code);
12120        if matches!(state, RealtimeState::Connected | RealtimeState::Disabled) {
12121            self.realtime_reason_code = None;
12122            self.realtime_retry_delay_ms = None;
12123        }
12124    }
12125
12126    #[must_use]
12127    fn realtime_connected(&self) -> bool {
12128        self.realtime_state == RealtimeState::Connected
12129    }
12130
12131    pub fn connect_realtime(&mut self, transport: &mut dyn Transport) -> Result<(), String> {
12132        if !self.transport_enabled {
12133            return Err("sync.offline: transport gate is closed".into());
12134        }
12135        if self.realtime_policy == RealtimePolicy::Off {
12136            return Err(
12137                "sync.invalid_request: realtime is off; realtime connect is refused".to_owned(),
12138            );
12139        }
12140        if self.realtime_connected() {
12141            return Ok(());
12142        }
12143        self.realtime_state = RealtimeState::Connecting;
12144        match transport.realtime_connect_for_client(&self.client_id) {
12145            Ok(()) => {
12146                self.set_realtime_state(RealtimeState::Connected, None);
12147                Ok(())
12148            }
12149            Err(error) => {
12150                self.set_realtime_state(RealtimeState::Refused, Some(&error.code));
12151                Err(format!("{}: {}", error.code, error.message))
12152            }
12153        }
12154    }
12155
12156    pub fn disconnect_realtime(&mut self, transport: &mut dyn Transport) {
12157        self.cancel_sync_round();
12158        // A deliberately disconnected or policy-disabled client has nothing
12159        // to release; a `lost` socket still does (the host owns the handle).
12160        if self.realtime_state == RealtimeState::Disconnected
12161            || self.realtime_state == RealtimeState::Disabled
12162        {
12163            return;
12164        }
12165        let _ = transport.realtime_close();
12166        self.set_realtime_state(
12167            if self.realtime_policy == RealtimePolicy::Off {
12168                RealtimeState::Disabled
12169            } else {
12170                RealtimeState::Disconnected
12171            },
12172            None,
12173        );
12174        self.presence.clear(); // §8.6.1: presence is per-connection
12175    }
12176
12177    /// §8.8: the host observed the socket end without disconnecting it (a
12178    /// peer close, an I/O error, a failed send; the native transport reports
12179    /// these as `Inbound::Disconnected`). Releases the transport, moves a
12180    /// `Connected` state to `Lost` with the transport's code as the reason, and schedules
12181    /// one background retry intent so the host reconnects and catches up.
12182    pub fn realtime_lost(&mut self, transport: &mut dyn Transport, error: &TransportError) {
12183        if self.realtime_state != RealtimeState::Connected {
12184            return;
12185        }
12186        self.cancel_sync_round();
12187        let _ = transport.realtime_close();
12188        self.set_realtime_state(RealtimeState::Lost, Some(&error.code));
12189        self.realtime_retry_delay_ms = Some(self.schedule_background_retry());
12190        self.presence.clear();
12191    }
12192
12193    /// §8.6.2: publish (or clear, `doc: None`) this client's presence
12194    /// document for `scope_key`. Requires a live socket; the document is
12195    /// ephemeral (lost on disconnect). Authorization is the connection's
12196    /// registration (§8.6.3) — an unheld key is rejected loudly by the
12197    /// server with `presence.forbidden`.
12198    pub fn set_presence(
12199        &mut self,
12200        transport: &mut dyn Transport,
12201        scope_key: &str,
12202        doc: Option<&Value>,
12203    ) -> Result<(), String> {
12204        if !self.transport_enabled {
12205            return Err("sync.offline: transport gate is closed".into());
12206        }
12207        if !self.realtime_connected() {
12208            return Err("setPresence requires a connected realtime socket (§8.6)".to_string());
12209        }
12210        let text = encode_presence_publish(scope_key, doc);
12211        transport
12212            .realtime_send(&text)
12213            .map_err(|e| format!("{}: {}", e.code, e.message))
12214    }
12215
12216    /// §8.6: the peers currently present on a scope key (ephemeral).
12217    pub fn presence(&self, scope_key: &str) -> Vec<PresencePeer> {
12218        self.presence
12219            .get(scope_key)
12220            .map(|peers| peers.values().cloned().collect())
12221            .unwrap_or_default()
12222    }
12223
12224    /// §8.6 apply an inbound presence fanout to the local map.
12225    fn apply_presence(
12226        &mut self,
12227        scope_key: String,
12228        kind: Option<PresenceKind>,
12229        actor_id: Option<String>,
12230        client_id: Option<String>,
12231        doc: Option<Value>,
12232        error: Option<String>,
12233    ) {
12234        // A refused publish (§8.6.2) changes no peer; the native host surfaces
12235        // it as a `presence` event carrying the server's `error` code.
12236        if error.is_some() {
12237            return;
12238        }
12239        let (Some(kind), Some(actor_id), Some(client_id)) = (kind, actor_id, client_id) else {
12240            return;
12241        };
12242        let peer_key = format!("{actor_id} {client_id}");
12243        match kind {
12244            PresenceKind::Leave => {
12245                if let Some(peers) = self.presence.get_mut(&scope_key) {
12246                    peers.remove(&peer_key);
12247                    if peers.is_empty() {
12248                        self.presence.remove(&scope_key);
12249                    }
12250                }
12251            }
12252            _ => {
12253                let doc = match doc {
12254                    Some(Value::Object(_)) => doc.unwrap(),
12255                    _ => return,
12256                };
12257                self.presence.entry(scope_key).or_default().insert(
12258                    peer_key,
12259                    PresencePeer {
12260                        actor_id,
12261                        client_id,
12262                        doc,
12263                    },
12264                );
12265            }
12266        }
12267    }
12268
12269    /// Inbound JSON control message (§8.1). Unknown events are tolerated.
12270    pub fn on_realtime_text(&mut self, text: &str) {
12271        if self.stopped || !self.transport_enabled || self.security_preflight {
12272            return;
12273        }
12274        match parse_control(text) {
12275            Ok(ControlMessage::Hello { requires_sync, .. }) => {
12276                if requires_sync {
12277                    // §8.1: pull before trusting the socket for continuity.
12278                    self.set_sync_needed(true, true);
12279                }
12280            }
12281            Ok(ControlMessage::Presence {
12282                scope_key,
12283                kind,
12284                actor_id,
12285                client_id,
12286                doc,
12287                error,
12288                ..
12289            }) => {
12290                self.apply_presence(scope_key, kind, actor_id, client_id, doc, error);
12291            }
12292            Ok(ControlMessage::Wake { .. }) => {
12293                // §8.3: any wake-up means "run a pull soon", never data.
12294                self.set_sync_needed(true, true);
12295            }
12296            _ => {}
12297        }
12298    }
12299
12300    /// Inbound binary delta: a complete SSP2 response (§8.2), applied like
12301    /// a pull response per section; an unapplied delta is a wake-up.
12302    /// Mailbox hosts send durable acknowledgements on their I/O executor.
12303    pub fn on_realtime_binary_queued(&mut self, bytes: &[u8]) -> Vec<String> {
12304        let mut transport = crate::round::DownloadResults::default();
12305        self.on_realtime_binary(&mut transport, bytes);
12306        transport.controls
12307    }
12308
12309    /// §8.2: a delta applies exactly like a live section and sets the replica
12310    /// cursor to its `throughSeq`; one at or below the replica cursor is a
12311    /// duplicate. A delta the client does not apply (no live unit, a status
12312    /// other than `active`, a decode or apply failure) is a drop and raises
12313    /// sync-needed.
12314    pub fn on_realtime_binary(&mut self, transport: &mut dyn Transport, bytes: &[u8]) {
12315        if self.stopped || !self.transport_enabled || self.security_preflight {
12316            return;
12317        }
12318        #[cfg(feature = "bench-internals")]
12319        let decode_phase = self.benchmark_phases.start(Phase::ResponseDecode);
12320        let message = match decode_message(bytes) {
12321            Ok(m) if m.msg_kind == MsgKind::Response => m,
12322            _ => {
12323                self.set_sync_needed(true, true);
12324                return;
12325            }
12326        };
12327        #[cfg(feature = "bench-internals")]
12328        drop(decode_phase);
12329        // §8.2: a delta's header means what a pull response's header means. A
12330        // schema floor (§1.6) is recorded, stops syncing and applies nothing.
12331        if let Some(Frame::RespHeader {
12332            required_schema_version: Some(required),
12333            latest_schema_version,
12334            ..
12335        }) = message.frames.first()
12336        {
12337            let floor = SchemaFloor {
12338                required_schema_version: Some(*required),
12339                latest_schema_version: *latest_schema_version,
12340            };
12341            if self.set_schema_floor(Some(floor)).is_err() {
12342                self.set_sync_needed(true, true);
12343            }
12344            return;
12345        }
12346        let through = message.frames.iter().find_map(|frame| match frame {
12347            Frame::LiveEnd { through_seq, .. } => Some(*through_seq),
12348            _ => None,
12349        });
12350        let epoch = self.get_meta(LOG_EPOCH_KEY).ok().flatten();
12351        let mut dropped = !matches!(message.frames.first(), Some(Frame::RespHeader {
12352                reset_required: false,
12353                log_epoch,
12354                ..
12355            }) if Some(log_epoch) == epoch.as_ref());
12356        let mut applied: Option<i64> = None;
12357        dropped |= self.begin_coalesced_apply().is_err();
12358        let mut receivers: Option<Vec<UnitRecord>> = None;
12359        for frame in message.frames {
12360            if dropped {
12361                break;
12362            }
12363            match frame {
12364                Frame::LiveStart { status, .. } => {
12365                    let Ok(cursor) = self.stored(replica_cursor(&self.conn)) else {
12366                        dropped = true;
12367                        break;
12368                    };
12369                    if status != LiveStatus::Active || cursor < 0 {
12370                        dropped = true;
12371                    } else if !through.is_some_and(|through| through <= cursor) {
12372                        // A catching-up unit receives no delta (§8.2).
12373                        receivers = self.stored(load_units(&self.conn)).ok().map(|units| {
12374                            units
12375                                .into_iter()
12376                                .filter(|unit| {
12377                                    unit.status == UnitStatus::Active
12378                                        && unit.echo.is_some()
12379                                        && unit.cursor.is_none()
12380                                })
12381                                .collect()
12382                        });
12383                        dropped = receivers.is_none();
12384                    }
12385                }
12386                Frame::Commit {
12387                    commit_seq,
12388                    tables,
12389                    changes,
12390                    ..
12391                } => {
12392                    let Some(receivers) = receivers.clone() else {
12393                        continue;
12394                    };
12395                    dropped = self
12396                        .apply_live_commit(
12397                            &receivers,
12398                            &tables,
12399                            changes,
12400                            commit_seq,
12401                            AppliedServerCommitSource::Delta,
12402                        )
12403                        .is_err();
12404                }
12405                Frame::LiveEnd { through_seq, .. } if receivers.is_some() => {
12406                    dropped = self
12407                        .set_meta(REPLICA_CURSOR_KEY, &through_seq.to_string())
12408                        .is_err();
12409                    applied = Some(through_seq);
12410                }
12411                Frame::Error { .. } => dropped = true,
12412                _ => {}
12413            }
12414        }
12415        // §1.4 rule 4: the ack follows the COMMIT. A failed COMMIT restored
12416        // the replica cursor, so the delta counts as a drop.
12417        if self.finish_coalesced_apply().is_err() || dropped {
12418            applied = None;
12419            dropped = true;
12420        }
12421        if let Some(cursor) = applied {
12422            // §8.2 ack point: the delta's throughSeq.
12423            let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
12424            let _ = transport.realtime_send(&ack);
12425        }
12426        if dropped {
12427            self.set_sync_needed(true, true);
12428        }
12429    }
12430
12431    /// §8.2 ack point after a pull round on a live connection: the replica
12432    /// cursor while it is at least `0`.
12433    fn ack_after_pull(&mut self, transport: &mut dyn Transport) {
12434        if !self.realtime_connected() {
12435            return;
12436        }
12437        if let Ok(cursor @ 0..) = self.stored(replica_cursor(&self.conn)) {
12438            let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
12439            let _ = transport.realtime_send(&ack);
12440        }
12441    }
12442}
12443
12444#[cfg(test)]
12445mod previous_version_wiring_tests;
12446
12447#[cfg(test)]
12448mod identity_tests;
12449
12450#[cfg(test)]
12451mod insert_intent_tests;
12452
12453#[cfg(test)]
12454mod robustness_tests;