Skip to main content

syncular_client/
api.rs

1//! Driver-facing API shapes (JSON-able), mirroring the conformance
2//! `ClientInstance` contract: sync reports, conflicts, rejections, row
3//! states, unit states. Serialized as camelCase to cross the shim
4//! boundary unchanged.
5
6use std::collections::BTreeMap;
7
8use serde::{Deserialize, Serialize};
9use serde_json::{Map, Value};
10
11use crate::previous_version::PreviousVersionContextConfig;
12/// Stable dynamic value boundary used by generated named queries.
13pub type QueryValue = Value;
14/// One dynamic query result row, keyed by QueryIR runtime projection name.
15pub type QueryRow = Map<String, QueryValue>;
16
17/// An owned blob body returned by the Rust client without driver encoding.
18#[derive(Debug, Clone, PartialEq, Eq)]
19pub struct FetchedBlob {
20    pub blob_id: String,
21    pub byte_length: i64,
22    pub bytes: Vec<u8>,
23    pub media_type: Option<String>,
24}
25
26#[derive(Debug, Clone, Copy, PartialEq, Eq)]
27pub enum TimeBucketUnit {
28    Month,
29}
30
31const MAX_TIME_BUCKET_MS: i64 = 253_402_300_799_999;
32
33fn utc_year_month(timestamp_ms: i64) -> Result<(i64, i64), String> {
34    if !(0..=MAX_TIME_BUCKET_MS).contains(&timestamp_ms) {
35        return Err(
36            "sync.invalid_request: time bucket timestamps must fall from 1970 through 9999"
37                .to_owned(),
38        );
39    }
40    let z = timestamp_ms / 86_400_000 + 719_468;
41    let era = z.div_euclid(146_097);
42    let day_of_era = z - era * 146_097;
43    let year_of_era =
44        (day_of_era - day_of_era / 1_460 + day_of_era / 36_524 - day_of_era / 146_096) / 365;
45    let mut year = year_of_era + era * 400;
46    let day_of_year = day_of_era - (365 * year_of_era + year_of_era / 4 - year_of_era / 100);
47    let month_prime = (5 * day_of_year + 2) / 153;
48    let month = month_prime + if month_prime < 10 { 3 } else { -9 };
49    if month <= 2 {
50        year += 1;
51    }
52    Ok((year, month))
53}
54
55/// Derive the immutable UTC scope value stored when a row is created.
56pub fn creation_time_bucket(created_at_ms: i64, unit: TimeBucketUnit) -> Result<String, String> {
57    match unit {
58        TimeBucketUnit::Month => {
59            let (year, month) = utc_year_month(created_at_ms)?;
60            Ok(format!("{year:04}-{month:02}"))
61        }
62    }
63}
64
65/// Return a rolling UTC month window ordered from oldest to newest.
66pub fn last(count: usize, unit: TimeBucketUnit, now_ms: i64) -> Result<Vec<String>, String> {
67    if !(1..=1_200).contains(&count) {
68        return Err(
69            "sync.invalid_request: time bucket count must be from 1 through 1200".to_owned(),
70        );
71    }
72    match unit {
73        TimeBucketUnit::Month => {
74            let (year, month) = utc_year_month(now_ms)?;
75            let current = year * 12 + month - 1;
76            if current - (count as i64 - 1) < 1970 * 12 {
77                return Err(
78                    "sync.invalid_request: every returned UTC month must fall from 1970 through 9999"
79                        .to_owned(),
80                );
81            }
82            Ok((0..count)
83                .rev()
84                .map(|offset| {
85                    let value = current - offset as i64;
86                    format!(
87                        "{:04}-{:02}",
88                        value.div_euclid(12),
89                        value.rem_euclid(12) + 1
90                    )
91                })
92                .collect())
93        }
94    }
95}
96
97/// §4.1: a unit's scope map, one value per requested scope variable.
98pub type UnitScopes = BTreeMap<String, String>;
99
100/// §4.1 persisted unit status.
101#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
102#[serde(rename_all = "lowercase")]
103pub enum UnitStatus {
104    Active,
105    Revoked,
106    Failed,
107}
108
109impl UnitStatus {
110    pub fn name(self) -> &'static str {
111        match self {
112            UnitStatus::Active => "active",
113            UnitStatus::Revoked => "revoked",
114            UnitStatus::Failed => "failed",
115        }
116    }
117}
118
119/// §4.4 one fenced record of a persisted echo: the effective lists the
120/// wildcard fence added for a covered table, or its revocation.
121#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
122pub struct EchoRecord {
123    pub table: String,
124    /// `active` or `revoked`.
125    pub status: String,
126    pub scopes: BTreeMap<String, Vec<String>>,
127}
128
129/// §7.4.3 a unit's restriction: the kept cursor `C` through which its other
130/// covered tables hold every change, and the tables it bootstraps, in
131/// ascending code-unit order. It travels as `RESTRICT` (§4.3).
132#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
133pub struct UnitRestriction {
134    pub cursor: i64,
135    pub tables: Vec<String>,
136}
137
138/// §4.1 one registered unit as the client persists it.
139#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
140#[serde(rename_all = "camelCase")]
141pub struct UnitRecord {
142    /// §4.1: derived from the scope map.
143    pub id: String,
144    pub scopes: UnitScopes,
145    /// An explicit `subscribe` holds the unit; window bases hold it through
146    /// the window registry (§4.1 references).
147    pub explicit: bool,
148    pub status: UnitStatus,
149    /// §10 code when not active, or `sync.cursor_expired` after a reset.
150    #[serde(skip_serializing_if = "Option::is_none")]
151    pub reason_code: Option<String>,
152    /// Absent while the unit is live (§4.5); otherwise `-1`, the pin, or the
153    /// post-bootstrap cursor `P`.
154    #[serde(skip_serializing_if = "Option::is_none")]
155    pub cursor: Option<i64>,
156    /// Opaque resume token from `SUB_END` (§4.7); present mid-bootstrap.
157    #[serde(skip_serializing_if = "Option::is_none")]
158    pub bootstrap_state: Option<String>,
159    /// Tables that received a segment in the current bootstrap (§5.6).
160    pub seeded: Vec<String>,
161    /// The echo persisted at the last `SUB_END` (§4.4).
162    #[serde(skip_serializing_if = "Option::is_none")]
163    pub echo: Option<Vec<EchoRecord>>,
164    /// §7.4.3: the restriction a schema bump gave the unit, while it holds one.
165    #[serde(skip_serializing_if = "Option::is_none")]
166    pub restriction: Option<UnitRestriction>,
167}
168
169impl UnitRecord {
170    /// §4.1: a catching-up unit holding cursor `-1` or a resume token.
171    pub fn bootstrapping(&self) -> bool {
172        self.cursor
173            .is_some_and(|cursor| cursor < 0 || self.bootstrap_state.is_some())
174    }
175}
176
177/// §4.8 window base: the selected scope variable plus the fixed scope values
178/// every unit of its family shares. A base names no table: each unit covers
179/// every table declaring its variables (§4.1).
180#[derive(Debug, Clone, Default)]
181pub struct WindowBase {
182    pub variable: String,
183    /// One value per other variable, shared by every unit.
184    pub fixed_scopes: UnitScopes,
185}
186
187/// §4.8 completeness oracle (I3): the windowed-in units for a base, plus
188/// the subset whose bootstrap has not yet completed. Registration alone is
189/// not completeness — a `pending` unit's local replica may be empty or
190/// partial (it still has `cursor: -1` or holds a resume token), and MUST NOT
191/// be rendered as complete. A unit with zero server
192/// rows still completes once its bootstrap round finishes.
193#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq, Eq)]
194#[serde(rename_all = "camelCase")]
195pub struct WindowState {
196    /// Windowed-in units for this base, ordered by value.
197    pub units: Vec<String>,
198    /// Registered units whose bootstrap has not yet completed.
199    pub pending: Vec<String>,
200    /// The pending units whose unit the server revoked
201    /// (`sync.scope_revoked`, §3.3): a refusal, not a running bootstrap.
202    #[serde(default)]
203    pub revoked: Vec<String>,
204}
205
206#[cfg(test)]
207mod time_bucket_tests {
208    use super::{creation_time_bucket, last, TimeBucketUnit};
209
210    #[test]
211    fn utc_month_buckets_cross_year_boundaries() {
212        let now = 1_770_508_800_000; // 2026-02-08T00:00:00Z
213        assert_eq!(
214            creation_time_bucket(now, TimeBucketUnit::Month).unwrap(),
215            "2026-02"
216        );
217        assert_eq!(
218            last(3, TimeBucketUnit::Month, now).unwrap(),
219            vec!["2025-12", "2026-01", "2026-02"]
220        );
221    }
222
223    #[test]
224    fn utc_month_buckets_reject_unbounded_input() {
225        assert!(last(0, TimeBucketUnit::Month, 0).is_err());
226        assert!(last(1_201, TimeBucketUnit::Month, 0).is_err());
227        assert!(last(2, TimeBucketUnit::Month, 0).is_err());
228        assert!(creation_time_bucket(-1, TimeBucketUnit::Month).is_err());
229    }
230}
231
232#[derive(Debug, Clone, Serialize)]
233#[serde(rename_all = "camelCase")]
234pub struct TableChange {
235    pub table: String,
236    #[serde(skip_serializing_if = "Option::is_none")]
237    pub scope_keys: Option<Vec<String>>,
238}
239
240#[derive(Debug, Clone, Serialize)]
241#[serde(rename_all = "camelCase")]
242pub struct WindowChange {
243    pub base_key: String,
244    /// Changed values of the base.
245    pub units: Vec<String>,
246}
247
248#[derive(Debug, Clone, Serialize)]
249#[serde(rename_all = "camelCase")]
250pub struct SyncStatusSnapshot {
251    pub current_schema_version: i32,
252    pub outbox: usize,
253    pub upgrading: bool,
254    /// §7.4.5: `upgrading` and the reset kept at least one readable table.
255    pub upgrade_kept_tables: bool,
256    #[serde(skip_serializing_if = "Option::is_none")]
257    pub lease_state: Option<LeaseState>,
258    #[serde(skip_serializing_if = "Option::is_none")]
259    pub schema_floor: Option<SchemaFloor>,
260    pub sync_needed: bool,
261    /// RFC 0005 A2: container presence, so a host can enforce the downgrade
262    /// precondition (`previousVersionDiscard`) instead of documenting it.
263    pub previous_version_context: PreviousVersionStatus,
264    /// §5.11: "preflight" while protected reads, claims and sync are refused;
265    /// a change batch carries the snapshot at each transition.
266    pub security_lifecycle: &'static str,
267}
268
269/// RFC 0005 A2: presence of the previous-version container file.
270#[derive(Debug, Clone, Copy, Default, Serialize, PartialEq, Eq)]
271#[serde(rename_all = "camelCase")]
272pub struct PreviousVersionStatus {
273    pub present: bool,
274    #[serde(skip_serializing_if = "Option::is_none")]
275    pub created_at_ms: Option<i64>,
276}
277
278pub const CLIENT_DIAGNOSTICS_VERSION: u8 = 2;
279pub const MAX_DIAGNOSTIC_QUERY_FAILURES: usize = 256;
280
281/// §8.8 client-local code: the `required` policy refused a sync round because
282/// the realtime socket is not connected. Never a wire code (§10.3).
283pub const REALTIME_UNAVAILABLE_CODE: &str = "sync.realtime_unavailable";
284/// §8.8 client-local code: a connected socket ended without a deliberate
285/// disconnect and the round reported no transport code. Never a wire code.
286pub const REALTIME_LOST_CODE: &str = "client.realtime_lost";
287/// §12 client-local code: a local-authority call or config on a host that
288/// has no local authority (the build lacks the `local-authority` feature, the
289/// config names no `localAuthorityPath`, or attach has no remote server).
290pub const LOCAL_AUTHORITY_UNCONFIGURED_CODE: &str = "client.local_authority_unconfigured";
291
292#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
293#[serde(rename_all = "camelCase")]
294pub struct ClientDiagnosticsHost {
295    pub kind: String,
296    pub role: String,
297    pub connectivity: String,
298    pub realtime: RealtimeState,
299    pub realtime_policy: RealtimePolicy,
300    #[serde(skip_serializing_if = "Option::is_none")]
301    pub realtime_reason_code: Option<String>,
302    #[serde(skip_serializing_if = "Option::is_none")]
303    pub realtime_retry_delay_ms: Option<u64>,
304}
305
306/// §7.6: registered units per state; a unit id never enters diagnostics.
307#[derive(Debug, Clone, Serialize, Default, PartialEq, Eq)]
308#[serde(rename_all = "camelCase")]
309pub struct DiagnosticUnits {
310    pub bootstrapping: usize,
311    pub complete: usize,
312    pub reset: usize,
313    pub revoked: usize,
314    pub failed: usize,
315    /// Distinct stable reason codes of registered units, ascending.
316    pub reason_codes: Vec<String>,
317}
318
319#[derive(Debug, Clone, Serialize, Default, PartialEq, Eq)]
320#[serde(rename_all = "camelCase")]
321pub struct DiagnosticRoundCounters {
322    pub pushed: u32,
323    pub applied: usize,
324    pub rejected: usize,
325    pub retryable: usize,
326    pub conflicts: u32,
327    pub commits_applied: u32,
328    pub segment_rows_applied: u32,
329    pub bootstrapping: usize,
330    pub resets: usize,
331    pub revoked: usize,
332    pub failed: usize,
333    pub deferred_commits: usize,
334}
335
336/// Bounded transport classification for progress and diagnostics (§1.8).
337#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
338#[serde(rename_all = "snake_case")]
339pub enum TransportCauseKind {
340    Network,
341    Connect,
342    Tls,
343    Io,
344    Request,
345    Protocol,
346    Timeout,
347    RoundDeadline,
348    Aborted,
349    Body,
350    Status,
351    Redirect,
352    Unknown,
353}
354
355#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
356#[serde(rename_all = "camelCase")]
357pub struct DiagnosticLastRound {
358    /// §7.6: (`epoch`, `attempt`) identifies the round; it equals its §7.7 progress pair.
359    pub epoch: String,
360    pub attempt: u64,
361    pub status: String,
362    pub started_at_ms: i64,
363    pub completed_at_ms: i64,
364    pub duration_ms: i64,
365    #[serde(skip_serializing_if = "Option::is_none")]
366    pub counters: Option<DiagnosticRoundCounters>,
367    #[serde(skip_serializing_if = "Option::is_none")]
368    pub error_code: Option<String>,
369    #[serde(skip_serializing_if = "Option::is_none")]
370    pub cause_kind: Option<TransportCauseKind>,
371    #[serde(skip_serializing_if = "Option::is_none")]
372    pub http_status: Option<u16>,
373}
374
375#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
376#[serde(rename_all = "camelCase")]
377pub struct DiagnosticLastChange {
378    pub revision: String,
379    pub recorded_at_ms: i64,
380    pub tables: Vec<String>,
381    pub windows: Vec<String>,
382    pub domains_truncated: bool,
383    pub status_changed: bool,
384    pub conflicts_changed: bool,
385    pub rejections_changed: bool,
386    pub outcomes_changed: bool,
387}
388
389#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
390#[serde(rename_all = "camelCase")]
391pub struct ClientDiagnosticsStorage {
392    pub status: String,
393    #[serde(skip_serializing_if = "Option::is_none")]
394    pub database_bytes_approx: Option<i64>,
395    #[serde(skip_serializing_if = "Option::is_none")]
396    pub pending_outbox_bytes_approx: Option<i64>,
397    #[serde(skip_serializing_if = "Option::is_none")]
398    pub retained_outcome_bytes_approx: Option<i64>,
399    #[serde(skip_serializing_if = "Option::is_none")]
400    pub retained_outcome_entries: Option<i64>,
401    #[serde(skip_serializing_if = "Option::is_none")]
402    pub blob_cache_bytes_approx: Option<i64>,
403    #[serde(skip_serializing_if = "Option::is_none")]
404    pub pressure_reason_code: Option<String>,
405}
406
407/// §7.6: the latest owned snapshot read of one query id failed.
408#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
409#[serde(rename_all = "camelCase")]
410pub struct DiagnosticQueryFailure {
411    pub id: String,
412    /// Distinct generated table names, ascending.
413    pub tables: Vec<String>,
414    /// `client.storage_corrupt`, `client.storage_io`, or `client.query_failed`.
415    pub code: String,
416    /// SQLite extended result code, when the driver exposed one.
417    #[serde(skip_serializing_if = "Option::is_none")]
418    pub sqlite_code: Option<i32>,
419    /// First failure since this id's last successful read.
420    pub at_ms: i64,
421}
422
423#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
424#[serde(rename_all = "camelCase")]
425pub struct ClientDiagnosticsSnapshot {
426    pub version: u8,
427    pub captured_at_ms: i64,
428    pub host: ClientDiagnosticsHost,
429    pub security_lifecycle: String,
430    pub schema: ClientDiagnosticsSchema,
431    pub replica: ClientDiagnosticsReplica,
432    pub lease: ClientDiagnosticsLease,
433    pub units: DiagnosticUnits,
434    /// Units the next registration list carries; the server limit counts
435    /// these (§4.1).
436    pub active_units: usize,
437    /// §4.5 replica cursor; `-1` while no unit is live.
438    pub replica_cursor: i64,
439    #[serde(skip_serializing_if = "Option::is_none")]
440    pub last_round: Option<DiagnosticLastRound>,
441    #[serde(skip_serializing_if = "Option::is_none")]
442    pub last_change: Option<DiagnosticLastChange>,
443    pub storage: ClientDiagnosticsStorage,
444    pub query_failures: Vec<DiagnosticQueryFailure>,
445}
446
447#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
448#[serde(rename_all = "camelCase")]
449pub struct ClientDiagnosticsSchema {
450    pub current_version: i32,
451    pub upgrading: bool,
452    #[serde(skip_serializing_if = "Option::is_none")]
453    pub required_version: Option<i32>,
454    #[serde(skip_serializing_if = "Option::is_none")]
455    pub latest_version: Option<i32>,
456}
457
458#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
459#[serde(rename_all = "camelCase")]
460pub struct ClientDiagnosticsReplica {
461    pub local_revision: String,
462    pub sync_needed: bool,
463    pub pending_outbox: usize,
464}
465
466/// §8.8: how this client treats the realtime binding for sync rounds.
467#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize)]
468#[serde(rename_all = "lowercase")]
469pub enum RealtimePolicy {
470    Required,
471    #[default]
472    Optional,
473    Off,
474}
475
476impl RealtimePolicy {
477    #[must_use]
478    pub fn as_str(self) -> &'static str {
479        match self {
480            RealtimePolicy::Required => "required",
481            RealtimePolicy::Optional => "optional",
482            RealtimePolicy::Off => "off",
483        }
484    }
485}
486
487/// §8.8: the explicit availability state of the realtime binding. The
488/// TypeScript host adds `unsupported` (no connector configured) and `unknown`
489/// (a wrapper without evidence); the Rust core reaches neither because a
490/// transport always carries a connect path.
491#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize)]
492#[serde(rename_all = "lowercase")]
493pub enum RealtimeState {
494    Connected,
495    Connecting,
496    #[default]
497    Disconnected,
498    Lost,
499    Refused,
500    Disabled,
501}
502
503#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
504#[serde(rename_all = "camelCase")]
505pub struct ClientDiagnosticsLease {
506    pub state: String,
507    #[serde(skip_serializing_if = "Option::is_none")]
508    pub expires_at_ms: Option<i64>,
509    #[serde(skip_serializing_if = "Option::is_none")]
510    pub error_code: Option<String>,
511}
512
513/// JSON bindings carry the u64 revision as a decimal string (§7.5).
514#[derive(Debug, Clone, Serialize)]
515#[serde(rename_all = "camelCase")]
516pub struct AppliedServerCommit {
517    pub table: String,
518    pub commit_seq: i64,
519    pub source: AppliedServerCommitSource,
520}
521
522#[derive(Debug, Clone, Copy, Serialize)]
523#[serde(rename_all = "camelCase")]
524pub enum AppliedServerCommitSource {
525    Delta,
526    Pull,
527}
528
529#[derive(Debug, Clone, Serialize)]
530#[serde(rename_all = "camelCase")]
531pub struct ClientChangeBatch {
532    pub revision: String,
533    pub tables: Vec<TableChange>,
534    pub windows: Vec<WindowChange>,
535    #[serde(skip_serializing_if = "Option::is_none")]
536    pub status: Option<SyncStatusSnapshot>,
537    pub conflicts_changed: bool,
538    pub rejections_changed: bool,
539    pub outcomes_changed: bool,
540    #[serde(skip_serializing_if = "Vec::is_empty")]
541    pub applied_commits: Vec<AppliedServerCommit>,
542}
543
544#[derive(Debug, Clone, Serialize)]
545#[serde(tag = "kind", rename_all = "camelCase")]
546pub enum SyncIntent {
547    None,
548    Interactive,
549    Background {
550        #[serde(rename = "delayMs")]
551        delay_ms: u64,
552    },
553}
554
555#[derive(Debug, Clone, Serialize)]
556pub struct CommandEffects {
557    pub sync: SyncIntent,
558}
559
560impl CommandEffects {
561    #[must_use]
562    pub fn none() -> Self {
563        Self {
564            sync: SyncIntent::None,
565        }
566    }
567
568    #[must_use]
569    pub fn interactive() -> Self {
570        Self {
571            sync: SyncIntent::Interactive,
572        }
573    }
574}
575
576#[derive(Debug, Clone)]
577pub struct WindowCoverage {
578    pub base: WindowBase,
579    pub units: Vec<String>,
580}
581
582#[derive(Debug, Clone, Serialize)]
583#[serde(rename_all = "camelCase")]
584pub struct WindowUnitRef {
585    pub base_key: String,
586    pub unit: String,
587}
588
589#[derive(Debug, Clone, Serialize)]
590#[serde(rename_all = "camelCase")]
591pub struct CoverageSnapshot {
592    pub complete: bool,
593    pub pending: Vec<WindowUnitRef>,
594    pub missing: Vec<WindowUnitRef>,
595    /// The pending units whose unit is revoked (`sync.scope_revoked`, §3.3).
596    pub revoked: Vec<WindowUnitRef>,
597}
598
599/// §7.5: the query that owns a snapshot read. The id is application-owned,
600/// stable, and PHI-free; generated named queries pass their `ID` and `TABLES`.
601#[derive(Debug, Clone, Copy)]
602pub struct QueryOwner<'a> {
603    pub id: &'a str,
604    pub tables: &'a [&'a str],
605}
606
607/// §7.5: a failed snapshot read or a failed local authoring write. `code` is
608/// `client.storage_corrupt`, `client.storage_io`, `client.storage_full`, or
609/// `client.storage_busy` when SQLite reported that condition, and `None` for
610/// every other failure, which keeps its existing message.
611#[derive(Debug, Clone, PartialEq, Eq)]
612pub struct QueryReadFailure {
613    pub code: Option<&'static str>,
614    pub sqlite_code: Option<i32>,
615    pub sqlite_message: Option<String>,
616    pub rollback_failure: Option<Box<QueryReadFailure>>,
617    pub message: String,
618}
619
620impl std::fmt::Display for QueryReadFailure {
621    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
622        match self.code {
623            Some(code) => write!(f, "{code}: {}", self.message),
624            None => f.write_str(&self.message),
625        }
626    }
627}
628
629impl From<String> for QueryReadFailure {
630    fn from(message: String) -> Self {
631        Self {
632            code: None,
633            sqlite_code: None,
634            sqlite_message: None,
635            rollback_failure: None,
636            message,
637        }
638    }
639}
640
641impl From<rusqlite::Error> for QueryReadFailure {
642    /// Classify by SQLite's primary result code, never by message text.
643    fn from(error: rusqlite::Error) -> Self {
644        let sqlite_code = match &error {
645            rusqlite::Error::SqliteFailure(failure, _) => Some(failure.extended_code),
646            _ => None,
647        };
648        match sqlite_code.map(|code| code & 0xff) {
649            Some(11 | 26) => Self {
650                code: Some("client.storage_corrupt"),
651                sqlite_code,
652                sqlite_message: Some(error.to_string()),
653                rollback_failure: None,
654                message: "local SQLite storage is corrupt".to_owned(),
655            },
656            Some(13) => Self {
657                code: Some("client.storage_full"),
658                sqlite_code,
659                sqlite_message: Some(error.to_string()),
660                rollback_failure: None,
661                message: "local SQLite storage is full".to_owned(),
662            },
663            Some(10) => Self {
664                code: Some("client.storage_io"),
665                sqlite_code,
666                sqlite_message: Some(error.to_string()),
667                rollback_failure: None,
668                message: "local SQLite storage I/O failed".to_owned(),
669            },
670            // SQLITE_BUSY (5) and SQLITE_LOCKED (6), including every extended
671            // code, are transient lock contention: the same operation can
672            // succeed after the conflicting operation releases its lock.
673            Some(5 | 6) => Self {
674                code: Some("client.storage_busy"),
675                sqlite_code,
676                sqlite_message: Some(error.to_string()),
677                rollback_failure: None,
678                message: "local SQLite storage is busy".to_owned(),
679            },
680            _ => Self {
681                code: None,
682                sqlite_code,
683                sqlite_message: Some(error.to_string()),
684                rollback_failure: None,
685                message: error.to_string(),
686            },
687        }
688    }
689}
690
691impl QueryReadFailure {
692    /// The operation can be retried after lock contention is resolved.
693    /// SQLITE_LOCKED can involve another statement on the same connection.
694    pub fn retryable(&self) -> bool {
695        self.code == Some("client.storage_busy")
696    }
697
698    pub fn details(&self) -> Option<Value> {
699        self.sqlite_code.map(|code| {
700            let mut details =
701                serde_json::json!({ "sqliteCode": code, "sqliteMessage": self.sqlite_message });
702            if let Some(rollback) = &self.rollback_failure {
703                details["rollbackFailure"] = serde_json::json!({
704                    "sqliteCode": rollback.sqlite_code, "message": rollback.sqlite_message
705                });
706            }
707            details
708        })
709    }
710}
711
712/// A structured failure from a local authoring API (`mutate`/`patch`). `code`
713/// is always a stable `client.*`/`sync.*` identity, `message` is static text
714/// with no table/row/column values, `details` carries SQLite classification
715/// evidence or the preserved legacy cause, and `retryable` is true only for
716/// transient storage contention. Callers read these fields instead of parsing
717/// a `"<code>: "` prefix.
718#[derive(Debug, Clone, PartialEq, Eq)]
719pub struct ClientError {
720    pub code: String,
721    pub message: String,
722    pub details: Option<Value>,
723    pub retryable: bool,
724}
725
726/// The stable default for an authoring failure with no recognized code.
727const DEFAULT_CLIENT_ERROR_CODE: &str = "client.failed";
728
729/// The static text used when no specific static authoring message exists.
730const GENERIC_AUTHORING_MESSAGE: &str = "the local authoring operation failed";
731
732/// The fixed user-facing text for a known authoring code. Dynamic values from
733/// a legacy cause string move to `details.legacyCause` instead.
734fn static_authoring_message(code: &str) -> Option<&'static str> {
735    match code {
736        "sync.unknown_table" => Some("the commit targets an unknown table"),
737        "sync.invalid_request" => Some("the authoring request is invalid"),
738        "sync.row_missing" => Some("a sparse patch requires a local row"),
739        "sync.constraint_violation" => Some("local write violates a unique constraint"),
740        DEFAULT_CLIENT_ERROR_CODE => Some(GENERIC_AUTHORING_MESSAGE),
741        _ => None,
742    }
743}
744
745fn is_client_code(candidate: &str) -> bool {
746    candidate.starts_with("client.") || candidate.starts_with("sync.")
747}
748
749impl std::fmt::Display for ClientError {
750    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
751        write!(f, "{}: {}", self.code, self.message)
752    }
753}
754
755impl std::error::Error for ClientError {}
756
757impl From<QueryReadFailure> for ClientError {
758    fn from(failure: QueryReadFailure) -> Self {
759        match failure.code {
760            // Classified storage messages are already static.
761            Some(code) => {
762                let details = failure.details();
763                let retryable = failure.retryable();
764                Self {
765                    code: code.to_owned(),
766                    message: failure.message,
767                    details,
768                    retryable,
769                }
770            }
771            None => {
772                let mut details = failure.details().unwrap_or_else(|| serde_json::json!({}));
773                if let Some(object) = details.as_object_mut() {
774                    object.insert("legacyCause".to_owned(), Value::String(failure.message));
775                }
776                Self {
777                    code: DEFAULT_CLIENT_ERROR_CODE.to_owned(),
778                    message: GENERIC_AUTHORING_MESSAGE.to_owned(),
779                    details: Some(details),
780                    retryable: false,
781                }
782            }
783        }
784    }
785}
786
787impl From<String> for ClientError {
788    /// Split a core error into structured fields. A recognized code identity
789    /// is preserved and gets static text; any dynamic cause stays in
790    /// `details.legacyCause`. Everything else defaults to `client.failed` with
791    /// the generic message.
792    fn from(message: String) -> Self {
793        // A code-only identity, e.g. `sync.unknown_table`.
794        if !message.contains(": ") && is_client_code(&message) {
795            return Self {
796                code: message.clone(),
797                message: static_authoring_message(&message)
798                    .unwrap_or(GENERIC_AUTHORING_MESSAGE)
799                    .to_owned(),
800                details: None,
801                retryable: false,
802            };
803        }
804        let (code, rest) = match message.split_once(": ") {
805            Some((code, rest)) if is_client_code(code) => (code, Some(rest)),
806            _ => (DEFAULT_CLIENT_ERROR_CODE, None),
807        };
808        match static_authoring_message(code) {
809            Some(fixed) => Self {
810                code: code.to_owned(),
811                message: fixed.to_owned(),
812                details: (rest != Some(fixed))
813                    .then(|| serde_json::json!({ "legacyCause": message })),
814                retryable: false,
815            },
816            None => Self {
817                code: code.to_owned(),
818                message: GENERIC_AUTHORING_MESSAGE.to_owned(),
819                details: Some(serde_json::json!({ "legacyCause": message })),
820                retryable: false,
821            },
822        }
823    }
824}
825
826#[derive(Debug, Clone, Serialize)]
827#[serde(rename_all = "camelCase")]
828pub struct QuerySnapshot {
829    pub revision: String,
830    pub rows: Vec<QueryRow>,
831    pub coverage: CoverageSnapshot,
832}
833
834impl WindowState {
835    /// The per-unit verdict: registered AND bootstrap-complete.
836    #[must_use]
837    pub fn complete(&self, unit: &str) -> bool {
838        self.units.iter().any(|u| u == unit) && !self.pending.iter().any(|u| u == unit)
839    }
840}
841
842/// One local mutation (§6.1 shapes, schema-agnostic local form per §0).
843#[derive(Debug, Clone)]
844pub enum Mutation {
845    Patch {
846        table: String,
847        values: Map<String, Value>,
848        base_version: Option<i64>,
849    },
850    Upsert {
851        table: String,
852        values: Map<String, Value>,
853        base_version: Option<i64>,
854    },
855    Delete {
856        table: String,
857        row_id: String,
858        base_version: Option<i64>,
859    },
860}
861
862#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq, Eq)]
863#[serde(rename_all = "camelCase")]
864pub struct SchemaFloor {
865    #[serde(skip_serializing_if = "Option::is_none")]
866    pub required_schema_version: Option<i32>,
867    #[serde(skip_serializing_if = "Option::is_none")]
868    pub latest_schema_version: Option<i32>,
869}
870
871/// §7.3.5: the client's opaque auth-lease state — `leaseId`/`expiresAtMs`
872/// from the last `LEASE` frame, and `errorCode` once a round was rejected
873/// with a request-level lease code (stop-and-surface; no data purge).
874#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq, Eq)]
875#[serde(rename_all = "camelCase")]
876pub struct LeaseState {
877    #[serde(skip_serializing_if = "Option::is_none")]
878    pub lease_id: Option<String>,
879    #[serde(skip_serializing_if = "Option::is_none")]
880    pub expires_at_ms: Option<i64>,
881    #[serde(skip_serializing_if = "Option::is_none")]
882    pub error_code: Option<String>,
883}
884
885/// §8.6 a peer's ephemeral presence document on a scope key.
886#[derive(Debug, Clone, Serialize)]
887#[serde(rename_all = "camelCase")]
888pub struct PresencePeer {
889    pub actor_id: String,
890    pub client_id: String,
891    pub doc: serde_json::Value,
892}
893
894#[derive(Debug, Clone, Serialize, Default)]
895#[serde(rename_all = "camelCase")]
896pub struct SyncReport {
897    pub pushed: u32,
898    pub applied: Vec<String>,
899    pub rejected: Vec<String>,
900    pub retryable: Vec<String>,
901    pub conflicts: u32,
902    pub commits_applied: u32,
903    pub segment_rows_applied: u32,
904    pub bootstrapping: Vec<String>,
905    pub resets: Vec<String>,
906    pub revoked: Vec<String>,
907    pub failed: Vec<String>,
908    pub deferred_commits: usize,
909    #[serde(skip_serializing_if = "Option::is_none")]
910    pub schema_floor: Option<SchemaFloor>,
911}
912
913impl SyncReport {
914    /// Aggregate completed rounds. Historical counters and outcome lists
915    /// accumulate; current readiness (`bootstrapping`, `deferred_commits`,
916    /// `schema_floor`) describes the latest round. A schema floor stops the
917    /// loop, so it can only arrive from the latest round.
918    pub fn merge(&mut self, report: &Self) {
919        self.pushed += report.pushed;
920        self.applied.extend(report.applied.iter().cloned());
921        self.rejected.extend(report.rejected.iter().cloned());
922        self.retryable.extend(report.retryable.iter().cloned());
923        self.conflicts += report.conflicts;
924        self.commits_applied += report.commits_applied;
925        self.segment_rows_applied += report.segment_rows_applied;
926        self.bootstrapping = report.bootstrapping.clone();
927        self.resets.extend(report.resets.iter().cloned());
928        self.revoked.extend(report.revoked.iter().cloned());
929        self.failed.extend(report.failed.iter().cloned());
930        self.deferred_commits = report.deferred_commits;
931        self.schema_floor = report.schema_floor.clone();
932    }
933}
934
935/// `sync()` never panics or errors out-of-band: transport and protocol
936/// failures come back as `Failed` (the driver's `{ ok: false }`).
937#[derive(Debug, Clone)]
938pub enum SyncOutcome {
939    Ok(SyncReport),
940    Failed {
941        error_code: String,
942        message: String,
943        details: Option<Value>,
944        /// §10.1 `recommendedAction` from the server's error body, when the
945        /// transport preserved one. Client-local and storage failures carry
946        /// `None`.
947        recommended_action: Option<String>,
948    },
949    /// §8.8: the `required` policy refused a round because the socket is not
950    /// connected. `reason_code` is present for `lost` and `refused` states,
951    /// and `retry_delay_ms` is the delay of the background retry intent this
952    /// outcome scheduled.
953    RealtimeUnavailable {
954        state: RealtimeState,
955        reason_code: Option<String>,
956        retry_delay_ms: u64,
957    },
958    /// §7.8: the round budget ran out while the client was still not idle.
959    /// The aggregate report of every round that ran is retained. This is a
960    /// partial success, not a failure, and MUST NOT be read as idle.
961    BudgetExhausted(SyncReport),
962}
963
964impl SyncOutcome {
965    pub fn to_json(&self) -> Value {
966        match self {
967            SyncOutcome::Ok(report) => {
968                let mut map = Map::new();
969                map.insert("ok".to_owned(), Value::Bool(true));
970                map.insert(
971                    "report".to_owned(),
972                    serde_json::to_value(report).expect("report serializes"),
973                );
974                Value::Object(map)
975            }
976            SyncOutcome::Failed {
977                error_code,
978                message,
979                details,
980                recommended_action,
981            } => {
982                let mut map = Map::new();
983                map.insert("ok".to_owned(), Value::Bool(false));
984                map.insert("errorCode".to_owned(), Value::from(error_code.clone()));
985                map.insert("message".to_owned(), Value::from(message.clone()));
986                if let Some(details) = details {
987                    map.insert("details".to_owned(), details.clone());
988                }
989                if let Some(recommended_action) = recommended_action {
990                    map.insert(
991                        "recommendedAction".to_owned(),
992                        Value::from(recommended_action.clone()),
993                    );
994                }
995                Value::Object(map)
996            }
997            SyncOutcome::RealtimeUnavailable {
998                state,
999                reason_code,
1000                retry_delay_ms,
1001            } => {
1002                let mut map = Map::new();
1003                map.insert("ok".to_owned(), Value::Bool(false));
1004                map.insert(
1005                    "errorCode".to_owned(),
1006                    Value::from(REALTIME_UNAVAILABLE_CODE),
1007                );
1008                map.insert(
1009                    "message".to_owned(),
1010                    Value::from("realtime is required and the realtime socket is not connected"),
1011                );
1012                map.insert(
1013                    "realtimeState".to_owned(),
1014                    serde_json::to_value(state).expect("state serializes"),
1015                );
1016                if let Some(reason_code) = reason_code {
1017                    map.insert(
1018                        "realtimeReasonCode".to_owned(),
1019                        Value::from(reason_code.clone()),
1020                    );
1021                }
1022                map.insert("retryDelayMs".to_owned(), Value::from(*retry_delay_ms));
1023                Value::Object(map)
1024            }
1025            SyncOutcome::BudgetExhausted(report) => {
1026                let mut map = Map::new();
1027                map.insert("ok".to_owned(), Value::Bool(true));
1028                map.insert("budgetExhausted".to_owned(), Value::Bool(true));
1029                map.insert(
1030                    "report".to_owned(),
1031                    serde_json::to_value(report).expect("report serializes"),
1032                );
1033                Value::Object(map)
1034            }
1035        }
1036    }
1037}
1038
1039#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1040#[serde(rename_all = "camelCase")]
1041pub struct ConflictRecord {
1042    pub client_commit_id: String,
1043    pub op_index: i32,
1044    pub table: String,
1045    pub row_id: String,
1046    pub code: String,
1047    pub message: String,
1048    pub server_version: i64,
1049    /// Driver row (bytes as `{"$bytes": hex}`), decoded from the conflict
1050    /// record's `serverRow` (§6.3).
1051    pub server_row: Map<String, Value>,
1052    /// §6.3 `conflictColumns`: the present columns whose `column_version`
1053    /// exceeded `baseVersion`, decoded from the bitmap into column names in
1054    /// declaration order. Absent on a legacy journal entry, which reads as an
1055    /// empty list.
1056    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1057    pub conflict_columns: Vec<String>,
1058    #[serde(skip_serializing_if = "Option::is_none")]
1059    pub operation: Option<CommitOperation>,
1060}
1061
1062/// Bounded code-like metadata explicitly declared safe for authorized client
1063/// recovery UI. Diagnostic prose remains in `RejectionRecord.message`.
1064#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1065#[serde(rename_all = "camelCase", deny_unknown_fields)]
1066pub struct RejectionDetails {
1067    #[serde(skip_serializing_if = "Option::is_none")]
1068    pub field_paths: Option<Vec<String>>,
1069    #[serde(skip_serializing_if = "Option::is_none")]
1070    pub reason: Option<String>,
1071    #[serde(skip_serializing_if = "Option::is_none")]
1072    pub required_action: Option<String>,
1073    #[serde(skip_serializing_if = "Option::is_none")]
1074    pub references: Option<BTreeMap<String, String>>,
1075}
1076
1077impl RejectionDetails {
1078    pub(crate) fn parse(raw: &str) -> Result<Self, String> {
1079        if raw.len() > 4_096 {
1080            return Err("rejection details exceed 4096 encoded bytes".to_owned());
1081        }
1082        let details: Self = serde_json::from_str(raw)
1083            .map_err(|error| format!("invalid rejection details: {error}"))?;
1084        details.validate()?;
1085        Ok(details)
1086    }
1087
1088    fn validate(&self) -> Result<(), String> {
1089        let mut members = 0;
1090        if let Some(paths) = &self.field_paths {
1091            members += 1;
1092            if paths.is_empty() || paths.len() > 32 {
1093                return Err("fieldPaths must contain 1-32 paths".to_owned());
1094            }
1095            let mut seen = std::collections::BTreeSet::new();
1096            for path in paths {
1097                if path.len() > 160 || !path.split('.').all(valid_identifier) || !seen.insert(path)
1098                {
1099                    return Err("fieldPaths contains an invalid or duplicate path".to_owned());
1100                }
1101            }
1102        }
1103        if let Some(reason) = &self.reason {
1104            members += 1;
1105            if !valid_token(reason, 96) {
1106                return Err("reason must be a lowercase stable token".to_owned());
1107            }
1108        }
1109        if let Some(action) = &self.required_action {
1110            members += 1;
1111            if !valid_token(action, 96) {
1112                return Err("requiredAction must be a lowercase stable token".to_owned());
1113            }
1114        }
1115        if let Some(references) = &self.references {
1116            members += 1;
1117            if references.is_empty() || references.len() > 16 {
1118                return Err("references must contain 1-16 entries".to_owned());
1119            }
1120            for (key, value) in references {
1121                if !valid_token(key, 64)
1122                    || value.is_empty()
1123                    || value.len() > 256
1124                    || value.trim() != value
1125                    || value.chars().any(char::is_control)
1126                {
1127                    return Err("references contains an invalid key or value".to_owned());
1128                }
1129            }
1130        }
1131        if members == 0 {
1132            return Err("rejection details must not be empty".to_owned());
1133        }
1134        Ok(())
1135    }
1136}
1137
1138fn valid_identifier(segment: &str) -> bool {
1139    let mut chars = segment.chars();
1140    matches!(chars.next(), Some(first) if first == '_' || first.is_ascii_alphabetic())
1141        && chars.all(|character| character == '_' || character.is_ascii_alphanumeric())
1142}
1143
1144fn valid_token(token: &str, max: usize) -> bool {
1145    if token.is_empty() || token.len() > max || !token.starts_with(|c: char| c.is_ascii_lowercase())
1146    {
1147        return false;
1148    }
1149    let mut previous_separator = false;
1150    for character in token.chars() {
1151        if character.is_ascii_lowercase() || character.is_ascii_digit() {
1152            previous_separator = false;
1153        } else if matches!(character, '.' | '_' | '-') && !previous_separator {
1154            previous_separator = true;
1155        } else {
1156            return false;
1157        }
1158    }
1159    !previous_separator
1160}
1161
1162#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1163#[serde(rename_all = "camelCase")]
1164pub struct RejectionRecord {
1165    pub client_commit_id: String,
1166    pub op_index: i32,
1167    pub code: String,
1168    pub message: String,
1169    pub retryable: bool,
1170    #[serde(skip_serializing_if = "Option::is_none")]
1171    pub details: Option<RejectionDetails>,
1172    #[serde(skip_serializing_if = "Option::is_none")]
1173    pub operation: Option<CommitOperation>,
1174}
1175
1176/// Schema-agnostic local operation retained with a failed final outcome.
1177#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1178#[serde(rename_all = "camelCase")]
1179pub struct CommitOperation {
1180    pub table: String,
1181    pub row_id: String,
1182    pub op: String,
1183    #[serde(skip_serializing_if = "Option::is_none")]
1184    pub base_version: Option<i64>,
1185    #[serde(skip_serializing_if = "Option::is_none")]
1186    pub values: Option<Map<String, Value>>,
1187    /// §7.1 insert intent: serialized as `"insert": true`, absent otherwise.
1188    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
1189    pub insert: bool,
1190}
1191
1192/// One pending outbox commit (§7.1), in the shape the TypeScript client's
1193/// `pendingCommits()` returns.
1194#[derive(Debug, Clone, Serialize, PartialEq)]
1195#[serde(rename_all = "camelCase")]
1196pub struct PendingCommit {
1197    /// The outbox sequence number; FIFO send order.
1198    pub seq: i64,
1199    pub client_commit_id: String,
1200    /// Local clock at `mutate`; 0 for a commit queued before 0.89.
1201    pub created_at_ms: i64,
1202    pub operations: Vec<CommitOperation>,
1203}
1204
1205#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
1206#[serde(rename_all = "snake_case")]
1207pub enum CommitOutcomeStatus {
1208    Applied,
1209    Cached,
1210    Conflict,
1211    Rejected,
1212}
1213
1214#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
1215#[serde(rename_all = "snake_case")]
1216pub enum CommitOutcomeResolution {
1217    Active,
1218    ResolvedKeepServer,
1219    Superseded,
1220    Dismissed,
1221}
1222
1223#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1224#[serde(tag = "status", rename_all = "snake_case")]
1225pub enum CommitOperationOutcome {
1226    Applied {
1227        #[serde(rename = "opIndex")]
1228        op_index: i32,
1229    },
1230    Conflict {
1231        conflict: ConflictRecord,
1232    },
1233    Error {
1234        rejection: RejectionRecord,
1235    },
1236}
1237
1238#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1239#[serde(rename_all = "camelCase")]
1240pub struct RetainedUniqueConflict {
1241    pub index: String,
1242    pub columns: Vec<String>,
1243    pub row_id: String,
1244    pub server_row: Map<String, Value>,
1245    pub server_version: i64,
1246}
1247
1248#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1249#[serde(rename_all = "camelCase")]
1250pub struct RetainedCommitRow {
1251    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1252    pub unique_conflicts: Vec<RetainedUniqueConflict>,
1253    pub table: String,
1254    pub row_id: String,
1255    pub local_row: Option<Map<String, Value>>,
1256    /// The latest delivered authorized base; rejection can precede the pull.
1257    pub server_row: Option<Map<String, Value>>,
1258    pub server_version: Option<i64>,
1259}
1260
1261/// Result of proving every retained base after a completed pull (§7.2.1).
1262#[derive(Debug, Clone, Serialize, PartialEq)]
1263#[serde(rename_all = "camelCase")]
1264pub struct CurrentBaseProof {
1265    pub proven: bool,
1266    #[serde(skip_serializing_if = "Option::is_none")]
1267    pub rows: Option<Vec<RetainedCommitRow>>,
1268    #[serde(skip_serializing_if = "Option::is_none")]
1269    pub reason: Option<CurrentBaseProofReason>,
1270}
1271
1272#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
1273#[serde(rename_all = "snake_case")]
1274pub enum CurrentBaseProofReason {
1275    Offline,
1276    SyncFailed,
1277    SchemaFloor,
1278    BudgetExhausted,
1279    SnapshotFailed,
1280    MissingCoverage,
1281    Revoked,
1282    OutcomeUnavailable,
1283}
1284
1285impl CurrentBaseProof {
1286    pub fn failure(reason: CurrentBaseProofReason) -> Self {
1287        Self {
1288            proven: false,
1289            rows: None,
1290            reason: Some(reason),
1291        }
1292    }
1293}
1294
1295#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1296#[serde(rename_all = "camelCase")]
1297pub struct CommitOutcome {
1298    pub sequence: i64,
1299    pub client_commit_id: String,
1300    pub status: CommitOutcomeStatus,
1301    pub recorded_at_ms: i64,
1302    pub results: Vec<CommitOperationOutcome>,
1303    /// Complete local failed-commit envelope retained after outbox drain.
1304    /// Absent for successful and historical outcomes; never sent over wire.
1305    #[serde(skip_serializing_if = "Option::is_none")]
1306    pub operations: Option<Vec<CommitOperation>>,
1307    #[serde(skip_serializing_if = "Option::is_none")]
1308    pub retained_rows: Option<Vec<RetainedCommitRow>>,
1309    pub resolution: CommitOutcomeResolution,
1310    #[serde(skip_serializing_if = "Option::is_none")]
1311    pub resolved_at_ms: Option<i64>,
1312    #[serde(skip_serializing_if = "Option::is_none")]
1313    pub replacement_client_commit_id: Option<String>,
1314}
1315
1316#[derive(Debug, Clone, Deserialize, Default)]
1317#[serde(rename_all = "camelCase")]
1318pub struct CommitOutcomeQuery {
1319    pub limit: Option<usize>,
1320    #[serde(default)]
1321    pub active_only: bool,
1322}
1323
1324/// §7.5: the catch-up state of one unit as persisted in the snapshot, never
1325/// the mutable owner cache. `Unknown` means the client does not currently
1326/// hold the unit (never registered, released, or removed).
1327#[derive(Debug, Clone, Serialize)]
1328#[serde(
1329    tag = "state",
1330    rename_all = "camelCase",
1331    rename_all_fields = "camelCase"
1332)]
1333pub enum UnitCatchup {
1334    Unknown {
1335        id: String,
1336    },
1337    Known {
1338        id: String,
1339        status: UnitStatus,
1340        live: bool,
1341        /// The unit's cursor while it catches up, the replica cursor while live.
1342        cursor: i64,
1343        has_resume_token: bool,
1344        /// True only for an `active` unit that is live or post-bootstrap.
1345        bootstrap_complete: bool,
1346        /// True only for an `active` unit with cursor `-1` or a resume token.
1347        known_pending_pages: bool,
1348        #[serde(skip_serializing_if = "Option::is_none")]
1349        reason_code: Option<String>,
1350    },
1351}
1352
1353/// §7.5: delivery status for one client commit id. A commit still in the
1354/// outbox is `pending`; a drained commit carries its persisted retained
1355/// outcome; an id the client never held, or whose outcome was pruned by
1356/// retention, is `unknown`. The outcome preserves every operation result,
1357/// rejection code, and conflict. The owning core attaches the retained-row
1358/// images of its in-memory failed-commit cache; the read-only sidecar reports
1359/// the persisted fields.
1360#[derive(Debug, Clone, Serialize)]
1361#[serde(tag = "status", rename_all = "snake_case")]
1362pub enum CommitDelivery {
1363    Pending {
1364        #[serde(rename = "clientCommitId")]
1365        client_commit_id: String,
1366    },
1367    Known {
1368        #[serde(rename = "clientCommitId")]
1369        client_commit_id: String,
1370        outcome: CommitOutcome,
1371    },
1372    Unknown {
1373        #[serde(rename = "clientCommitId")]
1374        client_commit_id: String,
1375    },
1376}
1377
1378/// §7.5: the result of one atomic snapshot read over a single SQLite read
1379/// transaction: one revision, every requested read-only statement's rows,
1380/// requested window coverage, requested unit catch-up states, and requested
1381/// commit deliveries.
1382#[derive(Debug, Clone, Serialize)]
1383#[serde(rename_all = "camelCase")]
1384pub struct SnapshotRead {
1385    pub revision: String,
1386    pub queries: Vec<Vec<QueryRow>>,
1387    pub coverage: CoverageSnapshot,
1388    pub units: Vec<UnitCatchup>,
1389    pub deliveries: Vec<CommitDelivery>,
1390}
1391
1392#[derive(Debug, Clone, Deserialize)]
1393#[serde(rename_all = "camelCase")]
1394pub struct ResolveCommitOutcomeInput {
1395    pub client_commit_id: String,
1396    pub resolution: CommitOutcomeResolution,
1397    pub replacement_client_commit_id: Option<String>,
1398}
1399
1400#[derive(Debug, Clone, Serialize)]
1401#[serde(rename_all = "camelCase")]
1402pub struct RowState {
1403    pub row_id: String,
1404    /// Local synced version: `-1` = optimistic, else the server version
1405    /// (from a `COMMIT` change or a segment row record, §5.2/§5.6).
1406    pub version: i64,
1407    pub values: Map<String, Value>,
1408    /// §5.11 `_sync_sealed_key` of a sealed row; absent on an unsealed row.
1409    #[serde(skip_serializing_if = "Option::is_none")]
1410    pub sealed_key: Option<String>,
1411}
1412
1413/// One AND-combined application-authorized local purge target. Targets in
1414/// one input are OR-combined. Selector columns must compile to plaintext
1415/// strings; values are bounded code-like routing identifiers.
1416#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1417#[serde(untagged, deny_unknown_fields)]
1418pub enum LocalDataPurgeTarget {
1419    Table {
1420        table: String,
1421        selectors: BTreeMap<String, Vec<String>>,
1422    },
1423    Projection {
1424        projection: String,
1425    },
1426}
1427
1428/// Durable local idempotency key plus exact routing targets. The host owns
1429/// directive authenticity and subscription gating; the client owns SQLite.
1430#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1431#[serde(rename_all = "camelCase", deny_unknown_fields)]
1432pub struct LocalDataPurgeInput {
1433    pub purge_id: String,
1434    pub targets: Vec<LocalDataPurgeTarget>,
1435}
1436
1437/// Privacy-safe local purge acknowledgement; row ids never cross the bridge.
1438#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1439#[serde(rename_all = "camelCase")]
1440pub struct LocalDataPurgeResult {
1441    pub already_applied: bool,
1442    pub purged_rows: usize,
1443    pub dropped_commits: usize,
1444}
1445
1446/// Durable application repair id. Reusing the id is an exact no-op.
1447#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1448#[serde(rename_all = "camelCase", deny_unknown_fields)]
1449pub struct LocalDataRebootstrapInput {
1450    pub rebootstrap_id: String,
1451}
1452
1453/// Privacy-safe acknowledgement for a replicated-projection recovery.
1454#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1455#[serde(rename_all = "camelCase")]
1456pub struct LocalDataRebootstrapResult {
1457    pub already_applied: bool,
1458    pub retained_commits: usize,
1459    pub reset_subscriptions: usize,
1460}
1461
1462/// Client limits (§4.2 request knobs).
1463#[derive(Debug, Clone, Default)]
1464pub struct ClientLimits {
1465    pub limit_commits: Option<i32>,
1466    pub limit_snapshot_rows: Option<i32>,
1467    pub max_snapshot_pages: Option<i32>,
1468    /// §4.2 accept bitmask; this client defaults to `0b0111` (rows
1469    /// baseline + sqlite images, §5.3 — rusqlite can always import).
1470    pub accept: Option<u8>,
1471    /// §5.9.7 B1 blob-cache size cap (bytes). When set and the sum of cached
1472    /// body sizes exceeds it, unreferenced bodies without pending work are
1473    /// evicted by creation timestamp after each cache write. `None` retains bodies
1474    /// until storage pressure (default).
1475    pub blob_cache_max_bytes: Option<i64>,
1476    /// Maximum durable final outcomes. Active conflicts/rejections are never
1477    /// pruned to satisfy the cap. Defaults to 1,000.
1478    pub outcome_retention_max_entries: Option<usize>,
1479    /// §7.1: maximum whole commits in one push request. `None` is unbounded.
1480    pub max_push_commits_per_request: Option<usize>,
1481    /// §7.1: maximum operations across the push commits in one request. `None`
1482    /// uses the reference default of 500. A first commit that alone exceeds it
1483    /// is a typed `client.push_request_too_large` capacity error and stays
1484    /// queued.
1485    pub max_push_operations_per_request: Option<usize>,
1486    /// §7.1: maximum bytes of the complete encoded SSP2 request (8-byte
1487    /// envelope, request header, push commits, pull header, units and progress frames,
1488    /// framing, and any §5.11 ciphertext). `None` is unbounded. A request whose
1489    /// fixed frames alone exceed it, or whose first commit alone does not fit,
1490    /// fails with `client.push_request_too_large` and keeps its intent.
1491    pub max_push_request_bytes: Option<usize>,
1492    /// RFC 0005 D8: the previous-version capture config. Absent or
1493    /// `enabled: false` runs the feature off (default); the descriptor write
1494    /// and the container orphan sweep still happen.
1495    pub previous_version_context: Option<PreviousVersionContextConfig>,
1496    /// Immutable, explicit preflight authority read policy.
1497    pub authority_reads: Vec<AuthorityReadDeclaration>,
1498}
1499
1500/// Static read policy; never accepted as snapshot parameters.
1501#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq)]
1502#[serde(rename_all = "camelCase", deny_unknown_fields)]
1503pub struct AuthorityReadDeclaration {
1504    pub table: String,
1505    pub columns: Vec<String>,
1506    pub scopes: std::collections::BTreeMap<String, Vec<String>>,
1507}